1. I/O

Functions to help with loading and saving data.

mbo_utilities.imwrite(lazy_array, outpath: str | Path, planes: list | tuple = None, roi: int | Sequence[int] | None = None, metadata: dict = None, overwrite: bool = True, ext: str = '.tiff', order: list | tuple = None, target_chunk_mb: int = 20, progress_callback: Callable = None, debug: bool = False)

mbo_utilities.imread(inputs: str | Path | Sequence[str | Path], **kwargs)

mbo_utilities.get_files(base_dir, str_contains='', max_depth=1, sort_ascending=True, exclude_dirs=None) → list | Path

Recursively search for files in a specified directory whose names contain a given substring, limiting the search to a maximum subdirectory depth. Optionally, the resulting list of file paths is sorted in ascending order using numeric parts of the filenames when available.

Parameters:

base_dirstr or Path

The base directory where the search begins. This path is expanded (e.g., ‘~’ is resolved) and converted to an absolute path.

str_containsstr, optional

A substring that must be present in a file’s name for it to be included in the result. If empty, all files are matched.

max_depthint, optional

The maximum number of subdirectory levels (relative to the base directory) to search. Defaults to 1. If set to 0, it is automatically reset to 1.

sort_ascendingbool, optional

If True (default), the matched file paths are sorted in ascending alphanumeric order. The sort key extracts numeric parts from filenames so that, for example, “file2” comes before “file10”.

exclude_dirsiterable of str or Path, optional

An iterable of directories to exclude from the resulting list of file paths. By default will exclude “.venv/”, “__pycache__/”, “.git” and “.github”].

Returns:

list of str

A list of full file paths (as strings) for files within the base directory (and its subdirectories up to the specified depth) that contain the provided substring.

Raises:

FileNotFoundError

If the base directory does not exist.

NotADirectoryError

If the specified base_dir is not a directory.

Examples

>>> import mbo_utilities as mbo
>>> # Get all files that contain "ops.npy" in their names by searching up to 3 levels deep:
>>> ops_files = mbo.get_files("path/to/files", "ops.npy", max_depth=3)
>>> # Get only files containing "tif" in the current directory (max_depth=1):
>>> tif_files = mbo.get_files("path/to/files", "tif")

mbo_utilities.npy_to_dask(files, name='', axis=1, astype=None)

Creates a Dask array that lazily stacks multiple .npy files along a specified axis without fully loading them into memory.

Taken from suite3d for convenience alihaydaroglu/suite3d To avoid the unnessessary import. Very nice function, thanks Ali!

Parameters:

fileslist of str or Path

A list of file paths pointing to .npy files containing array data. Each file must have the same shape except possibly along the concatenation axis.

namestr, optional

A string to be appended to a base name (“from-npy-stack-”) to label the resulting Dask array. Default is an empty string.

axisint, optional

The axis along which to stack/concatenate the arrays from the provided files. Default is 1.

astypenumpy.dtype, optional

If provided, the resulting Dask array will be cast to this data type. Otherwise, the data type is inferred from the first file.

Returns:

dask.array.Array

Examples

>>> # https://www.fastplotlib.org/
>>> import fastplotlib as fpl
>>> import mbo_utilities as mbo
>>> files = mbo.get_files("path/to/images/", 'fused', 3) # suite3D output
>>> arr = npy_to_dask(files, name="stack", axis=1)
>>> print(arr.shape)
(nz, nt, ny, nx )
>>> # Optionally, cast the array to float32
>>> arr = npy_to_dask(files, axis=1, astype=np.float32)
>>> fpl.ImageWidget(arr.transpose(1, 0, 2, 3)).show()

mbo_utilities.expand_paths(paths: str | Path | Sequence[str | Path]) → list[Path]

Expand a path, list of paths, or wildcard pattern into a sorted list of actual files.

This is a handy wrapper for loading images or data files when you’ve got a folder, some wildcards, or a mix of both.

Parameters:

pathsstr, Path, or list of (str or Path)

Can be a single path, a wildcard pattern like ‘*.tif’, a folder, or a list of those.

Returns:

list of Path

Sorted list of full paths to matching files.

Examples

>>> expand_paths("data/*.tif")
[Path('data/img_000.tif'), Path('data/img_001.tif'), ...]

>>> expand_paths(Path("data"))
[Path('data/img_000.tif'), Path('data/img_001.tif'), ...]

>>> expand_paths(["data/*.tif", Path("more_data")])
[Path('data/img_000.tif'), Path('more_data/img_050.tif'), ...]

mbo_utilities.get_mbo_dirs() → dict

Ensure ~/mbo and its subdirectories exist.

Returns a dict with paths to the root, settings, and cache directories.

mbo_utilities.load_ops(ops_input: str | Path | list[str | Path])

Simple utility load a suite2p npy file

mbo_utilities.write_ops(metadata, raw_filename)

Write metadata to an ops file alongside the given filename. metadata must contain ‘shape’ ‘pixel_resolution’, ‘frame_rate’ keys.

mbo_utilities.get_metadata(file: PathLike | str, z_step=None, verbose=False)

Extract metadata from a TIFF file produced by ScanImage or processed via the save_as function.

This function opens the given TIFF file and retrieves critical imaging parameters and acquisition details. It supports both raw ScanImage TIFFs and those modified by downstream processing. If the file contains raw ScanImage metadata, the function extracts key fields such as channel information, number of frames, field-of-view, pixel resolution, and ROI details. When verbose output is enabled, the complete metadata document is returned in addition to the parsed key values.

Parameters:

fileos.PathLike or str

The full path to the TIFF file from which metadata is to be extracted.

verbosebool, optional

If True, returns an extended metadata dictionary that includes all available ScanImage attributes. Default is False.

z_stepfloat, optional

The z-step size in microns. If provided, it will be included in the returned metadata.

Returns:

dict

A dictionary containing the extracted metadata (e.g., number of planes, frame rate, field-of-view, pixel resolution). When verbose is True, the dictionary also includes a key “all” with the full metadata from the TIFF header.

Raises:

ValueError

If no recognizable metadata is found in the TIFF file (e.g., the file is not a valid ScanImage TIFF).

Notes

• num_frames represents the number of frames per z-plane

Examples

>>> meta = get_metadata("path/to/rawscan_00001.tif")
>>> print(meta["num_frames"])
5345
>>> meta = get_metadata("path/to/assembled_data.tif")
>>> print(meta["shape"])
(14, 5345, 477, 477)
>>> meta_verbose = get_metadata("path/to/scanimage_file.tif", verbose=True)
>>> print(meta_verbose["all"])
{... Includes all ScanImage FrameData ...}