BactoScoop

BactoScoop enables reproducible high-throughput image-based profiling of individual bacterial cells. It takes multichannel microscopy images from individual fields through segmentation, cell mesh construction, quality curation, object detection, and feature extraction. The result is a per-cell table that connects morphology with membrane, nucleoid, and other fluorescence measurements. Each stage can be inspected, and saved masks, meshes, and feature tables make an analysis easier to review and repeat. Read the documentation · Three-channel walkthrough · Five-channel walkthrough

Install BactoScoop

BactoScoop requires Python 3.10. Choose either Conda or uv; both install the same package and its dependencies. The segmentation stack includes Omnipose 1.0.6 and NumPy below 2.

Install BactoScoop from PyPI using either environment option below. A tagged GitHub installation is also available.

Conda

Install Miniconda if needed, then run in Anaconda Prompt or Anaconda PowerShell Prompt:

conda create -n bactoscoop python=3.10 pip -y
conda activate bactoscoop
python -m pip install bactoscoop==0.1.1
python -m pip check
python -c "import bactoscoop; from importlib.metadata import version; print(version('bactoscoop'))"
jupyter lab

uv

Install uv, open PowerShell in a folder for your analysis, then run:

uv venv --python 3.10 .venv
uv pip install --python .venv bactoscoop==0.1.1
uv pip check --python .venv
.\.venv\Scripts\python.exe -c "import bactoscoop; from importlib.metadata import version; print(version('bactoscoop'))"
.\.venv\Scripts\jupyter.exe lab

uv can download Python 3.10 if needed. On macOS/Linux, use .venv/bin/python and .venv/bin/jupyter for the last two commands.

Stable release, GitHub release, or development checkout

The stable PyPI installation above pins the version for reproducibility. To upgrade to the newest stable PyPI release, use python -m pip install --upgrade bactoscoop (Conda) or uv pip install --python .venv --upgrade bactoscoop (uv).

The corresponding GitHub release can also be installed directly when Git is installed:

python -m pip install "bactoscoop @ git+https://github.com/Bart-Steemans/bactoscoop.git@v0.1.1"

For uv, use uv pip install --python .venv "bactoscoop @ git+https://github.com/Bart-Steemans/bactoscoop.git@v0.1.1". Select the tag shown in Releases when a newer release is available. To work on the development code instead:

git clone https://github.com/Bart-Steemans/bactoscoop.git
cd bactoscoop
python -m pip install -e .

An editable development install follows changes in your checkout. It may differ from the stable release. All installation commands must use your Python 3.10 analysis environment. Select that environment's kernel in JupyterLab.

Run a walkthrough

The wheel contains the Python package; the large TIFFs, masks, SVM models, and notebooks are supplied separately. Download and extract the v0.1.1 example archive, or use the examples/ folder in a cloned checkout.

Open examples/3_channel_example_walkthrough.ipynb or examples/5_channel_example_walkthrough.ipynb in JupyterLab. Run cells from top to bottom. The first cell locates the downloaded examples and copies the selected dataset into a fresh folder under ~/bactoscoop_runs/; the supplied images, masks, and saved reference outputs stay intact. If you open the notebook elsewhere, set the BACTOSCOOP_EXAMPLES_DIR environment variable to the downloaded examples folder before starting JupyterLab.

The examples reuse the supplied masks by default. Set RUN_SEGMENTATION = True for fresh Omnipose inference; the first inference may download model weights. Set PIXEL_SIZE_UM to your microscope calibration. The first cell prints the working output folder. Meshes, curated meshes, and feature tables are saved there. The example-specific SVM models are copied with their datasets; inspect their predictions before using those models on different images.

Segmentation on CPU or GPU

Segmentation automatically runs on the CPU when a usable CUDA GPU is unavailable. No additional configuration is required for the standard installation.

If CUDA-enabled PyTorch and a compatible NVIDIA GPU are available, Omnipose can use GPU acceleration. The walkthroughs include a check to verify whether PyTorch detects CUDA.

Optional GPU acceleration

To enable GPU acceleration, first install BactoScoop following the standard installation instructions. Then:

1. Check GPU compatibility: Consult the Omnipose documentation for GPU support, requirements, and Python compatibility.

2. Install CUDA-enabled PyTorch: Use the official PyTorch installer to select an appropriate CUDA-enabled build for your GPU and NVIDIA driver. Install the corresponding PyTorch and torchvision versions in your BactoScoop environment.

   For reference, we have successfully tested segmentation on Windows with Python 3.10, an NVIDIA RTX A6000, PyTorch 2.7.1+cu118, and torchvision 0.22.1+cu118, installed using:

   python -m pip install --upgrade torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu118
   

   This is an example of a working configuration, not a requirement. Other supported versions can be found in the PyTorch previous versions documentation.

3. Verify CUDA availability: Run the following command in the same environment:

   python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
   

   If the output is CUDA available: True, PyTorch can access CUDA. If it returns False, segmentation will still run on the CPU.

Important: Restart your Jupyter kernel after installing or updating PyTorch.

Expected input images (and masks)

Place one 2D TIFF per channel and field in the same folder. The shared name before _C1, _C2, and so on identifies a field. C1 is the phase image in the examples.

your_images/
  sample_XY1_C1.tiff
  sample_XY1_C2.tiff
  sample_XY1_C3.tiff
  sample_XY2_C1.tiff
  sample_XY2_C2.tiff
  sample_XY2_C3.tiff
  masks/
    sample_XY1_C1_cp_masks.tif
    sample_XY2_C1_cp_masks.tif

Channels and masks for one field must have the same height and width. BactoScoop can segment the phase image with Omnipose or use masks made by another program. Masks must be 2D integer images with background 0 and distinct cells labeled consecutively 1 through N. Check mask outlines before building meshes. Set the correct pixel size in µm/pixel and verify channel registration when measuring signals across channels.

Walkthroughs and the analysis stages

An example script of how we used BactoScoop to screen thousands of bacterial samples is also available in the example folder (named "BactoScoop Parallel Processing.py").

Load pickle-based SVM models and saved mesh tables only from trusted sources: pickle files can execute code when loaded. Use Parquet to share feature tables.