Sovereign 8s.is mirror of standardgalactic/SpatialPatternsCollectives
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jean-Baptiste Saulnier b31a499756 remove <br>
2025-12-01 16:55:58 +01:00
analysis update review 2025 2025-11-07 20:15:06 +08:00
scripts update linearisation codes (add them as scripts) 2025-12-01 16:52:36 +01:00
simulation update linearisation codes (add them as scripts) 2025-12-01 16:52:36 +01:00
.gitignore add .gitignore 2024-10-22 10:07:05 +02:00
CITATION.cff add CITATION.cff 2025-11-13 14:04:49 +08:00
LICENSE Create LICENSE 2025-11-13 11:09:40 +08:00
README.md remove <br> 2025-12-01 16:55:58 +01:00
requirements.txt update review 2025 2025-11-07 20:15:06 +08:00
utils.py update review 2025 2025-11-07 20:15:06 +08:00

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.

  1. Check that Python 3.10+ is installed:

    python3 --version
    

    or

    python --version
    
  2. Install uv and ensure it is available in your PATH.
    Installation instructions are provided on the official page: https://github.com/astral-sh/uv

  3. Move into the project directory:

    cd SpatialPatternsCollectives
    
  4. Create and activate a virtual environment:

    uv venv .venv
    source .venv/bin/activate        # Linux / macOS
    .venv\Scripts\Activate.ps1       # Windows PowerShell
    
  5. 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 .ipynb notebooks and cannot be run directly in Jupyter Notebook/Lab

5. Demo (tracking pipeline)

  1. Open:

    scripts/tracking_analysis.py
    

    (pseudo-notebook with # %% blocks)

  2. Run the first block (Ctrl + Enter).
    It loads the demo dataset:

    scripts/data/segmented_images_100X/
    

    and saves trajectories to:

    scripts/output/tracking/
    
  3. 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)

  1. Prepare segmented images (TIFF, 16-bit labeled)
    from tools such as Omnipose or Cellpose.

  2. Open:

    scripts/tracking_analysis.py
    
  3. Update the path:

    input_path = ["path/to/your/data1", "path_to/your/data2", ...]
    
  4. 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.