PalantiR

⭐ Recently updated (August 2026): version 1.2.0 contains substantial correctness fixes and polishing updates, following a full source review. The documentation site has been rebuilt with reproducible examples, and the repository now includes stand-alone command-line simulation scripts.

PalantiR is a framework for the simulation and visualization of sequence evolution along phylogenies, and is implemented as an R package with a fast C++ backend and interactive js visualizations.

The package facilitates the simulation and visualization of complete substitution histories, including the precise timing of substitution events, codon state transitions, and fitness flux. Palantir primarily uses time-heterogeneous mutation–selection codon substitution models that account for the fitness of amino-acid sequence states at each codon site. Models support site-specific fitness profiles, and fitness interactions between sites can be defined using a straightforward extension of Halpern-Bruno type models ("mutation-selection-epistasis" codon models), which are supported in a paired-site configuration. Changes in effective population size and fitness profile assignments are allowed along branches, and the transient approach from one stationary distribution to another, following a model change-point, is carefully modelled.

See the documentation at dekoning-lab.github.io/PalantiR

Visualization examples:

1. Substitution histories simulated under a mutation–selection model with epistasis between site pairs; joint states of the interacting sites are shown alongside the events on the tree:

2. A fitness shift under a time-heterogeneous mutation–selection model; each dot is a substitution (synonymous in green, non-synonymous in red), with the site's stationary distribution summarized as a frequency logo:

Recent updates

Version 1.3.0 makes scaling_type = "synonymous" an explicit dS gauge: branch lengths are neutral synonymous substitutions per synonymous opportunity, matching neutral nucleotide substitutions per site. The previous one-synonymous-event-per-codon convention is available as "synonymous-per-codon". GY94 uses its omega = 1 reference; mutation--selection models use a mutation-only reference shared across fitness profiles. During a fitness or population-size shift, the transient rescaler preserves the neutral-reference dS clock; it does not reinterpret dS as one realized synonymous event per codon.

Version 1.2.1 fixes event-position reporting through stiff transients under rescale_method = "exact"; the defect was found by the engine validation notebook (below) and is included in new regression tests.

Version 1.2.0 is a substantial overhaul that introduces a number of fixes and improvements. This includes updates to the mutation-selection-epistasis models in CoEvolution, affecting scaling and double-substitution semantics, patching of GTR switching processes for Markov-modulated models, input validation throughout, reproducible simulations via set_palantir_seed(), and a regression test suite. Some of these fixes change simulated output relative to earlier versions; NEWS.md lists critical changes in full.

Version 1.1.0 corrects the transient rescaler for time-heterogeneous simulations, which previously did not correctly account for rate variation. We've also added an opt-in to a faster, exact approach for simulating the transient approach to a new stationary distribution using rescale_method = "exact". This approach replaces our branch segmentation algorithm with a closed-form time change. For event-count scaling, the rescaler ensures that the expected number of substitutions per unit branch length is exact.

Installation

The package can be installed automatically with devtools:

devtools::install_github("dekoning-lab/PalantiR")

If you are installing from a local clone, use:

devtools::install_local("path/to/palantir/clone")

Note: RcppArmadillo is a required package. Compiling against it will require gfortran

For MacOS, a copy of gfortran binaries can be downloaded from CRAN tools

Downloading

First, clone the PalantiR repo:

git clone https://github.com/dekoning-lab/PalantiR.git

Dependencies

The dependencies for the R package can be installed as follows:

install.packages(c("Rcpp", "RcppArmadillo", "jsonlite", "htmlwidgets", "Matrix", "lattice"))

Building

If using RStudio, hit "Build & Reload".

Otherwise, navigate to one directory above PalantiR, and run:

R CMD INSTALL --preclean --no-multiarch --with-keep.source PalantiR

In a new R session, run:

library(PalantiR)

Short demonstration

Below we show how to run a simulation with the Mutation-Selection model:

use_genetic_code("Standard nuclear")

# read phylogeny (from a clone, this file is inst/extdata/mammals.newick)
p <- Phylogeny(system.file("extdata", "mammals.newick", package = "PalantiR"))

# read amino acid fitness values
data(amino_acid_fitness_N_1000)
aa_psi <- amino_acid_fitness_N_1000

# use first row
psi <- as.numeric(aa_psi[1,])

# make nucleotide substitution model
hky <- HasegawaKishinoYano(equilibrium = c(.25, .25, .25, .25))

# make codon substitution model
ms <- MutationSelection(
	population_size = 1000,
	mutation_rate = 1e-8,
	nucleotide_model = hky,
	fitness = psi)

# sample sequence from model equilibrium
s <- sample_sequence(model = ms, length = 100)

# simulate
sim <- simulate_over_phylogeny(phylogeny = p, model = ms, sequence = s)

We can view the resulting alignment:

# examine alignment
plot(sim$alignment)

# save alignment as fasta
as.fasta(sim$alignment, "PalantiR_ms.fa")

We can also visualize the substitutions that have been simulated:

# examine substitutions (sites are 0-based, so the first ten are 0:9)
plot(sim, sites = 0:9)

# check specific substitution data
head(sim$substitutions)

Goldman--Yang branch-site simulation

PalantiR also supports GY94 models with discrete site classes and branch heterogeneity. This example constructs the four standard Zhang--Nielsen--Yang classes: classes 0 and 1 retain their background omega on the foreground, whereas classes 2a and 2b switch to omega2.

use_genetic_code("Standard nuclear")

tree <- Phylogeny(system.file("extdata", "mammals.newick", package = "PalantiR"))
foreground <- Phylogeny(
    system.file("extdata", "mammals_switch.newick", package = "PalantiR"),
    type = "mode")

branch_site <- ZNYBranchSiteModel(
    mode_phylogeny = foreground,
    site_counts = c(40, 20, 20, 20), # classes 0, 1, 2a, and 2b
    omega0 = 0.2,
    omega2 = 3,
    kappa = 2,
    frequencies = c(T = 0.25, C = 0.25, A = 0.25, G = 0.25),
    frequency_model = "F1x4",
    scaling_type = "standard")

set_palantir_seed(20260825)
gy_sim <- simulate_gy94_site_model(tree, branch_site)

head(gy_sim$site_classes)
head(gy_sim$substitutions)
plot(gy_sim$alignment)       # site-class labels appear above the alignment
plot(gy_sim, sites = 0:9)    # event tooltips include the site class

The general GY94SiteModel() constructor can instead mix any number of time-homogeneous and branch-heterogeneous GY94 classes. Site classes share one mixture-weighted scaling denominator (one per branch type in a branch-site model), so branch lengths measure the mean rate across the mixture while relative rates among classes are retained. See the GY94 model page for frequency formats, scaling conventions, and output metadata.

The live R/PalantiR history-validation notebook provides a larger feature demonstration: it constructs the model, simulates 5,000 codons on a 50-taxon tree with two branch-specific omega values, inspects the native interactive alignment and history viewers, and reconstructs Goldman--Yang dN/dS from the complete recorded histories in one R kernel. A separate Python audit notebook independently recomputes the production artifact, and a polished reader view is also available.

Command-line simulation

The examples/ directory contains stand-alone scripts that run PalantiR simulations from the shell, with arguments for the tree, population sizes, number of sites, and random seed (run with --help for the full list):

# time-homogeneous mutation-selection with site-heterogeneous fitness profiles
Rscript examples/simulate_site_heterogeneous.R --sites=200 --population-size=10000

# time-heterogeneous: a larger population size on the primate clade
Rscript examples/simulate_time_heterogeneous.R --population-sizes=5000,30000

Each script writes codon and amino-acid FASTA alignments, the complete substitution history, an interactive substitution-history plot, and a run_info.txt recording parameters, seed, and package versions.

Engine validation

validation/engine_validation.Rmd tests the simulation engine against exact expectations and renders a standalone report with a pre-stated pass criterion and a computed verdict for each test: branch-length calibration under the three event-count gauges; homogeneous and time-heterogeneous dS calibration for GY94 and mutation--selection models; the stationary distribution against observed state frequencies; and the transient between two equilibria, compared with the master equation under both rescale methods.

The current report passes all tests under version 1.3.0. To rerun it with your own seed and simulation size:

# in validation/, with PalantiR and rmarkdown installed
rmarkdown::render("engine_validation.Rmd", params = list(seed = 1, n_sites = 3000))

The separate live R/PalantiR GY94 history-validation notebook tests branch-specific omega recovery from complete substitution histories; its rendered report also serves as a compact GY94 feature demonstration. This older event-count experiment now names its scaling explicitly as "synonymous-per-codon"; it does not use the default dS gauge.