[Epic] Implement composite genetic-distance threshold scoring and reusable component metrics #1750

Goal

Replace the current cluster-count-only Threshold Stability recommendation with a transparent composite score based on network component structure.

The threshold recommendation must use genetic-distance links only. The same reusable component-metric calculator should also support Network Statistics, where calculations use the currently visible network.

The resulting "Component Structure Score" is decision support, not a definitive cutoff.

Current state

MicrobeTrace already has:

• A cached, sorted genetic-distance threshold sweep
• Cluster, component, singleton, and largest-cluster counts
• Threshold Stability suggestions based on flat cluster-count regions
• A Network Statistics implementation on codex/network-statistics-updates

Missing functionality includes normalized component metrics, Gini, multi-cluster balance, composite scoring, and an explicitly genetic-only threshold edge policy.

V1 scope

Shared component metrics

Create a reusable calculator that accepts an explicit node and edge set and returns:

• Number of clusters
• Number of singletons
• Largest-cluster size and fraction (L1)
• Second-largest-cluster size and fraction (L2)
• Clustered fraction and singleton fraction
• Gini coefficient of component sizes
• Mean and median cluster size
• Largest-to-mean and/or largest-to-median cluster-size ratio
• L2/L1 as an optional advanced diagnostic

Define behavior for empty networks, all-singleton networks, one-cluster networks, and tied cluster sizes.

Edge-selection policies

Support separate, explicit policies:

• Threshold recommendation: threshold-controlled genetic TN93 or SNP links only; exclude epi/contact-only links and prevent mixed-origin links from becoming always-present epi edges.
• Network Statistics: use the currently active/visible nodes and links, including the user's filters and loaded link types.
• Preserve documented nearest-neighbor behavior for each policy.

Composite threshold score

For every distinct genetic-distance threshold:

1. Update connected components using the existing sorted-edge/union-find sweep.
2. Calculate the component metrics.
3. Normalize the metrics across the sweep.
4. Calculate a documented, deterministic Component Structure Score.
5. Rank candidate thresholds and identify the recommended threshold or range.

The implementation must document:

• Metric direction and normalization
• Default weights
• Tie-breaking behavior
• Treatment of singletons and minimum cluster size
• Why a threshold was recommended

Do not recompute connected components independently at every threshold.

User interface

Update Threshold Stability to display:

• Recommended threshold or range
• Component Structure Score
• Cluster count
• Largest-cluster fraction
• Clustered or singleton fraction
• Gini coefficient
• Multi-cluster balance metric
• Plain-language explanation and decision-support disclaimer
• Action to apply a recommendation

Expose L2/L1 as an advanced metric if retained.

Extend Network Statistics to show the applicable component metrics for the current visible network.

Tests

Add unit tests covering:

• Empty and all-singleton networks
• One cluster
• Multiple balanced clusters
• One dominant cluster
• Tied component sizes
• Genetic-only, epi-only, and mixed-origin links
• TN93 and SNP thresholds
• Nearest-neighbor mode
• Deterministic scores and tie-breaking
• Cache invalidation after data or edge-policy changes

Add Cypress coverage verifying that:

• Recommendations update when the genetic threshold data changes
• Applying a recommendation updates the visible network
• Epi-only links do not affect threshold recommendations
• Network Statistics responds to visible-network filtering
• Metric explanations and score details are accessible

V2 follow-up scope

Design the calculator so later work can support:

• Adjustable score weights
• Adjustable threshold
• Adjustable minimum cluster size
• Included/excluded link origins
• Nearest-neighbor policy selection
• Interactive score recomputation
• Comparing alternative score definitions
• Average genetic distance among known epi/contact pairs
• Exporting threshold sweeps and score components

These controls do not all need to be exposed in V1, but V1 should not require rewriting the metric engine to add them.

Validation

Identify representative datasets for:

• Fragmented networks
• Dominant-cluster networks
• Multiple balanced clusters
• High- and low-participation networks
• Networks with epi/contact and genetic links
• TN93 and SNP workflows
• Small and large performance cases

Record expected qualitative behavior and compare the recommendation with expert-selected thresholds.

Acceptance criteria

• Threshold recommendations are computed exclusively from eligible genetic links.
• Network Statistics uses the active visible-network policy.
• Both features consume the same component-metric calculator.
• All V1 metrics are calculated and displayed with documented definitions.
• The Component Structure Score is deterministic, explainable, and configurable internally.
• The threshold sweep reuses cached sorted edges and incremental component updates.
• Existing threshold, mixed-origin, and nearest-neighbor behavior has regression coverage.
• Representative validation datasets and expected outcomes are documented.