utils.file_helpers

utils.file_helpers

Attributes¶

Name	Description
`DCM2NIIX_HINT`

Classes¶

Name	Description
NiftiSeries	One series’ main NIfTI, identified from its JSON sidecar rather than any folder name.

NiftiSeries¶

utils.file_helpers.NiftiSeries(series_id, nii_path, description)

One series’ main NIfTI, identified from its JSON sidecar rather than any folder name.

Attributes¶

Name	Description
`description`
`nii_path`
`series_id`

Functions¶

Name	Description
get_all_exam_series_ids	Retrieve all exam series IDs from a specified folder.
get_all_nifti_series_ids	Retrieve all series IDs that have a NIfTI + sidecar pair, and any gaps between them.
get_exam_folder	Find a folder containing ‘Exam’ in its name within the specified base path.
get_exam_overview	Build (and optionally print) an overview of all exam series in a data folder.
get_h5_data_from_series	Find a specific .h5 file within a designated series folder.
get_latest_processing_file	Get the latest processing file for a given series ID.
get_mat_archives	List a series folder’s `ScanArchive*.mat` files, the raw archive first.
get_mat_data_from_series	Find a specific .mat file within a designated series folder.
get_nifti_data	Retrieve a NIfTI file from a folder.
get_nifti_file	Find the first NIfTI file in a folder matching the given keyword filters.
get_niftis_from_series	Find a series’ main NIfTI under a data folder, by the sidecar’s `SeriesNumber`.
index_nifti_series	Index every NIfTI series under a data folder by the `SeriesNumber` in its sidecar.
is_running_in_jupyter	Check if the code is being run within an IPython kernel (Jupyter Notebook or Console).
move_files_with_glob	Move files matching a glob pattern from a folder to a target folder.
print_hdf5_tree	Return a string containing the tree representation of the HDF5 file.

get_all_exam_series_ids¶

utils.file_helpers.get_all_exam_series_ids(exam_folder)

Retrieve all exam series IDs from a specified folder.

Scans the given folder for subdirectories whose names match the pattern “SeriesN”, where N is any number of digits, and that hold a ScanArchive*.mat. Series with only a raw .h5 archive are left out: they carry no series description to identify them by, but can still be loaded by explicit series ID.

Parameters¶

Name	Type	Description	Default
exam_folder	str or Path	The path to the folder containing the exam series.	required

Returns¶

Name	Type	Description
	list[int]	A sorted list of integers representing the series IDs.

get_all_nifti_series_ids¶

utils.file_helpers.get_all_nifti_series_ids(data_folder)

Retrieve all series IDs that have a NIfTI + sidecar pair, and any gaps between them.

Parameters¶

Name	Type	Description	Default
data_folder	str or Path	The folder holding the converted series, searched recursively.	required

Returns¶

Name	Type	Description
	tuple[list[int], list[int]]	A sorted list of the series IDs, and a list of missing series IDs, if any.

get_exam_folder¶

utils.file_helpers.get_exam_folder(base_path)

Find a folder containing ‘Exam’ in its name within the specified base path.

Parameters¶

Name	Type	Description	Default
base_path	str or Path	The base directory to search.	required

Returns¶

Name	Type	Description
	Path	The Path object to the found ‘Exam’ folder.

Raises¶

Name	Type	Description
	ValueError	If no ‘Exam’ folder is found or if multiple ‘Exam’ folders exist.

get_exam_overview¶

utils.file_helpers.get_exam_overview(data_folder, print_overview=True)

Build (and optionally print) an overview of all exam series in a data folder.

Series are found from the files, never from folder names: a NIfTI counts through the SeriesNumber in its JSON sidecar, raw data through a ScanArchive*.mat in an Exam*/SeriesN folder. A series’ description is the sidecar’s SeriesDescription when it has a NIfTI, else the .mat header’s se_desc.

Parameters¶

Name	Type	Description	Default
data_folder	str or Path	The data folder holding the converted NIfTIs and the `Exam*` folder.	required
print_overview	bool	Whether to print/display the overview. Defaults to True.	`True`

Returns¶

Name	Type	Description
	pandas.DataFrame	A DataFrame containing the overview of all exam series, indexed by series ID, with “Has Exam”, “Has NIfTI” and “Description” columns.

get_h5_data_from_series¶

utils.file_helpers.get_h5_data_from_series(
    base_folder,
    series,
    file_start='ScanArchive',
)

Find a specific .h5 file within a designated series folder.

Parameters¶

Name	Type	Description	Default
base_folder	str or Path	The base directory.	required
series	int	The series number.	required
file_start	str	The filename prefix to match. Defaults to “ScanArchive”.	`'ScanArchive'`

Returns¶

Name	Type	Description
	Path	The Path object to the first found .h5 file.

Raises¶

Name	Type	Description
	ValueError	If `base_folder` does not exist or `series` is not a positive integer.
	FileNotFoundError	If no .h5 files are found in the series folder.

get_latest_processing_file¶

utils.file_helpers.get_latest_processing_file(output_folder, series_id)

Get the latest processing file for a given series ID.

Parameters¶

Name	Type	Description	Default
output_folder	Path	The output folder where processing files are stored.	required
series_id	int	The series ID to look for.	required

Returns¶

Name	Type	Description
	Path	The path to the latest processing file.

Raises¶

Name	Type	Description
	FileNotFoundError	If no processing files are found for the given series ID.

get_mat_archives¶

utils.file_helpers.get_mat_archives(series_folder)

List a series folder’s ScanArchive*.mat files, the raw archive first.

Files derived from the archive (..._csi.mat, ..._snr_map.mat) share its name plus a suffix, so sorting by name length puts the plain archive first, and when only derived files exist, the one with the shortest suffix.

Parameters¶

Name	Type	Description	Default
series_folder	str or Path	The `SeriesN` folder inside the exam folder.	required

Returns¶

Name	Type	Description
	list[Path]	The matching files, best candidate first; empty if there are none.

get_mat_data_from_series¶

utils.file_helpers.get_mat_data_from_series(base_folder, series)

Find a specific .mat file within a designated series folder.

Parameters¶

Name	Type	Description	Default
base_folder	str or Path	The base directory.	required
series	int	The series number.	required

Returns¶

Name	Type	Description
	Path	The Path object to the first found .mat file.

Raises¶

Name	Type	Description
	ValueError	If `base_folder` does not exist or `series` is not a positive integer.
	FileNotFoundError	If no .mat files are found in the series folder.

get_nifti_data¶

utils.file_helpers.get_nifti_data(folder, **kwargs)

Retrieve a NIfTI file from a folder.

Parameters¶

Name	Type	Description	Default
folder	str \| Path	The folder path to search for NIfTI files.	required
**kwargs		Additional keyword arguments to pass to get_nifti_file().	`{}`

Returns¶

Name	Type	Description
	Path	The path to a NIfTI file found in the folder.

Raises¶

Name	Type	Description
	FileNotFoundError	If no NIfTI files are found in the folder.

Examples¶

>>> nifti_path = get_nifti_data('/path/to/series/folder')

get_nifti_file¶

utils.file_helpers.get_nifti_file(
    folder,
    filter_out_keywords=None,
    filter_in_keywords=None,
)

Find the first NIfTI file in a folder matching the given keyword filters.

Parameters¶

Name	Type	Description	Default
folder	Path	The folder to search for NIfTI files.	required
filter_out_keywords	list[str] or None	Keywords whose presence in a filename excludes it. Defaults to [“bet”, “skullstrip”, “ss”, “resampled”] when None.	`None`
filter_in_keywords	list[str] or None	Keywords a filename must contain to be included. Defaults to no filtering when None.	`None`

Returns¶

Name	Type	Description
	Path or None	The first matching NIfTI file, or None if no file matches.

get_niftis_from_series¶

utils.file_helpers.get_niftis_from_series(base_folder, series)

Find a series’ main NIfTI under a data folder, by the sidecar’s SeriesNumber.

Parameters¶

Name	Type	Description	Default
base_folder	str or Path	The data folder, searched recursively.	required
series	int	The series number.	required

Returns¶

Name	Type	Description
	Path	The Path object to the series’ NIfTI.

Raises¶

Name	Type	Description
	ValueError	If `base_folder` does not exist or `series` is not a positive integer.
	FileNotFoundError	If no NIfTI with a JSON sidecar carries this series number.

index_nifti_series¶

utils.file_helpers.index_nifti_series(data_folder)

Index every NIfTI series under a data folder by the SeriesNumber in its sidecar.

A NIfTI counts when it has a JSON sidecar of the same name carrying SeriesNumber, so derived files without one (_bet, *_resampled_*) are never picked. When a series has several such pairs (echoes, dynamics), the one with the shortest, then lowest, file name wins and a warning names it.

Parameters¶

Name	Type	Description	Default
data_folder	str or Path	The folder holding the converted series, searched recursively.	required

Returns¶

Name	Type	Description
	dict[int, NiftiSeries]	The main NIfTI of each series, sorted by series ID.

Raises¶

Name	Type	Description
	ValueError	If `data_folder` does not exist.

is_running_in_jupyter¶

utils.file_helpers.is_running_in_jupyter()

Check if the code is being run within an IPython kernel (Jupyter Notebook or Console).

move_files_with_glob¶

utils.file_helpers.move_files_with_glob(
    folder,
    file_glob,
    target_folder_name='old',
    prepend_creation_date=True,
)

Move files matching a glob pattern from a folder to a target folder.

Parameters¶

Name	Type	Description	Default
folder	str or Path	The folder to search for files.	required
file_glob	str	The glob pattern to look for (e.g. ‘*.csv’), passed directly to `Path.glob`.	required
target_folder_name	str	The name of the target folder, created inside `folder`. Defaults to “old”.	`'old'`
prepend_creation_date	bool	Whether to prepend the creation date to the filename when moving. Defaults to True.	`True`

Raises¶

Name	Type	Description
	ValueError	If the folder does not exist or is not a directory.

print_hdf5_tree¶

utils.file_helpers.print_hdf5_tree(hdf5_file, prefix='')

Return a string containing the tree representation of the HDF5 file.

Parameters¶

Name	Type	Description	Default
hdf5_file	h5py.File or h5py.Group	The HDF5 file object.	required
prefix	str	The line prefix, used for recursive indentation. Defaults to “”.	`''`

Returns¶

Name	Type	Description
	str	The full or partial tree representation of the file.