I/O Utilities#

NIfTI file loading/saving, bval/bvec handling, and filesystem helpers.

Input/Output utilities for the thesis framework.

thesis.core.io.load_nifti(file_path, as_array=True)[source]#
Overloads:

  • file_path (Union[str, Path]), as_array (Literal[True]) → np.ndarray

  • file_path (Union[str, Path]), as_array (Literal[False]) → SpatialImage

Parameters:
Return type:

ndarray | SpatialImage

Load a NIfTI image file.

Parameters:

  • file_path (Union[str, Path]) – Path to NIfTI file (.nii or .nii.gz)

  • as_array (bool) – If True, returns numpy array; if False, returns nibabel image

Returns:

Numpy array or nibabel image object

Raises:
Return type:

ndarray | SpatialImage

Example

>>> data = load_nifti("T1.nii.gz")
>>> print(data.shape)
(256, 256, 256)
thesis.core.io.save_nifti(data, file_path, affine=None, header=None)[source]#

Save data as a NIfTI image file.

Parameters:

  • data (Union[ndarray, SpatialImage]) – Numpy array or nibabel image to save

  • file_path (Union[str, Path]) – Path where to save the file

  • affine (Optional[ndarray]) – Affine transformation matrix (required if data is array)

  • header (Optional[object]) – Optional NIfTI header

Return type:

Path

Returns:

Path to saved file

Raises:

Example

>>> data = np.random.rand(64, 64, 64)
>>> affine = np.eye(4)
>>> save_nifti(data, "output.nii.gz", affine=affine)
thesis.core.io.load_bvals(file_path)[source]#

Load b-values from a text file.

Parameters:

file_path (Union[str, Path]) – Path to .bval file

Return type:

ndarray

Returns:

1D numpy array of b-values

Example

>>> bvals = load_bvals("data.bval")
>>> print(bvals.shape)
(32,)
thesis.core.io.load_bvecs(file_path)[source]#

Load b-vectors from a text file.

Parameters:

file_path (Union[str, Path]) – Path to .bvec file

Return type:

ndarray

Returns:

2D numpy array of shape (3, N) where N is number of directions

Example

>>> bvecs = load_bvecs("data.bvec")
>>> print(bvecs.shape)
(3, 32)
thesis.core.io.save_bvals(bvals, file_path)[source]#

Save b-values to a text file.

Parameters:

  • bvals (ndarray) – 1D array of b-values

  • file_path (Union[str, Path]) – Path where to save

Return type:

Path

Returns:

Path to saved file

thesis.core.io.save_bvecs(bvecs, file_path)[source]#

Save b-vectors to a text file.

Parameters:

  • bvecs (ndarray) – 2D array of shape (3, N)

  • file_path (Union[str, Path]) – Path where to save

Return type:

Path

Returns:

Path to saved file

thesis.core.io.check_file_exists(file_path, raise_error=True)[source]#

Check if a file exists.

Parameters:

  • file_path (Union[str, Path]) – Path to check

  • raise_error (bool) – If True, raises FileNotFoundError; if False, returns bool

Return type:

bool

Returns:

True if file exists, False otherwise (if raise_error=False)

Raises:

FileNotFoundError – If file doesn’t exist and raise_error=True

thesis.core.io.ensure_directory(dir_path, parents=True)[source]#

Ensure a directory exists, creating it if necessary.

Parameters:

  • dir_path (Union[str, Path]) – Directory path

  • parents (bool) – Whether to create parent directories

Return type:

Path

Returns:

Path object

Example

>>> output_dir = ensure_directory("./results/patient_001")
thesis.core.io.get_file_info(file_path)[source]#

Get information about a file.

Parameters:

file_path (Union[str, Path]) – Path to file

Return type:

dict[str, object]

Returns:

Dictionary with file information

Example

>>> info = get_file_info("data.nii.gz")
>>> print(info["size_mb"])
thesis.core.io.find_files(directory, pattern='*', recursive=False)[source]#

Find files matching a pattern in a directory.

Parameters:

  • directory (Union[str, Path]) – Directory to search

  • pattern (str) – Glob pattern to match

  • recursive (bool) – If True, search recursively

Return type:

List[Path]

Returns:

List of matching file paths

Example

>>> nii_files = find_files("./data", "*.nii.gz", recursive=True)
thesis.core.io.copy_nifti_metadata(source_path, target_data, target_path)[source]#

Copy metadata from source NIfTI to save target data.

Useful when you process an image and want to keep the same affine matrix and header information.

Parameters:

  • source_path (Union[str, Path]) – Source NIfTI file (for metadata)

  • target_data (ndarray) – New data array to save

  • target_path (Union[str, Path]) – Where to save the new file

Return type:

Path

Returns:

Path to saved file

Example

>>> processed = process_image(data)
>>> copy_nifti_metadata("input.nii.gz", processed, "output.nii.gz")