count-label-changes 0.1.3
A plugin for Nellie that counts label changes. One type of typically used fission and fusion metric.
Requires Python: >=3.9

# Overview

This module is designed to work within the Nellie-Napari ecosystem to detect organelle label changes between frames. One of the metrics for fission and fusion quantification. It leverages processed data from Nellie, performs event detection, and outputs the results for further analysis.

# Tutorial

https://github.com/user-attachments/assets/8844b54e-8d8f-472d-bcda-500cb4e05389

# Features

- Prerequisite Checks: Ensures all necessary data and preprocessing steps are completed before running the analysis. 
- Event Detection: Calculates the number of fission (splitting) and fusion (merging) events of organelles across time frames. 
- Data Output: Saves detailed per-frame event data to a CSV file for further analysis or visualization. 
- User Feedback: Provides real-time notifications through Napari’s interface to guide users through the process.

# Requirements 
- Python 3.9 or higher 
- Packages:
  - nellie
  - pandas
- Operating System: 
  - Cross-platform (Windows, macOS, Linux)

# Installation
```bash
pip install count-label-changes
```

# Usage

1. Load an Image in Nellie:
   1. Before running the fission and fusion detection, load your imaging data into Nellie.
   2. Enable automatic voxel reassignment in the settings tab.
   3. Run the full analysis pipeline. 
2. Perform Voxel Reassignment (if not already done):
   1. If not already automatically completed, perform voxel reassignment in Nellie's preprocessing tab.
3. Run Feature Extraction in Nellie:
   1. Ensure that organelle features have been extracted and saved. This is must be done after voxel reassignment.
4. Run the plugin via `Plugins > Nellie Plugin > Count Label Changes`.

# Understanding the Detection Algorithm

The detection algorithm operates as follows:

### Data Loading:
- Loads organelle feature data from a CSV file generated by Nellie.

### Prequisite Verification:
- Checks if the image, organelle features, and reassigned labels are available. 
- Ensures that voxel reassignment has been performed if required.

### Event Calculation:
- Computes the number of unique organelle labels in each time frame.
- Calculates the difference in label counts between consecutive frames.
- Positive differences indicate fission events (organelles splitting).
- Negative differences indicate fusion events (organelles merging).

### Result Compilation:
- Saves per-frame event data to a CSV file for detailed analysis.

## Output

### Notifications:
- Provides status updates and error messages through Napari’s show_info function.

### CSV File:
- Saves a file named <filename>-label_changes.csv containing:
  - t: Time frame index.
  - label_differences: Difference in label counts compared to the total number of reassigned labels.
  - events_per_frame: Number of events occurring in each frame.

### Console Output:
- Displays a summary message with the total number of fission and fusion events and the path to the saved CSV file.

# Troubleshooting

“No image loaded. Load one through Nellie.”:
- Ensure that an image is loaded in Nellie before running the detection script.

“No organelle features found. Run feature extraction through Nellie.”:
- Run the organelle feature extraction step in Nellie to generate the necessary data.

“No reassigned image found. Run voxel reassignment through Nellie.”:
- Perform voxel reassignment in Nellie.

“Rerun feature extraction after running voxel reassignment.”:
- After voxel reassignment, you need to rerun feature extraction to update the organelle features.