Skip to content

MS-supported prediction scores

Enable the opt-in ms-evidence-v1 policy with --ms-evidence. Hitlist is a regular dependency; installed, current data are optional. Missing or stale data remain explicitly unavailable and add no support. --ms-evidence-package DIR also enables the policy and uses a verified Hitlist MHC evidence package (using the producer's package verifier). A multi-modality EvidenceStore requires its own typed relation adapter and is currently rejected instead of being treated as the older package format.

evidence:
  ms:
    lookup: required             # auto (default), off, required
    package: /path/to/mhc-package
    parameters:
      gain: 1
      max_relaxation: null       # uncapped; an explicit cap must be >= 1
      reference_discount: 0.25
      prediction_ic50_cutoff: 50
      direct_admission: true
      weights:
        sequence: 0.25
        predicted_sequence: 0.5
        typed: 1
        recorded: 1
        predicted: 3
        experimental: 6
        monoallelic: 8

EpitopeConfig(ms_evidence={...}) accepts the same object as evidence.ms. CLI config overrides work, for example --config-value evidence.ms.parameters.gain=2.

For each exact peptide and patient allele, use the strongest applicable facet of each eligible observation. Exact peptide sequence, chemical form, MHC species and class constrain transfer. Unresolved class can contribute sequence support only. A typed multi-allelic source is not an experimentally restricted ligand. A qualifying class-I prediction is the selected affinity model's IC50 <= 50 nM; it contributes the prediction-supported facet only for the compatible allele. The current native package adapter does not assert source-prediction qualification without its model provenance. Unknown chemical forms and contaminants are held out.

Patient prediction alleles now use Topiary's exact-allele boundary consistently: allele groups, null alleles, and ambiguous class-I pairs are rejected at input. Source evidence can retain those unresolved declarations without promoting them to an exact restriction or assigning them to every patient allele.

Resolved native donors or engineered origins contribute at most once each. R sums those unit maxima, P is the largest presence contribution, and J is discounted support across connected references. Known shared units and reuse identities connect references before quality exclusion. Descriptive labels and row counts never establish independent donors. Packages lacking reviewed lineage can contribute P and J; they do not acquire invented recurrence counts.

Topiary evaluates M=max(R,P,J), S=log2(1+M), G=1+gain*S, and C=B^(1/G). An optional cap applies to G. B is the bounded prediction score before its soft cutoff. The default is normalized logistic affinity. A custom base_score needs an explicit soft_threshold; log_base_score may supply a matching log value. These weights and scores are heuristic ranking choices, not probabilities.

C can pass the soft gate; the user's epitopes.filter_expr remains a hard gate. Exact experimental/verified monoallelic support can admit a candidate directly only with positive support and G>1. Missing predictions remain missing unless an explicit ms_only_score in [0,1] is configured. A true zero stays zero. Native protein scans enumerate the models' declared peptide lengths and alleles independently of returned predictions; absent measurements remain blank rows.

Each admitted allele retains its prediction-only baseline contribution b0. An epitope adds the single increment max(C-b0) to its baseline allele sum. A window adds this increment once per unique peptide sequence. It is never multiplied by the number of matching alleles or repeated sequence positions.

Raw Hitlist captures, normalized observations, availability, per-allele baseline and adjusted values, R/P/J, M/S/G, and Topiary policy decisions travel with native datasets. Replay uses those captured observations without querying installed data. Report calculation details show the baseline allele contributions and MS increment. Keep native datasets to retain the complete acquisition and replay contract.

See the full design for richer EvidenceStore relationships, source quality calibration, and evaluation work.