API reference

Use this reference to look up constructors, fields, and methods. For a complete first prediction, start with getting started.

Task	Reference	Explanation and examples
Read predictions and scores	Results	Results and DataFrames
Describe a peptide or TCR	Inputs	Input shapes
Add predictions to a table	Table annotation	Annotation recipe
Download or inspect models	Models and artifacts	Getting models
See one enzyme's methods and predictions	Peptidase activity	Enzyme-centered guide
Assess individual peptide bonds	Peptidase activity	Activity guide
Model conditional vaccine exposure	Vaccine trajectories	Run, report and compare

Predictor-specific setup and examples are in the family guides. The predictor matrix lists Python classes and command-line names for every supported model.

Vaccine trajectories

Supply explicit rates and current-fragment cleavage assessments, then summarize or compare matched endpoints. These are conditional calculations with no fitted physiological defaults. See the trajectory guide for units and the comparison workflow for interpretation.

VaccineDose dataclass

Documented amount of the modeled starting peptide or carrier-bound RNA.

ug requires the molecular weight of the actual starting material in g/mol. For RNA this includes the full transcript, not the encoded protein. This conversion does not estimate encapsulation, release or bioavailability.

copies property

copies

Starting copies using the exact SI Avogadro constant.

VaccineTrajectoryInput dataclass

Inputs for one exact target and allele, with no physiological defaults.

Coordinates, including signal_end, are zero-based, half-open on the full translated construct. An mRNA source amount is transcript copies, whereas an SLP source amount is peptide copies. Their outputs have different units.

source_copies

source_copies()

Resolve explicit dose or legacy copies; otherwise normalize to one.

simulate_vaccine_trajectory

simulate_vaccine_trajectory(model, times_hours, cleavage_rates=None, *, max_states=10000)

Follow a target to APC loading using explicitly supplied rate channels.

Parameters:

• model (VaccineTrajectoryInput) –

  One exact target occurrence, allele, local delivery and rate audit.

• times_hours (iterable of float) –

  Finite nonnegative observation times; output preserves their order.

• cleavage_rates (callable, default: None ) –

  Called with (compartment, TargetFragment) for each reachable free fragment. Return VaccineCleavageRates using CURRENT-fragment bonds, or None when kinetics are missing. Empty channels need their own explicit no-cut source, not proof of stability. A serum predictor or score must never be silently reused in lymph.

• max_states (int, default: 10000 ) –

  Explicit size guard for fragment closure; no silent fragment pruning.

Returns:

• dict –

  Mechanism and rate audit, fragment states and expected-copy time courses. Missing reachable kinetics return unassessed with no numerical curves. Otherwise results are conditional scenarios, not calibrated forecasts. RNA translation yields multiple antigen copies per input transcript; SLP and RNA source-normalized outputs cannot be compared as probabilities.

summarize_vaccine_trajectory

summarize_vaccine_trajectory(result)

Summarize the last observation and finite-horizon presentation exposure.

The result must come from simulate_vaccine_trajectory. Missing kinetics leave numerical summaries absent. Means at a zero-hour horizon are undefined. Source normalization is per peptide or per transcript, never per APC.

assess_vaccine_windows

assess_vaccine_windows(request)

Assess every supplied candidate and scored core under explicit kinetics.

Parameters:

• request (dict) –

  Schema 1 with scenario, times_hours and candidates. Each candidate has id, peptide, delivery and cores (original window start/end, label, allele, MHC class, optional score contribution). kinetics maps MHC class to rates, a TAP/class-II length bound and a fragment cleavage table. Candidate kinetics replace the corresponding request-level class profile. Each profile must apply to that delivery. SLP dose defaults to 1 ug of the actual free linear peptide. RNA requires an explicit dose, using transcript molecular weight for a mass dose.

Returns:

• dict –

  Per-window, per-core summaries and full trajectory audits. Missing parameters remain unassessed. No ranking or physiological fit occurs.

vaccine_window_rows

vaccine_window_rows(result)

Flatten to one row per core occurrence/allele; preserve absent estimates.

format_vaccine_window_report

format_vaccine_window_report(result)

Readable endpoint table with dose bases, gaps and score-weighted summaries.

summarize_core_exposure

summarize_core_exposure(result)

Describe the observed blood curve and cumulative nodal APC entry.

The half-decline interval is measured from the sampled maximum and brackets the first subsequent downward half-maximum crossing. It is not a fitted terminal elimination half-life: injection-site absorption, secretion and precursor processing can all supply blood antigen throughout observation. No interpolation, extrapolation or physiological rate fitting is performed.

format_vaccine_trajectory_report

format_vaccine_trajectory_report(result)

Return a Markdown report with dose, endpoints, missing inputs and sources.

compare_vaccine_trajectories

compare_vaccine_trajectories(results)

Compare matched endpoints without ranking efficacy or equating RNA/SLP.

Require the same exact target sequence, allele, MHC class and horizon. Known organism differences are rejected. Route differences and unspecified context stay visible. Unassessed scenarios remain rows with absent outcomes. Results keep their input order; there is no winner or combined score.

format_vaccine_comparison_report

format_vaccine_comparison_report(comparison)

Render the matched endpoint comparison in supplied scenario order.

Results

predict() returns one PeptideResult per peptide. Its predictions are Prediction objects, each describing one endpoint and MHC or TCR context. Kind names the endpoint; MeasurementContext records its measurement semantics. MultiSample runs a predictor for several named MHC allele sets.

Read results and DataFrames for examples and prediction kinds for score meanings and units. Source: prediction types and sample helper.

PeptideResult dataclass

All predictions for one peptide (a tuple of Prediction objects).

kinds property

kinds

Set of Kind values present in this result.

alleles property

alleles

Set of allele strings present in this result.

tcrs property

tcrs

Set of TCR identifiers present in this result.

affinity property

affinity

Best affinity prediction, or None.

presentation property

presentation

Best presentation prediction, or None.

stability property

stability

Best stability prediction, or None.

immunogenicity property

immunogenicity

Best immunogenicity prediction, or None.

foreignness property

foreignness

Highest descriptive foreignness score, if one is present.

processing property

processing

Best antigen-processing prediction, or None.

cleavage property

cleavage

Best proteasomal cleavage prediction, or None.

endolysosomal_cleavage property

endolysosomal_cleavage

Best endolysosomal (MHC-II) cleavage prediction, or None.

tap_transport property

tap_transport

Best TAP transport prediction, or None.

erap_trimming property

erap_trimming

Best ERAP1 trimming prediction, or None.

peptide_half_life property

peptide_half_life

Peptide half-life when all available results share one context.

Comparing different matrices or systemic scopes is intentionally rejected; callers can select those contexts explicitly instead.

serum_half_life property

serum_half_life

Best peptide half-life measured in serum, or None.

plasma_half_life property

plasma_half_life

Best peptide half-life measured in plasma, or None.

blood_half_life property

blood_half_life

Best peptide half-life measured in whole blood, or None.

tcr_binding property

tcr_binding

Best pMHC:TCR binding prediction, or None.

filter

filter(kind=None, allele=None)

Filter preds. None means don't filter on that field.

to_dict

to_dict()

Serialize to a JSON-friendly dict.

from_dict classmethod

from_dict(d)

Deserialize from a dict (as produced by :meth:to_dict).

best_by

best_by(kind, field)

Return the prediction of kind with the best field, or None.

"Best" direction comes from :func:best_direction — score is max-better, percentile_rank is min-better, and value is kind-dependent (IC50 lower-better, half-life higher-better).

Predictions with None for field are skipped. Predictions with an allele are preferred; if none of the matching kind have an allele, falls back to allele-less predictions (e.g. processing predictors that emit allele-independent scores).

best_by_score

best_by_score(kind)

Best prediction of kind by score (max-better).

best_by_rank

best_by_rank(kind)

Best prediction of kind by percentile_rank (min-better).

best_by_value

best_by_value(kind)

Best prediction of kind by value. Direction is kind-specific (see :data:VALUE_BEST_DIRECTIONS). Raises ValueError for kinds without a registered value direction.

Prediction dataclass

Single prediction from one model on one peptide.

to_dict

to_dict()

Serialize to a JSON-friendly dict.

from_dict classmethod

from_dict(d)

Deserialize from a dict (as produced by :meth:to_dict).

Kind

String constants for prediction kinds.

You can use Kind.pMHC_affinity or just "pMHC_affinity" — they're the same string. These constants name what is measured, but predictor instances define the MHC context required for their supported kinds through kind_support().

MeasurementContext dataclass

Versioned semantics shared by every prediction.

unit and transform describe :attr:Prediction.value; the stored physical value remains linear, so transform must currently be "linear" when a value is present. Predictor-native or confidence outputs belong in score and are identified by score_semantics. Ordinary model outputs receive a small cached default; assay-specific wrappers fill only the fields they actually know. Unknown descriptive fields are None, never a plausible biological default.

to_dict

to_dict()

Serialize to a JSON-friendly dictionary.

from_dict classmethod

from_dict(value)

Deserialize a context while ignoring forward-compatible fields.

MultiSample

Run a predictor across multiple samples, each with its own alleles.

Parameters:

• samples (dict) –

  Mapping of sample_name -> list of allele strings. Example: {"pat001": ["HLA-A02:01", "HLA-B07:02"], "pat002": ["HLA-A01:01", "HLA-B08:01"]}

• predictor_class (class) –

  A predictor class (e.g. NetMHCpan41) that accepts an alleles keyword argument.

• **predictor_kwargs –

  Additional keyword arguments forwarded to the predictor constructor.

predict

predict(peptides)

Returns:

• dict mapping sample_name -> list of PeptideResult –

predict_dataframe

predict_dataframe(peptides)

predict() flattened to a DataFrame with sample_name column.

predict_proteins

predict_proteins(sequence_dict, peptide_lengths=None)

Returns:

• dict mapping sample_name -> {sequence_name: list of PeptideResult} –

predict_proteins_dataframe

predict_proteins_dataframe(sequence_dict, peptide_lengths=None)

predict_proteins() flattened to a DataFrame with sample_name column.

Inputs

TCR carries receptor sequences and gene identifiers. PeptideInput records a peptide's sequence, terminal chemistry, attachments, and source occurrence. PeptideContext adds study, formulation, and assay context when those details are known.

See input shapes, the TCR guide, and peptide exposure inputs. Source: TCR types and peptide types.

TCR dataclass

A paired αβ T-cell receptor, described by its six CDR loops.

Parameters:

• cdr1a (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the α chain (NetTCR A1/A2/A3).

• cdr2a (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the α chain (NetTCR A1/A2/A3).

• cdr3a (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the α chain (NetTCR A1/A2/A3).

• cdr1b (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the β chain (NetTCR B1/B2/B3).

• cdr2b (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the β chain (NetTCR B1/B2/B3).

• cdr3b (str, default: '' ) –

  CDR1/2/3 amino-acid sequences of the β chain (NetTCR B1/B2/B3).

• name (str, default: '' ) –

  Human-readable identifier (e.g. a clonotype name). If omitted, :attr:identifier falls back to the CDR3α/CDR3β pair.

• trav (str, default: '' ) –

  TCR alpha/beta V and J gene assignments. These fields intentionally preserve the caller's spelling: predictor-specific correction and allele handling belong in the predictor adapter.

• traj (str, default: '' ) –

  TCR alpha/beta V and J gene assignments. These fields intentionally preserve the caller's spelling: predictor-specific correction and allele handling belong in the predictor adapter.

• trbv (str, default: '' ) –

  TCR alpha/beta V and J gene assignments. These fields intentionally preserve the caller's spelling: predictor-specific correction and allele handling belong in the predictor adapter.

• trbj (str, default: '' ) –

  TCR alpha/beta V and J gene assignments. These fields intentionally preserve the caller's spelling: predictor-specific correction and allele handling belong in the predictor adapter.

Notes

CDR3β (cdr3b) carries most of the antigen-contact specificity, but NetTCR-2.2's pan model expects all six loops; leaving loops empty will encode as fully-padded (uninformative) features.

identifier property

identifier

Stable string identifier for this receptor.

Uses :attr:name if set, otherwise the CDR3α/CDR3β pair, which together define the clonotype for most practical purposes.

cdr_dict

cdr_dict()

Return the six CDRs keyed by NetTCR feature name (a1..b3).

gene_dict

gene_dict()

Return V/J assignments using standard AIRR-style gene names.

to_dict

to_dict()

Serialize to a JSON-friendly dict.

from_dict classmethod

from_dict(d)

Deserialize from a dict.

Accepts canonical cdr1a..cdr3b and trav..trbj keys case-insensitively, plus NetTCR/IMMREP-style short aliases a1..b3 / A1..B3. Canonical field names win if both a canonical key and an alias are present.

from_series classmethod

from_series(row)

Deserialize from a pandas Series or other mapping-like row.

PeptideInput dataclass

Canonical L-peptide chemical form plus provenance and context.

attachments contains (site, identity) pairs. Sites and identities are deliberately descriptive strings: adapters may support a documented subset, and must reject every other form rather than dropping it. Source occurrence provenance is kept separate from the chemical/context identity used for inference caching.

chemical_identity_sha256 property

chemical_identity_sha256

Identity of sequence, termini, and attachments only.

inference_identity_sha256 property

inference_identity_sha256

Chemical and model-input context identity, excluding occurrence.

record_identity_sha256 property

record_identity_sha256

Full record identity including occurrence and source provenance.

to_dict

to_dict(*, compact=False)

Return a JSON-friendly representation, optionally omitting defaults.

fragment

fragment(start, end, *, n_term, c_term)

Describe a conditional fragment with explicitly supplied termini.

Partial fragments of attached peptides cannot be described without a positional attachment map, so they are rejected rather than silently treated as unmodified.

from_dict classmethod

from_dict(value)

Restore an input while ignoring unknown same-version fields.

PeptideContext dataclass

Versioned administration, study, assay, and cellular context.

Every field is descriptive. None means unknown; this class does not infer patient-specific properties, physiological defaults, or a preferred formulation, route, or modification.

to_dict

to_dict()

Return a JSON-friendly representation.

from_dict classmethod

from_dict(value)

Restore a context while ignoring unknown same-version fields.

Annotating tables

annotate_table() adds predictions to a DataFrame. An AnnotationSpec selects the model, endpoint, and filter to apply. Start with the annotation recipe for a complete example.

Source: table annotation.

annotate_table

annotate_table(table, specs, peptide_column='peptide', allele_column=None, allele_sep=_DEFAULT_ALLELE_SEP, overwrite=False)

Append predictor score columns to a table, best-allele per row.

Parameters:

• table (DataFrame) –

  Input table; returned unmodified with new columns appended to a copy.

• specs (sequence of AnnotationSpec) –

  One entry per output column.

• peptide_column (str, default: 'peptide' ) –

  Column holding the peptide sequence for each row.

• allele_column (str, default: None ) –

  Column holding the row's allele(s). May contain several alleles per cell (see allele_sep). If omitted, predictors run allele-free and no best-allele provenance column is written.

• allele_sep (compiled regex, default: _DEFAULT_ALLELE_SEP ) –

  Splits multiple alleles packed into one cell. Defaults to splitting on whitespace, commas, and semicolons.

• overwrite (bool, default: False ) –

  If False (default), raise when an output column already exists.

Returns:

• DataFrame –

  A copy of table with one numeric column per spec appended (plus a <output_column>_best_allele column when an allele column is given). Rows with no usable prediction get NaN (and None best allele).

Notes

Every allele in the table must be supported by each predictor; commandline predictors raise UnsupportedAllele at construction otherwise, matching mhctools' behavior elsewhere.

AnnotationSpec dataclass

One predictor mapped to one output column.

Parameters:

• predictor (predictor instance, or callable ``alleles -> predictor``) –

  A built predictor (used as-is), or a factory that builds one given the union of alleles in the table. Commandline predictors validate their alleles at construction, so passing a factory lets the predictor be built with exactly the alleles the table needs.

• output_column (str) –

  Name of the appended score column.

• field (str, default: 'affinity' ) –

  Which prediction field to write, one of :func:output_field_tokens ("affinity", "score", "percentile_rank", ...). Determines both the value written and the best-allele direction.

• add_best_allele (bool, default: True ) –

  If True (default) and the table has an allele column, also append a provenance column naming the allele that won each row.

• best_allele_column (str, default: None ) –

  Name of the provenance column. Defaults to f"{output_column}_best_allele".

build_predictor

build_predictor(alleles)

Return a predictor instance for the given union of alleles.

A callable that is not itself a predictor (no predict method) is treated as a factory and called with alleles; anything else is assumed to already be a built predictor and returned unchanged.

direction_op

direction_op()

max or min callable for reducing candidate predictions.

matches_context

matches_context(prediction)

Whether a prediction satisfies this field's context selector.

Models and artifacts

fetch() installs managed model artifacts. list_artifacts() reports their installation status; integration_status() checks whether a predictor can run. See getting models for the installation workflow and licensing for upstream terms.

Source: artifact management and integration checks.

fetch

fetch(name, version=None, data_dir=None, accept_license=False, models=None, all_models=False, high_confidence=False)

Fetch a predictor's external artifacts and return their status.

Native download managers retain ownership of their files. Tested upstream snapshots are installed under :func:data_path. Predictors whose parameters are already packaged are successful no-ops.

list_artifacts

list_artifacts(names=None, data_dir=None)

List known packaged, native, managed, and manual artifacts.

integration_status

integration_status(name, check='runnable', data_dir=None, timeout=10)

Report located, runnable, and reproduced state for one integration.

Parameters:

• name (str) –

  Artifact/integration name accepted by :func:artifact_status.

• check ((located, runnable, reproduced), default: "located" ) –

  Highest capability to attempt. Reproduction probes are intentionally sparse and reference-backed; unsupported checks remain None.

• data_dir (path - like, default: None ) –

  Override the mhctools-managed artifact directory.

• timeout (float, default: 10 ) –

  Bound for command launch and import probes.

Peptidase activity

predict_cleavage() assesses individual bonds for selected peptidases. predict_cleavage_batch() assesses a set of inputs and processing scenarios. DPP4 and FAP are named enzyme classes. They discover and run every available method for that enzyme, returning distinct results in EnzymePredictions. EnzymePredictor.from_name() resolves configuration strings through the named-class registry or generic catalog. The shared PeptideInput supplies sequence and terminal chemistry and conditional fragments. motif_rule() constructs a sourced custom motif predictor; see the example. The biological workflow is explained in the peptidase activity guide.

See choosing processing models, reading the evidence, and batch assessments. Source: model dispatch, input and result types, and batch assessment.

predict_cleavage

predict_cleavage(peptide, models=None, compartment=None, *, enzyme_states=None)

Return distinct model results without aggregation or enzyme ranking.

compartment filters annotated enzyme locations, not assay validation. Explicit selections incompatible with that filter are rejected.

EnzymePredictor

Discover and run methods for an enzyme class or cataloged name.

Methods are reported independently: a motif is a recognition pattern, a scored model keeps its native units, and a time-dependent fraction is available only where a specified source assay has been calibrated.

Use a concrete class such as DPP4() or FAP() in Python. The string constructor remains for existing callers; from_name() is the explicit registry path for configuration-driven selection.

from_name staticmethod

from_name(name, *, include_optional=False)

Resolve a string from configuration, using concrete classes when registered.

available staticmethod

available(*, include_optional=False)

List enzymes with at least one curated cleavage method.

describe

describe()

Show what each named method assesses, with its assay and sources.

predict

predict(peptide, *, conditions=None, minutes=None, enzyme_state=None)

Run each method; include a 60-minute source-assay scenario by default.

conditions changes the assay exposure time and/or enzyme concentration. minutes remains a legacy exposure-time shortcut. Motifs and native cleavage scores do not depend on either parameter.

DPP4

Bases: EnzymePredictor

Human DPP4: sourced motifs, qPISA score, and Keane assay parent loss.

FAP

Bases: EnzymePredictor

Human FAP: dipeptidyl and endopeptidyl motifs, plus Keane assay loss.

EnzymePredictions dataclass

Results for one peptide and enzyme; methods keep their native meaning.

by_model property

by_model

Look up an existing result by its source-specific model name.

__repr__

__repr__()

Keep interactive displays readable; details remain in the fields.

summary_rows

summary_rows()

One human-readable endpoint row per method, without combining scores.

summary

summary()

Read the separate outputs in one compact, deliberately unranked report.

to_dict

to_dict()

Return concise endpoint rows for display or routine JSON output.

Model descriptions and source provenance are available through EnzymePredictor.describe() or to_evidence_dict().

to_evidence_dict

to_evidence_dict()

Return the lossless, source-rich schema v1 evidence export.

predict_cleavage_batch

predict_cleavage_batch(inputs, scenarios, *, predictors=None, reference_panels=(), raise_on_error=False)

Assess named occurrences under explicitly selected biological scenarios.

Parameters:

• inputs (iterable of dict) –

  Named sequences/peptide occurrences accepted by normalize_cleavage_input.

• scenarios (iterable of dict) –

  Named tumor/APC/extracellular questions with explicit model lists. Compartments filter enzyme locations, not experimental validation.

• predictors (mapping, default: None ) –

  Already constructed canonical predictors keyed by exact model name. Useful for user-managed assets and source-observation adapters.

• reference_panels (iterable of dict, default: () ) –

  Experimental source catalogs with model and cases fields, using the PeptidaseSubstrateReference contract. One named panel per assay/condition; exact sequence/chemistry lookup never extrapolates. Panels are retained in the output so imported observations round-trip.

• raise_on_error (bool, default: False ) –

  Raise backend errors instead of retaining failed assessment records.

Returns:

• dict –

  Versioned JSON manifest retaining inputs, scenarios, model results, conditional fragments, epitope overlays and declared coverage gaps.

motif_rule

motif_rule(*, name, enzyme, references, topology, assay, limitations, left=None, right=None, strictness=None, basis=None, accession=None, compartments=(), description=None, removed=0, species='Homo sapiens', version='1', min_length=None, max_length=None, n_chemistry=('free',), c_chemistry=('free',), requires_activation=False, enzyme_state='unknown')

Create a sourced per-bond motif predictor without registry changes.

left and right are Python regexes for residues before and after a candidate bond; None leaves that flank unconstrained. topology is internal, n_terminal or c_terminal; terminal rules also give removed. Supply cited references, the assay and limitations. An optional source-backed strictness grade is required, preferred or permissive. The returned predictor accepts strings and PeptideInput records. strictness interprets the evidence but does not change the binary pattern mask or supply a cleavage probability.

Whole-substrate MMP evidence

CleaveNet

Optional local inference for canonical sequences of 1–10 residues.

Parameters:

• cleavenet_home (str, default: None ) –

  Pinned upstream source/weights, or CLEAVENET_HOME. Otherwise use the managed installation from mhctools fetch cleavenet.

• cleavenet_python (str, default: None ) –

  Isolated interpreter containing upstream requirements (TensorFlow 2.18.0). Defaults to CLEAVENET_PYTHON or the current interpreter.

• subprocess_timeout (float, default: 300 ) –

  Maximum inference duration in seconds.

Notes

This adapter returns dedicated substrate results rather than site tracks. The assay endpoint is not serum half-life, uptake or antigen presentation. Construction verifies every runtime file against the pinned checksums.

fetch classmethod

fetch(version=None, data_dir=None, accept_license=False)

Fetch the pinned prediction assets and both license agreements.

kind_support

kind_support()

Native whole-substrate endpoint and its MHC independence.

predict

predict(peptides)

Return ordered substrate results, preserving duplicate occurrences.

Accept strings or exact PeptideInput records. Reject noncanonical sequences, longer inputs and unsupported chemistry before inference. Short inputs are centered in ten positions with the odd gap on the right, following upstream's README. Empty batches return an empty list.

predict_windows

predict_windows(peptide)

Score every ten-residue window with zero-based source coordinates.

These conditional sequence scores do not assert that the window is physically released or that an internal/central bond is cleaved.

predict_dataframe

predict_dataframe(peptides)

Flatten native substrate evidence to one row per input/enzyme.

CleaveNetResult dataclass

Whole-substrate evidence preserving input, padding and model identity.

Scores do not locate a scissile bond or quantify intact-peptide survival. Source coordinates identify the supplied window, never a cleavage site.

to_dict

to_dict()

Return JSON-compatible evidence without adding per-bond labels.

CleaveNetScore dataclass

One enzyme's native Z-score and spread across the five models.

The standard deviation is not a calibrated interval or a probability.