Merge Workflow

The merge workflow combines processed FOV results into sample-specific CSV files for analysis. This is essential when you have multiple experimental conditions or time points.

When to Use Merge

• Multiple experiments: Different samples or conditions

• Time series: Different time points as separate samples

• Technical replicates: Multiple slides analyzed as separate samples

• Spatial samples: Different regions or positions

Overview

1. Assign FOVs to samples - Define which FOVs belong to each sample

2. Save sample configuration - Create YAML file for reproducibility

3. Configure merge paths - Select input and output directories

4. Run merge - Generate per-sample CSV files

5. Verify results - Check merged files before analysis

Step-by-Step Guide

1. Assign FOVs to Samples

Using the Processing Tab:

1. In the Processing tab, find the Assign FOVs section (right side)

2. Click Add Sample to create new rows

3. Fill in each row:

   • Sample Name: Descriptive name (e.g., control, treatment, timepoint_1)

   • FOVs: Range or list of FOV indices

FOV Specification Formats:

Format	Example	Description
Single FOV	5	Individual FOV
Range	0-10	FOVs 0 through 10 (inclusive)
Multiple ranges	0-5, 10-15	Two separate ranges
Mixed	0, 2, 4-7, 10	Individual FOVs and ranges

Example Sample Assignments:

Sample Name     | FOVs
---------------|---------
control_01     | 0-9
control_02     | 10-19
treatment_01   | 20-29
treatment_02   | 30-39
edge_control   | 95-99

Managing Samples:

• Add Sample: Creates new row for another sample

• Remove Selected: Deletes selected rows (check boxes to select)

• Rows can be edited by clicking directly in cells

2. Save Sample Configuration

1. After defining all samples, click Save to YAML

2. Choose a location and filename (e.g., samples.yaml)

3. Why save YAML?

   • Reuse for later analyses

   • Share with collaborators

   • Documentation of sample organization

   • Prevent mistakes in large projects

3. Configure Merge Settings

File Path Configuration:

1. Sample YAML:

   • Click Browse next to “Sample YAML:”

   • Select your saved .yaml file

   • Loaded samples appear in table

2. Folder of processed FOVs:

   • Click Browse next to “Folder of processed FOVs:”

   • Select directory containing fov_000/, fov_001/, etc.

   • Must be the same directory used for processing

3. Output folder:

   • Click Browse next to “Output folder:”

   • Choose where merged CSVs will be saved

   • Usually same as processing directory for organization

Verification:

• Check that all sample paths exist

• Verify FOV ranges don’t overlap

• Ensure output directory has write permissions

4. Run Merge

1. Verify all paths are correct

2. Click Run Merge button

3. Progress appears:

   • Status message updates

   • Processing shows current sample

4. Completion:

   • “Merge completed successfully”

   • Shows location of created files

5. Verify Results

Check Created Files:

1. Navigate to output directory

2. Verify files exist:

   output_dir/
   ├── control_01_merged.csv
   ├── control_02_merged.csv
   ├── treatment_01_merged.csv
   ├── treatment_02_merged.csv
   └── edge_control_merged.csv
   

3. Spot-check files:

   • Open in spreadsheet software

   • Verify expected number of cells

   • Check FOV values in data

CSV Format:

fov,cell,frame,good,position_x,position_y,area_ch_0,intensity_total_ch_1
0,0,0,True,100.5,200.3,450,1234.5
0,0,1,True,101.2,199.8,455,1356.2
...

• fov: Original FOV index (preserved for reference)

• cell: Cell ID within original FOV

• frame: Time frame index

• good: Quality flag from Visualization tab

• position_x/y: Cell centroid coordinates

• area_ch_X: Morphological features from phase contrast

• intensity_*_ch_X: Fluorescence features

Advanced Usage

Using Inspected Data

If you performed quality control in the Visualization tab:

1. Save inspected CSV: traces_inspected.csv

2. Run merge with inspected file

3. Only “good” traces will be included in merged results

Benefit: Higher quality data for fitting, as bad traces are excluded

Batch Processing Multiple Experiments

For multiple experiments:

1. Process all experiments to separate folders

2. Create separate sample YAML for each experiment

3. Run merge for each experiment

4. Combine all CSVs in Analysis tab if needed

FOV Verification

Before merging:

# Check available FOVs
ls your_processing_folder/ | grep "fov_"

# Should show: fov_000, fov_001, ..., fov_099

Ensure your YAML ranges match existing FOVs to avoid errors.

YAML File Format

Example samples.yaml:

samples:
  - name: control
    positions: "0-10"
  - name: treatment
    positions: "11-20"
  - name: timepoint_1
    positions: "0, 5, 10-15"
  - name: timepoint_2
    positions: "16-25"

Manual Editing:

• Can edit YAML in text editor

• Follow format exactly (dashes, spaces)

• FOV strings use same specification as UI

Best Practices

Sample Naming

• Use descriptive, consistent names

• Include time points or conditions

• Avoid spaces (use underscores or hyphens)

• Examples:

  • cell_line_A_time0

  • experiment_1_dose_10uM

  • replicate_1

FOV Assignment

1. Keep biological samples together:

   • Same slide/experiment = different time points may be separate samples

   • Technical replicates = separate samples

2. Maintain spatial context:

   • Edge FOVs often have different behavior

   • Consider edge effects in biology

3. Balance sample sizes:

   • Similar number of cells per sample

   • Adjust if natural variation exists

File Organization

experiment_2024_01/
├── raw/
│   └── *.nd2 files
├── processing/
│   ├── samples.yaml
│   ├── processing_config.yaml
│   ├── fov_000/
│   ├── fov_001/
│   └── ...
└── merged/
    ├── control_01_merged.csv
    ├── treatment_01_merged.csv
    └── samples.yaml  # copy for reference

Troubleshooting

Common Errors

“Specified FOV range is invalid”:

• Check if FOV numbers exist (0-based indexing)

• Verify no negative numbers

• Ensure no overlaps between samples

“CSV file not found for FOV X”:

• Verify processing completed for that FOV

• Check fov_X/traces.csv exists

• Re-run processing if needed

“Output directory not accessible”:

• Check directory permissions

• Ensure path exists

• Try different output location

Recovery Strategies

Merge Failed Partially:

1. Check which files were created

2. Identify problematic sample in YAML

3. Remove or fix problematic assignment

4. Run merge again

Wrong Sample Assignment:

1. Edit YAML file to correct assignments

2. Delete incorrect merged files

3. Run merge with updated YAML

Next Steps

• Load merged CSVs in Analysis tab for fitting

• Compare parameters across conditions

• Use consistent naming for downstream analysis

The merge workflow is crucial for organizing your data before statistical analysis. Take care to document your sample assignments for reproducible science.