HelpSet Table of Contents Back to Project Home Page

Concepts

The contents of this page is meant to clarify some of the terms we will use frequently throughout the application screens and in this documentation, as well as give a high-level overview of the application architecture.

Here are the topics we will cover:

  1. Internal Project Hirtius structures
  2. Intended scope of Project Hirtius objects
  3. Introducing the INXtree
    1. Implementation details

Internal Project Hirtius structures

These are the internal Project Hirtius structures we may collectively refer to as objects (even though our application doesn't use the object-oriented programming paradigm). There are different kinds, though, with a hierarchy between them, based on the "features" they offer.

object:
What makes a fully-fledged object is the fact that it supports all of the relationships / metadata featured by the application. These relationships or metadata are:
In addition to these, and depending of the object type, additional relationships may be available (links to events, to alternate names or titles, links between events for the purpose of relative dating, etc.).
The fully-fledged objects are:
lesser object:
By opposition with the fully-fledged objects, the lesser objects support but a subset of the relationships / metadata featured by Project Hirtius. These relationships or metadata are:
The lesser objects are:
non-object entities (metadata):
Non-object entities, then, don't support any of the relationship / metadata featured by the program (although there may exist links between two kind of non-object entities, as between articles and books). These non-object entities are either leaves in the structure (e.g. attachments), or are used to embody the relationships themselves (e.g. a bibliographical reference is a link between an object and a book/article).
The non-object entities are:

All these entities (objects, lesser objects and non-object entities) can be referenced throughout the application using their prefix and ID. This is what separates them form other Project Hirtius data structures not metioned in this list (such as Trays, Users, etc.). For more information about these prefixes and how to use them, please refer to Objects and Metadata Types and Navigation Tips.

Intended scope of Project Hirtius objects

Let's now have a look at the most important objects (or lesser objects) supported by Project Hirtius and explain what they are meant to be used for in the context of historical research. What kind of data should we store in them ?

Slide:
The Slide object is meant to store any kind of picture, in any format you can think of (physical or digital). Once the picture is stored in the application (for physical pictures, only their metadata are kept in Project Hirtius of course), the Slide record will be used to document it (using all the fields and metadata supported by the application). Linking Slides to Events allows you to track the history of the artefact being discussed.
Slide records can thus represent any physical object from the real world (buildings, works of art, archeological artefacts, human impact on the landscape, etc.) and serve as basis for their study. Clearly, multiple pictures (and hence multiple Slide records) can be necessary to document a single real world object. When this is the case, one of the Slides can be identified as the entry-point: a central record that references all others (through See also) and that most likely stores a good deal of your research on the topic. Entry points are identified in the UI by the token "♠".
Please note that in some cases, a picture can also be treated as a historical source (as may be the case for inscribed stones, manuscripts, etc.). In a case like that, I recommend to create two separate objects: one Slide record for the purpose of tracking the picture, and one Source record for the purpose of quoting this source while documenting other objects (via Source references). The second object need only be created when there is a need to create a Source ref. pointing to it. The way you split the documentation effort about the source itself (between the Slide record and the Source record) is up to you. For the Reading and Translation fields, you can even link one to the other (see the Sources Edition Page for more information).
For more information about Slide objects, please refer to the Slides Edition Page and Pictures Management Workflow.
Tray:
Trays are containers for Slides. Either physical containers for physical pictures, such as plastic cartridges for 36mm slides or photo albums for still photographs, or directory structures on your server for digital shots. In addition to their ID, Trays can be given names, so you can also use them to organise your collection by broad categories.
For suggestions on the tray management policy you might want to implement, please refer to the Pictures Management Workflow.
Please note that Trays are not objects, lesser objects or even non-object entities (as defined above), as they can't be referred to using a prefix.
Source:
Historical Sources are original documents from the period that convey some form of historical content. A typical example would be old manuscripts. It is also customary, in ancient history, to consider as sources the authors of the period (through modern editions of their texts). Ancient inscriptions (epigraphy) and even the oral tradition may be considered as well.
For published sources (such as ancient authors), it is enough to create the record that references their work (you would typically link it to a bibliographical reference for the modern edition). But for other source types, you may wish to also store a picture or scan of the original document if possible. If this picture is rather large, it would make sense to treat it as a Slide object rather than just attach it to the Source object. If you decide to create a Slide object for it, you should link both objects through the See also feature, and you may also use the include feature to store the reading and translation fields only once (see the Sources Edition Page for more details about this).
Linking Sources to Events allows you to track the history of the document being discussed.
Creating a Source record is required if you wish to quote it (through a source reference) from other objects in the database. To summarise, the Source object plays a similar role to that of the Book and Article non-object entities, since you need it simply to create source references. But the Source itself may also become an object of historical research (for instance investigating the way it has been handed down to us), which is the reason why it has been implemented as a fully-fledged object in Project Hirtius.
Event:
As the name implies, the Event objects track historical events. Events can be recorded in Project Hirtius for their own sake (as the main focus of your study, managed only at the project level), or as metadata for other objects (Slides, Sources, Individuals or Families). In the latter case, the Event help tell the story of the object in question.
Events can be further grouped in Sequences (see below).
By definition, an Event has a date (even if its value is not known at present) or a duration (as expressed through a start date and an end date) and a location. A mechanism has also been provided to date events relatively to one another (using this information to sort Event objects is work in progress).
There are two kinds of Events:
Events also have a type, to make it easier to filter them. The existing types are mostly based on the GEDCOM standard, but a few extra types have been added, in acknowledgment of the fact that Project Hirtius is a generic historical research program, and doesn't limit itself to the biography of individuals.
Sequence:
Sequences are a way to group together related Events. As an example, when researching a war that lasted for several years, you are likely to create Event objects for each battle, treaty, siege, etc. All of these can then be grouped together inside a Sequence named after the war.
An Event can be made member of as many different Sequences as necessary. Once member of a Sequence, this link can be used to navigate between all members Events. Events inside a Sequence are ordered chronologically.
Individual:
Individual objects are meant to research a person's life. By linking Events, you can recreate a detailed biography, and linking Family objects, you can connect that Individual with his/her ancestors and descendants. Combine all of this together, and you will notice that Project Hirtius offers most of the basic features of a genealogy program.
When creating a new Individual record, two linked Events are automatically created for you (these are auto-events, see above):
When researching that person's life, make sure to further edit these two events to document them as well.
Family:
A Family object represents the union between two Individuals of opposite sex (please don't read this as a moral statement of any kind: the Family object is first and foremost the database structure used to link children with their natural parents -- that is all). Future versions of the program should include a way to track adoptions and other, non blood-based parental links.
When creating a Family object, a linked Event will be created automatically for you, representing the creation of the couple. At present, this event can be of one of the two following types:
Of course, even if the creation event identified for that Family object is of type "Union", nothing prevents you from further linking a "Marriage" event if it took place at a later date.
For more information on the Individual and Family objects, please refer to the Individuals Management Workflow.
Tiddler:
Contrary to the other structures that have been described above, Tiddlers do not represent any real-life object that the historian might wish to research. Tiddlers are simply unorganised, random notes, grouped inside a project. They are meant to store any data relevant to your research that doesn't readily fit in any of the other structures. But being implemented as Project Hirtius fully-fledged objects, they still support the same metadata as all other objects.
When researching a large subject or when preparing a scholarly work, you can use Tiddlers to formulate hypothesis, develop the global plan of your work, list avenues that remain to be explored, follow-up on open questions or keep records of your field trips and progress meetings (journal entries are well suited to the latter).
Project:
Projects are really the way to bring all of your research together and make it into a coherent whole. Projects, as a data structure, are in fact little more than a name and a pointer to a particular node in the INXtree beneath which your project structure has been slowly created and all the objects born from your research attached.
For a detailed description of how to use Projects to organise your research data and then draft your final work, please refer to the Projects Management Workflow.

Introducing the INXtree

The moniker INXtree stands for index tree. It is a hierarchical structure that you should build for the purpose of organizing your Project Hirtius objects. Each node of this tree is called a Category, and it may contain further sub-nodes (or leaves) as long as the maximum depth of the tree has not been reached. You can then attach your objects (fully-fledged objects only) at any level in the tree (not only on the nodes furthest down) -- except at the root, and any given object can be attached to any number of different nodes in the tree.

You are of course free to devise for your tree any structure you like, but it may be worthwhile to keep the following principles in mind when designing it:

Even though you should take great care when designing the structure of your INXtree, don't worry: no decision is ever set in stone. It is always possible to reorganize it later on without losing any info using the Edit, Copy, Move (also called "Prune and graft") and Del action commands. All of these are described in the INXtree Browser. Some recommendations as to this design are also offered in the Pictures Management Workflow and Projects Management Workflow.

This INXtree will be one of the main entry points into your data, as it is featured prominently on the Main Application Menu. It's very nature will enable you to hunt for your data by drilling down, navigating the branches of your tree. For each node you select on this screen, all attached objects will be listed in the right-hand frame, including all those attached to the subtree below. Any duplicate entries (remember: any given object can be linked with multiple categories, so it can appear multiple times below any given node) will be automatically removed.

Implementation details

The figure below attempts to visually explain how the INXtree is built and stored in the database.


INXtree implementation

Please note that the way each node is represented in the figure above is an approximation. To make it easier to read, I've drawn the nodes as if each only contained that part of the tag that is specific to their level (e.g. '0003' for the Egypt node). In fact, the 'tag' column in the database does contain the entire "path" leading to the node as well. Meaning that in our example, the value for the 'tag' column of the Egypt node would indeed contain '000200010003'.

See also:

Project Hirtius, © Les Ateliers du Héron, 2012.
Last updated: Friday, Jul. 31, 2020.

HelpSet Table of Contents Back to Project Home Page