Skip to content

Getting Started with mAIcrobe

Welcome to mAIcrobe! This guide will get you up and running with bacterial cell analysis in under 10 minutes.

Prerequisites

Before installing mAIcrobe we strongly recommend setting up a dedicated Python environment. This prevents dependency conflicts and ensures reproducibility. Any of the conda distributions (Anaconda, Miniconda, Miniforge) will work.

Step 1: Install a Conda Distribution

SKIP TO STEP 2 IF YOU ALREADY HAVE A CONDA DISTRIBUTION INSTALLED

Download and Install Miniconda

  1. Download the appropriate installer for your system from https://docs.conda.io/en/latest:

  2. Install by following the installer prompts:

    • Accept the license agreement
    • Choose installation location (default is recommended)
    • Important: When asked "Do you wish the installer to initialize Miniconda3?", choose Yes
    • Important: Do NOT install miniconda, or allow the environments to be managed, in a folder that contains spaces. If your user folder (default installation location)contains spaces, choose a different installation location.

  3. Restart your terminal/command prompt after installation

  4. Verify installation by running the following in your terminal (macOS/Linux) or anaconda/miniconda/miniforge command prompt (Windows): 

    conda --version
    You should also see base in your terminal prompt, indicating the base conda environment is active.

Step 2: Create a Dedicated Environment

To keep your system organized, create a clean environment specifically for mAIcrobe. You only need to create theis environment once. After the environment is created and mAIcrobe is installed you just need to activate the environment to use mAIcrobe.

To create an environment, in your terminal (macOS/Linux) or miniconda command prompt (Windows), run:

# Create new environment with Python 3.11
conda create -n mAIcrobe python=3.11

This creates a new conda environment named mAIcrobe with Python 3.11 installed. The name of the environment can be changed if desired.

To activate the environment, run:

# Activate the environment
conda activate mAIcrobe

Substitute mAIcrobe with your chosen environment name if you chose a different name. You should now see your environment name in your terminal prompt, indicating the environment is active. Subsequent installation commands should be run with the environment activated.

Step 3: mAIcrobe installation

With your conda environment activated, install mAIcrobe using pip:

# Install napari-mAIcrobe with pip
pip install napari-mAIcrobe

Important Make sure your conda environment is activated whenever you want to install and use mAIcrobe! You should see (mAIcrobe) or the name you chose in Step 2 in your terminal prompt.

#### mAIcrobe is now installed! πŸŽ‰

To use, just open your terminal or anaconda/miniconda/miniforge command prompt, activate your conda environment using the name you chose in Step 2 and launch napari. See below for more details.

TIP: If you forgot the name of your conda environment, you can list all your conda environments with:

conda env list
Alternative Installation Methods (click to expand)

Standard pip Installation (without conda)

If you prefer not to use conda, or are using a different environment manager, you can install mAIcrobe directly with pip.: 
pip install napari-mAIcrobe

Development Installation (from source)

For contributors or advanced users: 
git clone https://github.com/HenriquesLab/mAIcrobe.git
cd mAIcrobe
pip install -e .[testing]

βœ… Verify Installation

Test your installation by launching napari with the plugin. In your terminal, run:

# Activate your environment first (if using conda)
conda activate mAIcrobe

# Launch napari
napari

Or programmatically:

import napari
viewer = napari.Viewer()

In both cases the napari window should open, and you can check if the "mAIcrobe" plugin is listed under the Plugins menu.

πŸ”₯ First Analysis

Let's perform a quick bacterial cell analysis using the included sample data. For a more detailed walkthrough, refer to the basic-workflow tutorial.

Step 1: Launch napari

Go to your terminal and run:

napari

or programmatically:

import napari
viewer = napari.Viewer()

Step 2: Load Sample Data

mAIcrobe includes S. aureus test images. Load them via:

Option A: GUI Method

  1. Go to File > Open Sample > mAIcrobe

  2. Select the following samples one by one:

    • "Phase contrast S. aureus"
    • "Membrane dye S.aureus"
    • "DNA dye S.aureus"

Option B: Programmatic Method

import napari
import numpy as np

# Launch napari viewer
viewer = napari.Viewer()

# Load sample data
from napari_mAIcrobe._sample_data import phase_example, membrane_example, dna_example

# Get the sample images
phase_data = phase_example()[0]
membrane_data = membrane_example()[0]
dna_data = dna_example()[0]

# Add images to viewer
phase_layer = viewer.add_image(phase_data[0], **phase_data[1])
membrane_layer = viewer.add_image(membrane_data[0], **membrane_data[1])
dna_layer = viewer.add_image(dna_data[0], **dna_data[1])

Step 3: Segment Cells

  1. Go to Plugins > mAIcrobe > Compute label
  2. Configure segmentation parameters: 
    Base Image: Phase (select the phase contrast layer)
Fluor 1: Membrane (select the membrane layer)
Fluor 2: DNA (select the DNA layer)
Model: Isodata (or CellPose cyto3)
    For the purpose of this example, leave all other parameters as default. For more details on segmentation methods, see the Segmentation Guide.

  3. Click Run

    The segmentation will create a new "Labels" layer with individual cells outlined.

Step 4: Analyze Cells

  1. Go to Plugins > mAIcrobe > Compute cells
  2. Configure analysis parameters:
    • Label Image: Select the labels layer from Step 3
    • Membrane Image: Select membrane layer
    • DNA Image: Select DNA layer
    • Pixel size: Enter your pixel size (e.g., 0.065 ΞΌm/pixel - optional)
    • Classify cell cycle: Check this box
    • Model: Select "S.aureus DNA+Membrane Epi"
  3. Click Run

This will add statistical measurements to the Labels layer properties. For the purpose of this simple example, leave all other parameters as default. For more details on cell analysis, see the Cell Analysis Guide.

Step 5: View Results

After analysis completes, you can:

  • View cell statistics: Check the layer properties panel
  • Filter cells: Use Plugins > napari-mAIcrobe > Filter cells
  • Generate reports: Enable "Generate Report" in Step 4 to create HTML/CSV reports

πŸ“š Next Steps

Now that you've completed your first analysis:

  1. Segmentation Guide - Choose the optimal segmentation method
  2. Cell Analysis Guide - Comprehensive analysis workflows
  3. Cell Classification Guide - Cell classification in detail
  4. API Reference - Programmatic usage

Tip: Building your own classifier? Export per-cell training pickles via Plugins > mAIcrobe > Compute pickles. Provide a Labels layer, a Points layer named with the class id (e.g., "1"), select one/two channels, and choose an output folder. See the Cell Classification Guide and Generate Training Data for Cell Classification for details.

🀝 Getting Help

If you encounter issues:

  1. Check this documentation and troubleshooting guides
  2. Search GitHub Issues
  3. Include error messages, napari version, and system details

Welcome to the mAIcrobe community! πŸ”¬