Score a map by how many known relationships it recovers

[timtreis]

metrics.known_relationships reports the share of annotated perturbation pairs whose similarity falls in either tail of the similarity distribution over all pairs — the EFAAR benchmark, and the field's usual way to ask whether a map recovers known biology. Two-sided, so opposing effects on one process count as related. A map carrying no information recovers twice the tail size, 10% by default.

Nothing in the package could answer this before, so the choice between representations and corrections could not be measured. tl.pathway_coherence scores one set at a time against random sets, which is a different question.

The annotation is taken either as source/target sets, as tl.gene_sets returns and as a mechanism annotation is shaped, or as the entity1/entity2 pair rows CORUM, hu.MAP, Reactome, SIGNOR and StringDB are distributed as. Pairs are counted once in either direction; nothing is paired with itself. No loader for those sources is included.

Ranks come from searchsorted over the sorted comparison distribution, matching EFAAR_benchmarking at 2935f21, rather than from interpolated percentiles. The tie convention is not cosmetic: on a rohban pipeline that keeps the degenerate-scale features, where 97% of the cosines are tied, percentile cutoffs report 0.688 against a 0.10 baseline where the reference definition reports 0.101.

Verified: 801 tests pass, mypy, ruff and the formatters clean. The new tests pin the reference's tie vector, the agreement with the definition computed pair by pair, that both tails count, and that the two annotation shapes give the same answer. On real data, BBBC021 against its mechanism annotation recalls 0.478 against 0.109 with the mechanisms shuffled; rohban against hallmark sits at chance, which is the verdict pathway_coherence already reaches there in tutorial 08.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.41270% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 89.25%. Comparing base (60eead3) to head (5bac585).

Files with missing lines	Patch %	Lines
src/mantispy/metrics/_relationships.py	98.38%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #99      +/-   ##
==========================================
+ Coverage   89.15%   89.25%   +0.09%     
==========================================
  Files          80       81       +1     
  Lines        5865     5928      +63     
==========================================
+ Hits         5229     5291      +62     
- Misses        636      637       +1     

Files with missing lines	Coverage Δ
src/mantispy/metrics/__init__.py	100.00% <100.00%> (ø)
src/mantispy/metrics/_evaluate.py	93.10% <ø> (ø)
src/mantispy/metrics/_relationships.py	98.38% <98.38%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.