BIDS

Handle BIDS specific operations

exception heudiconv.bids.BIDSError

class heudiconv.bids.BIDSFile(entities, suffix, extension)

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)

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, newrows)

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)

Shim for stripping any non-BIDS compliant characters within subject_id

Parameters:subject_id (string) – Returns:

• sid (string) – New subject ID
• subject_id (string) – Original subject ID

heudiconv.bids.find_compatible_fmaps_for_run(json_file, fmap_groups, matching_parameters)

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 or os.path) – 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, matching_parameters)

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 or os.path) – 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)

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 or os.path) – 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)

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

heudiconv.bids.get_formatted_scans_key_row(dcm_fn)

Parameters:item – Returns:row – [ISO acquisition time, performing physician name, random string] Return type:list

heudiconv.bids.get_key_info_for_fmap_assignment(json_file, matching_parameter)

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 or os.path) – 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:

dict

heudiconv.bids.get_shim_setting(json_file)

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

Parameters:json_file (str) – Returns: Return type:str with “ShimSetting” value

heudiconv.bids.maybe_na(val)

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)

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, defaults={})

Premake BIDS text files with templates

heudiconv.bids.populate_intended_for(path_to_bids_session, matching_parameters, criterion)

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 or os.path) – 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)

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, bids_files)

Parameters:

• item –
• bids_files (str or list) –

heudiconv.bids.select_fmap_from_compatible_groups(json_file, compatible_fmap_groups, criterion)

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 or os.path) – 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 or os.path

heudiconv.bids.treat_age(age)

Age might encounter ‘Y’ suffix or be a float

heudiconv.bids.tuneup_bids_json_files(json_files)

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