EM workspace preparation

Before authoring an Extended Matrix project, three preparatory artifacts need to live on your file system, alongside any tooling you’ll use. They belong to the EM language itself, not to a specific tool — set them up once at the start of a new project, and iterate on them as your evidence base grows.

This page is the canonical “before you start” checklist. The full repository layout for production projects is documented in Project Organization and Workflow; this page focuses on the minimal preparation that every EM project shares, so the picker, EM Tools, yEd and Heriverse all find what they expect.

Standard folder structure

Extended Matrix expects a specific folder layout for any project workspace. A reference structure is provided as a downloadable zip — unzip it at the root of a new project to obtain the canonical tree.

Download the workspace template

EM_FolderTree_v1.5.zip — the canonical folder tree maintained in the Extended Matrix repository.

The minimal shape every EM project shares looks like this:

my_project/
├── my_project.graphml          # the EM graph (yEd / em_data.xlsx output)
├── source_list.xlsx            # the source register
├── em_data.xlsx                # optional tabular authoring companion
├── DosCo/                      # the document collection
│   ├── D.01_first_document.pdf
│   ├── D.02_aerial_photo_1972.jpg
│   └── ...
└── (additional project folders — see project_organization.rst)

The full v1.5 production layout (00_Quick_Views/, 01_Archival_Sources/, 05_Reality_Based_Data/ and so on) is the recommended structure for multi-year fieldwork. For a first project, a small replica, or a teaching exercise, the four pieces above are enough — and every EM-aware tool will work with them.

Note

Once the workspace is set up, you also need to install the Extended Matrix palette in yEd. See the mini tutorial: Set up the yEd palette.

The DosCo folder

DosCo (Dossier Comparativo / Document Collection) is a folder where you place every file that you want to elevate to the rank of document within the EM graph: PDFs, images, historical photographs, 3D models, drawings, written sources. Anything that will serve as evidence in your reconstruction.

You do not put every file you have into DosCo — only the ones you intend to cite in the graph as documents. The graph references documents from this folder by their identifier (see below). At any later moment you can elevate an additional file to document status from within EM Tools in Blender; this preparatory step simply seeds the initial collection.

Naming convention

Every file in DosCo carries a sequential identifier with the prefix D.:

DosCo/
├── D.01_first_document_label.pdf
├── D.02_aerial_photo_1972.jpg
├── D.03_excavation_drawing.dwg
└── ...

The label after the underscore is freeform — pick whatever is most informative to you. The graph references the document by its D.NN identifier, so the descriptive label is for human readability only.

Note

The D.NN identifier is the single link that propagates from the Source List to the file on disk and to the Document node in the graph. Keep the prefix stable once assigned — the rest of the filename can be renamed freely.

The `source_list.xlsx` register

Alongside the DosCo folder, keep a source_list.xlsx spreadsheet (Microsoft Excel or LibreOffice Calc, saved as .xlsx) that catalogs each document in DosCo with structured metadata: identifier, description, citation/URL, type, which properties the source can validate, and any other field your project needs.

This register is the canonical source of truth for what’s in DosCo. When you later import the sources into the graph via EM Tools (EMdb), the register is the file you point the import to.

Download the source_list.xlsx template

The current template lives in the Extended Matrix repository under 03_Sources_list. Place the file at the root of your project, next to the .graphml, and rename it source_list.xlsx.

The column schema (Name / Description / Url / Property that can validate / original id. / Type / Preview / Notes) is documented in detail in Source List schema. For a new project, the only columns you cannot skip are Name (D.NN), Description and Type — the rest can be filled in iteratively as the dossier grows.

Iterating the DosCo

The DosCo folder is not a one-off setup — it’s expected to grow and change throughout the lifetime of a project. New sources surface during fieldwork, additional documents are found in archives, an image needs to be replaced with a higher-quality scan. The source_list.xlsx register and the DosCo folder are designed to absorb these changes without forcing a workspace rebuild.

The iteration pattern

Add new files to the DosCo folder with the next sequential identifier (D.04, D.05, …). Don’t renumber existing entries — once a document has been cited in the graph as D.03, its identifier is part of the graph’s history.
Update source_list.xlsx with the new entries: identifier, title, author, license, brief description. Save.
Re-import the source list into the graph through your authoring tool. For EM Tools in Blender, this is done from the auxiliary files panel — see Loading DosCo documents into the graph in the EM Tools manual for the panel commands. The reimport is additive: new D.NN entries appear as document nodes ready to be referenced, while existing references are preserved.
Reference the new documents from the relevant stratigraphic or paradata nodes as you continue the reconstruction work.

Notes

DosCo is not bound to EM Tools. The folder + register pattern is a generic EM convention. EM Tools is one consumer; custom mappers can read the DosCo from external systems (the PyArchInit bridge is an example — see PyArchInit ↔ Extended Matrix integration).
Iteration is not blocking. You can start drawing the matrix and modelling proxies before the DosCo is “complete”. Add evidence as you go.
Avoid renaming existing files. A renamed file breaks every reference in the graph that pointed to its old identifier. If you really need to rename (e.g., an obvious typo in the descriptive label), do so via the authoring tool’s “rename document” command which propagates the change to all referring nodes; do not rename through the filesystem.

Why these three artifacts, set up now

Adopting the folder tree, the DosCo dossier and the source_list.xlsx register at the start of a project saves you from restructuring later. By the time you open Blender to start modelling, your evidence base is already organised and citable, and every tool downstream — yEd for drawing the matrix, EM Tools for connecting it to proxies, Heriverse for publishing the result — finds the files where it expects them.

The same three artifacts are also what makes an EM project shareable: zip the folder, hand it to a collaborator, and they have everything they need to open the graph and trace every document back to its source.