directus-extension-harris-matrix

directus-extension-harris-matrix is a Directus layout extension that brings graph visualisation of stratigraphy data to your archaeological database.

The Harris matrix is a tool used to depict the temporal succession of archaeological contexts and thus the sequence of depositions and surfaces on a 'dry land' archaeological site, otherwise called a 'stratigraphic sequence'. The matrix reflects the relative position and stratigraphic contacts of observable stratigraphic units, or contexts. It was developed in 1973 in Winchester, England, by Edward C. Harris.

How to install

1. Create, if not yet available, a directory named extensions in the root directory of your running Directus instance.
2. Create the directory directus-extension-harris-matrix inside the extensions directory
3. Copy inside extensions/directus-extension-harris-matrix/ the file package.json and the directory dist from this repository
4. Restart Directus and you are done!

How to model your database to record and display stratigraphy data

Database Schema Requirements

The Harris Matrix extension requires two collections in your Directus database:

1. Contexts Collection (e.g., contexts)

This is the main collection containing your archaeological contexts. Required fields:

| Field Name | Type | Description | Required | |------------|------|-------------|----------| | id | Integer | Primary key (auto-increment) | Yes | | context_id | String (varchar) | Unique context identifier (e.g., "149", "US001") | Yes | | context_type | String | Type of context (e.g., "layer", "cut", "structure") | Recommended | | description | Text | Context description | Optional | | stratigraphy | O2M Relation | One-to-Many relationship to stratigraphic_relationships | Yes |

Note: The context_id field should be unique and is used to identify contexts in the graph. The id field is the database primary key.

2. Stratigraphic Relationships Collection (e.g., stratigraphic_relationships)

Junction collection storing stratigraphic relationships between contexts:

| Field Name | Type | Description | Required | |------------|------|-------------|----------| | id | Integer | Primary key (auto-increment) | Yes | | this_context | String | Foreign key to contexts.context_id (source context) | Yes | | other_context | M2O Relation | Many-to-One relation to contexts collection (target context) | Yes | | relationship | String | Relationship type (see below) | Yes |

Supported relationship types:

• Stratigraphic above: fills, covers, cuts, leans against
• Stratigraphic below: is filled by, is covered by, is cut by, carries
• Contemporary: is the same as, is bound to

3. Directus Relationship Configuration

In Directus Data Model settings:

1. Create the stratigraphic_relationships collection with the fields above
2. In the contexts collection, add a field named stratigraphy:
   • Field Type: One to Many (O2M)
   • Related Collection: stratigraphic_relationships
   • Foreign Key Field: this_context
3. In the stratigraphic_relationships collection, configure other_context:
   • Field Type: Many to One (M2O)
   • Related Collection: contexts
   • Display Template: {{context_id}} (to show the context identifier)

Example SQL Schema (PostgreSQL)

-- Contexts table
CREATE TABLE contexts (
    id SERIAL PRIMARY KEY,
    context_id VARCHAR(255) UNIQUE NOT NULL,
    context_type VARCHAR(255),
    description TEXT,
    -- ... other fields as needed
);

-- Stratigraphic relationships table
CREATE TABLE stratigraphic_relationships (
    id SERIAL PRIMARY KEY,
    this_context VARCHAR(255) NOT NULL REFERENCES contexts(context_id),
    other_context INTEGER NOT NULL REFERENCES contexts(id),
    relationship VARCHAR(255) NOT NULL
);

Video Tutorial

Here you can find a very extensive tutorial on how to configure your directus collections to be rendered by the HMDE. Currently only in italian. We hope we'll be back with an english version ASAP

Graph Engines

The extension provides two visualization engines:

Standard Engine

• Shows all stratigraphic relationships without simplification
• Groups contemporary contexts (same as/bound to) into subgraphs with dashed blue lines
• Best for: Small to medium stratigraphic sequences where seeing all relationships is important

Carafa Engine (recommended)

• Applies transitive reduction using Graphviz's built-in algorithm to remove redundant edges
• Automatically clusters related contemporary contexts into single nodes
• Exports JSON Graph Format (JGF) data
• Best for: Large, complex archaeological sites with many relationships

The Carafa engine simplifies complex graphs by removing redundant edges (transitive reduction) and merging contemporary contexts into clusters, making large stratigraphic sequences easier to understand and visualize.

Credits

The repository is maintained by LAD and developed by Domenico Santoro and Julian Bogdani.

License

This plugins is released with the GNU Affero General Public License (AGPL) v.3.0 License. Full text is available at https://www.gnu.org/licenses/agpl-3.0.en.html.

Did you found a bug? Do you need any improvement? Please file an issue.