BIDS¶
Handle BIDS specific operations
-
exception
heudiconv.bids.
BIDSError
¶
-
class
heudiconv.bids.
BIDSFile
(entities: dict, suffix: str, extension: Optional[str])¶ 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) → heudiconv.bids.BIDSFile¶ Parse the filename for BIDS entities, suffix and extension
-
classmethod
-
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) → 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, matching_parameters: list) → dict¶ 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) → Optional[dict]¶ 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¶ 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¶ 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¶ 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) – Returns: 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
.json
s into top level.json
sTop level .json files would contain only the fields which are common to all
subject[/session]/type/*_modality.json
s.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: Optional[dict] = 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, bids_files: list) → None¶ Parameters: - item –
- bids_files (list of str) –
-
heudiconv.bids.
select_fmap_from_compatible_groups
(json_file: str, compatible_fmap_groups: dict, criterion: str) → Optional[str]¶ 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) → None¶ Given a list of BIDS .json files, e.g.