I/O

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)[source]#

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

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

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)[source]#

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][source]#

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[source]#

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])[source]#: Simple utility load a suite2p npy file

mbo_utilities.write_ops(metadata, raw_filename)[source]#: 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)[source]#

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 ...}

I/O

Contents

1. I/O#