MotilA: A pipeline for microglial fine process motility analysis

MotilA is a Python-based image analysis pipeline designed to quantify microglial fine process motility from 4D and 5D time-lapse image stacks acquired through multi-photon in vivo imaging. While developed for microglial analysis, MotilA can be applied to other cell types and imaging studies as well. The pipeline supports both single-file and batch processing, making it adaptable for various experimental designs and high-throughput analyses.

What does MotilA do?

MotilA automates the processing and analysis of fluorescence microscopy data, particularly for microglial process dynamics. It performs:

• Preprocessing: Image registration, spectral unmixing, histogram equalization, bleach correction, and projection of z-layers to enhance signal quality.
• Segmentation: Adaptive thresholding and noise filtering to isolate microglial processes.
• Motility quantification: Frame-to-frame analysis of pixel changes in microglial structures.
• Batch processing: Automated handling of multiple datasets with standardized parameter settings.
• Flexible image I/O: Reading is handled through OMIO, supporting TIFF/OME-TIFF, CZI, Thorlabs RAW and LSM files with automatic normalization to TZCYX.

A high-level description of all processing steps and parameters is given in the online documentation.

How is "motility" determined?

MotilA quantifies motility by first extracting a sub-volume from the 3D stack at each imaging time point $t_i$ and performing a maximum intensity z-projection. This sacrifices the z-axis information but enables segmentation and quantification of stable, lost, and gained pixels in a computationally efficient manner, facilitating batch processing with standard image analysis techniques. This approach aligns with methodologies used in prior studies, such as Nebeling et al. (2023) or Fuhrmann et al. (2010). The temporal variation $\Delta B(t_i)$ is then computed as:

$$\Delta B(t_i) = 2 \times B(t_i) - B(t_{i+1})$$

where $B(t)$ represents the binarized image at time point $t$. From this, MotilA categorizes pixels as follows:

• Stable pixels (S): Pixels that remain unchanged $\Delta B = 1$.
• Gained pixels (G): Newly appearing microglial pixels $\Delta B = -1$.
• Lost pixels (L): Pixels that disappear $\Delta B = 2$.

From these, MotilA derives the turnover rate (TOR), a key metric for motility:

$$ TOR = \frac{G + L}{S + G + L} $$

This turnover rate represents the fraction of pixels undergoing change, providing a quantitative measure of microglial fine process motility.

Core pipeline steps of MotilA illustrated using a representative microglial cell from the included example dataset. a) The pipeline begins with loading and z-projecting 3D image stacks, followed by optional preprocessing steps such as spectral unmixing, registration, and histogram equalization (upper panel). The resulting projections are filtered and binarized for segmentation of microglial fine processes (lower panel). b) Motility analysis compares consecutive time points by classifying stable (S), gained (G), and lost (L) pixels, from which the turnover rate (TOR) is computed. c) The TOR is plotted across time points, quantifying microglial fine process motility over time.

Installation

Installation via PyPI

The easiest way to install MotilA is via PyPI:

conda create -n motila python=3.12 -y
conda activate motila
pip install motila

Installation from source

We recommend using a dedicated virtual environment for development and reproducibility.

Below is an example using conda:

conda create -n motila python=3.12 -y
conda activate motila

Clone the GitHub repository and install the package from its root directory:

git clone https://github.com/FabrizioMusacchio/MotilA.git
cd MotilA
pip install .

Alternatively, install directly from GitHub without cloning:

pip install git+https://github.com/FabrizioMusacchio/MotilA.git

Note: If you are contributing or making code changes, install in editable mode so updates are immediately reflected:

pip install -e .

⚠️ Avoid mixing install methods:
If you install MotilA via pip, make sure you do not place a local folder named motila/ in the same directory where you run your scripts (e.g., a cloned or downloaded source folder). Python may try to import from the local folder instead of the installed package, leading to confusing errors.

Compatibility

We have tested MotilA for Python 3.9 to 3.12 on Windows, macOS, and Linux systems. The pipeline should work on all these platforms without any issues. If you encounter any platform-specific issues, feel free to open an issue.

Example data set and tutorials

To help you get started with MotilA, we provide an example dataset and tutorials to guide you through the pipeline steps.

The example dataset includes sample image stacks and metadata files for testing the pipeline. You can download the

• full example dataset from Zenodo (Gockel & Nieves-Rivera & Musacchio et al., 2025, doi: 10.5281/zenodo.15061566; data based on Gockel & Nieves-Rivera et al., 2026), or a
• subset ("cutout") of the example dataset, also from Zenodo (Musacchio, 2025, doi: 10.5281/zenodo.17803977)

After downloading and extracting, place it in the example_project directory. If you use one of the provided datasets for any purpose beyond the example tutorials, please cite both the dataset record (Gockel & Nieves-Rivera & Musacchio et al., 2025, doi: 10.5281/zenodo.15061566 / Musacchio, 2025, doi: 10.5281/zenodo.17803977) and Gockel & Nieves-Rivera et al., 2026.

The tutorials cover the core pipeline steps, from loading and preprocessing image data to analyzing microglial motility and visualizing the results. A second tutorial demonstrates batch processing for analyzing multiple datasets in a structured project folder.

Jupyter notebooks:

• single_file_run.ipynb
• batch_run.ipynb

Python scripts:

• single_file_run.py
• batch_run.py

We used the following Python script to generate the figures presented in our submitted manuscript:

• single_file_run_paper.py

This script includes all parameter settings used during analysis and can be employed to reproduce the figures. It was applied to the subset of the example dataset described above.

Running the example scripts and notebooks

The example scripts in example_scripts and example_notebooks expect a relative path layout and therefore must be executed from within that directory. For example:

cd example_scripts
python single_file_run_paper.py

Alternatively, users may modify the DATA_Path variable inside the script to point to the absolute location of your example_project folder.

Quick start

Single file processing

Here is an example of how to use MotilA for single file processing. First, import the necessary modules:

import motila as mt
from pathlib import Path

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

mt.hello_world()

Init the logger to get a log file for your current run:

# init logger:
log = mt.logger_object()

Then, define the corresponding parameters. A set of example values can be found in the tutorial notebooks and scripts provided in the repository.

When you have set the parameters, run the pipeline via:

mt.process_stack(fname=fname,
                MG_channel=MG_channel, 
                N_channel=N_channel,
                two_channel=two_channel,
                projection_layers=projection_layers,
                projection_center=projection_center,
                histogram_ref_stack=histogram_ref_stack,
                log=log,
                blob_pixel_threshold=blob_pixel_threshold, 
                regStack2d=regStack2d,
                regStack3d=regStack3d,
                template_mode=template_mode,
                spectral_unmixing=spectral_unmixing,
                hist_equalization=hist_equalization,
                hist_equalization_clip_limit=hist_equalization_clip_limit,
                hist_equalization_kernel_size=hist_equalization_kernel_size,
                hist_match=hist_match,
                RESULTS_Path=RESULTS_Path,
                ID=Current_ID,
                group=group,
                threshold_method=threshold_method,
                compare_all_threshold_methods=compare_all_threshold_methods,
                gaussian_sigma_proj=gaussian_sigma_proj,
                spectral_unmixing_amplifyer=spectral_unmixing_amplifyer,
                median_filter_slices=median_filter_slices,
                median_filter_window_slices=median_filter_window_slices,
                median_filter_projections=median_filter_projections,
                median_filter_window_projections=median_filter_window_projections,
                clear_previous_results=clear_previous_results,
                spectral_unmixing_median_filter_window=spectral_unmixing_median_filter_window,
                debug_output=debug_output,
                stats_plots=stats_plots)

More complete examples, including batch processing and collection of cohort-level metrics, are explained in online documentation.

Flexible batch processing

MotilA v1.2.0 introduces a flexible BIDS-like batch processor. The project root contains subject folders, and tag_folder_levels describes how MotilA should walk the folder tree below each subject:

result = mt.batch_process_stacks(
    project_root=PROJECT_ROOT,
    subject_ids=None,
    subject_prefix="ID",
    tag_folder_levels=[
        ("DC000_FOV", "DA000_FOV"),
        ("TL_000",)],
    image_patterns=None,
    exclude_name_contains=("Preview",),
    skip_processed=True,
    processing_options=processing_options)

image_patterns=None uses MotilA defaults for TIFF/OME-TIFF, CZI, LSM and RAW files. Existing outputs are skipped, not treated as failures. Each run updates motila_batch_run_report.txt in the project root; failures are collected in a timestamped motila_batch_error_report_*.txt and do not stop the full batch by default.

mt.batch_collect(...) uses the same discovery settings (subject_ids, subject_prefix, tag_folder_levels, image_patterns, exclude_name_contains) so cohort-level collection can follow the same folder logic as processing.

Future developments

Please refer to the ROADMAP.md file for an overview of planned improvements and future extensions of MotilA.

How to contribute

MotilA is an open-source software and improves because of contributions from users all over the world. If there is something about Motila that you would like to work on, then please reach out:

• open an issue, or
• submit a pull request against the main branch.

Please find more information on how to contribute in the CONTRIBUTING.md file.

Citation

If you use this software in your research, please cite the peer-reviewed article published in the Journal of Open Source Software:

Musacchio, F., Crux, S., Nebeling, F., Gockel, N., Fuhrmann, F., & Fuhrmann, M. (2025). MotilA – A Python pipeline for the analysis of microglial fine process motility in 3D time-lapse multiphoton microscopy data. Journal of Open Source Software, 10(116), 9267. https://doi.org/10.21105/joss.09267

BibTeX

@article{Musacchio2025,
  doi       = {10.21105/joss.09267},
  url       = {https://doi.org/10.21105/joss.09267},
  year      = {2025},
  publisher = {The Open Journal},
  volume    = {10},
  number    = {116},
  pages     = {9267},
  author    = {Musacchio, Fabrizio and Crux, Sophie and Nebeling, Felix and Gockel, Nala and Fuhrmann, Falko and Fuhrmann, Martin},
  title     = {MotilA – A Python pipeline for the analysis of microglial fine process motility in 3D time-lapse multiphoton microscopy data},
  journal   = {Journal of Open Source Software}
}

Note: An earlier version of this work was available as a bioRxiv preprint. The peer-reviewed JOSS article above is the canonical reference.

Acknowledgments

We gratefully acknowledge the Light Microscopy Facility (LMF) and the Animal Research Facility (ARF) at the German Center for Neurodegenerative Diseases (DZNE) for their essential support in acquiring the in vivo imaging data upon which this pipeline is built.

We also thank Gockel & Nieves-Rivera and colleagues (2026) for providing the example dataset used in this repository, which allows users to test and explore MotilA.

Contact

For questions, suggestions, or feedback regarding MotilA, please contact:

Fabrizio Musacchio
German Center for Neurodegenerative Diseases (DZNE)
Email: fabrizio.musacchio@dzne.de | GitHub: @FabrizioMusacchio | Website: fabriziomusacchio.com