Metadata-Version: 2.1
Name: segmentation_skeleton_metrics
Version: 4.12.32
Summary: Python package for evaluating neuron segmentations in terms of the number of splits and merges
Author-email: Anna Grim <anna.grim@alleninstitute.org>
License: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-image
Requires-Dist: tensorstore
Requires-Dist: tifffile
Requires-Dist: xlwt
Requires-Dist: zarr
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: interrogate; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: Sphinx; extra == "dev"
Requires-Dist: pygit2; extra == "dev"
Requires-Dist: furo; extra == "dev"

# SkeletonMetrics

[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
![Code Style](https://img.shields.io/badge/code%20style-black-black)

[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)

Python package that evaluates the topological accuracy of a predicted neuron segmentation by comparing it to a set of ground truth skeletons. Topological errors (e.g. splits and merges) are detected by examining skeleton edges and checking if the corresponding nodes belong to the same object in the segmentation. Once the accuracy of each edge has been determined, several skeleton-based metrics are then computed to quantify the topological accuracy.

The pipeline for computing skeleton metrics consists of three main steps:

<blockquote>
  <p>a. <strong>Label Graphs</strong>: Nodes in ground truth graphs are labeled with segmentation IDs.</p>
  <p>b. <strong>Error Detection</strong>: Compare labels of neighboring nodes to detect mistakes.</p>
  <p>c. <strong>Compute Metrics</strong>: Update graph structure by removing omit nodes and compute graph-based metrics.</p>
</blockquote>
<br>

<p>
  <img src="imgs/pipeline.png" width="800" alt="pipeline">
  <br>
  <b> Figure: </b>Visualization of skeleton metric computation pipeline, see Method section for description of each step.
</p>

## Method

### Step 1: Label Graphs

We start with a set of ground truth graphs stored as individual SWC files, where the "xyz" attribute represents voxel coordinates in an image. Each ground truth graph is loaded and represented as a NetworkX graph with these coordinates as a node-level attribute. The first step is to label the nodes of each graph with the corresponding segment IDs.

Note: Misalignments between the ground truth graphs and prediction segmentation are detected and corrected.

<p align="center">
  <img src="imgs/misalignment-example.png" width="400" alt="misalignment-example">
  <br>
  <b>Figure:</b> Node 4 is an example of a misalignment between a ground truth graph and segmentation.
</p>


### Step 2: Error Detection

To do...

<p>
  <img src="imgs/topological_mistakes.png" width="170" alt="Topological mistakes detected in skeleton">
  <br>
  <b> Figure: </b>Edges from graph superimposed on segmentation, where colors represent to segment IDs. From top to bottom: correct edge (nodes have same segment ID), split edge (nodes have different segment IDs), omit edge (one or two nodes do not have a segment ID), merged edge (segment intersects with multiple graphs).
</p>

### Step 3: Compute Metrics

To do...

- \# Splits: Number of connected components (minus 1) in a ground truth graph after removing omit nodes.
- \# Merges: Number of ground truth graphs that contain at least one merge.
- Omit Edge Ratio: Proportion of omitted edges.
- Split Edge Ratio: Proportion of split edges.
- Merged Edge Ratio: Proportion of merged edges.
- Edge Accuracy: Proportion of edges that are correct.
- Expected Run Length (ERL): Expected run length of connected ground truth graph after removing omit nodes.


## Usage

Here is a simple example of evaluating a predicted segmentation.

```python
import numpy as np
from xlwt import Workbook

from segmentation_skeleton_metrics.skeleton_metric import SkeletonMetric
from segmentation_skeleton_metrics.utils.img_util import TiffReader


def evaluate():
    # Initializations
    segmentation = TiffReader(segmentation_path)
    skeleton_metric = SkeletonMetric(
        groundtruth_pointer,
        segmentation,
        fragments_pointer=fragments_pointer,
        output_dir=output_dir,
    )
    full_results, avg_results = skeleton_metric.run()

    # Report results
    print(f"\nAveraged Results...")
    for key in avg_results.keys():
        print(f"   {key}: {round(avg_results[key], 4)}")

    print(f"\nTotal Results...")
    print("# splits:", np.sum(list(skeleton_metric.split_cnt.values())))
    print("# merges:", np.sum(list(skeleton_metric.merge_cnt.values())))

    # Save results
    path = f"{output_dir}/evaluation_results.xls"
    save_results(path, full_results)


if __name__ == "__main__":
    # Initializations
    output_dir = "./"
    segmentation_path = "./pred_labels.tif"
    fragments_pointer = "./pred_swcs.zip"
    groundtruth_pointer = "./target_swcs.zip"

    # Run
    evaluate()


```

<p>
  <img src="imgs/printouts.png" width=750">
</p>

Note: this Python package can also be used to evaluate the accuracy of a segmentation in which split mistakes have been corrected.

## Installation
To use the software, in the root directory, run
```bash
pip install -e .
```

## License
segmentation-skeleton-metrics is licensed under the MIT License.
