Skip to content
A Python library

De-identify a DICOM cohort without touching the source files.

And hand compliance a report that names anything the run could not do.

$pip install isocenter
Read the quick start

Python 3.12 or later, on Linux or macOS. Release candidates: pip install --pre isocenter. Apache-2.0. No command-line tool: the Python API is the whole interface.

Compliance reportcompliance_report.md
Validation StatusREVIEW_REQUIRED
Total Patients14
Total Instances192
Instances Written191 of 192 requested
Privacy Profilebasic@2026c
One instance was not written. The report names it and why, and the grade will not read PASS until a person has looked. Illustrative figures.

The pipeline

Ten steps. Until export, step 9, the session writes only the store, isocenter.log and files you ask for (a configuration, a key, a report, a manifest or a cohort table), and the store holds the original identifiers. The report comes last.
In memory. The source tree is never written to. On disk, in a new directory. 1Ingest 2Examine 3Configure 4Audit 5Lock identities(optional) 6Anonymize 7Redact 8Verify 9Export 10Report

Home

The situation

You have a cohort of studies and a protocol an IRB approved. You need to hand a de-identified copy to a collaborator, a registry, or a model. You also need to hand your compliance reviewer a record: what was removed, what stayed because the protocol allowed it, and anything the run lost on the way.

Isocenter is the Python library your script imports to do that. It builds a SQLite metadata index and a pixel/waveform sidecar beside a read-only source tree, applies your de-identification profile and pixel redaction rules to an in-memory object graph, grades its own output, and writes clean copies to a new directory as DICOM or PhysioNet WFDB.

There is no command-line tool. The Python API is the whole interface, because a library that lives in your script can be paused, resumed, inspected, and audited in ways a batch command cannot.

What it refuses to do

  • Modify a source file. Ingest reads. Anonymize and redact change an in-memory graph. Until export(), the session writes only the store, isocenter.log and files you ask for (a configuration, a key, a report, a manifest or a cohort table). export() writes copies to a directory you name, so a crashed or abandoned run leaves the originals as they were. The store (<name>.db and <name>_pixels.bin) holds the original identifiers and pixels, so keep it where PHI may live.
  • Grade a lossy export PASS. Every step that can lose data writes an audit row, and the report reads those rows. A cohort that lost a file, a private tag, a waveform group, or a pixel frame grades REVIEW_REQUIRED and names the loss. An export that attempted instances and wrote none of them raises ExportError rather than returning quietly, in either format.
  • Pass through pixels it could not decode. A frame that cannot be decompressed fails its instance's export rather than being copied uninspected.
  • Advertise a Python version it does not test. The suite runs on all four supported versions, including the free-threaded 3.14t build, at every release, and 3.12 and 3.14t must pass before anything is uploaded. The PyPI classifiers list only those.

What it does

  • An object model over pydicom. Patient, Study, Series, and Instance, with attributes keyed by tag. Pixel and waveform data load lazily from the sidecar and can be released. See Architecture.
  • A persistent session. Reopen a 10,000-instance cohort without rescanning, pause and resume a job, and read the audit log of every action. See the Quick Start.
  • De-identification against the DICOM PS3.15 Annex E Basic Profile table. A profile decides which tags go, are emptied, are replaced, or are date-shifted. A field the protocol permits stays. PHI detection walks nested sequences structurally. With no configuration a 646-rule floor policy applies: the PS3.15 Annex E Basic Profile table (2026c) plus three research defaults. Study, Series, SOP Instance and the other UIDs the table names are replaced by UIDs derived from a secret kept in the store. See Configuration.
  • Machine-specific pixel redaction. Zones are keyed by device. An optional OCR pass finds where burned-in text actually lands, and CTP DicomPixelAnonymizer.script rules import directly. See Burned-in text (OCR) and Import CTP rules.
  • Reversible anonymization, if you choose it. Original identities encrypted under a Fernet key, stored in the Encrypted Attributes Sequence (0400,0500), recoverable by whoever holds the key. The export discloses when recoverable identities are present.
  • Waveforms. DICOM waveform IODs in, PhysioNet WFDB records out, with an annotation bridge to Murmur Studio. See Waveforms & WFDB.
  • A compliance report. Cohort summary, audit trail, every exception listed, a PASS or REVIEW_REQUIRED grade, and a signature block for the reviewer who accepts it. See Analytics & Reporting.

Start here

Isocenter needs Python 3.12 or later on Linux or macOS. On Windows, use WSL or a Linux container.

pip install isocenter

Release candidates: pip install --pre isocenter.

Check which version you have:

python -c "import isocenter; print(isocenter.__version__)"

Installation covers the optional OCR and NLP extras. Then the Quick Start walks the pipeline end to end: ingest, examine, configure, audit, anonymize, redact, export, report. The Configuration guide is where your protocol becomes a profile.

The Tutorials each follow one question end to end over files bundled with pydicom, and every code block in them runs in the test suite. Start with De-identify a cohort and read the grade: what PASS and REVIEW_REQUIRED mean, and what to keep so a later export matches this one.

If you used Isocenter 0.9.x, Upgrading from 0.9.x says what 1.0 does with your stores, configurations and identity tokens.

If you are evaluating Isocenter for an institution rather than running it, For institutions is the page to read: the license, the citation, and what the report gives a reviewer.

Measured, not promised

One benchmark has a recorded run behind it: 100 multi-frame files, about 50 GB raw, ingest through export, January 2026. The numbers and the machine are on the Performance page, and larger runs will appear there when they exist.

License and citation

Apache-2.0 (0.9.2 and earlier: AGPL-3.0-or-later). Each release is archived on Zenodo under the concept DOI 10.5281/zenodo.22104298, and the repository carries a CITATION.cff. If Isocenter's de-identification is part of how a dataset was prepared, it belongs in the methods section.

Bug reports and questions about documented behaviour go to GitHub Issues, in public and for free. Help beyond that, such as configuring a profile for your protocol, integrating Isocenter into a pipeline, or reviewing a run's report, is available as paid consulting: write to support@isocenter.net with what you need, and use the same address for anything that should not be public.