# Understanding Ultrasound Metrics

Ultrasound data quality assessment is fundamental to diagnostic accuracy, system optimization, and research advancement.
This library provides quantitative metrics to objectively evaluate ultrasound data at multiple stages of the imaging pipeline.

## Why Use Metrics in Ultrasound?

Quantitative metrics enable objective assessment across multiple applications:

- **Automated data cleaning**: Filter low-quality acquisitions from large datasets across operators and systems
- **System evaluation**: Compare hardware, algorithms, and reconstruction techniques
- **Machine learning**: Loss functions for neural beamformers and image reconstruction algorithms
- **Research benchmarking**: Enable reproducible comparisons between methods
- **Proxy measures**: Use easy-to-calculate metrics as a simpler proxy for difficult-to-acquire metrics (e.g. sensitivity to neural activity)

> **⚠️ Note:** This software is intended for research purposes only and is not clinical-grade software.

## Why Ultrasound-Specific Metrics?

While many data quality metrics exist in general computer vision and signal processing libraries ([scikit-image](https://scikit-image.org/docs/stable/api/skimage.measure.html), [PIQ](https://piq.readthedocs.io/en/latest/usage_examples.html)), ultrasound presents unique challenges that require specialized approaches:

- **Multi-channel phase**: Unlike natural images, ultrasound systems capture signals from multiple array elements with precise phase relationships. Metrics like **coherence factor** exploit these multi-channel characteristics to assess beamforming quality—something rarely found outside ultrasound applications.
- **Sub-pixel precision**: Some metrics, such as the point-spread function (PSF), require specialized interpolation algorithms to characterize at sub-pixel precision.
- **Signal Characteristics**: Ultrasound systems provide access to raw radiofrequency data before image formation, which may have their own non-image metrics.

Despite these unique concerns, many `ultrasound-metrics` can also be applied to conventional
signal data or images.

## Metric Categories

Here are a couple ways to group ultrasound metrics.
For equations and more detail, refer to the {doc}`../example_gallery/index` and {doc}`../autoapi/index`.

### Contrast and Signal Quality
**CNR** and **gCNR** quantify distinguishability between tissue types, while **coherence factor** evaluates multi-channel phase alignment unique to array-based imaging systems.

### Resolution and Sharpness
**FWHM** measures point spread function width with ultrasound-specific interpolation, while **side lobe level** quantifies unwanted acoustic energy outside the main beam.

### Radiofrequency Analysis
**RF SNR** and **clipping detection** operate on raw acoustic signals before image reconstruction, providing insights unavailable in post-processed images.

## Why a Dedicated Library?

While existing libraries implement subsets of ultrasound metrics ([ultraspy](https://ultraspy.readthedocs.io/en/latest/), [CUBDL](https://gitlab.com/dongwoon.hyun/cubdl)), this library provides several key advantages:

- **Cross-Platform Compatibility**: Built on the **Array API standard**, enabling seamless operation across NumPy, JAX, PyTorch, and CuPy backends—unlike libraries that separately reimplement metrics for each framework.
- **Comprehensive Coverage**: Unified implementation of metrics across the full ultrasound pipeline, from raw RF signals to final images.

## Implementation Approach

Detailed implementation guidance, mathematical formulations, and validation procedures are provided in the {doc}`../autoapi/index` and {doc}`../getting_started` sections.