MOSES — Motion Sensing Superpixels

MOSES is a computational framework for quantifying single-cell and collective motion phenotypes from time-lapse microscopy videos, by tracking superpixels and organizing them into a dynamic mesh.

The original paper repository is fyz11/MOSES. Active development is now maintained here, at BIA-Lab-Team/MOSES.

Contents

• What is MOSES?
• Used In
• Installation
• Dependencies
• Quickstart: Examples
• Example Output
• Citation
• Keywords
• License

What is MOSES?

Cell migration assays produce time-lapse videos, but turning that video into quantitative, comparable motion measurements is hard — especially at the scale of high-throughput screens. MOSES addresses this by tracking dense grids of superpixels with optical flow instead of trying to segment and track individual cells, then connecting those superpixel tracks into a "MOSES mesh" that captures the local collective structure of the tissue as it moves and deforms over time.

How it works: MOSES first extracts dense, frame-to-frame optical flow over the whole field of view — a per-pixel motion field with no notion of tracking windows yet. It then lays a regular grid of superpixel "windows" over the image and propagates each window's centroid frame-by-frame using the local average of the underlying dense flow, accumulating short, per-frame displacements into long-term trajectories. Because the flow field is computed independently of the window grid, the size of the tracking window is fully decoupled from the spatial resolution of the underlying motion field — you can track with large, robust windows while the flow itself stays pixel-resolution, or vice versa, and change one without recomputing the other. This is the key structural difference from classical Particle Image Velocimetry (PIV), where the interrogation window size is the motion resolution and the two cannot be tuned independently. That decoupling, plus the ability to propagate windows over arbitrarily long sequences rather than a single frame pair, makes MOSES a more flexible drop-in alternative to PIV for long-term motion analysis.

From the resulting superpixel tracks and mesh, MOSES computes a set of motion phenotype metrics used in the original study to characterize how two epithelial cell populations behave as they close a gap between them:

• Boundary Formation Index — whether/how strongly a stable boundary forms between two cell populations
• Mesh Stability Index — how much collective motion persists once the tissue reaches steady state
• Max. Velocity Cross-Correlation Index (VCCF) — how correlated the motion of two populations is, before vs. after they meet
• Spatial Correlation Function — how far motion correlation extends spatially through the tissue
• Mesh Order Index — how ordered/aligned local motion is across the mesh

These metrics generalize beyond the two-population wound-healing assay used in the paper to any single- or multi-channel time-lapse video where motion phenotyping is of interest.

Used In

MOSES' superpixel tracking has been applied well beyond the original in vitro epithelial assay:

• Intravital imaging of immune cells — used to track T cell migration in the spleen in Chauveau et al., Visualization of T Cell Migration in the Spleen Reveals a Network of Perivascular Pathways that Guide Entry into T Zones, Immunity 2020.
• Embryo tissue deformation and developmental staging — used to quantify collective tissue flow and stage mouse embryo development in Stower et al., Quantitative multi-scale morphodynamic analysis reveals ratchet-like collective DVE migration and epiblast retrograde cell flow during anterior patterning in the mouse embryo, eLife reviewed preprint and Stower et al., Single-cell phenomics reveals behavioural and mechanical heterogeneities underpinning collective migration during mouse anterior patterning, bioRxiv 2023.
• Tracking on unwrapped 3D cell surfaces — MOSES' 2D superpixel tracking can be applied directly to surfaces unwrapped into a flattened 2D coordinate system, enabling motion tracking of membrane-associated signals in 3D, as in Zhou et al., Surface-guided computing to quantify dynamic interactions between cell morphology and molecular signals in 3D, bioRxiv (u-Unwrap3D).

Installation

pip install v-MOSES

Or install from source:

git clone https://github.com/BIA-Lab-Team/MOSES.git
cd MOSES
pip install .

For development (editable install):

pip install -e .

MOSES imports as MOSES, e.g. from MOSES.Motion_Analysis import mesh_statistics_tools.

Dependencies

numpy, scipy, scikit-image, scikit-learn, opencv-python, matplotlib, seaborn, pillow, tifffile, tqdm, moviepy — all installed automatically via pip.

MOSES is tested against both NumPy 1.x (>=1.21) and NumPy 2.x.

Quickstart: Examples

The Examples/ folder walks through a full single-video analysis, from a raw multi-page TIFF to the paper's motion phenotype metrics:

• run_single_video_example.py — a standalone script version of the pipeline; run it directly against a video file.
• Run Example Analysis - ipython notebook.ipynb — the same pipeline as an annotated, step-by-step Jupyter notebook, better suited for exploring intermediate results interactively.

Both cover the same steps:

1. Read a multi-page TIFF video with Utility_Functions.file_io.read_multiimg_PIL.
2. Extract motion as superpixel tracks via optical flow (Optical_Flow_Tracking.superpixel_track.compute_grayscale_vid_superpixel_tracks), one channel at a time. The optical-flow method itself is pluggable — pass any (frame1, frame2) -> flow callable, e.g. Optical_Flow_Tracking.optical_flow.farnebackflow.
3. Filter tracks to the relevant cell populations (Track_Filtering.filter_meantracks_superpixels).
4. Build the MOSES mesh from the filtered tracks (Motion_Analysis.mesh_statistics_tools.construct_MOSES_mesh) and visualize it (Visualisation_Tools.mesh_visualisation).
5. Compute the motion phenotype metrics listed above and plot the resulting curves.

To run the notebook, download an example video from the paper's dataset and place it in the repository root, then launch:

jupyter notebook "Examples/Run Example Analysis - ipython notebook.ipynb"

Example Output

MOSES mesh constructed independently for two epithelial cell populations (red, green) at frame 20.

Left: motion saliency map used to compute the Boundary Formation Index. Right: MOSES mesh strain curves per population.

Citation

MOSES was introduced in:

Zhou FY, Ruiz-Puig C, Owen RP, White MJ, Rittscher J, Lu X. Motion sensing superpixels (MOSES) is a systematic computational framework to quantify and discover cellular motion phenotypes. eLife 2019;8:e40162. https://doi.org/10.7554/eLife.40162

@article{zhou2019moses,
  title   = {Motion sensing superpixels (MOSES) is a systematic computational framework to quantify and discover cellular motion phenotypes},
  author  = {Zhou, Felix Y and Ruiz-Puig, Carlos and Owen, Richard P and White, Michael J and Rittscher, Jens and Lu, Xin},
  journal = {eLife},
  volume  = {8},
  pages   = {e40162},
  year    = {2019},
  doi     = {10.7554/eLife.40162}
}

Keywords

cell migration · superpixel tracking · optical flow · collective cell motion · epithelial dynamics · live-cell imaging · computational biology · time-lapse microscopy

License

MOSES is made available under the Ludwig Non-Commercial License for academic and non-profit research use — see the included license document in this repository for full terms.

For-profit or commercial use requires a separate license. To arrange one, contact the Ludwig Institute for Cancer Research at eauffarth@licr.org.