Architecture of SILKin, Part 1

A Mixture of GUI Types

As previously discussed, the GUI for SILKin was a fork of the KinshipEditor of the KAES Project. The KinshipEditor was built using the first generation of Java's GUI primitives.

In 2010 when Gary began work full-time on developing a User Interface for SILKin, a new set of tools for interface building had been released by Java: Swing. So new elements added to the GUI – and modifications to it – were written in Swing in 2010. Later yet, Java released a version of the NetBeans IDE that provided a graphical GUI Builder (i.e. a Swing code generator). This was much more efficient, so Gary began to generate new screens with that tool.

Thus, there is a hodgepodge of GUI code in SILKin. And because of its bulk it will remain so unless the system is completely re-written, an unlikely event.

Support files in the Library

ClauseIndex

When SILKin is searching for a kin term definition in the Library which covers all kin types that are covered by a new kin term, an indexed search is needed. A kin type is a particular chain of relationships. For example, the English term 'aunt' covers 4 kin types:

By using standard abbreviations for each of the basic relationships (e.g. brother) we generate a unique code for each kin type. 'Mother's brother's wife' is always encoded MoBroWi. Importantly, this coding does not depend on how the relationship might be expressed in a kin term definition. If the definition leads to a particular leaf on the family tree, the encoding is always the same no matter how we got there.

As part of pre-computing the SILKin Library files, each kin term definition in every language is indexed by each kin type it covers. Since each part of a kin term definition is a Horn Clause, we call this the ClauseIndex.

So, if we are searching for a kin term definition in the Library that covers 6 different kin types, we need only retrieve the 6 sets of definitions that cover each one of them and take the set intersection.

Contexts Under Construction

This folder contains all the silk files created by the user, or provided with the system. The user may always choose to keep silk files somewhere else, but this is the default location. No matter what locations the user may choose, SILKin keeps a list of the last five SILK file locations with their complete pathnames.

  SILK files

A SILK file is the complete repository of all data gathered, all preferences expressed, and the current state of computation for any one project. It is an XML style file. Most of the blocks are unique to SILKin; the XML rules of block definition are followed. The legal elements and permissible sequences of blocks in a SILK file are as follows:

A standard file header is expected:

<?xml version="1.0" encoding="UTF-8" ?>
<?xml-stylesheet type="text/xsl" href="Silk-status.xsl"?>
<!DOCTYPE SIL_KinData>
<SIL_KinData>

Theoretically, all blocks enclosed by the SIL_KinData are optional. However, the parameters and editorSettings blocks are always written.

The Parameter Block

The parameters block is next. Most parameter names are self-explanatory. Technically, all blocks are optional. But a SILK file without a language name is useless, etc. 'SC' indicates a self-contained 1-piece tag versus a conventional 2-piece tag. The parameter tag is a 2-piece tag.

Contents of parameter block
Tag SC Attribute Data Type Options
language Y name text
theory Y file text: name of file containing a domain theory 0,1 or 2
comments text
createDate Y value text: YYYY-MM-DD
dataAuthors dataAuthor tags
dataAuthor Y name text
lastDataChangeDate Y value text: YYYY-MM-DD
lastSuggestionDate Y value text: YYYY-MM-DD
indSerNum highest serial number of an individual
linkSerNum highest serial number of a link
famSerNum highest serial number of a family (union)
polygamyPermit boolean
UDP a UDP block 0 or more

Each optional UDP block contains the specs for a User Defined Property (or Predicate). Note that this structure is used for both the template of a UDP (stored on the Context) and for any individual's instance of the property (stored on the Individual). Hence, there is both a tag to hold one person's value ('value') as well as a default value, etc. A UDP block contains the following tags in order. The UDP tag is a 2-piece tag. NOTE that the last 2 blocks are optional.

Contents of UDP block
Tag SC Attributes Data Type
propertyName text: name of UDP must begin with asterisk
typ one of: integer, float, string, boolean, individual
value text: value(s) of correct type, comma separated
singleValue text: boolean
validEntries text: list of legal values, comma separated
defaultValue a single value of proper type
minVal text: lowest legal value
maxVal text: highest legal value
chartable boolean
chartColor Y R, G, and B 3 integers to specify a color

This is the end of the parameters block.

The Editor Settings Block

Next comes the editorSettings block. It records the state of the editor for this project, so that if multiple projects are being pursued on the same laptop, each carries its own settings. This block has a 2-piece tag and encloses the following blocks in order.

Contents of editorSettings block
Tag SC Attributes Data Type Encloses
currentEgo Y n text: serial number of the current Ego
editDirectory Y dir text: complete pathname to folder holding SILK files
currentChart Y id text: capital letter (ID) of current family tree chart
chartDescriptions chart blocks (defined in 3 following lines)
chart Y name text: User-provided description of this chart
origin Y x, y integers specifying location of top left of chart
area Y W, H integers: width and height of screen
infoPerson serial number of person in focus, or -1
infoMarriage serial number of family in focus, or -1
label integer: code of labeling choice for charts
ktlabel integer: code of kin term labeling choice
editable boolean
distinctAdrTerms boolean
maxNoise integer
ignorable integer
doBaseCBs Y value boolean
doInduction Y value boolean
surnameCapture Y value boolean
birthdateCapture Y value boolean
chartFont Y name, size text: a font name and an integer
printFont Y name, size text: a font name and an integer
printOrientation Y value 0 or 1
lastPersonIndexed integer: serial nmbr of last person indexed
kinTypePriorities maleFirst boolean. kinType blocks (defined in the next line)
kinType Y name, priority text: a kin type code and a capital letter
snapToGrid Y val, x, y boolean, grid width, grid height
adoptionHelp Y val boolean
saveInterval Y val int
displayGEDCOM Y val boolean

In the rare event that data was imported to this project from a GEDCOM file, there may follow up to four special blocks that simply store the extra GEDCOM data (not used by SILKin) for later use in exporting data in that format.

Each of these blocks will contain one or more gedcomItem blocks. The gedcomItem tag has four attributes: The gedcomItem block always encloses a text block that encloses arbitrary text for this item. Optionally, the gedcomItem block may also enclose a subItems block that encloses gedcomItem blocks (presumably at a lower level than this block). There is no limit on the depth of subItems.

The Special Relationships Block

Next may come a specialRelationships block that encloses one or more chart blocks. The chart tag has a single attribute 'name' that is the letter ID of a chart. The chart block encloses one or more specRel 1-piece tags. Each of these has three attributes:

This is the end of the editorSettings block.

Domain Theory Block

The editorSettings block may be followed by zero, one or two domainTheory blocks. If two domain theories are present, the first one will always be for terms of reference, and the second will be for terms of address. The domain-theory tag is a 2-piece tag with a single attribute 'type' whose value must be 'Ref' or 'Adr'.

Contents of a domain-theory block
Tag SC Attributes Data Type Encloses
author Y name text: name of field worker creating this project
non-terms zero or more non-term blocks (defined on the next line)
non-term Y value text: name of a pre-defined non-primitive kin term
levels-of-recursion Y n integer: number of recursive levels allowed in definition expansions
theory kin-term-def blocks

A theory block contains zero or more kin-term-def blocks. The 2-piece kin-term-def tag itself has a single attribute 'non-term' which is a boolean. Two of the tags have 'eqc' in their name. That is an abbreviation for 'equivalence class.' Often two different languages have a kin term for exactly the same set of kin types, and therefore they have identical kin type encodings. They are members of an equivalence class.

Contents of a kin-term-def block
Tag SC Attributes Data Type Encloses
head text: the kin term
eqcSigExact text: the precise kin type coding for this entire definition
eqcSigStruct This OPTIONAL block encloses text: the gender-neutral kin type coding
gloss one or more element blocks (defined on the next line)
element Y text one text element of the gloss for this defintion
definitions one or more clause blocks (defined below)
clause level integer. an optional pc-string block, an optional pc-string-structural block, plus one or more literal blocks (all defined below).
pc-string text: the kin type encoding of the clause
pc-string-structural text: the gender-neutral kin type encoding of the clause
literal one predicate block and one arg-list block (both defined below).
predicate text: the name of a kinship predicate (e.g. father)
arg-list literal blocks or var blocks (defined below); theoretically any number of them, but in practice one or two
var text: the name of a variable (e.g. Ego)
expandedDefs one or more clause blocks. NOTE: in an expandedDefs block, all clauses use system-defined predicates

Individual Census Block

Next may come the individualCensus block. This 2-piece tag encloses one or more individual blocks. The individual tag has a single attribute, an integer = serial number.

Contents of an individual block
Tag SC Attributes Data Type Encloses
sex text: M for male; F for female
homeChart Y id text: the letter ID of the chart on which this person was created.
location Y x, y integer: the coordinates of this person's symbol on the home chart
surname Y value text: person's surname
firstNames Y value text: all of a person's names preceding the surname
dataChangeDate Y value text: a date in YYYY-MM-DD format
dataAuthor Y name text: name of user who created this person
deleted boolean
birthFamily contains zero or one integer: the serial number of this person's family of origin
marriages zero or more mar blocks (defined below)
mar Y n integer: serial number of a family in which this person is a spouse

Link Census Block

Next may come a linkCensus block enclosing link tags. A link tag is a very large 1-piece tag with the following attributes:

Attributes of a link tag
Attribute Data Type Meaning
person integer serial number of person linked to
deleted boolean
gender text M for male; F for female
homeChart text Letter ID of home chart for this link
locationX integer x coordinate on the home chart
locationY integer y coordinate on the home chart
serial integer serial number of this link
author text name of user creating this link
chgDate text date of last change to this link: YYYY-MM-DD

Family Census Block

Next may come a familyCensus block enclosing family blocks. The family tag has a single attribute 'n' whose integer value is the serial number of that family. A family block encloses the following blocks.

Contents of a family block
Tag SC Attributes Data Type Encloses
homeChart Y id text: the letter ID of the chart on which this family was created.
location Y x, y integer: the coordinates of this family's symbol on the home chart
reason text: either NA, Death, Divorce, or Other
deleted boolean
husband Y n integer: husband's serial number
wife Y n integer: wife's serial number
children zero or more kid 1-piece tags (defined below)
kid Y n integer: kid's serial number
marriageDate Y value date union began: YYYY-MM-DD
endDate Y value date union ended: YYYY-MM-DD
dataChangeDate Y value date of last change to this family: YYYY-MM-DD
dataAuthor Y name text: name of user who created this family

Kin Term Matrix

Next may come a matrix block enclosing one or more row blocks. Each row block in turn encloses one or more cell blocks. Each row tag has a single attribute, 'ego' whose value is the serial number of the person whose kin term data is stored in this row. Each cell tag has a single attribute, 'alter' whose value is the serial number of the person whose kin term (relative to Ego) is stored in this cell.

This matrix represents an N-by-N table of kin terms. In row 6, column 10 is a cell containing the kin term(s) that person #6 calls person #10. More than one kin term may apply to any pair of persons (e.g. grandparent and grandmother may both be correct). SILKin allows for 6 different categories of kin terms:

  1. Primary Reference (tag is PR)
  2. Extended Reference (tag is ER)
  3. eXception Reference (tag is XR)
  4. Primary Address (tag is PA)
  5. Extended Address (tag is EA)
  6. eXception Address (tag is XA)
In practice, PR and PA terms are the only ones captured by field workers.

Contents of a cell block
Tag SC Attributes Data Type Encloses
pcString text: the kin type encoding for this relationship
level integer: the 'height' of alter on Ego's family tree chart. A sibling is on level 0, parents on level 1, children on level -1, etc.
miniPreds one or more pred 1-piece tags
pred Y rel, arg0, arg1 rel is a kin type encoding. arg0 and arg1 are integers: the serial numbers of the two persons who are arguments to this predicate. So each pred tag shows one link in the chain of relations between Ego & Alter.
NOTE: the cell block is completed by one or more of the following legal tags for a kin term.
PR text: a kin term
ER text: a kin term
XR text: a kin term
PA text: a kin term
EA text: a kin term
XA text: a kin term

Dyads: Defined, Undefined, Reference, and Address

Next may come a dyadsUndefinedRef block enclosing one or more dyadKinTerm blocks. The dyadKinTerm tag has a single attribute 'kinTerm' whose value is the kin term associated with all the enclosed dyads. The dyadKinTerm block encloses one or more dyad 1-piece tags.

A dyad is logically a triple: Ego, Alter, KinTerm. But I add extra information for convenience. The dyad tag has up to 8 attributes:

Next may come a dyadsDefinedRef block that is identical in structure to the above, but contains dyads for which the user has accepted a kin term definition. Likewise for dyadsUndefinedAdr and dyadsDefinedAdr blocks containing terms of address.

Next may come a kinTypeIndex block that contains one or more entry blocks. The entry tag has a single attribute 'kt' whose value is a kin type encoding. The entry block contains one or more pair 1-piece tags. The pair tag has two attributes:

Thus the kinTypeIndex is a list of entries, one for each kin type observed in the data. Each entry is a list of all the Ego-Alter pairs in the data that have this structural relationship.

Learning History

Next may come one or two learning-history blocks, each containing one or more history blocks. The learning-history tag has a single attribute 'type' that is either 'Ref' or 'Adr'. The history tag has a single attribute 'kinTerm' whose value is a kin term that has been involved in learning. Each history block contains one or more of the following:

Here are the specifications of those blocks:

Contents of the blocks in a history block
Tag SC Attributes Data Types Encloses
accepted-def kinTerm, date, rescinded, notes text: a kin term, date of learning event, boolean, comments zero or one auto-defs block
auto-defs one or more pair blocks
pair Y ego, alter integers: serial numbers of the ego and alter in a relationship
rejected-def Y kinTerm, date, rescinded, notes, sigString, protoLang, protoKT text: a kin term, date of learning event, boolean, comments, a kin type encoding, a language name (in the Library), a kin term from that language
accepted-synonym Y primary, date, rescinded, notes, synonym text: the primary kin term, date of learning event, boolean, comments, the synonym (secondary) kin term
rejected-synonym Y primary, date, rescinded, notes, synonym text: the primary kin term, date of learning event, boolean, comments, the synonym (secondary) kin term
accepted-umbrella umbTerm, date, rescinded, notes, text: the umbrella term, date of learning event, boolean, comments, An original-sub-terms block, an edited-sub-terms block, and optionally an added-sub-terms block.
original-sub-terms zero or more sub-term 1-piece tags
sub-term Y value text: a kin term that is included under this umbrella
edited-sub-terms zero or more sub-term 1-piece tags
added-sub-terms zero or more sub-term 1-piece tags
rejected-umbrella umbTerm, date, rescinded, notes text: the umbrella term, date of learning event, boolean, comments, An original-sub-terms block.
umbrella-into-synonyms umbTerm, date, rescinded, newKey, notes, text: the umbrella term, date of learning event, boolean, new primary kin term, comments, An optional sub-terms block and/or an optional syn-terms block.
sub-terms one or more sub-term 1-piece tags
syn-terms one or more syn-term 1-piece tags
syn-term Y value text: a kin term that is synonymous with the newKey
accepted-overlaps Y term1, date, rescinded, notes, term2 text: kin term, date of learning event, boolean, comments, a second kin term whose coverage overlaps the first term
rejected-overlap Y term1, date, rescinded, notes, term2 text: kin term, date of learning event, boolean, comments, a second kin term whose coverage overlaps the first term
NOTE: all dates are in the universal YYYY-MM-DD format.

After this may come one or two auto-def blocks. [These record any kin types that SILKin should automatically label with a kin term dictated by an accepted definition.] The auto-def tag has a single attribute 'type' that is either 'Ref' or 'Adr'.

Contents of the blocks in an auto-def block
Tag SC Attributes Data Types Encloses
kinType type text: a kin type one or more def blocks
def Y kinTerm, clause-number the kin term, an integer

NOTE: In the def block, and other places in SILKin, we refer to a kin term and clause number. The clause number always refers to the expandedDef for the kin term. An expandedDef uses only singular, gender-specific, system-defined predicates.

FOR EXAMPLE: the definition of the English kin term 'aunt' covers four kin types, but it can be expressed in only two clauses:

This compact expression of the definition is good for human display, but SILKin will always expand this for internal purposes as a four clause definition, one clause per kin type: Any reference to clause number will aways refer to the expandedDef clause.

Issues for User

Next may come zero, one or two silkin-issues blocks. [These record any suggestions or issues that have been reported to the User.] The silkin-issues tag has a single attribute 'type' that is either 'Ref' or 'Adr'. The block encloses one or more blocks of the ISSUE class. The ISSUE class has 7 subclasses generating 6 distinct tags:

  1. Anomaly: tag = anomaly
  2. ComposedDef: tag = proposed-def
  3. DataRequest: tag = data-request
  4. OverlapCandidate: tag = overlap
  5. ProposedDef: tag = proposed-def
  6. SynonymCandidate: tag = synonym
  7. UmbrellaCandidate: tag = umbrella
NOTE: Each block in these 7 subclasses has an optional final request-date block. This 2-piece tag is no longer used, but it remains a legal option for compatibility with SILK files written by earlier versions.

Contents of the blocks in the ISSUE class
Tag SC Attributes Data Types Encloses
anomaly kinTerm text: a kin term an optional processed block, a basis-type block, an anomaly-type block, an optional questions block, a basis block, a barriers block, and a misfits block.
processed boolean: true = User has dealt with this issue
basis-type text: 'definition', 'clause', or 'contradictions'
anomaly-type text: 'falsePos', 'falseNeg', or 'nearMiss'
questions one or more qn blocks
qn Y text text: a question to be presented to the User
basis either a barriers 1-piece tag, or a kin-term-def block (defined above).
barriers Y nothing. This tag is merely a flag.
misfits one or more dyad 1-piece tags (defined above).
proposed-def kinTerm text: a kin term a kin-term-def block (defined above), an optional questions block (defined above), an optional pos-dyads-uncovered block, an optional neg-dyads-covered block, an optional kin-term-eqc block.
pos-dyads-uncovered one or more dyad 1-piece tags (defined above).
neg-dyads-covered one or more dyad 1-piece tags (defined above).
kin-term-eqc a signature-string block, a prototype block, a members block, and an optional unused-clauses block.
request-date Y
data-request kinTerm text: a kin term an optional processed block (defined above), then either a kin-type-dyad block or a named-dyad block.
kin-type-dyad text: a description of the type of dyad User should find or create.
named-dyad a text string (the gloss of a kin type), followed by an ego-serial block, an alter-serial block, a pc-string block (defined above), and a clause block (defined above).
ego-serial integer: the serial number of ego
alter-serial integer: the serial number of alter
synonym kinTerm text: a kin term an optional processed block (defined above), an other-term block (defined above), a pc-strings-covered block, a kinTerm-dyads (defined above), and an other-term-dyads block (defined above).
pc-strings-covered text: a comma-separated list of kin type encodings
umbrella kinTerm text: a kin term an optional processed block (defined above), a pc-strings-covered block (defined above), and a sub-terms block.
sub-terms one or more sub-term blocks.
sub-term a sub-kin-term block, a pc-strings-covered block (defined above), a dyads-covered block, and an optional type block.
sub-kin-term text: the name of a kin term
dyads-covered one or more dyad blocks defined above.
type integer: 1 or a 2 (indicates which threshold value was used).

This the end of the ISSUES FOR USER section, which is the final (optional) section of a SILK file.

Continue to the next topic: the Contexts Folder.