Quick start

This walks through a small accession flow on a synthetic sample DICOM series, so you don't need real patient data to follow along. The series is collated once, then deposited twice from the same collated copy: first in a folder store on your own disk, which needs no server, then in an XNAT project. Only the label and store subcommands change between the two, since collation doesn't depend on where the data is going.

See Concepts for what each stage does, and Command-line interface for every option.

1. Install

$ python3 -m pip install accessionflow medimages4tests

medimages4tests generates synthetic DICOM series for exactly this kind of test-drive.

2. Get some sample data

$ python3 -c "
from medimages4tests.dummy.dicom.mri.t1w.siemens.skyra.syngo_d13c import get_image
print(get_image())
"

This prints the path to a directory of DICOM files for a synthetic T1-weighted MRI scan (downloaded and cached the first time it's run). Substitute your own directory of DICOM files if you have some handy.

3. Collate

Collate the files into accessions, acquisitions and resources:

$ accessionflow collate folder /path/to/dicom/series /tmp/quickstart/collated

DICOM files are grouped into an accession per study (StudyInstanceUID) and an acquisition per series (SeriesNumber) by default. /tmp/quickstart/collated now holds one accession, in a directory named _. followed by its study's UID.

4. Deposit in a folder store

A folder store has no fixed hierarchy, so you name its levels when labelling, along with the metadata field each one is labelled from. Here the accession is filed by subject and then by the date of the study:

$ accessionflow label folder /tmp/quickstart/collated /tmp/quickstart/labelled-folder \
    --level subject PatientID --level visit StudyDate

$ accessionflow store folder /tmp/quickstart/labelled-folder /tmp/quickstart/archive

$ accessionflow check-store folder /tmp/quickstart/labelled-folder /tmp/quickstart/archive

/tmp/quickstart/archive now holds the series in a folder per label, then per acquisition and resource, with a manifest of the files' checksums:

archive/
    Session_Label/                         # subject (PatientID)
        20180525/                          # visit (StudyDate)
            2.t1_mprage_sag_p2_iso_1/      # acquisition: <SeriesNumber>.<SeriesDescription>
                DICOM/                     # resource
                    0.dcm  1.dcm  ...
                    __MANIFEST__.json

check-store folder reads every file back and reports anything missing or different. The destination could just as well be an S3 bucket (s3://my-bucket/archive) — see Folder store.

5. Deposit in XNAT

If you already have an XNAT instance and a project to upload to, skip the next command. Otherwise, xnat4tests can launch a disposable XNAT instance in a Docker container:

$ python3 -m pip install xnat4tests
$ xnat4tests start

This starts XNAT at http://localhost:8080 with the credentials admin/admin. Either way, log in to the web interface and create a project (e.g. MYPROJECT) to upload to — AccessionFlow doesn't create projects itself.

XNAT's hierarchy is fixed (project, subject and session), so label xnat has an option for each level instead of --level. The sample data doesn't populate StudyComments or AccessionNumber, the fields label xnat uses for the project and session by default, so fix the project and take the session from the StudyInstanceUID instead (see XNAT for the defaults):

$ accessionflow label xnat /tmp/quickstart/collated /tmp/quickstart/labelled-xnat \
    --constant-project-id MYPROJECT --session StudyInstanceUID

$ accessionflow store xnat /tmp/quickstart/labelled-xnat http://localhost:8080 \
    --user admin --password admin

$ accessionflow check-store xnat /tmp/quickstart/labelled-xnat http://localhost:8080 \
    --user admin --password admin

Open MYPROJECT in the XNAT web interface and you should see a new subject and session containing the uploaded scan.

Next steps

  • Deidentify — strip patient-identifying data before it is deposited

  • Orthanc — collate straight from an Orthanc server instead of a folder

  • Deployment — leave the stages running continuously