De-id profile transformation reference guide

Describes what format Flywheel should expect for dates in the metadata of the file. This enables Flywheel to properly parse the date. Only use if the date fields in your data have a format that is different than the DICOM default %Y%m%d

The format interpretation follows the format codes that the 1989 C standard requires.

date-format: %m-%d

Describes what format Flywheel should expect for dates in the metadata of the file. This enables Flywheel to properly parse the date. Only use if the datetime fields in your data have a format that is different than the DICOM default %Y%m%d%H%M%S.%f”

The format interpretation follows the format codes that the 1989 C standard requires.

datetime-format: %H:%M.%S.%f

Controls how much time to offset each date or datetime field where the increment-date(true/false) or increment-datetime(true/false) transformation is chosen.

date-increment: -5

The range used to offset a value by a random number. The new value is in [-jitter-range, +jitter-range]. Use jitter-type to change the random number to an integer

Jitter-range can also be set at field level.

Default is jitter-range is 2

- name: PatientWeight
  jitter: true
  jitter-range: 10

Draws a random number from a uniform distribution set by jitter-range. You can configure the random number to be an integer (int) or a floating-point number (float). Jitter-type can also used at the field level.

Default is float.

dicom:  
  jitter-range: 10
  jitter-type: int
  fields:
     - name: PatientWeight
       jitter: true 

When set totrue, this will set the PatientAge DICOM header as a 3-digit value with a suffix indicating units.

For example an age in days would be 091D, and that same age in months would be 003M. By default, the age will be set using a best-fit approach. This means if the age fits in days, then days will be used, otherwise if it fits in months, then months will be used, otherwise years will be used

Default is false.

dicom
   patient-age-from-birthdate: true

When set in conjunction with patient-age-from-birthdate, this will act as a preference for which units to use. If the value does not fit into the desired unit, the next level of units will be used.

The most common use for this field would be to always use years as the patient age. Valid values are D, M, Y for Days, Months and Years respectively.

dicom
   patient-age-from-birthdate: true
   patient-age-units: Y

When set to true, the private DICOM tags will be removed. Private DICOM tags are any tags not included in the standard DICOM data elements

Default is false.

dicom
   remove-private-tags: true

When set to true, each element of a sequence (VR=SQ) will be processed according to the profile, recursively for all nested sequence elements. When used withremove-undefined: true setting, any sequences or sequence elements defined under fieldswill result in full sequence having de-id profile applied

Default is false (false means only the top-level field for the sequence is processed by the de-id profile)

dicom
  fields:
    - name: RequestedProcedureCodeSequence
      recurse-sequence: true
      replace-with: XXX

This is also called a "keeplist". When set to true, all data elements not defined in thefields section of the profile will be removed. If any field references a nested element in a sequence the whole sequence element will be kept. Default is false.

dicom:
  remove-private-tags: true
  remove-undefined: true
  fields:
    - name: PatientID
      replace-with: MY_PATIENT_ID
    - name: StudyInstanceUID
      hashuid: true
    - name: PatientName
      replace-with: REDACTED

If true, replace-with actions will insert the field inside record if it does not exist already and replace its value. If false, replace-with will not insert the field if it exists in the record already.

Default is true.

replace-with-insert: false
fields:
    - name: StudyTime
      replace-with: REDACTED

This file profile supports 3 ways to reference a DICOM data element: keyword, tag, or dotty-notation.

fields:
   - name: PatientName
     replace-with: REDACTED

# straight forward dicom tag with or w/o spaces
- name: (0002, 0010)

# dicom tag with no punctuation 
#no spaces must be in quotes 
- name: '00100

# dicom tag with no spaces
- name: '00100021'

# dicom tag as hexademical format
- name: '0x00100022' 

- name: (0009, "GEMS_IDEN_01", 04)

# repeating group hexadecimal example
- name: '0x60XX0022'

# repeating group no punctuation no spaces example
- name: '60XX0040'
 
# repeating group range example (old format)
- name: (6000-60FF, 0010)

# using XX to reference all elements in a range
- name: 0x50XX1001
  replace-with: REDACTED
- name: (50XX,1001)
  remove: true
- name: (60XX, 0050)
  remove: true

# nested tags (*) meaning 'for all indexes in sequence'
- name: ReferencedImageSequence.*.ReferencedSOPClassUID 
# (0008, 1140).*.(0008, 1150)

# nested tag with specific index in sequence
- name: ReferencedPerformedProcedureStepSequence.1.ReferencedSOPInstanceUID 
# (0008, 1111).1.(0008, 1155)

Replace the contents of the field with a one-way cryptographic hash in hexadecimal form. Only the first 16 characters of the hash will be used, in order to support short strings.

- name: AccessionNumber
  hash: true

Replaces a UID field with a hashed version of that field. By default, the first four nodes (prefix) and last node (suffix) will be preserved, with the middle being replaced by the hashed value.

Either of those can be applied at the field level or at the global level.

- name: AccessionNumber
  hashuid: true

Offsets the date by the number of days defined in the date-increment setting, preserving the time and timezone. If the date format does not match the DICOM default: %Y%m%d , tell Flywheel what format to expect by using the date-format setting (the date-format setting helps Flywheel parse the string.)

You can apply either of these settings at the global level as well as at the field level.

- name: StudyDate
  increment-date: true
  date-format: "%Y-%m-%d"

Offsets the date by the number of days defined in the date-increment setting of the file profile, preserving the time and timezone. If the format of the datetime fields in your data does not match the DICOM default: %Y%m%d%H%M%S.%f, tell Flywheel what format to expect by using the datetime-format setting (the datetime-format helps Flywheel parse the string.)

You can apply either of these settings at the global level as well as at the field level.

- name: AcquisitionDateTime 
  increment-datetime: true
  datetime-format: "%Y-%m-%d %H:%M:%S"

Offsets a numeric (integer or float) value by a random value drawn from a uniform distribution centered on 0. By default, Flywheel uses integers and the range [-1,1]. You can change this range with jitter-range. You can also set if the numeric value is an integer or a floating-point number with jitter-type. These can also be set at the field level or the global level.

- name: PatientWeight
  jitter: true
  jitter-range: 10
  jitter-type: float

Used when creating a keeplist using remove-undefined:true or to override global or file de-identification settings.

- name: SeriesDescription
  keep: true

Replaces the contents of the field with the value provided. Please be aware of the the length of the field being replaced because some DICOM fields only support a limited number of characters). By default, the field will be created in the Flywheel record if it does not exist. This behavior can be reversed by setting replace-with-insert: False at the profile or the field.

- name: PatientID
  replace-with: REDACTED
  replace-with-insert: False