Reproducibility

dicom-dre is reproducible by design. The engine makes no network calls, consults no external mapping tables, and draws no random values. Given the same input DICOM and the same parameters, it produces byte-for-byte identical output. Every value the engine writes is either copied verbatim from a parameter or computed by a pure function of the input and the parameters. The hashed identifiers and UIDs, the date shift, and free-text redaction are all computed this way.

What the caller supplies

The caller may supply already-mapped replacement values; when it omits them the engine derives them deterministically rather than looking them up:

  • The engine writes caller-supplied replacement identifiers (patient ID, patient name, accession number) verbatim. When the caller omits one, the engine derives the replacement by hashing the original element value, a pure function of that value, the ProfileSettings.hash_salt value, and the study identifier.

  • UID re-derivation is a pure function of the UID root and salt passed in; the same source UID plus the same root and salt always yields the same output UID.

  • Date shifting uses the caller-supplied jitter value when provided. When it is omitted, the shift is a pure function of the hash salt, the study identifier, and the original PatientID, so it is deterministic rather than a random draw.

  • The engine writes free-text description values verbatim when the caller provides them; when the caller omits them, redaction is a pure function of the field content and the allowlist.

The identifier-hash salt is itself a parameter. The dicom-dre CLI can generate and persist one on first use (a one-time random draw), but reusing that saved salt keeps every subsequent run reproducible. This keeps identifier mapping, salt management, and any cross-study consistency under the caller’s control rather than hidden inside the engine. See De-identification Profiles and Text redaction.

Cross-object linkage

A retained presentation state and the images it references align only when both are processed with the same study_id on DeidParameters. UID re-derivation salts each UID with the study identifier (use_study_salt=True), and the identifier hash applied to Tracking ID salts with the same study identifier. Processing every instance of a study with one STUDY_ID parameter therefore yields matching hashed references between the presentation state and its referenced images. Processing them under different study identifiers breaks the linkage.

The same requirement governs Key Object Selection (KO) documents. A KO’s referenced UIDs (Referenced SOP Instance UID (0008,1155), Series Instance UID (0020,000E), Study Instance UID (0020,000D)) are hashed with the study identifier, so a de-identified KO links to a referenced object only when both are processed with the same study_id. Under the per-recipient assignment, every object in one recipient’s export is de-identified with the same study_id, so a KO reference resolves when its target is included in the same export and dangles when the target is excluded.

Regression guard

A regression test suite built from sampled DICOM studies guards reproducibility. Each fixture records the technical matching tags and the expected catalog filtering and pixel-scrub decisions, with no PHI or pixel data. The tests assert that the engine still reaches the recorded decision for every case. This suite catches catalog or profile changes that alter existing outcomes. See Testing and Local validation.