BIDS

Handle BIDS specific operations

exception heudiconv.bids.BIDSError

class heudiconv.bids.BIDSFile(entities: dict[str, str], suffix: str, extension: str | None)

as defined in https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html which might soon become machine readable order matters

classmethod parse(filename: str) → BIDSFile

Parse the filename for BIDS entities, suffix and extension

heudiconv.bids.HEUDICONV_VERSION_JSON_KEY = 'HeudiconvVersion'

JSON Key where we will embed our version in the newly produced .json files

heudiconv.bids.add_rows_to_scans_keys_file(fn: str, newrows: dict[str, list[str]]) → None

Add new rows to the _scans file.

Parameters:

• fn (str) – filename

• newrows (dict) – extra rows to add (acquisition time, referring physician, random string)

heudiconv.bids.convert_sid_bids(subject_id: str) → str

Shim for stripping any non-BIDS compliant characters within subject_id

Parameters:

subject_id (string) –

Returns:

sid – New subject ID

Return type:

string

heudiconv.bids.find_compatible_fmaps_for_run(json_file: str, fmap_groups: dict[str, list[str]], matching_parameters: list[str]) → dict[str, list[str]]

Finds compatible fmaps for a given run, for populate_intended_for. (Note: It is the responsibility of the calling function to make sure the arguments are OK)

Parameters:

• json_file (str) – path to the json file

• fmap_groups (dict) – key: prefix common to the group value: list of all fmap paths in the group

• matching_parameters (list of str from AllowedFmapParameterMatching) – matching_parameters that will be used to match runs

Returns:

compatible_fmap_groups – Subset of the fmap_groups which match json_file, according to the matching_parameters. key: prefix common to the group value: list of all fmap paths in the group

Return type:

dict

heudiconv.bids.find_compatible_fmaps_for_session(path_to_bids_session: str, matching_parameters: list[str]) → dict[str, dict[str, list[str]]] | None

Finds compatible fmaps for all non-fmap runs in a session. (Note: It is the responsibility of the calling function to make sure the arguments are OK)

Parameters:

• path_to_bids_session (str) – path to the session folder (or to the subject folder, if there are no sessions).

• matching_parameters (list of str from AllowedFmapParameterMatching) – matching_parameters that will be used to match runs

Returns:

compatible_fmap – Dict of compatible_fmaps_groups (values) for each non-fmap run (keys)

Return type:

dict

heudiconv.bids.find_fmap_groups(fmap_dir: str) → dict[str, list[str]]

Finds the different fmap groups in a fmap directory. By groups here we mean fmaps that are intended to go together (with reversed PE polarity, magnitude/phase, etc.)

Parameters:

fmap_dir (str) – path to the session folder (or to the subject folder, if there are no sessions).

Returns:

fmap_groups – key: prefix common to the group (e.g. no “dir” entity, “_phase”/”_magnitude”, …) value: list of all fmap paths in the group

Return type:

dict

heudiconv.bids.find_subj_ses(f_name: str) → tuple[str | None, str | None]

Given a path to the bids formatted filename parse out subject/session

heudiconv.bids.get_formatted_scans_key_row(dcm_fn: str | Path) → list[str]

Parameters:

dcm_fn (str) –

Returns:

row – [ISO acquisition time, performing physician name, random string]

Return type:

list

heudiconv.bids.get_key_info_for_fmap_assignment(json_file: str, matching_parameter: str) → list[Any]

Gets key information needed to assign fmaps to other modalities. (Note: It is the responsibility of the calling function to make sure the arguments are OK)

Parameters:

• json_file (str) – path to the json file

• matching_parameter (str in AllowedFmapParameterMatching) – matching_parameter that will be used to match runs

Returns:

key_info – part of the json file that will need to match between the fmap and the other image

Return type:

list

heudiconv.bids.get_shim_setting(json_file: str) → Any

Gets the “ShimSetting” field from a json_file. If no “ShimSetting” present, return error

Parameters:

json_file (str) –

Return type:

str with “ShimSetting” value

heudiconv.bids.maybe_na(val: Any) → str

Return ‘n/a’ if non-None value represented as str is not empty

Primarily for the consistent use of lower case ‘n/a’ so ‘N/A’ and ‘NA’ are also treated as ‘n/a’

heudiconv.bids.populate_aggregated_jsons(path: str) → None

Aggregate across the entire BIDS dataset .jsons into top level .jsons

Top level .json files would contain only the fields which are common to all subject[/session]/type/*_modality.jsons.

ATM aggregating only for *_task*_bold.json files. Only the task- and OPTIONAL _acq- field is retained within the aggregated filename. The other BIDS _key-value pairs are “aggregated over”.

Parameters:

path (str) – Path to the top of the BIDS dataset

heudiconv.bids.populate_bids_templates(path: str, defaults: dict[str, Any] | None = None) → None

Premake BIDS text files with templates

heudiconv.bids.populate_intended_for(path_to_bids_session: str, matching_parameters: str | list[str], criterion: str) → None

Adds the ‘IntendedFor’ field to the fmap .json files in a session folder. It goes through the session folders and for every json file, it finds compatible_fmaps: fmaps that have the same matching_parameters as the json file (e.g., same ‘Shims’).

If there are more than one compatible_fmaps, it will use the criterion specified by the user (default: ‘Closest’ in time).

Because fmaps come in groups (with reversed PE polarity, or magnitude/ phase), we work with fmap_groups.

Parameters:

• path_to_bids_session (str) – path to the session folder (or to the subject folder, if there are no sessions).

• matching_parameters (list of str from AllowedFmapParameterMatching) – matching_parameters that will be used to match runs

• criterion (str in ['First', 'Closest']) – matching_parameters that will be used to decide which of the matching fmaps to use

heudiconv.bids.sanitize_label(label: str) → str

Strips any non-BIDS compliant characters within label

Parameters:

label (string) –

Returns:

clean_label – New, sanitized label

Return type:

string

heudiconv.bids.save_scans_key(item: tuple[str, tuple[str, ...], list[str]], bids_files: list[str]) → None

Parameters:

• item –

• bids_files (list of str) –

heudiconv.bids.select_fmap_from_compatible_groups(json_file: str, compatible_fmap_groups: dict[str, list[str]], criterion: str) → str | None

Selects the fmap that will be used to correct for distortions in json_file from the compatible fmap_groups list, based on the given criterion (Note: It is the responsibility of the calling function to make sure the arguments are OK)

Parameters:

• json_file (str) – path to the json file

• compatible_fmap_groups (dict) – fmap_groups that are compatible with the specific json_file

• criterion (str in ['First', 'Closest']) – matching_parameters that will be used to decide which fmap to use

Returns:

selected_fmap_key – key from the compatible_fmap_groups for the selected fmap group

Return type:

str

heudiconv.bids.treat_age(age: str | float | None) → str | None

Age might encounter ‘Y’ suffix or be a float

heudiconv.bids.tuneup_bids_json_files(json_files: list[str]) → None

Given a list of BIDS .json files, e.g.