Rules TSV Format Reference

A rules TSV file is a tab-separated table that defines which mutations confer resistance. Each row is one rule. This document is the source of truth for the file format used by respro init and respro add.

Quick example

A minimal rules TSV with only the required columns:

feature	reference_identifier	position	reference	mutation	antiviral	phenotype
UL23	NC_001806	336	A	V	Aciclovir	resistant

With optional columns for metadata and combination rules:

feature	reference_identifier	position	reference	mutation	antiviral	phenotype	ic50	fold_ic50	member_id
UL23	NC_001806	336	A	V	Aciclovir	resistant	32.5	4.1	mut_A
UL30	NC_001806	715	K	I	Aciclovir	resistant	28.0	3.5	mut_B

Combination rules use a separate formula TSV (--formula-rules) that defines boolean expressions over member IDs:

group_id	antiviral	expression	phenotype
group_1	Aciclovir	(mut_A OR mut_B) AND NOT mut_C	resistant

For full column definitions, mutation notation, and combination rule syntax, see the sections below.

Overview

• The primary rules TSV defines single-mutation rules — one row per mutation.
• Single rules can carry their own metadata (phenotype, IC50, publications, …) or act mainly as building blocks for combination rules.
• Optional boolean combination rules can be provided in a second TSV via --formula-rules.
• Combination rules reference single rules by their member_id values.

---

Single Rules

Required columns

Column	Meaning	Constraints
feature	CDS or mat_peptide feature name	Must match a feature loaded from GenBank
reference_identifier	Reference accession or name	Must match a reference in the project DB
position	Amino-acid position	File-wide 0-based or 1-based, auto-detected
reference	Reference amino acid at position	Checked against reference AA sequence
mutation	Alternate amino-acid event token	Normalized to canonical mutation forms
antiviral	Drug name	Stored normalized (lowercase)

Optional columns

Column	Meaning	Constraints
phenotype	Rule-level phenotype interpretation
clinical_phenotype	Clinical interpretation field
ic50 / ic_50	Absolute IC50 value
fold_ic50 / fold_ic_50	Fold IC50 value
publication	DOI, PMID, or source publication text
source	Provenance label
comment	Free-text curator note
member_id	Stable atomic rule identifier	Required when referenced by formula rules
score	Numeric quality/evidence score

Notes:

• member_id is required when atomic rules are referenced by formula expressions in the formula TSV.
• member_id values must be unique when provided.
• member_id values must not use reserved boolean keywords such as AND, OR, NOT, or XOR.

Coordinate rules (position)

• Positions are interpreted as amino-acid coordinates.
• Import auto-detects 0-based vs 1-based using the reference AA and GenBank translation.
• Use one coordinate system consistently across the entire TSV file.

Mutation token rules (mutation)

Supported canonical categories:

1. Substitution: single AA (V) or rewrite notation (A336V)
2. Stop: *, STOP, rewrite with stop (A336*)
3. Frameshift: fs, fsX, A336fs, A336frameshift
4. Insertion: canonical and HGVS-like insertion forms
5. Deletion: canonical and HGVS-like deletion forms
6. Generic insertion wildcard: INS_any — matches any in-frame insertion at this position

Notes:

• Non-standard wildcard tokens (for example X, any) are not accepted as rule alleles, except INS_any.
• INS_any matches any in-frame insertion at the given position regardless of inserted sequence or length.
• The reference column is still required and validated against the GenBank translation even for INS_any rules.
• If both a specific insertion rule and an INS_any rule exist for the same position and drug, the specific rule takes precedence and INS_any is suppressed (deterministic matching).
• No-op rules (mutation == reference) are rejected.
• Mutation tokens are normalized before DB insertion to support deterministic matching.

How mutation normalization works

Different textual inputs can describe the same biological event (for example, V and A336V both mean "change position 336 to V"). Normalisation converts all of these to one canonical form before rules are stored and matched, so matching is exact and deterministic.

Processing order:

1. Read the row context (feature, reference_identifier, position, reference).
2. Detect the mutation category (substitution, stop, frameshift, insertion, deletion).
3. Convert the token to its canonical internal form.
4. Validate it against the reference protein context.
5. Store the explicit allele state for deterministic matching.

Normalization examples (input → canonical interpretation)

Substitutions and stop events

Input mutation	Example row context	Canonical interpretation
V	reference=A, position=336	substitution to V
A336V	reference=A, position=336	substitution to V
STOP	reference=A, position=336	stop mutation (*)
A336*	reference=A, position=336	stop mutation (*)

Frameshift events

Frameshift rules are normalized to the anchored form XfsX, where X is the reference amino acid anchor from the row context.

Input mutation	Example row context	Canonical interpretation
fs	reference=K, position=715	frameshift after the K at position 715
frameshift	reference=K, position=715	frameshift after the K at position 715
K715fs	reference=K, position=715	frameshift after the K at position 715
K715fsATFF*	reference=K, position=715	frameshift after the K at position 715

Note

Any trailing sequence-like suffix after fs is not treated as a separate allele. It is collapsed to the canonical frameshift sentinel form.

In-frame insertion events

Insertion rules are normalized to a canonical insertion allele that preserves anchor amino acid, anchor position, and resulting inserted payload context.

Input mutation	Example row context	Canonical interpretation
F50FGG	reference=F, position=50	GG insertion after the F at position 50
F50_F51insGG	reference=F, position=50	GG insertion after the F at position 50
50insGG	reference=F, position=50	GG insertion after the F at position 50, anchor resolved from reference

In-frame deletion events

Input mutation	Example row context	Canonical interpretation
FGG50F	reference=FGG, position=50	GG deletion after F at position 50
F50delGG	reference=FGG, position=50	GG deletion after F at position 50
Q35del	reference=FQ, position=34	Q deletion after F at position 34, anchor resolved from reference

Anchor-less deletion

Helper forms like Q35del depend on upstream sequence context. If the required anchor context is biologically inconsistent with the reference, the row is rejected or skipped according to validation rules.

Generic insertion wildcard

INS_any is a special token that matches any in-frame insertion at the given position. The reference column is still required and validated as with all other rules.

Input mutation	Example row context	Canonical interpretation
ins_any	reference=F, position=50	any insertion after the F at position 50
INS_ANY	reference=F, position=50	any insertion after the F at position 50

• INS_any matches only in-frame insertions — frameshifts and deletions are not matched.
• If a specific insertion rule (e.g. F50FGG) fires for the same position and drug, INS_any is suppressed. Specific rules always win over the wildcard.
• In the database hits report tab, the rule label shown is INS_any. In the mutations tab, the actual sample allele is shown.

Edge-case events

Mid-codon in-frame events

Mid-codon in-frame insertions and deletions are split into two annotations: a missense (or synonymous) annotation for the anchor codon change, and an insertion or deletion annotation for the indel payload. Synonymous anchor changes are omitted, producing a single indel annotation.

For curated rules TSV:

• encode biologically specific events as explicit insertion or deletion alleles,
• avoid wildcard-like shorthand for complex events,
• prefer decomposed, clearly interpretable rule entries.

Unsupported ambiguity patterns

Examples that are not accepted as mutation rules:

• wildcard-like tokens (X, any) — note that INS_any is the one supported wildcard exception,
• malformed HGVS-like fragments that cannot be resolved,
• no-op entries where mutation equals reference.

TSV-to-database interpretation

During import, in-frame indels are converted to explicit allele representations so matching is exact:

• insertion rules track anchor and inserted payload
• deletion rules track deleted block and resulting anchor state

For substitutions/stops, reference and normalized mutation are stored as direct allele states.

Antiviral

• Required.
• Drug names are normalized to lowercase in the database.
• ResPro can try to fetch information for those drugs.

Phenotype normalization

phenotype and clinical_phenotype are stored verbatim — lowercased and whitespace-stripped, exactly as written in the rules sheet. Each label maps to a rank via the built-in vocabulary below, and the rank is inferred wherever severity comparison or colouring is needed.

Rank	Accepted labels (case-insensitive)	Report colour	Fallback label
1	susceptible, sensitive, normal inhibition, ni, normal	green	susceptible
2	potential low-level resistance, possibly resistant, suspected reduced	yellow	potential low-level resistance
3	low-level resistance, reduced susceptibility, limited susceptibility	slight orange	low-level resistance
4	intermediate, intermediate resistance, reduced inhibition, ri	orange	intermediate
5	resistant, high-level resistance, highly reduced inhibition, hri	red	resistant
0	unknown, not analysed, none, (empty cell)	grey	unknown
-1	contradictory, conflicting	slate	contradictory

Ranks run 1 (mildest) to 5 (most severe); 0 and -1 are sentinels for unknown and contradictory.

Normalization rules:

• Labels are lowercased and whitespace-stripped before storage and lookup.
• Bare ranks accepted. A value of 1–5 resolves to the fallback label for that rank (the last column above).
• Empty = unknown. An empty cell stores '' (rank 0). The synonyms none and not analysed collapse to the canonical unknown label.
• phenotype and clinical_phenotype are normalized independently. You may provide either, both, or neither.

IC50 parsing rules

• ic50 and ic_50 are aliases (use at most one in a file)
• fold_ic50 and fold_ic_50 are aliases (use at most one in a file)
• absolute and fold columns may coexist in the same TSV
• values are parsed numerically and stored in dedicated DB fields

Score

• Optional numeric field accepted in the score column.
• Accepts any finite numeric value (integer or decimal, including negative values).
• Useful for evidence scores, confidence scores, or any database-specific numeric quality metric.
• Shown in the HTML report as a dedicated column when at least one rule carries a non-empty value.
• The value is stored and propagated as-is; ResPro does not interpret or threshold it.

Publications and sources

publication accepts:

• DOI forms (doi:10..., https://doi.org/..., doi.org/...)
• PMID forms (PMID:12345678)
• Multiple entries must be comma-separated
• free text

Import deduplicates publication entries and links them to atomic rules and formula rules.

Source

• Optional free text.
• Helpful for indicating merged databases.

Comment

• Optional free text.
• Any information the curator considers relevant; stored verbatim.
• Displayed in the HTML report when at least one rule carries a non-empty value.

Minimal single-rule example

feature	reference_identifier	position	reference	mutation	antiviral	phenotype
UL23	NC_001806	336	A	V	Aciclovir	resistant

Minimal single-rule example for INDELs and frameshifts

Frameshift rules are normalized to anchor the reference amino acid:

feature	reference_identifier	position	reference	mutation	antiviral	phenotype
UL30	NC_001806	715	K	fs	Aciclovir	resistant
UL23	NC_001806	50	F	FGG	Aciclovir	intermediate
UL23	NC_001806	73	MGH	M	Aciclovir	resistant

• Frameshift (fs): Normalized to anchor-form internally; trailing sequence context ignored.
• Insertion (FGG): Insertion of GG after the F anchor at position 50.
• Deletion (M): Deletion of the MGH block at position 73, resulting in M anchor.

---

Formula rules TSV (--formula-rules)

The optional formula TSV defines higher-order resistance rules over atomic member_id values from the primary rules TSV.

Required columns

Column	Meaning	Constraints
group_id	Formula rule identifier	Must be unique across all formula rules
antiviral	Drug name	Stored normalized like atomic rules
expression	Boolean rule formula	Uses atomic member_id values and AND / OR / NOT / XOR

Optional columns

Column	Meaning
label	Human-readable display label
phenotype	Formula-level phenotype interpretation
clinical_phenotype	Formula-level clinical interpretation
ic50 / ic_50	Absolute IC50 value
fold_ic50 / fold_ic_50	Fold IC50 value
score	Numeric quality/evidence score
publication	DOI, PMID, or source publication text
source	Provenance label
comment	Free-text curator note

Expression rules

• Supported operators are AND, OR, NOT, and XOR. Parentheses are supported and should be used whenever precedence should be explicit.
• Atomic identifiers in expression must match member_id values from the primary rules TSV.
• Unsupported characters, duplicate group ids, duplicate normalized formulas for the same drug, and unknown atomic ids are rejected during import.
• Each group_id in the formula TSV must be unique.
• Duplicate atomic ids inside one formula are rejected.

Single-member OR de-duplication: a pure-OR formula (no AND/XOR/NOT) that fires through exactly one present member is logically equivalent to that member's own atomic rule. If the member also has an independently-curated atomic rule for the same drug (i.e. it is not a formula-only placeholder), the formula hit is suppressed so the exact match isn't reported twice — only the atomic hit stands. Members intended to fire only through the formula (never independently) should be curated with a placeholder drug, not the formula's own drug. AND/XOR/NOT clauses are never suppressed this way, since a single surviving contributor there still encodes a distinct claim (e.g. co-occurrence or absence of other members).

See Interpretation Algorithms for a visual overview of the boolean operators.

Minimal combination-rule example

Atomic rules (rules.tsv)

Define the individual mutations:

feature	reference_identifier	position	reference	mutation	antiviral	phenotype	ic50	fold_ic50	member_id
UL23	NC_001806	336	A	V	Aciclovir	resistant	32.5	4.1	mut_A
UL30	NC_001806	715	K	I	Aciclovir	resistant	28.0	3.5	mut_B
UL30	NC_001806	725	A	AGG					mut_C

Combination rule (formula.tsv)

Define a formula that requires both mutations:

group_id	antiviral	expression	phenotype	clinical_phenotype
group_1	Aciclovir	(mut_A OR mut_B) AND NOT mut_C	resistant	resistant

The group_id in the formula TSV identifies each formula rule. Each member_id value from the primary rules TSV that appears in an expression must correspond to a single rule.

Annotation handling

When optional metadata columns are provided in the primary rules TSV:

• If provided (ic50, fold_ic50, phenotype, clinical_phenotype, source, publication, comment):
  • Values are stored in the single rule row.
  • If the same mutation appears in both single and formula contexts, the stored annotation applies to all uses.
  • Formula-level annotations (provided in the formula.tsv) override single-rule annotations for that specific formula combination.
• If omitted (e.g., all rows lack ic50):
  • The field is stored as NULL or empty for that rule.
  • During profiling, the absence is treated as "no data available" and reported as unknown or blank in output.
  • Formulas can still reference the atomic rule; the combination's interpretation is determined by formula-level metadata.

---

Common validation failures

1. feature not found in imported GenBank annotations
2. reference_identifier not present in project references
3. Inconsistent coordinate system inside one file
4. reference amino acid mismatch at the given position
5. Malformed or unsupported mutation token
6. Ambiguous helper notation that cannot be resolved in sequence context

For reproducible curation workflows:

• keep reference_identifier explicit in every row
• keep mutation notation consistent across sources
• use member_id and formula expressions for combinatorial association
• when possible, prefer canonical insertion/deletion forms to reduce ambiguity