Building tools/data model

The directory structure xnat_ingest reads and writes at every pipeline stage is deliberately plain and human-readable, rather than a database or opaque intermediate format:

<project>.<subject>.<session>/
    __METADATA__.json                  # session-level metadata
    <scan_id>.<scan_type>/
        __METADATA__.json              # scan-level metadata
        <resource_name>/
            __METADATA__.json          # resource-level metadata
            __MANIFEST__.json          # checksums + datatype
            <data files>

Nothing stops you from reading these JSON files directly, but the model classes give you a typed, correct way to work with the same structure — handling checksums, deidentification, and staging consistently with the rest of the pipeline:

• ImagingSession — a whole session: its project/subject/session IDs, scans, session-level resources, and metadata. Load an existing one from disk with ImagingSession.load, or build one from scratch with ImagingSession.from_paths.

• ImagingScan — one scan within a session, and the resources attached to it.

• ImagingResource — one resource: a FileSet, its checksums, and its metadata.

A minimal example of a custom script that loads a staged session and inspects it:

from xnat_ingest.model.session import ImagingSession

session = ImagingSession.load("/data/staging/assigned/MYPROJECT.subject1.1")

print(session.project_id, session.subject_id, session.session_id)
for scan_id, scan in session.scans.items():
    print(scan_id, scan.type, list(scan.resources))
    print(scan.metadata.get("SeriesDescription"))

The API functions that back each CLI sub-command (group, assign, deidentify, upload, associate, ...) are themselves just plain Python functions built on these model classes, so they're usable directly from a script without going through the CLI at all if that's a better fit for what you're building.