A stochastic simulator for synthetic protein families.
FakeProt is a stochastic simulator for generating synthetic protein families with known evolutionary histories. It produces multiple-sequence alignments, a gene tree, a species cladogram, ortholog-group assignments, ancestral sequences, and per-column physicochemical annotations. The intended use is methodological benchmarking: aligners, tree inference procedures, orthology pipelines, ancestral-sequence methods, and downstream comparative-genomics workflows can be tested against data for which the generating history is known.
Simulation studies in molecular evolution often require sequence families whose ground truth is explicit: the species tree, gene tree, duplication history, ortholog groups, ancestral states, and column-wise constraints should all be recoverable. FakeProt implements a discrete, event-driven generator for protein families. Starting from a single ancestral protein, the simulator repeatedly selects an extant species, optionally creates a paralog by gene duplication (Ohno, 1970), and then speciates the selected lineage into two daughter species. Sequence evolution along every gene-tree edge combines WAG-derived amino-acid substitution probabilities (Whelan & Goldman, 2001), gamma-distributed site-rate heterogeneity (Yang, 1994), a TKF92-compatible fragment indel model (Thorne, Kishino & Felsenstein, 1992), and probabilistic physicochemical constraints based on overlapping amino-acid property classes (Taylor, 1986). Insertions are represented as new alignment columns, while deletions are represented as gaps, so every emitted sequence remains in a common alignment.
FakeProt is not intended to be a fully calibrated biological model of protein evolution. Its substitution and indel components follow continuous-time formulations (WAG CTMC, TKF92), but the physicochemical constraint scheme and rate parameters are not estimated from empirical data. It is a transparent benchmark generator whose parameters control sequence-family size, root length, indel frequency, site-rate heterogeneity, and the target number of ortholog groups.
FakeProt requires Python 3.10 or later.
pip install .For development:
pip install -e ".[dev]"# 50 extant sequences, root length 200, three ortholog groups, fixed seed
fakeprot 50 200 -n 3 -r 42 -o my_familyThe command above writes a set of FASTA, tree, CSV, and JSON files using
my_family as the filename prefix.
fakeprot SIZE LENGTH [options]
| Argument | Meaning |
|---|---|
SIZE |
Minimum number of extant, leaf-level sequences to generate. The final number can exceed this value because one simulation step may add multiple leaves. |
LENGTH |
Root sequence length before lineage-specific insertions. |
| Option | Default | Meaning |
|---|---|---|
-o, --out
|
fakeprot_out |
Prefix for all output files. |
-d, --mu
|
0.05 |
TKF91/92 deletion rate |
-i, --lam
|
0.001 |
TKF91/92 insertion rate |
--q |
0.5 |
TKF92 fragment extension probability |
-n, --n-orthologs
|
1 |
Target number of ortholog-group anchors. |
-a, --alpha
|
0.75 |
Shape parameter |
-b, --branch-length
|
0.05 |
Expected substitutions per site on a branch of average rate. Controls overall sequence divergence; also scales the per-edge intensities |
--dup-boost-factor |
2.0 |
Branch-length multiplier applied to a boosted duplicate edge. |
--dup-boost-decay |
3.0 |
E-folding distance in speciation steps for the post-duplication rate burst. Set to 0 for a single-edge burst only. |
--branch-cv |
0.4 |
Coefficient of variation for per-branch stochastic rate noise (σ_log ≈ 0.39). Each speciation edge draws its length from a mean-preserving log-normal; 0 gives deterministic (equal-length) branches. Default chosen as the centre of the empirical range reported by Drummond et al. (2006). |
-r, --seed
|
None |
Random seed for reproducible simulations. |
-f, --msa-format
|
fasta |
Alignment format: fasta, clustal, nexus, phylip, or stockholm. |
-t, --tree-format
|
newick |
Tree format: newick, nexus, nexml, phyloxml, or cdao. |
Let dat/wag.dat). The WAG rate matrix has off-diagonal entries
where
Let
The conditional amino-acid distribution inside class
Given root length
so the mean rate equals 1, following the standard phylogenetic convention
(Yang, 1994). These rate values are then reordered by a local smoothing procedure
(wave_shuffle). Each rate
so that all keys lie in
The original gamma-derived rates are returned in the order determined by this
traversal, so the marginal rate distribution is unchanged. Using normalised
substitution probabilities as sort keys ensures the kernel has full dynamic range
for any
The ancestral sequence begins with methionine:
For every other site
If constrained, the class is drawn from
For each child sequence, FakeProt iterates through the parent sequence from left
to right. At a non-gap site with parent residue
where --mu and
If the site is not deleted, the substitution probability is derived from the
standard continuous-time Markov chain survival formula for a branch of length
If there is no physicochemical constraint, the new residue is sampled using the
WAG conditional substitution matrix
If the site is constrained to physicochemical class
(Since
When
If
Gaps in the final alignment arise from two distinct processes with separate
per-branch Poisson intensities --mu) and --lam) are the TKF91/92 rate parameters.
Deletions accumulate along each lineage's path from the root. For a Yule
(pure-birth) tree with
Insertions in any one lineage create a new alignment column that appears
as a gap in all other
These formulas simplify to the above form because the gamma rates
The likelihood that a gappy column with
Columns with few gaps (
The defaults are design choices tuned to produce realistic scaling behaviour rather than values read directly from any single empirical study:
giving per-edge intensities
After each non-gap site — whether the site survives or is deleted — FakeProt may introduce an insertion fragment using the TKF92 birth/death model (Thorne, Kishino & Felsenstein, 1992). This is a fragment generalisation of TKF91 (Thorne, Kishino & Felsenstein, 1991) in which insertions arrive as geometric-length runs rather than single residues.
Let --q, default 0.5) is the fragment extension probability. The
TKF92 probability that at least one fragment is inserted after site
with the limit
This gives a geometrically distributed run length with mean --lam directly controls the
per-unit-rate residue insertion intensity regardless of
Deletions do not suppress fragment birth: a deleted position can still birth a fragment (a "ghost lineage" in TKF terminology), consistent with the continuous-time formulation.
A geometric run-length distribution is a tractable approximation to the
Zipfian (power-law) distribution empirically observed in real protein
alignments, where the probability of a gap of length
Inserted residues are sampled from the WAG background distribution, assigned rate
Existing gap runs can also be filled in descendant lineages. The first position
in a gap run is filled with the TKF92 probability
FakeProt maintains two directed graphs during simulation: a species tree and a sequence/gene tree. The species tree contains extant and ancestral species nodes. The gene tree contains ancestral, duplicated, and extant sequence nodes. The orthology and paralogy terminology used throughout follows the definitions introduced by Fitch (1970) and the modern formulation reviewed by Koonin (2005): orthologs descend from a common ancestor via speciation, while paralogs descend via gene duplication.
At each simulation step:
- One extant species is selected uniformly at random.
- A gene duplication may occur inside that species.
- The selected species is split into two daughter species.
- Each paralog in the selected species independently evolves into one child sequence in each daughter species.
The process stops when the number of extant sequence leaves is at least SIZE.
Let
When a duplication occurs, one paralog in the selected species is copied and mutated. The new copy becomes an ortholog-group anchor. Its rate profile is redrawn using a perturbed shape parameter
with scale fixed to
For duplicated sequences, physicochemical constraints may also be relaxed or
changed. Let dup_boost_factor for a boosted duplication, and
If the retained or newly chosen class does not contain the current residue,
FakeProt resamples the residue using the WAG probabilities restricted to the new
class. Sites with no parent constraint (
Each duplication modulates the new copy's divergence rate. The duplicate's creation edge and its downstream lineage carry an elevated branch-length multiplier that decays exponentially with each subsequent speciation event:
where dup_boost_factor (default 2.0). At dup_boost_decay
(default 3.0) it has decayed by --dup-boost-decay 0 restricts
the boost to the duplicate's creation edge only. This models the transient rate
asymmetry between paralogs observed in the period immediately following
duplication (Ohno, 1970; Conant & Wagner, 2003; Lynch & Conery, 2000;
Kellis et al., 2004). The boost is directly visible in the output gene tree: edges in the
duplicate's subtree carry their elevated generative branch length, decaying
toward the global rate with each subsequent speciation event.
Speciation replaces one extant species by two daughter species. Every paralog in the parent species gives rise to one independently mutated copy in each daughter. Thus a speciation event branches both the species tree and, for every inherited paralog, the gene tree.
Ortholog groups are defined by anchor nodes (Fitch, 1970; Koonin, 2005): the
root sequence and every successful duplication copy. A leaf belongs to anchor
This definition ensures that every extant sequence is assigned to exactly one ortholog group in the emitted CSV file.
Gene-tree edge weights are the generative branch-length values recorded at the
time of evolution. For each speciation edge the realised length is drawn
independently from a log-normal with mean --branch-cv; with
--branch-cv 0 every edge uses the mean exactly. Because these values are
stored during simulation rather than derived from the alignment after the fact,
they constitute true ground-truth branch lengths for the simulated family.
The species cladogram is emitted without branch lengths.
For output prefix PREFIX, FakeProt writes:
| File | Contents |
|---|---|
PREFIX_all_sequences.<msa-format> |
All generated sequences, including ancestral and internal sequence nodes. |
PREFIX_current_sequences.<msa-format> |
Extant leaf sequences only. |
PREFIX_gene_tree.<tree-format> |
Gene tree with generative (ground-truth) branch lengths. |
PREFIX_species_cladogram.<tree-format> |
Species cladogram without branch lengths. |
PREFIX_ortholog_groups.json |
Mapping from extant sequence identifiers to ortholog-group labels ({"sp1_seq1": "OG_A", ...}). |
PREFIX_OG_A.<msa-format>, PREFIX_OG_B.<msa-format>, ... |
Per-ortholog-group alignments, emitted when --n-orthologs > 1. |
PREFIX_physicochemical_groups.json |
Per-column amino-acid frequencies and physicochemical class annotations for each ortholog group. |
PREFIX_run_info.json |
Version, timestamp, parameters, and random seed for reproducibility. |
Sequences are stored in three aligned NumPy arrays: amino-acid/gap codes, site-rate values, and physicochemical-class codes. Insertions are handled by adding columns to the global alignment store and filling earlier rows with gap sentinels. This makes output generation straightforward because every internal and extant sequence is already represented in a shared alignment.
Trees and traversal operations are implemented with NetworkX. Sequence and tree serialization use Biopython, and tabular outputs use pandas.
FakeProt is a benchmark simulator rather than an inference-calibrated biological model. In particular:
- Physicochemical classes overlap (Taylor, 1986), so class priors are normalized over class masses rather than over a partition of amino acids.
- The requested number of ortholog groups is a target, not a hard guarantee; if too few duplication opportunities occur before the leaf target is reached, the simulator emits a warning.
- The requested size is a lower bound because one speciation event can add more than one sequence leaf.
These design choices make the simulator easy to inspect and useful for controlled benchmarking, but they should be considered when interpreting results as biological evolutionary histories.
pip install -e ".[dev]"
pytestIf you use this simulator in your research, please cite the original software and the associated publication (if any). The original module was developed by Lucas Carrijo de Oliveira (lucas@ebi.ac.uk). For now, you may reference the repository directly:
Lucas C. de Oliveira. FakeProt. 2018–2026.
https://github.com/lucas-ebi/fakeprot
A formal publication is in preparation; check the repository for updates.
Whelan, S. and Goldman, N. (2001). A general empirical model of protein evolution derived from multiple protein families using a maximum-likelihood approach. Molecular Biology and Evolution, 18(5), 691–699.
Yang, Z. (1994). Maximum likelihood phylogenetic estimation from DNA sequences with variable rates over sites: approximate methods. Journal of Molecular Evolution, 39(3), 306–314.
Felsenstein, J. and Churchill, G. A. (1996). A Hidden Markov Model approach to variation among sites in rate of evolution. Molecular Biology and Evolution, 13(1), 93–104.
Yang, Z. (1995). A space-time process model for the evolution of DNA sequences. Genetics, 139(2), 993–1005.
Taylor, W. R. (1986). The classification of amino acid conservation. Journal of Theoretical Biology, 119(2), 205–218.
Thorne, J. L., Kishino, H. and Felsenstein, J. (1991). An evolutionary model for maximum likelihood alignment of DNA sequences. Journal of Molecular Evolution, 33(2), 114–124.
Thorne, J. L., Kishino, H. and Felsenstein, J. (1992). Inching toward reality: an improved likelihood model of sequence evolution. Journal of Molecular Evolution, 35(1), 3–16.
Benner, S. A., Cohen, M. A. and Gonnet, G. H. (1993). Empirical and structural models for insertions and deletions in the divergent evolution of proteins. Journal of Molecular Biology, 229(4), 1065–1082.
Chang, M. S. S. and Benner, S. A. (2004). Empirical analysis of protein insertions and deletions determining parameters for the correct placement of gaps in protein sequence alignments. Journal of Molecular Biology, 341(2), 617–631.
Yule, G. U. (1925). A mathematical theory of evolution, based on the conclusions of Dr. J. C. Willis, F.R.S. Philosophical Transactions of the Royal Society of London, Series B, 213, 21–87.
Aldous, D. J. (2001). Stochastic models and descriptive statistics for phylogenetic trees, from Yule to today. Statistical Science, 16(1), 23–34.
Fitch, W. M. (1970). Distinguishing homologous from analogous proteins. Systematic Zoology, 19(2), 99–113.
Koonin, E. V. (2005). Orthologs, paralogs, and evolutionary genomics. Annual Review of Genetics, 39, 309–338.
Drummond, A. J., Ho, S. Y. W., Phillips, M. J. and Rambaut, A. (2006). Relaxed phylogenetics and dating with confidence. PLoS Biology, 4(5), e88.
Ohno, S. (1970). Evolution by Gene Duplication. Springer-Verlag, Berlin.
Conant, G. C. and Wagner, A. (2003). Asymmetric sequence divergence of duplicate genes. Genome Research, 13(9), 2052–2058.
Lynch, M. and Conery, J. S. (2000). The evolutionary fate and consequences of duplicate genes. Science, 290(5494), 1151–1155.
Kellis, M., Birren, B. W. and Lander, E. S. (2004). Proof and evolutionary analysis of ancient genome duplication in the yeast Saccharomyces cerevisiae. Nature, 428(6983), 617–624.
Finn, R. D., Mistry, J., Schuster-Böckler, B., Griffiths-Jones, S., Hollich, V., Lassmann, T., Moxon, S., Marshall, M., Khanna, A., Durbin, R. et al. (2006). Pfam: clans, web tools and services. Nucleic Acids Research, 34, D247–D251.
Mistry, J., Chuguransky, S., Williams, L., Qureshi, M., Salazar, G. A., Sonnhammer, E. L. L., Tosatto, S. C. E., Paladin, L., Raj, S., Richardson, L. J., Finn, R. D. and Bateman, A. (2021). Pfam: the protein families database in 2021. Nucleic Acids Research, 49(D1), D412–D419.
GNU General Public License v3.0 or later. See LICENSE.
Copyright (C) 2018 Lucas Carrijo de Oliveira.