2. Utility

Functions used by the pipeline that users can take advantage of to further process LBM datasets.

2.1. Readers

read_h5_metadata(h5_fullfile, loc)

Reads metadata from an HDF5 file.

Reads the metadata attributes from a specified location within an HDF5 file and returns them as a structured array.

Parameters:

h5_fullfilechar

Full path to the HDF5 file from which to read metadata.

locchar, optional

Location within the HDF5 file from which to read attributes. Defaults to ‘/’.

Returns:

metadatastruct

A structured array containing the metadata attributes and their values read from the HDF5 file.

Notes

The function uses h5info to retrieve information about the specified location within the HDF5 file and h5readatt to read attribute values. The attribute names are converted to valid MATLAB field names using matlab.lang.makeValidName.

Examples

Read metadata from the root location of an HDF5 file:

metadata = read_h5_metadata(‘example.h5’);

Read metadata from a specific group within an HDF5 file:

metadata = read_h5_metadata(‘example.h5’, ‘/group1’);

read_plane(path, ds, varargin)

Read a specific plane from an HDF5 or MAT file and return the data. If input is a MAT file, a matfile object is returned.

Parameters:

pathstr, optional

Path to the HDF5 or MAT file or the directory containing plane files. If empty, a file selection dialog will open.

dsstr, optional

Dataset group name within the HDF5 file. If empty, the function will attempt to find a valid dataset or prompt the user.

planeint, optional

Plane number to read from the file. User is prompted if not given.

framesstr or int, optional

Frames to read from the dataset. Can be ‘all’, a scalar frame number i.e. 2, a slice i.e. 1:400, vector of size 2 with the start and stop index i.e. [5 400]. Default is ‘all’.

Returns:

Y_outarray-like or MAT-file object

The data read from the specified plane and frames in the file.

Notes

This function interactively prompts the user for input if any required parameter is not provided. It handles various errors and prompts the user again for correct input.

Examples

Use dialog and prompts only:

Y_out = read_plane();

Read all frames from a file givin the full filepath:

Y_out = read_plane(‘data.h5’);

Use plane argument to read from a folder of files with _plane_ in the name:

Y_out = read_plane(‘C:/data/extracted_files’, ‘plane’, 4);

Read specific frames from a dataset in a folder:

Y_out = read_plane(‘data.h5’, 4, ‘all’);

Read specific frames from a dataset in a file:

Y_out = read_plane(‘path/to/file.h5’, ‘/Y’, [], 1:10);

get_metadata(filename)

Extract metadata from a ScanImage TIFF file.

Read and parse Tiff metadata stored in the .tiff header and ScanImage metadata stored in the ‘Artist’ tag which contains roi sizes/locations and scanning configuration details in a JSON format.

Parameters:

filenamechar

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

Returns:

metadata_outstruct

A struct containing metadata such as center and size of the scan field, pixel resolution, image dimensions, number of frames, frame rate, and additional roi data extracted from the TIFF file.

Examples

metadata = get_metadata(“path/to/file.tif”);

2.2. Writers

write_frames_2d(filename, data, dataset_name, overwrite, append)

get the size of the data

write_frames_3d(file, Y_in, ds, append, chunk_mb)

Write in-memory 3D or 4D data to an HDF5 file in chunks.

This function writes a multidimensional array Y_in to an HDF5 file specified by file in chunks. It creates a dataset within the HDF5 file and writes the data in specified chunk sizes. If dataset_name is not provided, it defaults to ‘/Y’. If target_chunk_mb size is not provided, it defaults to 4MB.

Parameters:

filechar

The name of the HDF5 file to write to.

Y_inarray

The multidimensional array to be written to the HDF5 file.

dschar, optional

The name of the dataset group within the HDF5 file. Default is ‘/Y’.

appendlogical, optional

Whether to append to an existing HDF5 dataset. Dims must match. Default is false.

chunk_mbint, optional

In MB, the chunk_size to include in each HDF5 write. Default is 4MB.

Notes

This function trims the last frame of each chunk if the chunk size exceeds the remaining data size.

Examples

Write a 3D array to an HDF5 file with default chunk size and dataset name:

write_frames(‘data.h5’, my_data);

Write a 4D array to an HDF5 file with a specified chunk size:

write_frames(‘data.h5’, my_data, 2); % 2MB chunks

Write a 3D array to an HDF5 file with a specified dataset name:

write_frames(‘data.h5’, my_data, ‘/Y’, 2, true, false);

write_frames_to_avi(data, filename, frame_rate, x, y)

Write a 3D array to an AVI video file.

This function takes a 3D numeric array data and writes it to an AVI video file specified by filename. The video is created with the specified frame rate and spatial dimensions x and y.

Parameters:

datanumeric array

A 3D array containing the data to be written to the video file.

filenamechar

The name of the output AVI video file.

frame_ratedouble, optional

The frame rate of the video. Default is 1.

xdouble array, optional

The x-coordinates for the spatial dimensions of the data. Default is 1:size(data,2).

ydouble array, optional

The y-coordinates for the spatial dimensions of the data. Default is 1:size(data,1).

Notes

The function normalizes the data, applies a moving mean filter, and writes the frames to an uncompressed AVI video file. It also sets up the figure properties for visualization and adjusts the color axis limits.

Examples

Write a 3D array to an AVI file with default settings:

write_frames_to_avi(my_data, ‘output.avi’);

Write a 3D array to an AVI file with a specified frame rate:

write_frames_to_avi(my_data, ‘output.avi’, 10);

Write a 3D array to an AVI file with specified spatial dimensions:

write_frames_to_avi(my_data, ‘output.avi’, 10, 1:256, 1:256);

write_frames_to_gif(array_3D, gif_filename, size_mb)

Create a GIF from a 3D array with a target size in MB.

This function converts a 3D array (height x width x frames) into a GIF file with a specified maximum size in megabytes. The function normalizes each frame, converts it to grayscale, and writes it to the GIF file.

Parameters:

array_3D3D array

The 3D array to convert to a GIF, with dimensions (height x width x frames).

gif_filenamechar

The name of the output GIF file.

size_mbnumeric

The target size of the GIF in megabytes. The number of frames will be adjusted to fit within this size, rounding down to the nearest whole frame.

Notes

Frames are normalized to [0, 1] and converted to grayscale before being written to the GIF file. This will result in the final image being smaller than the original, as will the resulting gif.

Examples

Example 1:

% Create a GIF from a 3D array with a target size of 45 MB array_3D = rand(100, 100, 500); % Example 3D array write_frames_to_gif(array_3D, ‘output.gif’, 45);

Example 2:

% Create a GIF from a 3D array loaded from a file with a target size of 25 MB array_3D = h5read(‘data.h5’, ‘/dataset’); % Load 3D array from file write_frames_to_gif(array_3D, ‘output_25mb.gif’, 25);

write_frames_to_h5(file, Y_in, varargin)

Write in-memory 3D or 4D data to an HDF5 file in chunks.

This function writes a multidimensional array Y_in to an HDF5 file specified by file in chunks. It creates a dataset within the HDF5 file and writes the data in specified chunk sizes. If dataset_name is not provided, it defaults to ‘/Y’. If target_chunk_mb size is not provided, it defaults to 2000.

Parameters:

filechar

The name of the HDF5 file to write to.

Y_inarray

The multidimensional array to be written to the HDF5 file.

dschar, optional

The name of the dataset group within the HDF5 file. Default is ‘/Y’.

target_chunk_mbint, optional

In MB, the chunk_size to include in each h5 write. Default is 4MB.

Notes

The function handles 3D or 4D arrays and writes them incrementally to the HDF5 file to manage memory usage efficiently. It also trims the last frame of each chunk if the chunk size exceeds the remaining data size.

Examples

Write a 3D array to an HDF5 file with default chunk size and dataset name:

write_frames_to_h5(‘data.h5’, my_data);

Write a 4D array to an HDF5 file with a specified chunk size:

write_frames_to_h5(‘data.h5’, my_data);

Write a 3D array to an HDF5 file with a specified dataset name:

write_frames_to_h5(‘data.h5’, my_data,’/Y’);

write_frames_to_tiff(varargin)

Write image to TIFF file with specified datatype.

Parameters:

imgdatanumeric array

Image data to be exported. It must be a numeric array.

imfilechar

Name of the output TIFF file.

datatypechar

Data type for the export. Supported data types include ‘uint16’ and ‘int16’.

hTiffTiff object

Tiff object containing metadata tags.

Notes

To avoid errors such as ‘??? Error using ==> tifflib The value for MaxSampleValue must be …’, override the tag MaxSampleValue with MATLAB supported values or simply remove the tag from the header.

Overwriting of the existing image files is not checked. Be cautious with the export image file name.

Examples

imgdata = imread(‘ngc6543a.jpg’); header = imfinfo(‘ngc6543a.jpg’); write_frames_to_tiff(imgdata,header,’new_zplane_1.tif’,’uint16’);

imgdata = imread(‘mri.tif’); write_frames_to_tiff(imgdata,[],’new_mri.tif’,’int32’,’Copyright’,’MRI’, ‘Compression’,1);

More information can be found by searching for ‘Exporting Image Data and Metadata to TIFF Files’ in MATLAB Help.

write_images_to_gif(image_files, save_name, delay_time)

Creates an animated GIF from a series of images on disk.

This function generates an animated GIF from a series of images specified by their file paths. The images are read, converted to indexed color, and sequentially written to a GIF file with a specified delay between frames.

Parameters:

image_filescell array of strings

A cell array containing the file paths of the images to be included in the GIF.

save_namestring

The directory and filename where the output GIF file will be saved.

delay_timeint, optional

Time, in seconds, to delay each frame of the GIF. Defaults to 0.5 seconds.

Returns:

None

Notes

The function reads each image file, converts it to an indexed color map, and writes it to the GIF file. The first image initializes the GIF file, and subsequent images are appended. If the delay_time parameter is not specified, it defaults to 0.5 seconds between frames. The function checks for valid input types and existence of image files before proceeding with the GIF creation.

write_images_to_tile(images, metadata, varargin)

Creates a tiled figure with scale bars and specified titles.

Parameters:

imagescell array

Cell array of 2D or 3D images to be tiled.

metadatastruct

Metadata structure containing necessary information.

titlescell array, optional

Cell array of titles for each image.

scalescell array, optional

Cell array of sizes for the scale bar, in micron. If empty or 0, no scale is drawn.

fig_titlechar, optional

Title for the entire figure.

save_namechar, optional

Name to save the figure.

layoutchar, optional

Layout for the tiles (‘horizontal’, ‘vertical’, ‘square’).

write_mean_images_to_png(directory)

Create a grid of mean-images from HDF5 datasets in the specified directory.

This function reads HDF5 files from a specified directory, extracts the ‘/Ym’ dataset (assumed to be a 2D image) from each file, and creates a 5x6 grid of these images with no padding or tile spacing. The function processes up to 30 HDF5 files in the directory.

Parameters:

directorychar

The directory containing the HDF5 files.

dschar, optional

The group/dataset name. Default is ‘/Y’.

Notes

• The function processes up to 30 HDF5 files. If there are fewer than 30 files, it will process all available files.

• The function uses MATLAB’s tiled layout feature to create a 5x6 grid of images with no padding or tile spacing.

Examples

Example 1:

% Create an image grid from HDF5 files in a specified directory write_image_grid(‘path/to/hdf5/files’);

reorder_h5_files(h5path, order)

Reorder and rename HDF5 files based on a specified order.

This function reorders and renames HDF5 files in a specified directory (h5path) based on the provided order array. It temporarily renames files to avoid conflicts, updates the HDF5 attributes to store the original order, and saves the original order as a .mat file.

Parameters:

h5pathchar or string

The path to the directory containing the HDF5 files to be reordered.

orderarray

An array specifying the new order of the HDF5 files. The length of this array must match the number of HDF5 files in the directory.

Notes

The function ensures that the HDF5 files are sorted, renames them to temporary names to avoid conflicts, and then renames them to their new ordered names. The original order is stored as an attribute in each HDF5 file and saved as a .mat file.

Examples

Reorder HDF5 files in a directory based on a specified order:

h5path = ‘path/to/h5/files’; order = [3, 1, 2, 4]; reorder_h5_files(h5path, order);

2.3. Visualization

play_movie(movie_cell_array, labels_cell_array, min_mov, max_mov)

Play a movie or list of movies with labels, press any key to stop the movie from playing.

Parameters:

movie_cell_arraycell array

Cell array of movies. Each movie is a 3D array (height x width x frames).

labels_cell_arraycell array, optional

Cell array of titles for the movies. If not provided, empty labels will be used.

min_movnumeric, optional

Minimum value for setting the color limits on the movies. If not provided, will be computed from the first movie.

max_movnumeric, optional

Maximum value for setting the color limits on the movies. If not provided, will be computed from the first movie.

Examples

play_movie({movie1, movie2}, {‘Movie 1’, ‘Movie 2’}, 0, 255) play_movie(movie, ‘Sample Movie’)

set_caxis(stack)

Set the color axis limits for an image stack.

This function sets the color axis limits of the current figure based on the cumulative distribution function (CDF) of pixel values in the first image of the provided stack. The limits are set to the 0.5th and 99.5th percentiles to improve the contrast of the displayed images.

Parameters:

stack3D array

The input image stack (height x width x frames).

calculate_scale(img_size, pixel_resolution)

Calculates the appropriate scale bar size from an image size and pixel resolution.

Parameters:

img_sizeint

Width of the image in pixels.

pixel_resolutiondouble

Pixel resolution in microns per pixel.

Returns:

scale_sizeint

Calculated scale bar size in microns.

get_central_indices(img, margin)

Returns the central indices of the image with a given margin.

Parameters:

img2D array

The input image.

marginint

The margin around the central part.

Returns:

yindarray

Indices for the y-dimension.

xindarray

Indices for the x-dimension.

get_segmentation_metrics(savePath, T_all, Nsamples)

Compute and save segmentation metrics based on the ration of t Z-Score of the moving mean to the standard deviation of the difference between time-series data and the moving mean.

Parameters:

savePathchar

Path where the resulting figures will be saved.

T_allnumeric array

Time series data for all neurons.

Nsamplesnumeric

Number of samples for the moving mean calculation.

This function calculates the Z-score for

each neuron and plots histograms of the Z-scores and maximum

DeltaF/F_0 (%) values. The resulting figures are saved to the specified

save path.

Notes

The Z-score is calculated as the ratio of the maximum moving mean to the standard deviation of the difference between the time series data and its moving mean.

Examples

savePath = ‘results/’; T_all = randn(100, 1000); % Example time series data Nsamples = 10; get_segmentation_metrics(savePath, T_all, Nsamples);

translate_frames(Y, shifts_2D)

Translate image frames based on provided translation vectors.

This function applies 2D translations to an image time series based on a series of translation vectors, one per frame. Each frame is translated independently, and the result is returned as a 3D stack of (Height x Width x num_frames) translated frames.

Parameters:

Y - A 3D time series of image frames (Height x Width x Number of Frames).

t_shifts - An Nx2 matrix of translation vectors for each frame (N is the number of frames).

Returns:

translatedFrames - A 3D array of translated image frames, same size and type as Y.

2.4. Validation

validate_toolboxes()

Report missing MATLAB toolboxes that are required to execute this pipeline.

display_dataset_names(h5_fullfile, loc)

Display available datasets in an HDF5 file.

This function displays the names, sizes, and datatypes of datasets in the provided group location in the dataset.

Parameters:

h5_fullfilechar

Full path to the HDF5 file.

locchar

Dataset group name. Default is ‘/’.

Returns:

None