Usage

Web App (Discovering m2m)

The m2m toolkit provides a user-friendly Streamlit web interface for discovering its functionalities.

Using Local Installation

source .venv/bin/activate  # or: conda activate m2m
streamlit run app/m2m_main_page.py
# Click the link to open the Streamlit Web App

Note

The Streamlit Web App is designed for discovering m2m’s functionalities. For large images (exceeding 200 MB) or advanced usage, we recommend using the command line interface.

Command Line (Advanced Usage)

Here are examples of typical command line usage.

Using Docker

All m2m scripts are available in the Docker container. You can run them by mounting your scripts directory:

docker run --rm \
  -v $(pwd)/scripts:/scripts:ro \
  -v $(pwd)/data:/data:rw \
  linumuqam/m2m:latest \
  python /scripts/m2m_download_template.py allen_template_100.nii.gz -r 25

Using Local Installation

Make sure your virtual environment is activated:

source .venv/bin/activate  # or: conda activate m2m

Step 1 - Download a User-Space Reference Image

  • Download an Allen mouse brain template at 100 microns (up to 10 microns):

m2m_download_template.py allen_template_100.nii.gz -r 25

  • Download an Allen mouse brain annotation at 100 microns (up to 10 microns):

m2m_download_annotation.py allen_annotation_100.nii.gz labels.txt -r 25

Step 2 - Compute a Transform Matrix

Compute the transform matrix transform_50.mat at 50 microns, given a user-space reference volume reference.nii.gz at 100 microns:

m2m_compute_transform_matrix.py reference.nii.gz transform_50.mat 50

Note

A transformation matrix for a specific resolution is valid only for that specific resolution. If you want to import data (Step 3) with another resolution, compute another matrix.

Step 3 - Example Use Cases

With your reference image (e.g., reference.nii.gz) and your resolution-specific transformation matrix (e.g., transform_50.mat), you can:

  • Import the projection density from experiment id 100140756:

m2m_import_proj_density.py --id 100140756 reference.nii.gz transform_50.mat 50

  • Find crossing ROIs based on two injection positions:

    • First injection: (132,133,69)

    • Second injection: (143,94,69)

    • Threshold: 0.07

m2m_crossing_finder.py transform_50.mat reference.nii.gz 50 \
  --red 132 133 69 --green 143 94 69 --injection --threshold 0.07

  • Find 5 experiment IDs given an injection position (132,133,69):

m2m_experiments_finder.py 50 transform_50.mat reference.nii.gz \
  experiments_ids.csv 132 133 69 --injection --nb_of_exps 5

Getting Help

Display help for any script:

m2m_compute_transform_matrix.py --help

Or consult the Scripts page in this documentation for detailed information about each tool.

Using m2m as a Python Library

You can also use m2m directly in your Python code:

import m2m
# Access m2m modules and functions
# See API documentation for available functions

Example workflow in Python:

import m2m
from m2m import template, annotation

# Your analysis code here
# See API documentation for detailed examples