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, custom)¶

TE: float¶: Alias for field number 11

TR: float¶: Alias for field number 10

accession_number: str¶: Alias for field number 21

custom: Hashable | None¶: Alias for field number 27

date: str | None¶: Alias for field number 24

dcm_dir_name: str¶: Alias for field number 3

dim1: int¶: Alias for field number 6

dim2: int¶: Alias for field number 7

dim3: int¶: Alias for field number 8

dim4: int¶: Alias for field number 9

example_dcm_file: str¶: Alias for field number 1

image_type: tuple[str, ...]¶: Alias for field number 20

is_derived: bool¶: Alias for field number 14

is_motion_corrected: bool¶: Alias for field number 13

patient_age: str | None¶: Alias for field number 22

patient_id: str | None¶: Alias for field number 15

patient_sex: str | None¶: Alias for field number 23

protocol_name: str¶: Alias for field number 12

referring_physician_name: str¶: Alias for field number 17

sequence_name: str¶: Alias for field number 19

series_description: str¶: Alias for field number 18

series_files: int¶: Alias for field number 4

series_id: str¶: Alias for field number 2

series_uid: str | None¶: Alias for field number 25

study_description: str¶: Alias for field number 16

time: str | None¶: Alias for field number 26

total_files_till_now: int¶: Alias for field number 0

unspecified: str¶: Alias for field number 5

class heudiconv.utils.StudySessionInfo(locator, session, subject)¶

locator: str | None¶: Alias for field number 0

session: str | None¶: Alias for field number 1

subject: str | None¶: 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[str]) → None¶: Ensures DICOM temporary directories are safely cleared

heudiconv.utils.create_file_if_missing(filename: str, content: str, glob_suffixes: list[str] | None = None) → bool¶

Create file if missing, so we do not override any possibly introduced changes.

Note: if glob_suffixes list is used, and it is desired also to allow for original filename to ‘match’, add an empty string within glob_suffixes.

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.datetime_utc_offset(datetime_obj: datetime, utc_offset: str) → datetime¶: set the datetime’s tzinfo by parsing an utc offset string

heudiconv.utils.docstring_parameter(*sub: str) → 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[str]¶: Return a list of heuristic names present under heudiconv/heuristics

heudiconv.utils.get_typed_attr(obj: Any, attr: str, _type: type[T], default: V) → T | V¶

heudiconv.utils.get_typed_attr(obj: Any, attr: str, _type: type[T], default: None = None) → T | 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) → ModuleType¶: 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.sanitize_path(path: str, descr: str = 'path') → str¶

Sanitize a path by replacing multiple consecutive unwanted characters with _.

Due to https://github.com/nipy/nipype/issues/3604 we would like to avoid spaces in the paths, or any special characters which could cause special treatment in the shell, e.g. characters like ; or & serving as command separators.

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[str, Any]) → dict[str, Any]¶

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(datetime_string: str, fmts: list[str]) → datetime¶

Try datetime.strptime on a list of formats returning the first successful attempt.

Parameters:

datetime_string (str) – Datetime string to parse
fmts (list[str]) – List of format strings

heudiconv.utils.strptime_bids(datetime_string: str) → datetime¶

Create a datetime object from a bids datetime string.

Parameters:: date_string (str) – Datetime string to parse

heudiconv.utils.strptime_dcm_da_tm(dcm_data: dcm.Dataset, da_tag: TagType, tm_tag: TagType) → datetime.datetime¶

Create a datetime object from a dicom DA tag and TM tag.

Parameters:

dcm_data (dcm.Dataset) – DICOM with header, e.g., as read by pydicom.dcmread.
da_tag (str) – Dicom tag with DA value representation
tm_tag (str) – Dicom tag with TM value representation

heudiconv.utils.strptime_dcm_dt(dcm_data: dcm.Dataset, dt_tag: TagType) → datetime.datetime¶

Create a datetime object from a dicom DT tag.

Parameters:

dcm_data (dcm.FileDataset) – DICOM with header, e.g., as read by pydicom.dcmread. Objects with __getitem__ and have those keys with values properly formatted may also work
da_tag (str) – Dicom tag with DT value representation

heudiconv.utils.strptime_micr(date_string: str, fmt: str) → 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

Utility¶

heudiconv

Navigation

Related Topics