De-identification Profiles

A de-identification profile is an immutable set of tag-level rules plus global flags that dicom-dre applies to instance metadata. The profile you select determines which attributes the engine keeps, removes, empties, date-shifts, or re-derives, and how it redacts free-text description fields.

dicom-dre includes four profiles: default, lds, lds-no-dob, and strict. dicom_dre.profiles.builder.list_profiles() returns the authoritative list.

Profile	Preserve dates	Use case
default	No (dates shifted)	Standard full de-identification
lds	Yes	HIPAA limited data set with date/time retention
lds-no-dob	Yes, except birth date	Limited data set without patient date of birth
strict	No (dates removed)	Most aggressive; minimal retained technical metadata

dicom_dre.profiles.builder.build_profile() constructs a patient-invariant profile from a profile name and an optional dicom_dre.profiles.config.ProfileSettings (its uid_root, allowlist_csv, and hash_salt fields). Per-patient identity values (PatientID, AccessionNumber, StudyID, PatientName, the free-text description overrides, and the date jitter) are supplied at apply time via dicom_dre.parameters.DeidParameters, not to build_profile. A single profile is reusable across any number of patients. When a caller supplies a replacement PatientID, PatientName, or AccessionNumber the engine writes it verbatim. When it does not, the engine derives the replacement by hashing the original element value (SHA-256, salted with the ProfileSettings.hash_salt value and the study identifier, truncated to 16 uppercase hex characters), reusing the PatientID hash for PatientName. It falls back to [REDACTED] only when there is no value to hash. It re-derives UIDs by deterministic hashing (the UID root and the study-ID salt). It performs no identifier-mapping lookups, no settings lookups, and no network calls, so the same profile and parameters always produce the same output. See Reproducibility.

Default (full de-identification)

Profile name: default

The default profile applies DICOM PS3.15E basic de-identification with date shifting. It shifts date and datetime attributes by a per-patient jitter value (the JITTER parameter). When JITTER is not supplied, the shift is derived deterministically from the hash salt, the study identifier, and the original (PHI) PatientID, yielding a non-zero value in the range -30 to +30 days. The same patient within a study always shifts by the same amount (longitudinal consistency), while the same patient in a different study shifts differently. It shifts patient birth date, removes patient birth time, and caps patient age at 89 years (it replaces values at or above the cap with 090Y). It re-derives UIDs. It redacts free-text description fields against the allowlist, which also masks dates, times, emails, URLs, and hexadecimal numbers. See Text redaction.

Reference sequences (Referenced Series Sequence (0008,1115), Referenced Image Sequence (0008,1140), and Referenced Instance Sequence (0008,114A)) are retained rather than removed. The engine applies the tag rules recursively into the item datasets of every sequence at every depth, so a nested UID that is in the UID-hash set (for example ReferencedSOPInstanceUID or SeriesInstanceUID) is hashed while a UID that is not (for example ReferencedSOPClassUID (0008,1150) and Transfer Syntax UID) is left unchanged. Hashing is keyed on the tag, not the VR, so registered class and transfer-syntax UIDs are never hashed. Recursion into every sequence is engine behavior shared by all profiles; retaining the reference sequences (omitting them from the removal set) is a property of the default, lds, and lds-no-dob profiles.

A UID fallback catches identifier UIDs that no explicit rule covers. For a UI element with no more-specific rule, the value is hashed unless it is under the DICOM root 1.2.840.10008., which is reserved for registered values (SOP Class, Transfer Syntax, coding scheme, well-known SOP instance) and is left unchanged. The fallback uses the same UID root and study-salt policy as the explicit UID rules, so a UID that appears both under an explicit rule and an unruled tag maps to the same replacement and cross-references stay consistent. The default, lds, and lds-no-dob profiles hash with the study salt; the strict profile hashes without it.

Attribute	Action
StudyDate, SeriesDate, AcquisitionDate, ContentDate	Shifted by the jitter (JITTER, or the derived per-patient/study shift)
StudyTime, SeriesTime, AcquisitionTime, ContentTime	Kept
PatientBirthDate	Shifted by the jitter (JITTER, or the derived per-patient/study shift)
PatientBirthTime	Removed
PatientAge	Kept if under 89, otherwise replaced with 090Y
Free-text fields	Dates and times masked by the redactor

Use the default profile for standard research exports where temporal precision is not required.

LDS (limited data set)

Profile name: lds

The LDS profile produces a HIPAA limited data set. Here, “limited data set” refers to keeping dates and times, including birth dates. The profile preserves no other information that HIPAA permits in a limited data set (such as geographic data); it removes those attributes as in the default profile.

The profile keeps date, time, and datetime elements unchanged. At apply time, it inspects each element’s value representation: it skips and leaves intact elements with VR DA, DT, or TM. It keeps patient birth date. It keeps patient age without the 89-year cap. It configures the redactor with preserve_dates=True, so dates and times embedded in free-text fields are also kept.

Because the profile preserves dates, it rejects a non-zero JITTER: supplying a non-zero JITTER with lds (or any date-preserving profile) is a usage error rather than a silently ignored value. JITTER=0 requests no shift and is accepted and inert.

Attribute	Action
StudyDate, SeriesDate, AcquisitionDate, ContentDate	Kept
StudyTime, SeriesTime, AcquisitionTime, ContentTime	Kept
PatientBirthDate	Kept
PatientBirthTime	Kept
PatientAge	Kept (no 89-year cap)
Free-text fields	Dates and times preserved by the redactor

Use the LDS profile when the downstream use case requires accurate temporal information and a Data Use Agreement is in place.

LDS no DOB

Profile name: lds-no-dob

Identical to the lds profile except that it removes PatientBirthDate and PatientBirthTime instead of keeping them. These two tags are date-override tags, so the date-preservation skip does not apply to them and their removal rule runs. The profile keeps all other date, time, and datetime attributes and configures the redactor with preserve_dates=True.

Attribute	Action
StudyDate, SeriesDate, AcquisitionDate, ContentDate	Kept
StudyTime, SeriesTime, AcquisitionTime, ContentTime	Kept
PatientBirthDate	Removed
PatientBirthTime	Removed
PatientAge	Kept (no 89-year cap)
Free-text fields	Dates and times preserved by the redactor

Use this profile when the downstream use case requires temporal information but the patient date of birth must not be included in the output.

Strict

Profile name: strict

The strict profile retains the least metadata while still yielding a file that most DICOM viewers and libraries can open. It is an allow-list profile: it retains a fixed set of technical elements, re-derives UIDs (no salt), and removes every element that has no explicit rule. It always protects groups 0028 (image pixel description) and 7FE0 (pixel data), plus SOPClassUID, SOPInstanceUID, and StudyInstanceUID, from the unspecified-element removal. It removes private groups, curves, and overlays.

It removes dates entirely (neither kept nor shifted). It keeps allow-listed time attributes. It redacts free-text description fields with preserve_dates=False.

Attribute	Action
StudyTime, SeriesTime, AcquisitionTime, ContentTime	Kept
Date and datetime attributes	Removed
Free-text fields	Dates and times masked by the redactor

Key Object Selection (KO) and Presentation State (PR) objects carry no pixel data but hold clinician-curated labels. The profile designates their structured-content and graphic-annotation sequences as content roots (Content Sequence (0040,A730), Concept Name Code Sequence (0040,A043), Current Requested Procedure Evidence Sequence (0040,A375), Identical Documents Sequence (0040,A525), Referenced Request Sequence (0040,A370), Anatomic Region Sequence (0008,2218), and Graphic Annotation Sequence (0070,0001)). The PR rendering sequences that bind annotations to their images and define their geometry are also content roots (Referenced Series Sequence (0008,1115), Displayed Area Selection Sequence (0070,005A), and Graphic Layer Sequence (0070,0060)), so a viewer can render the retained annotations. Unspecified-element removal is disabled below a content root, so the coded labels and cross-object references survive, while the shared PHI-removal, date-removal, and free-text redaction rules de-identify every element inside the subtree. Referenced UIDs are hashed without the study salt, so references resolve within a single strict export but not against objects de-identified by another profile. Each DICOM cohort is processed with a single profile. The profile declares the Clean Graphics Option (113103) and the Clean Structured Content Option (113104).

Because the profile may remove required interchange elements, the output is likely not conformant to the DICOM specification. Use this profile only when the pixel data is the sole item of interest.

Text redaction

Each profile configures the redactor through its preserve_dates flag:

• default / strict: dates, times, emails, URLs, and hexadecimal numbers are masked in free-text fields.

• lds / lds-no-dob: dates and times are kept intact; emails, URLs, and hexadecimal numbers are still masked.

The allowlist CSV is a property of each profile (allowlist_csv, default default.csv). It controls which tokens may appear in free-text fields. When a caller supplies an explicit description value, the engine writes it verbatim and runs no redaction for that field. See Text redaction.

Graphic annotation subtree

The default profile admits 2D softcopy presentation states and retains their Graphic Annotation Sequence (0070,0001). The sequence is absent from the removal set, so the engine keeps it and recurses into its items like any other sequence. Because the module is fully specified (DICOM PS3.3 C.10.5), every attribute is handled by an explicit rule or by the bulk rules:

• The two free-text attributes, Unformatted Text Value (0070,0006) and Tick Label (0070,0289), are redacted against the allowlist. The redaction action decodes raw bytes and resolves the dictionary VR for an implicit-VR (UN/OB) element, so redaction is independent of encoding.

• Identifiers are hashed by the bulk rules: Tracking UID (0062,0021), Referenced SOP Instance UID (0008,1155), Series Instance UID (0020,000E), and any other UID under the UID-hash set. Tracking ID (0062,0020) is hashed with the study-scoped identifier hash, matching the study-scoped Tracking UID hash so the pair links consistently within a study.

• Referenced SOP Class UID (0008,1150) and the font names Font Name (0070,0227) and CSS Font Name (0070,0229) are kept. Graphic geometry (Graphic Data, Graphic Type) and the technical/styling attributes are kept because they carry no identity and have no removal rule.

Key Object Selection content

The default profile admits Key Object Selection (KO) documents that reference at least one instance and retains and cleans their structured content under the Clean Structured Content Option (PS3.15 code 113104). Content Sequence (0040,A730) is absent from the removal set, so the engine keeps it and recurses into its items like any other sequence:

• Text Value (0040,A160), the KO/SR free-text content attribute, is redacted against the allowlist by the same redaction action used for the graphic annotation free text.

• Referenced UIDs in Content Sequence, Current Requested Procedure Evidence Sequence (0040,A375), Identical Documents Sequence (0040,A525), and Referenced Request Sequence (0040,A370) are hashed by the bulk UID rules: Referenced SOP Instance UID (0008,1155), Series Instance UID (0020,000E), and Study Instance UID (0020,000D). Every UID is hashed with the study-scoped hash, so a de-identified KO links to the de-identified referenced objects included in the same export.

• The document title (Concept Name Code Sequence (0040,A043)) and Anatomic Region Sequence (0008,2218) are retained; their coded triples carry no identity.

• Issuer of Accession Number Sequence (0008,0051) is removed, so a retained Referenced Request Sequence cannot carry an assigning-authority identifier.

Every de-identified instance receives the De-identification Method Code Sequence (0012,0064). Each item contains a code value (0008,0100), the DCM coding scheme designator (0008,0102), and a code meaning (0008,0104). The items a profile emits follow from its configuration:

Code value	Code meaning	Emitted
113100	Basic Application Confidentiality Profile	When the profile sets emits_basic_profile (default, lds, lds-no-dob); not for strict
113101	Clean Pixel Data Option	When the pixel blanker scrubs burned-in text from the instance
113107	Retain Longitudinal Temporal Information With Modified Dates	For date-shifting profiles (default)
113106	Retain Longitudinal Temporal Information With Full Dates	For date-preserving profiles (lds, lds-no-dob)
113105	Clean Descriptors Option	Declared in deid_options (default, lds, lds-no-dob)
113108	Retain Patient Characteristics Option	Declared in deid_options (default, lds, lds-no-dob)
113103	Clean Graphics Option	Declared in deid_options (strict)
113104	Clean Structured Content Option	Declared in deid_options (default, strict)
113111	Retain Safe Private Option	When the instance retains a preserved private element (all profiles declare the same approved private-creator specs)

The temporal code is derived from the profile’s date policy: 113107 for modified dates, 113106 for full dates, and neither when dates are removed (strict). A profile emits no sequence when it declares no Basic Profile, no temporal code, no options, and no preserved private tags.

The profile leaves the existing DeIdentificationMethod (0012,0063) free-text element intact.

API reference

The profile builder and its build_profile / list_profiles entry points are documented in the API Reference.

Canonical profile builder.

Given a profile name and an optional ProfileSettings, build_profile() returns a patient-invariant DeidProfile policy object. The build configuration carries only build-time settings (UID root, allowlist CSV, and identifier-hash salt); per-patient identity values are supplied at apply() time via dicom_dre.parameters.DeidParameters.

Free-text description elements (SeriesDescription, StudyDescription, ProtocolName) follow a precedence-or-redact contract at apply time: a per-patient value is written verbatim, and when it is absent the element is redacted using the allowlist.

dicom_dre.profiles.builder.build_profile(name, settings=None)

Construct a patient-invariant DeidProfile for a named profile.

Parameters:

• name (str) – Profile name, one of "default", "lds", "lds-no-dob", or "strict".

• settings (ProfileSettings | None) – Optional build-time configuration. When omitted, the ProfileSettings defaults apply.

Returns:

A profile ready for apply(ds, params).

Raises:

ValueError – If the name is unknown.

Return type:

DeidProfile

dicom_dre.profiles.builder.list_profiles()

Return the names of all buildable profiles.

Return type:

list[str]