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.get_today()

Get today’s date in the format YYYY-MM-DD.

nipoppy.utils.is_nipoppy_project(cwd=Path.cwd())

Verify if the current directory is a nipoppy project.

This is done by checking if the .nipoppy directory exists in the current directory or any of its parents. If the directory is found, it returns the path to the .nipoppy directory. If not, it returns False.

Parameters:

cwd (nipoppy.env.StrOrPathLike, optional) – Path to directory, by default Path.cwd()

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_HPC
nipoppy.utils.DPATH_LAYOUTS
nipoppy.utils.FIELD_DESCRIPTION_MAP
nipoppy.utils.FPATH_DEFAULT_LAYOUT
nipoppy.utils.FPATH_HPC_TEMPLATE
nipoppy.utils.FPATH_SAMPLE_CONFIG
nipoppy.utils.FPATH_SAMPLE_DICOM_DIR_MAP
nipoppy.utils.FPATH_SAMPLE_MANIFEST
nipoppy.utils.TEMPLATE_PIPELINE_PATH
nipoppy.utils.TEMPLATE_REPLACE_PATTERN