Installation

Requirements

exo2micro is a Python package. You need:

  • Python 3.9 or newer. Most conda/miniforge or pyenv installations will work. If you don’t already have Python set up, install Miniforge — it’s the quickest path.

  • A working Jupyter environment if you want to use the interactive GUI (recommended for first-time users).

Getting the code

git clone https://github.com/kfollette/Exo2Micro.git
cd Exo2Micro

Installing the dependencies

All dependencies are available via pip:

pip install numpy scipy opencv-python-headless matplotlib \
            astropy tifffile Pillow ipywidgets

Or, if you prefer a single copy-paste command with version pins:

pip install "numpy>=1.22" "scipy>=1.8" "opencv-python-headless>=4.5" \
            "matplotlib>=3.5" "astropy>=5.0" "tifffile>=2022.0" \
            "Pillow>=9.0" "ipywidgets>=8.0"

ipywidgets is only needed for the interactive GUI; everything else is required.

Setting up your raw image directory

exo2micro expects your raw images to live in a directory tree with one folder per sample:

raw/
  CD070/
    Sample001_PreStain_SybrGld.tif
    Sample001_PostStain_SybrGld.tif
  CD063/
    Sample002_PreStain_SybrGld.tif
    Sample002_PostStain_SybrGld.tif
    Sample002_pre_run3_DAPI.tiff
    Sample002_post_run3_DAPI.tiff

Filename rules

Each raw image filename must follow these rules:

  1. The filename must end with .tif or .tiff (case-insensitive — .TIF and .TIFF are also fine).

  2. The filename must contain pre or post (case-insensitive) somewhere in the basename. This tells exo2micro whether the file is a pre-stain or post-stain image. The substring can be anywhere — PreStain, pre, Pre_run3, and so on all work.

  3. The filename must end with _<DyeName>.tif (or .tiff), where <DyeName> is your dye identifier. The dye name is the substring between the last underscore and the extension.

  4. Dye names must not contain underscores. SybrGld and DAPI and Cy5 are fine; SybrGld_microbe is not — the loader will only see microbe. Use SybrGldMicrobe or similar instead.

Each sample directory must contain exactly one pre-stain and one post-stain file per dye. If multiple dyes are stained on the same sample, you can have multiple pre/post pairs in the same folder (see CD063 above), but no more than one of each per dye.

Examples

Valid filenames (all of these work):

  • Sample001_PreStain_SybrGld.tif

  • Sample001_PostStain_SybrGld.tif

  • my_2024-03-15_pre_run3_DAPI.tiff

  • whatever_post_Cy5.TIF

Invalid filenames (these will be skipped or rejected):

  • Sample001_PreStain_SybrGld_microbe.tif — dye name has an underscore. The loader will parse the dye as microbe, which is almost certainly not what you want.

  • Sample001_pre_post_SybrGld.tif — contains both pre and post. Ambiguous — the loader can’t tell which one applies.

  • Sample001_SybrGld.tif — contains neither pre nor post. The loader has no way to classify the stain type.

  • CD050/Sample004a_PreStain_SybrGld.tif and CD050/Sample004b_PreStain_SybrGld.tif — two pre-stain files for the same dye in one sample. The loader expects exactly one of each.

What happens when a filename is wrong

When you click ▶ Run Pipeline in the GUI or call SampleDye.run() from a script, the pipeline iterates over every (sample, dye) task you requested. Each task is loaded independently:

  • If the filenames for that (sample, dye) are clean, processing proceeds normally.

  • If the loader can’t cleanly resolve the requested pair, the task fails with a multi-line “FILE PROBLEM” message in the output and the run continues with the next task.

  • All failed tasks are listed in a “PROBLEMS” section at the bottom of the summary table after the batch finishes.

This means a single broken filename doesn’t block your whole batch — other dyes and other samples keep processing. You see exactly what broke and why, all in one place at the end. See Troubleshooting for the catalogue of error messages and what each one means.

If your directory layout is different, you can pass a custom raw_dir to the GUI or the scripting API.

Verifying the install

Open a Python prompt and confirm the package imports:

import exo2micro as e2m
print(e2m.__version__)

If that prints 2.3.0 (or newer), you’re set.

Next: Quickstart.