Utility¶
Utility objects and functions
-
class
heudiconv.utils.File(name: str, executable: bool = False)¶ Helper for a file entry in the create_tree/@with_tree
It allows to define additional settings for entries
-
class
heudiconv.utils.SeqInfo(total_files_till_now, example_dcm_file, series_id, dcm_dir_name, series_files, unspecified, dim1, dim2, dim3, dim4, TR, TE, protocol_name, is_motion_corrected, is_derived, patient_id, study_description, referring_physician_name, series_description, sequence_name, image_type, accession_number, patient_age, patient_sex, date, series_uid, time)¶ -
TE¶ Alias for field number 11
-
TR¶ Alias for field number 10
-
accession_number¶ Alias for field number 21
-
date¶ Alias for field number 24
-
dcm_dir_name¶ Alias for field number 3
-
dim1¶ Alias for field number 6
-
dim2¶ Alias for field number 7
-
dim3¶ Alias for field number 8
-
dim4¶ Alias for field number 9
-
example_dcm_file¶ Alias for field number 1
-
image_type¶ Alias for field number 20
-
is_derived¶ Alias for field number 14
-
is_motion_corrected¶ Alias for field number 13
-
patient_age¶ Alias for field number 22
-
patient_id¶ Alias for field number 15
-
patient_sex¶ Alias for field number 23
-
protocol_name¶ Alias for field number 12
-
referring_physician_name¶ Alias for field number 17
-
sequence_name¶ Alias for field number 19
-
series_description¶ Alias for field number 18
-
series_files¶ Alias for field number 4
-
series_id¶ Alias for field number 2
-
series_uid¶ Alias for field number 25
-
study_description¶ Alias for field number 16
-
time¶ Alias for field number 26
-
total_files_till_now¶ Alias for field number 0
-
unspecified¶ Alias for field number 5
-
-
class
heudiconv.utils.StudySessionInfo(locator, session, subject)¶ -
locator¶ Alias for field number 0
-
session¶ Alias for field number 1
-
subject¶ Alias for field number 2
-
-
class
heudiconv.utils.TempDirs¶ A helper to centralize handling and cleanup of dirs
-
heudiconv.utils.anonymize_sid(sid: AnyStr, anon_sid_cmd: str) → AnyStr¶ Raises: ValueError– if script returned an empty string (after whitespace stripping), or output with multiple words/lines.
-
heudiconv.utils.assure_no_file_exists(path: str | Path) → None¶ Check if file or symlink (git-annex?) exists, and if so – remove
-
heudiconv.utils.clear_temp_dicoms(item_dicoms: list) → None¶ Ensures DICOM temporary directories are safely cleared
-
heudiconv.utils.create_file_if_missing(filename: str, content: str) → bool¶ Create file if missing, so we do not override any possibly introduced changes
-
heudiconv.utils.create_tree(path: str, tree: Union[Sequence[Tuple[Union[str, heudiconv.utils.File], Union[str, TreeSpec, dict]]], Mapping[str, Union[str, TreeSpec, dict]]], archives_leading_dir: bool = True) → None¶ Given a list of tuples (name, load) or a dict create such a tree
if load is a tuple or a dict itself – that would create either a subtree or an archive with that content and place it into the tree if name ends with .tar.gz
-
heudiconv.utils.docstring_parameter(*sub) → collections.abc.Callable[T, T]¶ Borrowed from https://stackoverflow.com/a/10308363/6145776
-
heudiconv.utils.get_datetime(date: str, time: str, *, microseconds: bool = True) → str¶ Combine date and time from dicom to isoformat.
Parameters: - date (str) – Date in YYYYMMDD format.
- time (str) – Time in either HHMMSS.ffffff format or HHMMSS format.
- microseconds (bool, optional) – Either to include microseconds in the output
Returns: datetime_str – Combined date and time in ISO format, with microseconds as if fraction was provided in ‘time’, and ‘microseconds’ was True.
Return type: str
-
heudiconv.utils.get_known_heuristic_names() → list¶ Return a list of heuristic names present under heudiconv/heuristics
-
heudiconv.utils.get_typed_attr(obj: Any, attr: str, _type: type[T], default: Optional[V] = None) → T | V | None¶ Typecasts an object’s named attribute. If the attribute cannot be converted, the default value is returned instead.
Parameters: - obj (Object) –
- attr (Attribute) –
- _type (Type) –
- default (value, optional) –
-
heudiconv.utils.is_readonly(path: str) → bool¶ Return True if it is a fully read-only file (dereferences the symlink)
-
heudiconv.utils.json_dumps(json_obj: Any, indent: int = 2, sort_keys: bool = True) → str¶ Unified (default indent and sort_keys) invocation of json.dumps
-
heudiconv.utils.json_dumps_pretty(j: Any, indent: int = 2, sort_keys: bool = True) → str¶ Given a json structure, pretty print it by colliding numeric arrays into a line.
If resultant structure differs from original – throws exception
-
heudiconv.utils.load_heuristic(heuristic: str) → module¶ Load heuristic from the file, return the module
-
heudiconv.utils.load_json(filename: str | Path, retry: int = 0) → Any¶ Load data from a json file
Parameters: - filename (str or Path) – Filename to load data from.
- retry (int, optional) – Number of times to retry opening/loading the file in case of failure. Code will sleep for 0.1 seconds between retries. Could be used in code which is not sensitive to order effects (e.g. like populating bids templates where the last one to do it, would make sure it would be the correct/final state).
Returns: data
Return type: dict
-
heudiconv.utils.remove_prefix(s: str, pre: str) → str¶ Remove prefix from the beginning of the string
Parameters: - s (str) –
- pre (str) –
Returns: s – string with “pre” removed from the beginning (if present)
Return type: str
-
heudiconv.utils.remove_suffix(s: str, suf: str) → str¶ Remove suffix from the end of the string
Parameters: - s (str) –
- suf (str) –
Returns: s – string with “suf” removed from the end (if present)
Return type: str
-
heudiconv.utils.safe_copyfile(src: str, dest: str, overwrite: bool = False) → None¶ Copy file but blow if destination name already exists
-
heudiconv.utils.safe_movefile(src: str, dest: str, overwrite: bool = False) → None¶ Move file but blow if destination name already exists
-
heudiconv.utils.save_json(filename: str | Path, data: Any, indent: int = 2, sort_keys: bool = True, pretty: bool = False) → None¶ Save data to a json file
Parameters: - filename (str or Path) – Filename to save data in.
- data (dict) – Dictionary to save in json file.
- indent (int, optional) –
- sort_keys (bool, optional) –
- pretty (bool, optional) –
-
heudiconv.utils.set_readonly(path: str, read_only: bool = True) → int¶ Make file read only or writeable while preserving “access levels”
So if file was not readable by others, it should remain not readable by others.
Parameters: - path (str) –
- read_only (bool, optional) – If True (default) - would make it read-only. If False, would make it writeable for levels where it is readable
-
heudiconv.utils.slim_down_info(j: dict) → dict¶ Given an aggregated info structure, removes excessive details
Such as CSA fields, and SourceImageSequence which on Siemens files could be huge and not providing any additional immediately usable information. If needed, could be recovered from stored DICOMs
-
heudiconv.utils.strptime_micr(date_string: str, fmt: str) → datetime.datetime¶ Decorate strptime while supporting optional [.%f] in the format at the end
Parameters: - date_string (str) – Date string to parse
- fmt (str) – Format string. If it ends with [.%f], we keep it if date_string ends with ‘.d+’ regex and not if it does not.
-
heudiconv.utils.treat_infofile(filename: str) → None¶ Tune up generated .json file (slim down, pretty-print for humans).
-
heudiconv.utils.update_json(json_file: str | Path, new_data: dict[str, Any], pretty: bool = False) → None¶ Adds a given field (and its value) to a json file
Parameters: - json_file (str or Path) – path for the corresponding json file
- new_data (dict) – pair of “key”: “value” to add to the json file
- pretty (bool) – argument to be passed to save_json