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.

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.

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

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.

The easiest way to install MotilA is via PyPI:

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

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.

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.

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., currently under revision), 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., currently under revision (we will update the citation once available).

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.

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.

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.

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

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.

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

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

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 (currently under revision) for providing the example dataset used in this repository, which allows users to test and explore MotilA.

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