EpiLink
EpiLink scores how compatible pairs of sampled infections are with recent transmission scenarios, using the difference in sampling dates and the consensus genetic distance between the samples.
It is designed for epidemiological linkage workflows where you want to compare observed pairs against hypotheses such as direct transmission, transmission with hidden intermediates, or recent shared ancestry. Scores are compatibility summaries, not posterior probabilities unless you combine them with an explicit prior model.
Features
- Scenario-based linkage scores for ancestor-descendant and common-ancestor hypotheses.
- Deterministic and stochastic mutation-process models.
- Scalar and NumPy-broadcasted scoring for batch workflows.
- Typed result objects with attribute access and lightweight dictionary-style compatibility.
- Simulation helpers for epidemic dates, genomic sequences, and pairwise case tables.
- A small CSV command-line interface for batch scoring.
Installation
EpiLink requires Python 3.10 or newer.
Install the published package from PyPI:
python -m pip install epilink
Install from a local checkout for development:
git clone https://github.com/ydnkka/epilink.git
cd epilink
python -m pip install -e ".[dev]"
Alternatively, create the repository conda environment:
conda env create -f environment.yml
conda activate epilink
Quick Start
from epilink import EpiLink, InfectiousnessToTransmission
profile = InfectiousnessToTransmission(rng_seed=2026)
model = EpiLink(
transmission_profile=profile,
maximum_depth=2,
mc_samples=20000,
target=["ad(0)", "ca(0,0)"],
mutation_process="stochastic",
)
result = model.score_pair(
sample_time_difference=3.0,
genetic_distance=2.0,
)
print(result.target_labels)
print(result.target_compatibility)
print(result.scenario_scores["ad(0)"].compatibility)
Core Concepts
EpiLink scores observations against generated transmission scenarios.
maximum_depth controls how many hidden generations are included.
ad(0): direct ancestor-descendant transmission.ad(1): ancestor-descendant transmission with one hidden intermediate.ca(0,0): two sampled cases with a recent shared common ancestor.ca(m_i,m_j): a common-ancestor scenario withm_iandm_jhidden generations on each branch.
Each individual scenario compatibility lies in [0, 1]. If target contains
multiple scenarios, target_compatibility is the sum across that target subset
and can be greater than 1.
Common Workflows
Score a Target Subset
Use score_target when you only need the combined compatibility score:
score = model.score_target(
sample_time_difference=3.0,
genetic_distance=2.0,
target=["ad(0)", "ad(1)", "ca(0,0)"],
)
print(score)
You can also pass Scenario objects instead of string labels:
from epilink import Scenario
score = model.score_target(
sample_time_difference=3.0,
genetic_distance=2.0,
target=[
Scenario.ancestor_descendant(0),
Scenario.common_ancestor(0, 0),
],
)
Score Many Pairs
score_target and pairwise_model broadcast NumPy inputs, so you can score a
grid or batch efficiently:
import numpy as np
pairwise = model.pairwise_model(target=["ad(0)", "ca(0,0)"])
time_differences = np.array([[0.0], [2.0], [4.0]])
genetic_distances = np.array([[0.0, 1.0, 2.0, 3.0]])
scores = pairwise(time_differences, genetic_distances)
print(scores.shape) # (3, 4)
Simulate a Pairwise Case Table
The simulation helpers are useful for synthetic examples, tests, and downstream benchmarking:
import networkx as nx
from epilink import (
InfectiousnessToTransmission,
build_pairwise_case_table,
simulate_epidemic_dates,
simulate_genomic_sequences,
)
profile = InfectiousnessToTransmission(rng_seed=2026)
tree = nx.DiGraph(
[
("case-0", "case-1"),
("case-0", "case-2"),
]
)
dated_tree = simulate_epidemic_dates(profile, tree, fraction_sampled=1.0)
simulated = simulate_genomic_sequences(profile, dated_tree, genome_length=500)
pair_table = build_pairwise_case_table(simulated, dated_tree)
print(pair_table.head())
simulate_genomic_sequences(...) returns a SimulationResult with packed and
optional raw sequence sets. Each sequence set exposes deterministic and
stochastic members. The original, unmutated reference is always available as
simulated.reference_sequence (or simulated["reference_sequence"]), including
when return_raw=False. It is a one-dimensional NumPy int8 array of length
genome_length, encoded as 0=A, 1=C, 2=G, and 3=T.
The decoded A/C/G/T string is available as simulated.reference_sequence_string
(or simulated["reference_sequence_string"]) and is also included in to_dict().
To export node sequences and the reference together for phylogenetic inference:
simulated.packed.stochastic.write_fasta("sequences.fasta")
with open("sequences.fasta", "a") as fasta:
fasta.write(f">reference\n{simulated.reference_sequence_string}\n")
Use the reference sequence as the outgroup in your tree inference/rooting tool.
Use simulated.packed.deterministic to export the deterministic sequences instead.
Infer Sampled Phylogenies
See the small demonstration notebook for simulation, inference, and side-by-side genetic and dated tree plots.
Install the optional tree-parsing dependency:
python -m pip install 'epilink[phylogeny]'
Install IQ-TREE version 2.0.6 or later
separately. EpiLink discovers iqtree3, iqtree2, or iqtree on PATH, or you
can provide its path with iqtree_executable.
Using the simulation above:
from epilink import build_phylogenetic_tree
phylogeny = build_phylogenetic_tree(
simulated,
dated_tree, # Epidemic graph supplying sampled flags and sampling dates
sequence_model="stochastic", # Or "deterministic"
dated=True,
output_dir="phylogeny",
model="JC",
threads=1,
seed=2026,
)
raw_tree = phylogeny.raw_tree # Biopython Tree; substitutions/site
time_tree = phylogeny.dated_tree # Biopython Tree; days
print(phylogeny.node_dates)
print(phylogeny.output_paths["raw_tree"])
print(phylogeny.output_paths["dated_tree"])
The helper lives in epilink.simulation.phylogeny. It selects only nodes marked
sampled=True, requires at least three sampled cases, and works with
return_raw=False. Sequence rows are matched by case ID; transmission edges
are not used to infer the phylogeny.
IQ-TREE infers a maximum-likelihood genetic tree with the original reference as
the outgroup. LSD2 then dates the sampled-case tree using numeric sample_date
values. The genetic tree retains the reference (phylogeny.reference_name);
the dated tree excludes it because the reference has no sampling date. Dates
and branch lengths remain in simulation days, without assigning calendar dates.
model="JC" matches the simulator's symmetric nucleotide changes. Other IQ-TREE
models, including "GTR+G" and automatic selection with "MFP", are supported.
The clock rate is estimated by default; supply clock_rate in
substitutions/site/day to fix it. Identical sampling dates require a fixed
rate. Use dated=False to infer only the genetic tree without sampling dates.
timeout optionally limits inference runtime in seconds.
Each call creates a separate run-* directory beneath output_dir, containing
sampled FASTA, label mappings, genetic Newick, dated Newick/NEXUS, node-date TSV,
sampling dates, IQ-TREE/LSD2 reports, and logs. Alignment labels are safe backend
IDs recorded in taxon_labels.tsv; returned/exported tree labels are the
original case IDs. Inputs are preserved, and failures raise PhylogenyError
with the inference log path. Dated Newick is exported from LSD2's time-scaled
NEXUS, since its own .timetree.nwk file uses substitution lengths.
Use an Aligned FASTA and Sampling Dates
build_phylogenetic_tree_from_fasta() accepts an existing aligned DNA FASTA,
including gaps and IUPAC ambiguity bases. Choose a reference already in it:
from epilink import build_phylogenetic_tree_from_fasta
phylogeny = build_phylogenetic_tree_from_fasta(
"aligned_samples_with_reference.fasta",
reference_id="reference",
dates="sampling_dates.csv",
output_dir="phylogeny",
)
Or supply a separate, single-record reference FASTA aligned to the same columns:
phylogeny = build_phylogenetic_tree_from_fasta(
"aligned_samples_only.fasta",
reference_fasta="aligned_reference.fasta",
dates={
"sample-1": "2026-10-01",
"sample-2": "2026-10-04",
"sample-3": "2026-10-09",
},
)
Supply exactly one reference form. FASTA IDs are the first token of each header,
and at least three sample sequences are needed in addition to the reference.
All sequences must already share alignment columns. The default model="MFP"
uses IQ-TREE ModelFinder; inference options match the simulation helper.
Date files can be CSV or TSV with case_id and sample_date columns:
case_id,sample_date
sample-1,2026-10-01
sample-2,2026-10-04
sample-3,2026-10-09
Date mappings/files may instead use numeric days, such as
{"sample-1": 0.0, "sample-2": 3.5, "sample-3": 8.0}. Calendar values can also
be Python datetime.date objects. Use one date format per dataset; sample IDs
must match exactly (including leading zeros), with a date for every sample.
An optional reference date is ignored because the reference is an outgroup.
Both interfaces return PhylogenyResult. For calendar inputs, date_origin is
the earliest sample date; node_dates.date and node_dates.sample_date are days
relative to it. Additional calendar_date and sample_calendar_date columns
retain reconstructed and observed calendar datetimes, including ancestral dates
before the origin. The origin is also exported as date_origin.txt, with calendar
dates in node-date TSV and dated-tree comments. Numeric time origins are
preserved and have date_origin=None. Branch lengths and clock rates remain in
days and substitutions/site/day for either input format. Use dated=False for
a genetic tree without sampling dates. Source files are preserved.
Score a CSV File
The command-line interface expects an input CSV with these columns:
sample_time_differencegenetic_distance
epilink observations.csv \
--output scored_observations.csv \
--target "ad(0)" "ca(0,0)" \
--maximum-depth 2 \
--mc-samples 20000 \
--mutation-process stochastic
The output CSV includes an epilink_score column.
Mutation Models
mutation_process="deterministic"compares the observation with expected mutation counts.mutation_process="stochastic"compares the observation with Poisson mutation-count draws.
The stochastic option is usually preferable when mutation-count variability should contribute to the score.
Reproducibility
- Randomness is controlled by the transmission profile RNG, or by the explicit
rng=argument passed toEpiLink. - For reproducible scores and simulations, construct profiles with a fixed
rng_seedand reuse the resulting model instance. score_pair(...)andpairwise_model(...)use cached Monte Carlo draws, so repeated evaluations on the same model are stable unless you replacedraws_by_scenario.
Performance
EpiLink(...)precomputes scenario draws, so model construction is the main fixed cost.- Reuse one model instance for repeated scoring instead of rebuilding it inside loops.
- Use
pairwise_model(...)when scoring many observations against the same target subset. - See docs/performance.md for benchmark guidance.
Documentation
- Workflow figure: docs/epilink_schematic.pdf
- Performance guide: docs/performance.md
Development
Run the test suite:
python -m pytest
Run formatting and lint checks:
python -m ruff check src tests
python -m black --check src tests
python -m mypy src
Citation
If you use EpiLink in research, please cite the software metadata in CITATION.cff. The underlying infectiousness model is:
- Hart WS, Maini PK, Thompson RN. High infectiousness immediately before COVID-19 symptom onset highlights the importance of continued contact tracing. eLife. 2021;10:e65534. http://dx.doi.org/10.7554/eLife.65534
License
EpiLink is distributed under the MIT license. See LICENSE.
Acknowledgement
This project used AI-assisted development for code implementation, documentation, and utility commands.
Metadata
Release files for epilink 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| epilink-0.1.6.tar.gz | 607.0 kB | With provenance | Details for epilink-0.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| epilink-0.1.6-py3-none-any.whl | Python 3 | none | any | Details for epilink-0.1.6-py3-none-any.whl |
Total release size: 646.0 kB
Release files / epilink-0.1.6.tar.gz
| Download URL | epilink-0.1.6.tar.gz |
|---|---|
| Size | 607.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72c277f19a8cd58648e6e48fbd0e58c83f3c9328a61939356d41d399e892b90e
|
|
BLAKE2b-256 checksum How to use checksums |
16195ac7a8b207a69eba28a90fb80c0c66b386535cb15ac3b662d882d787d8db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / epilink-0.1.6-py3-none-any.whl
| Download URL | epilink-0.1.6-py3-none-any.whl |
|---|---|
| Size | 39.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
786f01aae5000e8d3ae31b4bbbd35159c712ced83424704e45a484b641d073fd
|
|
BLAKE2b-256 checksum How to use checksums |
5568edc2f8984b5676ffcb158ed4ffc31138bba5080ab4d21bd2d704de4bbc9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for epilink 0.1.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for epilink-0.1.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.