docs: create crawl file documentation

[jjjermiah]

Warning

** this is a chatgpt generated doc from katy's dictionary**

DICOM Metadata Dictionary Explanation

This document describes the metadata schema used for organizing DICOM (Digital Imaging and Communications in Medicine) files. The schema is represented in a table that maps various metadata fields to their corresponding descriptions and DICOM-specific values. It serves as a guide for interpreting the data stored in DICOM files.

---

Metadata Fields and Their Descriptions

Patient Information

• patient_ID:
  Anonymous identifier for a patient. This corresponds to the DICOM tag PatientID.

---

Study-Level Information

• study:
  The unique identifier for a study. Multiple series may belong to the same study.
  DICOM Value: StudyInstanceUID

• study_description:
  Descriptive information about the study. This field is left blank if the information is not available in the DICOM file.
  DICOM Value: StudyDescription

---

Series-Level Information

• series:
  Unique identifier for a series. Each image has a unique series ID, but slices within the same CT/MR image share this ID.
  DICOM Value: SeriesInstanceUID

• series_description:
  Descriptive information about the series. This field is left blank if not found.
  DICOM Value: SeriesDescription

• subseries:
  Defaults to a standard value if the DICOM file does not provide this information.
  DICOM Value: AcquisitionNumber

• modality:
  Specifies the type of image (e.g., CT, MRI, PET, RTSTRUCT, etc.).
  DICOM Value: Modality

• instances:
  The number of DICOM files associated with the same patient_ID, study, and series. This value is computed by storing paths to each DICOM file in a dictionary and then counting its length.

---

File-Level Information

• instance_uid:
  Unique identifier for an individual file instance.
  DICOM Value: SOPInstanceUID

---

Reference Information

• reference_ct:
  Series ID of the CT referenced by a segmentation or RTSTRUCT. The reference is derived from one of the following DICOM values:

  • RTSTRUCT: ReferencedFrameOfReferenceSequence[0].RTReferencedStudySequence[0].RTReferencedSeriesSequence[0].SeriesInstanceUID
  • DICOM-SEG: ReferencedSeriesSequence[0].SeriesInstanceUID
  • meta.ReferencedImageSequence[0].ReferencedSOPInstanceUID

• reference_rs:
  Series ID for the RTSTRUCT file that corresponds to a segmentation.
  DICOM Value: ReferencedStructureSetSequence[0].ReferencedSOPInstanceUID

• reference_pl:
  Series ID for the RT Plan associated with this DICOM file.
  DICOM Value: ReferencedRTPlanSequence[0].ReferencedSOPInstanceUID

• reference_frame:
  Unique identifier for the first slice in the CT or the CT referenced by a segmentation.
  DICOM Value:

  • FrameOfReferenceUID
  • ReferencedFrameOfReferenceSequence[0].FrameOfReferenceUID

---

File Location Information

• folder:
  Relative path to the directory containing the DICOM files. This is computed based on the directory from which the pipeline or script is executed.

• file_path:
  Relative path to an individual DICOM file from the directory where the script is executed.

---

Orientation Information

• orientation:
  Information about the patient’s orientation relative to the image acquisition system.
  DICOM Value: ImageOrientationPatient

• orientation_type:
  Anatomical orientation of the patient in the DICOM image.
  DICOM Value: AnatomicalOrientationType

---

MRI-Specific Parameters

• MR_repetition_time:
  The time interval between successive pulse sequences in MRI.
  DICOM Value: RepetitionTime

• MR_echo_time:
  The time between the application of the radiofrequency pulse and the peak of the echo signal in MRI.
  DICOM Value: EchoTime

• MR_scan_sequence:
  Describes the sequence of radiofrequency and gradient pulses used in MRI.
  DICOM Value: ScanningSequence

• MR_magnetic_field_strength:
  The strength of the magnetic field used during the MRI scan.
  DICOM Value: MagneticFieldStrength

• MR_imaged_nucleus:
  The nucleus targeted for imaging in MRI, typically hydrogen (protons).
  DICOM Value: ImagedNucleus

---

Notes

1. Fields without direct DICOM mappings, such as instances and folder, are computed or assigned by the processing software (e.g., MIT or an autopipeline).
2. reference_ct, reference_rs, and reference_frame may have multiple DICOM value mappings depending on the modality or specific DICOM file type.

---

This dictionary serves as a comprehensive schema for extracting, organizing, and interpreting DICOM metadata in medical imaging workflows.