- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| analysis | ||
| scripts | ||
| simulation | ||
| .gitignore | ||
| CITATION.cff | ||
| LICENSE | ||
| README.md | ||
| requirements.txt | ||
| utils.py | ||
The mechanisms of spatial pattern transition in motile bacterial collectives
This repository provides the Python 3 analysis and simulation codes used in the paper:
"The mechanisms of spatial pattern transition in motile bacterial collectives" (2025)
Saulnier et al., 2025.
Authors
Jean-Baptiste Saulnier, Michèle Romanos, Jonathan Schrohe, Clémence Cuzin,
Vincent Calvez*, Tâm Mignot* (corresponding authors)
All codes are implemented as pseudo-notebooks (plain .py files with # %% markers),
allowing sequential execution of code blocks using Ctrl + Enter in VSCode or similar editors.
1. Clone this repository
git clone https://github.com/MignotLab/SpatialPatternsCollectives.git
2. Repository structure
All scripts are located in the scripts/ folder.
Outputs are saved in: scripts/output/
Main analysis scripts
nematic_analysis.py– Computes nematic alignment grids and spatial correlations.reversal_and_signaling_analysis.py– Detects reversals and computes signaling quantities.tracking_analysis.py– Segmentation, skeletonization, tracking, and Napari visualization.simulation_1d_cpu.py/simulation_1d_cupy.py– 1D simulation model (CPU/GPU).linear_stability_guzzo.py/linear_stability_igoshin.py- Runs the full linear stability analysis for the Guzzo et al. (2018) model and the Igoshin et al. (2001) model, respectively.
Subdirectories
analysis_reversals_detection_SgmX/– Supplementary analyses.simu_2d/– 2D agent-based simulations (swarming and rippling).
3. Environment installation
All analyses and simulations use a standard Python environment and are fully installable using
uv, a fast and reliable Python package manager compatible with pip.
Installation (recommended)
-
Check that Python 3.10+ is installed:
python3 --versionor
python --version -
Install
uvand ensure it is available in your PATH.
Installation instructions are provided on the official page: https://github.com/astral-sh/uv -
Move into the project directory:
cd SpatialPatternsCollectives -
Create and activate a virtual environment:
uv venv .venv source .venv/bin/activate # Linux / macOS .venv\Scripts\Activate.ps1 # Windows PowerShell -
Install all required dependencies:
uv pip install -r requirements.txt
This installs every package needed to run all analysis and simulation scripts in the repository.
Optional: GPU acceleration (CuPy)
Some simulations (e.g., simulation_1d_cupy.py) support GPU acceleration with CuPy (NVIDIA GPU required):
uv pip install cupy-cuda12x
4. System requirements
- Python: 3.10 or newer
- Tested operating systems: Ubuntu 24.04 (Linux), macOS Sonoma (Apple Silicon M4), Windows 10
- Hardware:
- CPU only required
- Optional NVIDIA GPU for CuPy (1D GPU simulations)
- Compatible editors:
- Fully tested in VSCode (Python + Jupyter extensions)
- Also compatible with Spyder and PyCharm Scientific Mode
- Note: scripts are not
.ipynbnotebooks and cannot be run directly in Jupyter Notebook/Lab
5. Demo (tracking pipeline)
-
Open:
scripts/tracking_analysis.py(pseudo-notebook with
# %%blocks) -
Run the first block (Ctrl + Enter).
It loads the demo dataset:scripts/data/segmented_images_100X/and saves trajectories to:
scripts/output/tracking/ -
Run the second block to open the Napari viewer.
Expected output
- Tracking CSV files
- Napari visualization of trajectories overlaid on segmentation
Runtime
~1 minute on a standard laptop.
6. Instructions for use (tracking on your own data)
-
Prepare segmented images (TIFF, 16-bit labeled)
from tools such as Omnipose or Cellpose. -
Open:
scripts/tracking_analysis.py -
Update the path:
input_path = ["path/to/your/data1", "path_to/your/data2", ...] -
Run the script block-by-block (Ctrl + Enter)
or from command line:python scripts/tracking_analysis.py
Output
- CSV tracking files in:
scripts/output/tracking/ - Optional Napari viewer
7. Simulations (1D and 2D)
All simulation scripts are .py pseudo-notebooks with a single # %% cell.
Run using:
- Pseudo-notebook mode (recommended): open in VSCode → Ctrl + Enter
- Command-line mode:
python path/to/script.py
Both methods produce identical results.
7.1 Lightweight 2D control simulation (runnable on any laptop)
Run:
scripts/simu_2d/agent_based_model_control.py
Outputs:
scripts/simu_2d/output/agent_based_model_control/sample*
Runtime: ~1–3 hours depending on parameters.
7.2 Full 2D simulations (Figures 5–7)
Run full-scale simulations:
scripts/simu_2d/agent_based_simulation_script.py
Outputs:
scripts/simu_2d/output/agent_based_simulation_script/sample*
Runtime:
- several days on a desktop
- several hundred hours on a 48-core workstation
Unless reproducing Figures 5–7, we recommend using the lightweight version above.
7.3 1D simulations (Figure 2c)
CPU version:
scripts/simulation_1d_cpu.py
Outputs:
scripts/output/result_simu_1d/
GPU version (optional):
scripts/simulation_1d_cupy.py
Runtime: a few minutes on a laptop.
License
This project is licensed under the MIT License — see the LICENSE file for details.