MotilA Advanced Batch Processing¶

This script demonstrates how to use the MotilA pipeline for batch analyzing microglial fine process motility in 4D/5D image stacks.

Overview¶

• Scans and processes multiple registered 4D TIFF image stacks from multiple experimental folders.
• Applies preprocessing steps such as projection, registration, and spectral unmixing.
• Performs image enhancements like histogram equalization and filtering.
• Segments microglia, applies thresholding, and quantifies motility.
• Collects results from all processed stacks into summary tables for cohort analysis.

Workflow¶

1. Batch processing
   • Iterates over multiple subject folders (ID_list) and searches for experiment folders (project_tag).
   • Processes microglial motility for each dataset according to predefined settings.
   • Saves analysis results per subject in a structured output folder.
2. Batch collection
   • Gathers and combines results across all processed datasets.
   • Saves consolidated results into a cohort-level output directory.

Usage¶

• Modify parameters: Adjust paths, projection settings, thresholding methods, and filter settings.
• Run the script: Execute the script to batch process and collect results.
• Check outputs: Processed images, histograms, and motility metrics are saved in structured folders for further analysis and parameter tuning.

Dependencies¶

• Requires MotilA to be installed and accessible (available in the GitHub repository).

Author¶

Fabrizio Musacchio, March 20, 2025

Installation¶

First, download the MotilA repository from GitHub.

Then, create and activate a conda environment with the following packages:

conda create -n motila python=3.12 mamba -y
conda activate motila
mamba mamba install -y numpy scipy matplotlib scikit-image scikit-learn pandas tifffile zarr numcodecs openpyxl xlrd ipywidgets ipykernel ipympl

We have tested MotilA for Python 3.9 and higher. If you encounter any issues, please let us know.

Don't forget to select the correct kernel in Jupyter Notebook (!)

1. Import libraries and download the example data set¶

First, we import MotilA and other required libraries:

Note: sys.path.append('../motila') is used to add the MotilA directory to the system path – relative to the current working directory. If you execute this notebook from a different location, you may need to adjust the path accordingly.

You can verify the correct import by running the following cell:

Before you proceed, please make sure that you have downloaded the example data from Zenodo:

• Gockel & Nieves-Rivera (2025), doi: 10.5281/zenodo.15061566

Place the downloaded and extracted data set into the example project folder.

2. Define MotilA parameters¶

Next, we define the parameters for the MotilA pipeline.

Input/Outut parameters¶

Define the input/output path and folder and file tags for the batch processing:

Note: By placing an excel file (e.g., metadata.xls) in the project_tag folder for each animal ID folder (listed in ID_list), the following parameters set in this notebook will be overwritten by the parameters in the excel file:

• two_channel_default: True/False
• MG_channel_default: 0/1
• N_channel_default: 0/1
• spectral_unmixing: True/False
• projection_center_default: integer

This allows for individual settings for each dataset.

The table below shows an example of the content of the metadata.xls file:

A template for this excel files is provided in the MotilA repository. In this template, ignore the columns Registration Channel and Registration Co-Channel as they are not used in this pipeline.

You can add several projection centers (Projection Center 1, Projection Center 2, etc.) to the excel file. The pipeline will then create a projection for each center along with the corresponding analysis results.

Projection parameters¶

MotilA will generate maximum intensity projections along the specified axes. For this, we need to define the projection center and ranges:

Clear previous results?¶

Define whether to clear the output folder before running the pipeline:

Thresholding parameters¶

Define the thresholding method and parameters for segmenting microglia.

As a thresholding method (threshold_method), you can choose between otsu, li, isodata, mean, triangle, yen, and minimum.

blob_pixel_threshold defines the minimum number of pixels for a blob to be considered a microglial cell.

With compare_all_threshold_methods, a plot is generated comparing all thresholding methods listed above to facilitate the selection of the best method.

Image enhancement parameters¶

Define the parameters for enhancing the images, such as histogram equalization and filtering.

With hist_equalization set to True, the pipeline will apply histogram equalization WITHIN each time (3D) stack. This enhances the contrast within each 3D stack.

With hist_match set to True, the pipeline will apply histogram matching BETWEEN the time (3D) stacks. This homogenizes the intensity distribution across the time stacks and acts as a bleaching correction.

Image filtering parameters¶

Define the parameters for filtering the images, such as median filtering and Gaussian smoothing.

Median filtering¶

Regarding median filtering, you have the option to filter on the single slices BEFORE the projection (median_filter_slices) and/or on the projected images (median_filter_projections). For both options, you can choose from:

• False (no filtering)
• square (square kernel): integer numbers (3, 5, 9)
• circular (disk-shaped kernel; analogous to the median filter in ImageJ/Fiji): only values >= 0.5 allowed/have an effect

When you apply median filtering, you need to additionally provide the kernel size (median_filter_window_slices for single slices and median_filter_window_projections for projections). Depending on the chosen filtering kernel method, you can choose a kernel size as listed above.

Gaussian smoothing¶

Gaussian smoothing further enhances the contrast and reduces noise. Set

• gaussian_smoothing to 0: no smoothing, or
• gaussian_smoothing to a value > 0: the standard deviation of the Gaussian kernel.

Channel parameters¶

Define the channel parameters for single-channel or two-channel data:

Note: If you stack contains only one channel, set two_channel_default = False; any value set in N_channel_default will be ignored.

Note: If metadata.xls is present in project_tag folder, the above defined values (two_channel_default, MG_channel_defaulta, N_channel_default) are ignored and values from the metadata.xls are used instead (in batch processing only!)

Registration parameters¶

MotilA provides the option to register the image stacks. Two registration options are available:

• regStack3d: register slices WITHIN each 3D time-stack; True or False
• regStack2d: register projections on each other; True or False

With template_modeyou can define the template mode for the registration. Choose between mean (default), median, max, min, std, and var.

With max_xy_shift_correction, you can define the maximum allowed shift in x and y (and z) direction for the registration. This is useful to avoid overcorrection.

Spectral unmixing parameters¶

MotilA provides the option to perform spectral unmixing on two-channel data. At the moment, only a simple method is implemented, which subtracts the N-channel from the MG-channel. Set spectral_unmixing to True to enable this feature.

With spectral_unmixing_amplifyer_default you can define the amplification factor for the MG-channel before subtraction. This can be useful to preserve more information in the MG-channel.

spectral_unmixing_median_filter_window defines the kernel size for median filtering of N-channel before subtraction. This can be useful to reduce noise in the N-channel and, thus, achieve a better unmixing result. Allowed are odd integer numbers (3, 5, 9, ...).

3. Initialize the logger¶

Initialize the logger to track the progress of the pipeline. The log file will be saved in the same folder as this notebook is located.

4. Run the MotilA pipeline¶

Finally, we run the MotilA pipeline with the defined parameters. Simply execute the following cell to start the processing:

5. Assessing your results¶

After running the pipeline, you can assess the results in the specified output folder. The results of each processing step described above are saved in separate tif and PDF files. By carefully investigating these results, you can evaluate the quality of the processing and adjust the parameters if necessary.

An example assessment is given in the MotilA Quick Start (Single File) notebook.

6. Batch collection¶

After processing all datasets, you can collect the results and save them to a central output folder. This allows you to perform cohort-level analyses and visualize the results across all datasets.

First, define the parameters for batch collection:

Then, start the batch collection by executing the following cell:

Let's investigate the cohort results by loading the summary tables:

This table contains the motility metrics for each dataset for each ID, time lapse stack, project tag, and projection center. You can use this table to perform cohort-level analyses and visualize the results across all datasets.

Also a summary table with the mean and standard deviation of the motility metrics for each ID and project tag is generated:

Similarly, all brightness values and pixel areas are summarized in separate tables for any further analysis: