feat: ranking & filtering support for biolink:statistical_significance_qualifier

[SkyeAv]

Summary

Add support for the new biolink:statistical_significance_qualifier across Shepherd so incorporated ARAs can rank and filter on it:

1. Ranking — treat the qualifier as an additive scoring signal.
   • aragorn_score (primary goal — Aragorn's live ranker; Shepherd-specific, no RTX analog).
   • arax_rank (keep Shepherd's dict-based port of ARAX_ranker.py in sync with the equivalent RTX change).
2. Filtering — a new shared filter_edges_by_statistical_significance operation (worker + shepherd_utils helper) that removes KG edges whose significance band falls below a minimum_significance threshold, wired into the Aragorn pipeline.

Why

biolink-model added a standardized statistical significance qualifier (enum StatisticalSignificanceQualifierEnum: very_strongly_significant / strongly_significant / significant / suggestive / not_significant) on the root association class. As KPs/Retriever begin populating it, Shepherd ARAs should prioritize and be able to filter on well-supported evidence.

Dependencies / related

• Upstream model: feat: statistical significance qualifier on associations biolink/biolink-model#1766
• Retriever pass-through (pending): feat: implement pass through logic for the new biolink:statistical_significance_qualifier retriever#197
• Equivalent RTX (ARAX) work: feat: implement ranking and filtering logic for the new biolink:statistical_significance_qualifier RTXteam/RTX#2858

Key assumptions

• Because the qualifier is_a: statement_qualifier (a descendant of qualifier), BMT/Retriever will most likely deliver it in edge.qualifiers[]; some KPs may send it as an edge.attributes[] entry. We check both locations.
• Rollout is incremental, so edges without the qualifier are neither penalized in ranking nor removed by the filter (only edges that explicitly carry a below-threshold band are removed).
• Numeric p-values remain authoritative; the qualifier is a conservative additive companion.

Implementation plan + drafted issue comments live in PLAN.md on branch feat/implement-ranking-logic-for-the-statistical-significance-qualifier.

[SkyeAv]

What this PR adds

PR: #135 — this work is now proposed to the upstream repo (cross-repo PR from SkyeAv/shepherd to BioPack-team/shepherd:main).

Ranking + filtering support for biolink:statistical_significance_qualifier (shepherd#134), built for a minimal diff.

One shared source of truth, reused everywhere:

• shepherd_utils/statistical_significance_qualifier.py (NEW) — band→score + ordinal tables, a source-agnostic trust weight, and get_statistical_significance(edge) (qualifiers-only lookup).
• aragorn_score — scores the qualifier. This is the shared Aragorn + BTE ranker, so this one change updates both ARAs (no separate BTE ranker exists).
• arax_rank — same additive score, keeping Shepherd's dict port of ARAX_ranker.py in sync with the RTX change (feat: implement ranking and filtering logic for the new biolink:statistical_significance_qualifier RTXteam/RTX#2858).
• filter_edges_by_statistical_significance (NEW shared function + super-thin worker + compose service) — ordinal edge removal, shipped as runnable infrastructure and wired into the Aragorn + BTE lookup workflows with minimum_significance=suggestive (removes only not_significant; qualifier-less edges kept). It is inert until retriever#197 ships qualifier-bearing edges, so it changes no production behavior today (see comment 6).

The ranking lands in code already in the Aragorn/BTE pipeline, so it takes effect with zero workflow changes. No changes to message schemas, DB, or broker. Qualifier-less edges are untouched.

[SkyeAv]

Where the qualifier lives (and why we only look there)

statistical_significance_qualifier is_a: statement_qualifier, a descendant of qualifier, so BMT/Retriever route it into edge.qualifiers[], and that's the only place we read it:

{"qualifier_type_id": "biolink:statistical_significance_qualifier", "qualifier_value": "significant"}

get_statistical_significance(edge) reads edge.qualifiers only and strips any biolink: prefix from the value. This matches the ARAX PR (RTX#2859), which was refactored to qualifier-only (its earlier defensive edge.attributes lookup and decorator registration were removed). If a KP is ever found to deliver the qualifier as an attribute, the shared helper takes a one-line fallback (and ARAX would need the same change).

[SkyeAv]

Edges without the qualifier are NOT penalized

The qualifier is rolling out incrementally across KGs. Penalizing edges that lack it would unfairly downrank sources that haven't adopted it. So:

• Ranking: only bands with a positive score (very_strongly_significant…suggestive) add a boost; not_significant and qualifier-less edges keep their existing score unchanged.
• Filtering: only edges that explicitly carry a below-threshold band are removed; qualifier-less edges are always kept.

This asymmetry is intentional during rollout. Revisit the trust weight once adoption is universal.

[SkyeAv]

How Aragorn/BTE scoring uses the qualifier

(aragorn_score is the shared ranker for both Aragorn and BTE, so this one change covers both ARAs.)

Ranker.get_edge_values() turns edge attributes into per-source property weights; each property contributes an admittance -1/log(weight) to the graph Laplacian used for effective-resistance scoring. We add statistical_significance as a new property:

• band → property_weight via the shared SIGNIFICANCE_BAND_SCORES (0.70 … 0.0)
• source_weight = SIGNIFICANCE_SOURCE_WEIGHT (0.5, conservative)

The qualifier is a property of the evidence, not a knowledge source, so it is deliberately not routed through the per-source get_source_weight() (whose fallback would zero it for sources already in a profile's source_weights). Max effective weight 0.70 × 0.5 = 0.35 → a bounded boost. not_significant adds nothing (guarded by property_w > 0, also avoids log(0)).

[SkyeAv]

arax_rank: keeping the dict port in sync

workers/arax_rank/ranker.py is a dict-based replication of RTX ARAX_ranker.py. The RTX PR added the qualifier there; Shepherd's port is a separate codebase that won't receive that edit, so this PR ports the same change. Mirroring the current (post-refactor) RTX code, the trust weight comes from the shared SIGNIFICANCE_SOURCE_WEIGHT constant (0.5) — not known_attributes_to_trust (RTX moved it out of that dict in the same refactor) — and the qualifier is looked up separately (categorical bypass) and appended as band_score × SIGNIFICANCE_SOURCE_WEIGHT to edge_attribute_score_list in _calculate_edge_confidence(). It flows through the existing _combine_scores() loop unchanged.

[SkyeAv]

Filtering: filter_edges_by_statistical_significance

New shared function shepherd_utils.shared.filter_edges_by_statistical_significance(message, minimum_significance, logger), plus a super-thin worker (included) and its compose.yml service. The worker is async/inline (no process pool) and does a single linear scan — fast and non-blocking, mirroring filter_kgraph_orphans.

What it does: removes KG edges whose band ordinal is below minimum_significance (very_strongly_significant=4 … not_significant=0). minimum_significance=suggestive removes only not_significant. Analyses/results that lose a required edge binding are pruned so the TRAPI stays valid; filter_kgraph_orphans (downstream) removes the orphaned nodes. Qualifier-less edges are kept.

Wired into the Aragorn + BTE lookup workflows right after aragorn.score (this is the first edge-attribute-filter slot in these workflows; the existing filters are sort_results_score, filter_results_top_n, filter_analyses_top_n, filter_kgraph_orphans):

{"id": "filter_edges_by_statistical_significance",
 "parameters": {"minimum_significance": "suggestive"}}

The default suggestive is the most conservative meaningful threshold — it removes only edges explicitly labeled not_significant, and qualifier-less edges (i.e. everything today) are kept. Until retriever#197 ships, no edges carry the qualifier, so the filter removes 0 edges and changes no production behavior; it auto-activates when qualifier data starts flowing. The threshold is trivially adjustable per ARA / per query later. The worker reads the nested parameters dict (note: the older filter_*_top_n workers read flat keys and silently use defaults — this one honors the parameter).

Caveat: if a KP later mislabels a genuinely-significant edge as not_significant, that edge gets hidden — but that is the qualifier/source's fault (Retriever controls pass-through), not the filter's, and it is recoverable by bumping the threshold.

[SkyeAv]

Two scope findings that shaped this PR

1. aragorn_score is the shared Aragorn + BTE ranker. Both ARAs' workflows run … → aragorn.score → sort_results_score → filter_results_top_n → filter_kgraph_orphans (confirmed in workers/aragorn/worker.py and workers/bte/worker.py). So the ranking change covers both ARAs at once — there is no separate BTE ranker to modify.

2. The RTX remove_edges_by_* KG-filter had no analog in Shepherd. No worker or shared util removed edges by attribute/qualifier; Aragorn/BTE had no framing for edge-level attribute filtering. This PR adds that framing: the filter ships as reusable infrastructure (shared function + thin worker) and is wired into the Aragorn + BTE lookup workflows as the first edge-attribute-filter slot, with the most conservative meaningful default (suggestive = remove only not_significant). It is inert until retriever#197 ships qualifier-bearing edges, so it changes no production behavior today.

[SkyeAv]

Score & ordinal mappings (single source: shepherd_utils/statistical_significance_qualifier.py)

Band	Ordinal (filter)	Rank score	Effective (×0.5 trust)
very_strongly_significant	4	0.70	0.35
strongly_significant	3	0.55	0.275
significant	2	0.40	0.20
suggestive	1	0.15	0.075
not_significant	0	0.00	0.00

filter(minimum_significance=significant) removes ordinal < 2 (suggestive, not_significant).

[SkyeAv]

Testing

• tests/unit/test_statistical_significance_qualifier.py — lookup (qualifiers-only, prefix strip, attributes ignored), tables.
• tests/unit/aragorn/test_aragorn_score_ranker.py — qualifier extraction + scoring; not_significant adds nothing.
• tests/unit/test_arax_rank_ranker.py — additive boost alongside pValue.
• tests/unit/test_filter_edges_by_statistical_significance.py — ordinal removal, qualifier-less kept, result pruning, worker reads nested params.

Run: tox. Integration via scripts/test_shepherd.py is forward-looking until retriever#197 ships.

[SkyeAv]

Summary (non-technical)

The biolink data model now has a standard label for how statistically significant a piece of evidence is ("very strongly significant" … "not significant"). This PR lets Shepherd ARAs use that label:

1. Ranking — results backed by more significant evidence rank a bit higher. Results without the label are unaffected.
2. Filtering — ARAs can drop low-significance evidence (e.g. "remove anything below suggestive").

Conservative by design so it doesn't disrupt existing results while adoption ramps up across the Translator KG ecosystem. Depends on Retriever populating the label (retriever#197).

[SkyeAv]

Dependencies

• ✅ Biolink model: approved (feat: statistical significance qualifier on associations biolink/biolink-model#1766)
• ⏳ Retriever pass-through: pending (retriever#197)
• ✅ This PR: Shepherd ranking (aragorn_score + arax_rank) + filtering
• 🔜 Future: significance-aware path scoring in score_paths (TODO); revisit ranking tunables post-rollout

[SkyeAv]

Decisions on where statistical significance filtering lives (Gandalf, not Shepherd) are now recorded in #136.

[SkyeAv]

Status update: the filtering portion of this work has been removed from #135 per #136 — implicit filtering for the statistical significance qualifier belongs in Gandalf, not Shepherd. The ranking/scoring portion (aragorn_score for Aragorn + BTE, arax_rank dict port) remains in #135, now titled "feat: ranking for biolink:statistical_significance_qualifier".

Full CI-equivalent test suite (tox, py312 + coverage envs) passes: 502 passed, total coverage 56.66%.

Follow-ups spawned by #136:

• TRAPI standard for overriding implicit filtering defaults (statistical significance cutoff, negated edges) retriever#198 — TRAPI standard for overriding the default significance cutoff (+ negated edges)
• retriever#197 — Retriever pass-through for the qualifier (unchanged dependency)