Image Info

File handling and metadata management for microscopy images.

File Information and Verification

Classes for loading, validating, and managing metadata from various microscopy file formats.

verifier

File verification and image metadata handling for microscopy images.

This module provides FileInfo and ImInfo classes for loading, validating, and managing metadata from various microscopy file formats (TIFF, OME-TIFF, ND2).

FileInfo

FileInfo(filepath, output_dir=None, output_naming='detailed')

A class to handle file information, metadata extraction, and basic file operations for microscopy image files.

Attributes:

Name	Type	Description
filepath	str	Path to the input file.
metadata	dict or None	Stores the metadata extracted from the file.
metadata_type	str or None	Type of metadata detected (e.g., 'ome', 'imagej', 'nd2').
axes	str or None	String representing the axes in the file (e.g., 'TZCYX').
shape	tuple or None	Shape of the image file.
dim_res	dict or None	Dictionary of physical dimensions (X, Y, Z, T) resolution in microns or seconds.
input_dir	str	Directory of the input file.
basename	str	Filename with extension.
filename_no_ext	str	Filename without the extension.
extension	str	File extension (e.g., '.tiff', '.nd2').
output_dir	str	Output directory for processed files.
output_naming	str	Output naming strategy ("detailed" or "stable").
nellie_necessities_dir	str	Directory for internal processing data.
ome_output_path	str or None	Path for OME TIFF output.
good_dims	bool	Whether the dimensional metadata is valid.
good_axes	bool	Whether the axes metadata is valid.
ch	int	Selected channel.
t_start	int	Start timepoint for processing.
t_end	int or None	End timepoint for processing.
dtype	type or None	Data type of the image.

Methods:

Name	Description
_find_tif_metadata	Extract metadata from TIFF or OME-TIFF files.
_find_nd2_metadata	Extract metadata from ND2 files.
find_metadata	Detect file type and extract corresponding metadata.
_get_imagej_metadata	Extract dimensional resolution from ImageJ metadata.
_get_ome_metadata	Extract dimensional resolution from OME metadata.
_get_tif_tags_metadata	Extract dimensional resolution from generic TIFF tags.
_get_nd2_metadata	Extract dimensional resolution from ND2 metadata.
load_metadata	Load and validate dimensional metadata based on the file type.
_check_axes	Validate the axes metadata for correctness.
_check_dim_res	Validate the dimensional resolution metadata for correctness.
change_axes	Change the axes string and revalidate the metadata.
change_dim_res	Modify the resolution of a specific dimension.
change_selected_channel	Select a different channel in the file for processing.
select_temporal_range	Select a temporal range for processing.
_validate	Validate the current state of axes and dimension metadata.
read_file	Read the image file based on its type.
_get_output_path	Generate the output file path based on the current axes, resolution, and channel.
save_ome_tiff	Save the processed image file as an OME-TIFF file with updated metadata.

Initializes the FileInfo object and creates directories for outputs if they do not exist.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the input file.	required
output_dir	str	Directory for saving output files. Defaults to a subdirectory within the input file's directory.	None
output_naming	str	Output naming strategy ("detailed" or "stable"). Defaults to "detailed".	'detailed'

find_metadata

find_metadata()

Detects file type (e.g., TIFF or ND2) and calls the appropriate metadata extraction method.

Raises:

Type	Description
ValueError	If the file type is not supported.

load_metadata

load_metadata()

Loads and validates dimensional metadata based on the file type (OME, ImageJ, ND2, or generic TIFF).

change_axes

change_axes(new_axes)

Changes the axes string and revalidates the metadata.

Parameters:

Name	Type	Description	Default
new_axes	str	New axes string to replace the existing one.	required

change_dim_res

change_dim_res(dim, new_size)

Modifies the resolution of a specific dimension.

Parameters:

Name	Type	Description	Default
dim	str	Dimension to modify (e.g., 'X', 'Y', 'Z', 'T').	required
new_size	float	New resolution for the specified dimension.	required

change_selected_channel

change_selected_channel(ch)

Changes the selected channel for processing.

Parameters:

Name	Type	Description	Default
ch	int	Index of the new channel to select.	required

Raises:

Type	Description
ValueError	If the axes or dimension metadata are invalid.
KeyError	If no channel dimension is available.
IndexError	If the selected channel index is out of range.

select_temporal_range

select_temporal_range(start=0, end=None)

Selects a temporal range for processing.

Parameters:

Name	Type	Description	Default
start	int	Start index of the temporal range. Defaults to 0.	0
end	int	End index of the temporal range. Defaults to None, which includes all timepoints.	None

read_file

read_file()

Reads the image file into memory, supporting TIFF and ND2 formats.

Returns:

Type	Description
ndarray	Numpy array representing the image data.

Raises:

Type	Description
ValueError	If the file type is unsupported.

save_ome_tiff

save_ome_tiff()

Saves the processed image data as an OME-TIFF file, including updated metadata.

Raises:

Type	Description
ValueError	If the axes or dimensional resolution metadata is invalid.

ImInfo

ImInfo(file_info)

A class to manage image data and file outputs related to microscopy image processing.

This class handles the initialization of memory-mapped image data, creation of output paths, extraction of OME metadata, and memory allocation for various stages of an image processing pipeline.

Attributes:

Name	Type	Description
file_info	FileInfo	The FileInfo object containing metadata and file paths.
im_path	str	Path to the OME-TIFF image file.
im	ndarray	Memory-mapped image data loaded from the file.
screenshot_dir	str	Directory for saving screenshots of processed images.
graph_dir	str	Directory for saving graphs of processed data.
dim_res	dict	Dictionary storing the resolution of the image along the dimensions (X, Y, Z, T).
axes	str	Axes string representing the dimensions in the image (e.g., 'TZYX').
new_axes	str	Modified axes string if additional dimensions are added.
shape	tuple	Shape of the image data.
ome_metadata	OME	OME metadata object extracted from the image.
no_z	bool	Flag indicating if the Z dimension is absent or has a single slice.
no_t	bool	Flag indicating if the T dimension is absent or has a single timepoint.
pipeline_paths	dict	Dictionary storing output paths for different stages of the image processing pipeline.

Methods:

Name	Description
_check_axes_exist	Checks if the Z and T dimensions exist and updates the flags no_z and no_t accordingly.
create_output_path	Creates a file path for a specific stage of the image processing pipeline.
_create_output_paths	Creates all necessary output paths for various stages in the image processing pipeline.
remove_intermediates	Removes intermediate files created during the image processing pipeline, except for .csv files.
_get_ome_metadata	Extracts OME metadata from the image and updates resolution, axes, and shape information.
get_memmap	Returns a memory-mapped array for the image data from the specified file.
allocate_memory	return_memmap: bool = False, read_mode: str = 'r+') Allocates memory for new image data, saves it to the specified file, and writes updated OME metadata.

Initializes the ImInfo object, loading image data and setting up directories for screenshots and graphs.

If the OME-TIFF file does not exist, it creates one by calling save_ome_tiff() from the FileInfo class.

Parameters:

Name	Type	Description	Default
file_info	FileInfo	An instance of the FileInfo class, containing metadata and paths for the image file.	required

create_output_path

create_output_path(pipeline_path, ext='.ome.tif', for_nellie=True)

Creates a file path for a specific stage of the image processing pipeline.

Parameters:

Name	Type	Description	Default
pipeline_path	str	A descriptive string representing the stage of the image processing pipeline (e.g., 'im_preprocessed').	required
ext	str	The file extension to use (default is '.ome.tif').	'.ome.tif'
for_nellie	bool	Whether the output is for internal use by Nellie (default is True).	True

Returns:

Type	Description
str	The full file path for the given stage of the image processing pipeline.

remove_intermediates

remove_intermediates()

Removes intermediate files created during the image processing pipeline, except for CSV files.

This method loops through all pipeline paths and deletes files (except .csv files) that were created during processing. It also deletes the main image file if it exists.

get_memmap

get_memmap(file_path, read_mode='r+')

Returns a memory-mapped array for the image data from the specified file.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the image file to be memory-mapped.	required
read_mode	str	Mode for reading the memory-mapped file (default is 'r+').	'r+'

Returns:

Type	Description
ndarray	A memory-mapped numpy array representing the image data.

allocate_memory

allocate_memory(output_path, dtype='float', data=None, description='No description.', return_memmap=False, read_mode='r+')

Allocates memory for new image data or writes new data to an output file.

This method creates an empty OME-TIFF file with the specified dtype and shape, or writes the given data to the file. It also updates the OME metadata with a description and the correct pixel type.

Parameters:

Name	Type	Description	Default
output_path	str	Path to the output file.	required
dtype	str	Data type for the new image (default is 'float').	'float'
data	ndarray	Numpy array containing image data to write (default is None, which allocates empty memory).	None
description	str	Description for the OME metadata (default is 'No description.').	'No description.'
return_memmap	bool	Whether to return a memory-mapped array for the newly allocated file (default is False).	False
read_mode	str	Mode for reading the memory-mapped file if return_memmap is True (default is 'r+').	'r+'

Returns:

Type	Description
(ndarray, optional)	A memory-mapped numpy array if return_memmap is set to True.