Processing Tab

The Processing tab handles the complete microscopy image analysis workflow, from loading ND2 files to extracting cell traces.

Workflow Overview

  1. Load Microscopy File - Browse and select your ND2 file

  2. Configure Channels - Select phase contrast and fluorescence channels with features

  3. Set Output Folder - Choose where to save processing results

  4. Configure Parameters (optional) - Adjust FOV range, batching, and workers

  5. Run Workflow - Execute the complete processing pipeline

  6. Merge Results (optional) - Combine multiple samples into merged CSVs

Step-by-Step Guide

1. Load Microscopy File

  1. Click Browse next to “Microscopy File:”

  2. Select your ND2 file

  3. The filename appears once loaded successfully

2. Configure Channels

Phase Contrast Channel:

  1. Select the phase contrast channel from the dropdown

  2. In the “Phase Contrast Features” list, multi-select (Ctrl+Click or Shift+Click) the features you want

    • Common features: area, aspect_ratio

Fluorescence Channels:

  1. Select a fluorescence channel from the dropdown

  2. Select a feature from the feature dropdown

  3. Click Add to add the channel-feature combination

  4. Repeat for additional channels

  5. To remove: select in “Fluorescence Features” list and click Remove Selected

3. Set Output Folder

  1. Click Browse next to “Save Directory:”

  2. Select where processed results will be saved

  3. This directory will contain:

    • raw.zarr, crops.zarr, traces/ - Pipeline outputs

    • traces_merged/ - Merged CSVs (if you use the merge feature)

4. Configure Parameters (Optional)

Check Set parameters manually to show advanced options:

  • positions: Position range (e.g. all, 0:10)

  • n_workers: Parallel workers (default: 1)

  • n_workers: Parallel threads (default: 2, match to CPU cores)

  • background_weight: Fluorescence background correction (0-1 range)

    • 0.0 = no correction

    • 1.0 = full background subtraction

    • Values between 0 and 1 apply partial correction

5. Run Workflow

  1. Click Start Complete Workflow

  2. Progress bar appears during processing

  3. Click Cancel to stop if needed

  4. Status message shows completion

Processing Steps:

  1. Copying - Extract frames from ND2/CZI to Zarr format

  2. Segmentation - Cell segmentation using phase contrast (requires PC channel)

  3. Tracking - Track cells across time points (requires PC channel)

  4. Background Estimation - Background estimation for fluorescence (requires FL channels)

  5. Cropping - Extract cell bounding box crops (requires PC channel)

  6. Extraction - Generate feature traces to CSV (always runs if PC configured)

  7. Caching - Generate visualization levels for all channels

6. Assign FOVs to Samples (for Multiple Samples)

  1. In the Assign FOVs section (right side):

    • Click Add Sample to create a new row

    • Enter a sample name (e.g., sample1)

    • Enter FOV range (e.g., 0-5 for FOVs 0 through 5)

    • Use format 0, 2, 4-6 for non-consecutive FOVs

  2. Use Remove Selected to delete rows

  3. Click Save to YAML to save sample definitions

7. Merge Processing Results

  1. Click Browse next to Sample YAML: and load your samples file

  2. Click Browse next to Folder of processed FOVs: - select your processing output

  3. Click Browse next to Output folder: - where merged CSVs will be saved

  4. Click Run Merge

  5. Merged CSVs are created with sample names

Output Structure

After processing, your output directory contains:

output_dir/
├── raw.zarr/                        # Raw frames + segmentation, tracking, background
├── crops.zarr/                      # Per-cell crop tensors and metadata
├── traces/                          # Per-position trace CSVs
│   ├── position_0.csv
│   ├── position_1.csv
│   └── ...
├── traces_merged/                   # Merged results (after merge step)
│   ├── sample1_merged.csv
│   └── sample2_merged.csv
└── processing_config.yaml           # Metadata and parameters

Tips and Tricks

  • Start Small: Process 1-2 FOVs first to verify parameters

  • Check Memory: Large datasets may need smaller batch sizes

  • Monitor Progress: Watch status messages for each processing stage

  • Cancel Safely: Canceling preserves completed FOVs

  • Reuse Configs: Save sample YAML files for consistent batch processing

Common Issues

“Workflow cancelled” appears immediately:

  • Check if output directory has write permissions

  • Verify ND2 file exists and is readable

  • Reduce batch_size if memory is limited

Fewer cells detected than expected:

  • Check phase contrast channel selection

  • Verify cell features are selected

  • Consider adjusting segmentation parameters (advanced)

Fluorescence traces are all zero:

  • Ensure fluorescence channels are configured

  • Verify fluorescence features are added to queue

  • Check background_weight isn’t set to 1.0 with weak signal

Next Steps

  • Use the Visualization Tab to inspect your results

  • Load merged CSVs in the Analysis Tab for model fitting

  • See Visualization Tab Guide for quality control