DICOMS

class heudiconv.dicoms.CustomSeqinfoT(*args, **kwargs)
class heudiconv.dicoms.SeriesID(series_number, protocol_name, file_studyUID)
file_studyUID: str | None

Alias for field number 2

protocol_name: str

Alias for field number 1

series_number: int

Alias for field number 0

heudiconv.dicoms.compress_dicoms(dicom_list: list[str], out_prefix: str, tempdirs: TempDirs, overwrite: bool) str | None

Archives DICOMs into a tarball

Also tries to do it reproducibly, so takes the date for files and target tarball based on the series time (within the first file)

Parameters:
  • dicom_list (list of str) – list of dicom files

  • out_prefix (str) – output path prefix, including the portion of the output file name before .dicom.tgz suffix

  • tempdirs (TempDirs) – TempDirs object to handle multiple tmpdirs

  • overwrite (bool) – Overwrite existing tarfiles

Returns:

filename – Result tarball

Return type:

str

heudiconv.dicoms.create_seqinfo(mw: dw.Wrapper, series_files: list[str], series_id: str, custom_seqinfo: CustomSeqinfoT | None = None) SeqInfo

Generate sequence info

Parameters:
  • mw (Wrapper) –

  • series_files (list) –

  • series_id (str) –

heudiconv.dicoms.embed_dicom_and_nifti_metadata(dcmfiles: List[str], niftifile: str, infofile: str | Path, bids_info: Dict[str, Any] | None) None

Embed metadata from nifti (affine etc) and dicoms into infofile (json)

niftifile should exist. Its affine’s orientation information is used while establishing new NiftiImage out of dicom stack and together with bids_info (if provided) is dumped into json infofile

Parameters:
  • dcmfiles

  • niftifile

  • infofile

  • bids_info (dict) – Additional metadata to be embedded. infofile is overwritten if exists, so here you could pass some metadata which would overload (at the first level of the dict structure, no recursive fancy updates) what is obtained from nifti and dicoms

heudiconv.dicoms.embed_metadata_from_dicoms(bids_options: str | None, item_dicoms: list[str], outname: str, outname_bids: str, prov_file: str | None, scaninfo: str, tempdirs: TempDirs, with_prov: bool) None

Enhance sidecar information file with more information from DICOMs

Parameters:
  • bids_options

  • item_dicoms

  • outname

  • outname_bids

  • prov_file

  • scaninfo

  • tempdirs

  • with_prov

heudiconv.dicoms.get_datetime_from_dcm(dcm_data: FileDataset) datetime | None

Extract datetime from filedataset, or return None is no datetime information found.

Parameters:

dcm_data (dcm.FileDataset) – DICOM with header, e.g., as ready by pydicom.dcmread. Objects with __getitem__ and have those keys with values properly formatted may also work

Returns:

One of several datetimes that are related to when the scan occurred, or None if no datetime can be found

Return type:

Optional[datetime.datetime]

Notes

The following fields are checked in order

  1. AcquisitionDate & AcquisitionTime (0008,0022); (0008,0032)

  2. AcquisitionDateTime (0008,002A);

  3. SeriesDate & SeriesTime (0008,0021); (0008,0031)

heudiconv.dicoms.get_reproducible_int(dicom_list: list[str]) int

Get integer that can be used to reproducibly sort input DICOMs, which is based on when they were acquired.

Parameters:

dicom_list (list[str]) – Paths to existing DICOM files

Returns:

An integer relating to when the DICOM was acquired

Return type:

int

Raises:

AssertionError

Notes

  1. When date and time for can be read (see get_datetime_from_dcm()), return

    that value as time in seconds since epoch (i.e., Jan 1 1970).

  2. In cases where a date/time/datetime is not available (e.g., anonymization stripped this info), return

    epoch + AcquisitionNumber (in seconds), which is AcquisitionNumber as an integer

  3. If 1 and 2 are not possible, then raise AssertionError and provide message about missing information

Cases are based on only the first element of the dicom_list.

heudiconv.dicoms.group_dicoms_into_seqinfos(files: list[str], grouping: str, file_filter: Callable[[str], Any] | None = None, dcmfilter: Callable[[Dataset], Any] | None = None, flatten: Literal[False] = False, custom_grouping: str | Callable[[list[str], Callable[[dcm.dataset.Dataset], Any] | None, type[SeqInfo]], dict[SeqInfo, list[str]]] | None = None, custom_seqinfo: CustomSeqinfoT | None = None) dict[str | None, dict[SeqInfo, list[str]]]
heudiconv.dicoms.group_dicoms_into_seqinfos(files: list[str], grouping: str, file_filter: Callable[[str], Any] | None = None, dcmfilter: Callable[[Dataset], Any] | None = None, *, flatten: Literal[True], custom_grouping: str | Callable[[list[str], Callable[[dcm.dataset.Dataset], Any] | None, type[SeqInfo]], dict[SeqInfo, list[str]]] | None = None, custom_seqinfo: CustomSeqinfoT | None = None) dict[SeqInfo, list[str]]

Process list of dicoms and return seqinfo and file group seqinfo contains per-sequence extract of fields from DICOMs which will be later provided into heuristics to decide on filenames

Parameters:
  • files (list of str) – List of files to consider

  • grouping ({'studyUID', 'accession_number', 'all', 'custom'}) – How to group DICOMs for conversion. If ‘custom’, see custom_grouping parameter.

  • file_filter (callable, optional) – Applied to each item of filenames. Should return True if file needs to be kept, False otherwise.

  • dcmfilter (callable, optional) – If called on dcm_data and returns True, it is used to set series_id

  • flatten (bool, optional) – Creates a flattened seqinfo with corresponding DICOM files. True when invoked with dicom_dir_template.

  • custom_grouping (str or callable, optional) – grouping key defined within heuristic. Can be a string of a DICOM attribute, or a method that handles more complex groupings.

  • custom_seqinfo (callable, optional) – A callable which will be provided MosaicWrapper giving possibility to extract any custom DICOM metadata of interest.

Returns:

  • seqinfo (list of list) – seqinfo is a list of info entries per each sequence (some entry there defines a key for filegrp)

  • filegrp (dict) – filegrp is a dictionary with files grouped per each sequence

heudiconv.dicoms.parse_private_csa_header(dcm_data: Dataset, _public_attr: str, private_attr: str, default: str | None = None) str

Parses CSA header in cases where value is not defined publicly

Parameters:
  • dcm_data (pydicom Dataset object) – DICOM metadata

  • public_attr (string) – non-private DICOM attribute

  • private_attr (string) – private DICOM attribute

  • (optional) (default) – default value if private_attr not found

Returns:

val (default – private attribute value or default

Return type:

empty string)

heudiconv.dicoms.validate_dicom(fl: str, dcmfilter: Callable[[Dataset], Any] | None) tuple[Wrapper, tuple[int, str], str | None] | None

Parse DICOM attributes. Returns None if not valid.