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
AcquisitionDate & AcquisitionTime (0008,0022); (0008,0032)
AcquisitionDateTime (0008,002A);
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
- 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).
- When date and time for can be read (see
- 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
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.