nipoppy.utils

Utility functions.

Module Contents

nipoppy.utils.add_path_suffix(path, suffix, sep='-')

Add a suffix to a path, before the last file extension (if any).

Parameters:

  • path (nipoppy.env.StrOrPathLike)

  • suffix (str)

Return type:

pathlib.Path

nipoppy.utils.add_path_timestamp(path, timestamp_format='%Y%m%d_%H%M', sep='-')

Add a timestamp to a path, before the last file extension (if any).

Parameters:

path (nipoppy.env.StrOrPathLike)

Return type:

pathlib.Path

nipoppy.utils.add_pybids_ignore_patterns(current, new)

Add pattern(s) to ignore for PyBIDS.

Parameters:
nipoppy.utils.apply_substitutions_to_json(json_obj, substitutions)

Apply substitutions to a JSON object.

Parameters:
Return type:

dict | list

nipoppy.utils.check_participant_id(participant_id, raise_error=False)

Make sure a participant ID is valid.

Specifically: - Check that it does not have the sub- prefix, stripping it if it does - Check that it only has alphanumeric characters

Parameters:

  • participant_id (Optional[str]) – The participant ID to check. If None, returns None.

  • raise_error (bool, optional) – Whether to raise an error if the participant ID has the sub- prefix, by default False. Note: an error is always raised if the participant ID contains non-alphanumeric characters after being stripped of the sub- prefix.

Returns:

The participant ID without the BIDS prefix

Return type:

str

Raises:

ValueError –

nipoppy.utils.check_session_id(session_id, raise_error=False)

Make sure a session ID is valid.

Specifically: - Check that it does not have the ses- prefix, stripping it if it does - Check that it only has alphanumeric characters

Parameters:

  • participant_id (Optional[str]) – The participant ID to check. If None, returns None.

  • raise_error (bool, optional) – Whether to raise an error if the session ID has the ses- prefix, by default False. Note: an error is always raised if the session ID contains non-alphanumeric characters even being stripped of the ses- prefix.

  • session_id (Optional[str])

Returns:

The session ID without the BIDS prefix

Return type:

str

Raises:

ValueError –

nipoppy.utils.create_bids_db(dpath_bids, dpath_pybids_db=None, validate=False, reset_database=True, ignore_patterns=None, resolve_paths=True)

Create a BIDSLayout using an indexer.

Parameters:

  • dpath_bids (nipoppy.env.StrOrPathLike)

  • dpath_pybids_db (Optional[nipoppy.env.StrOrPathLike])

  • ignore_patterns (Optional[list[str | re.Pattern] | str | re.Pattern])

Return type:

bids.BIDSLayout

nipoppy.utils.get_pipeline_tag(pipeline_name, pipeline_version, pipeline_step=None, participant_id=None, session_id=None, sep='-')

Generate a tag for a pipeline.

Parameters:

  • pipeline_name (str)

  • pipeline_version (str)

  • pipeline_step (Optional[str])

  • participant_id (Optional[str])

  • session_id (Optional[str])

nipoppy.utils.load_json(fpath, **kwargs)

Load a JSON file.

Parameters:

  • fpath (nipoppy.env.StrOrPathLike) – Path to the JSON file

  • **kwargs – Keyword arguments to pass to json.load

Returns:

The JSON object.

Return type:

dict

nipoppy.utils.participant_id_to_bids_participant_id(participant_id)

Add the BIDS prefix to a participant ID.

Parameters:

participant_id (str)

Return type:

str

nipoppy.utils.process_template_str(template_str, resolve_paths=True, objs=None, **kwargs)

Replace template strings with values from kwargs or objects.

Parameters:

template_str (str)

Return type:

str

nipoppy.utils.save_df_with_backup(df, fpath_symlink, dname_backups=None, use_relative_path=True, dry_run=False, **kwargs)

Save a dataframe as a symlink pointing to a timestamped “backup” file.

Parameters:

  • df (pd.DataFrame) – The dataframe to save

  • fpath_symlink (nipoppy.env.StrOrPathLike) – The path to the symlink

  • dname_backups (Optional[str], optional) – The directory where the timestamped backup file should be written (automatically determined if None), by default None

  • use_relative_path (bool, optional) – Use relative instead of absolute path for the symlink, by default True

  • dry_run (bool, optional) – Return the file path but do not save the file, by default False

Returns:

None if no file was saved, otherwise the path to the backup file

Return type:

Path or None

nipoppy.utils.save_json(obj, fpath, **kwargs)

Save a JSON object to a file.

Parameters:

  • obj (dict) – The JSON object

  • fpath (nipoppy.env.StrOrPathLike) – Path to the JSON file to write

  • indent (int, optional) – Indentation level, by default 4

  • **kwargs – Keyword arguments to pass to json.dump

nipoppy.utils.session_id_to_bids_session_id(session_id)

Add the BIDS prefix to a session ID.

If session_id is None, returns None.

Parameters:

session_id (Optional[str])

Return type:

str

nipoppy.utils.DPATH_DATA
nipoppy.utils.DPATH_EXAMPLES
nipoppy.utils.DPATH_LAYOUTS
nipoppy.utils.DPATH_SAMPLE_PIPELINES
nipoppy.utils.FIELD_DESCRIPTION_MAP
nipoppy.utils.FPATH_DEFAULT_LAYOUT
nipoppy.utils.FPATH_SAMPLE_CONFIG
nipoppy.utils.FPATH_SAMPLE_CONFIG_FULL
nipoppy.utils.FPATH_SAMPLE_DICOM_DIR_MAP
nipoppy.utils.FPATH_SAMPLE_MANIFEST
nipoppy.utils.TEMPLATE_REPLACE_PATTERN