Commented guide to the simulation model

This guide annotates the exact source files in Online Resource 2 without changing their executable contents. It follows the order of model/duplication_invasion.slim and the portable R launchers.

1. Population-genetic question

The model separates two events that are often treated as one outcome of gene duplication:

  1. Access: can one new duplicate survive stochastic loss and increase in frequency?
  2. Divergence after retention: once two copies are already present throughout the population, does selection divide the two catalytic functions between them?

The same catalytic landscape is used in both experiments. DUP_INTRO_COPIES changes only the population-genetic starting point: one marked chromosome for access from a single origin, or 2*POP_SIZE marked chromosomes for imposed retention.

2. initialize(): parameters and genome structure

The first block assigns a default only when a value was not supplied with SLiM’s -d option. The R launchers therefore control an experiment without editing the model.

Population and time

  • POP_SIZE: diploid Wright–Fisher population size.
  • BURNIN_GENERATIONS: ancestral single-copy adaptation phase.
  • POST_DUPLICATION_GENERATIONS: observation phase after duplicate introduction.
  • GENERATIONS: required to equal the sum of the two phases.
  • OUTPUT_EVERY: interval for trajectory rows.
  • EVENT_CHECK_EVERY: interval for threshold-event checks.

The production design uses generation counts scaled by N, but no demographic rescaling is applied. Population size, mutation rate, recombination rate, and selection are passed directly.

Catalytic mutation model

  • RELATIONSHIP selects the correlation between mutational effects on activities 1 and 2.
  • MUT_RATE is the per-position catalytic mutation rate.
  • MUT_STEP_SD controls the magnitude of catalytic effects.
  • BASE_ACTIVITY sets the initial activity of each reaction.
  • RECOMB_RATE controls recombination across the simulated region.

The simulated genome contains two 1,000-position catalytic-copy intervals and one structural-marker position. Mutations arise across the catalytic intervals. The marker position has mutation rate zero because the duplicate is introduced explicitly at a declared generation.

Boundary, dosage, and selection

  • BOUNDARY_MODE = "hard" assigns zero feasibility outside the catalytic region.
  • BOUNDARY_MODE = "soft" applies an exponential penalty determined by SOFT_BOUNDARY_STRENGTH.
  • DOSAGE_MODE = "compensated" averages catalytic output across present copies.
  • DOSAGE_MODE = "additive" sums full copy contributions and normalizes them to the ancestral diploid.
  • SELECTION_STRENGTH scales log relative fitness before it becomes a Wright–Fisher reproductive weight.

DUP_COST is an additional cost paid by duplicate carriers. It was zero in the focal production analyses, allowing the compensated and additive contrasts to isolate immediate catalytic dosage.

Outcome thresholds

  • ESTABLISHMENT_FREQ and FIXATION_FREQ define duplicate-frequency events.
  • SPECIALIZATION_THRESHOLD defines complementary catalytic separation among carriers.
  • PERSIST_GENERATIONS requires specialization to remain above the threshold across time.
  • TARGET_FITNESS_FRACTION records recovery toward the declared catalytic target.

These thresholds are measurement rules. They do not alter reproduction except through options such as stopping after complete duplicate loss.

Ancestral-state reuse and mutation fates

The save/load parameters preserve a fully adapted ancestral population. writeAncestralMutationEffects() creates the required effect sidecar; restoreAncestralMutationEffects() reconnects those effects after a binary population file is loaded.

Mutation-fate parameters define a sampling window and classification thresholds. They are optional and do not alter the catalytic fitness calculation.

3. Assigning mutations to copies

hasDuplication() detects the structural marker. The mutation(m1) callback rejects a mutation in the second-copy interval when its genome does not carry that marker. Thus, the duplicated interval is mutationally available only after duplication, while the ancestral interval remains available in all genomes.

The callback draws a two-dimensional catalytic effect from the selected relationship. Strong antagonism makes opposing changes most likely; strong synergism makes aligned changes most likely. Effects are stored on each mutation so that activity can be reconstructed in every carrier.

4. Genotype-to-phenotype functions

The middle functions perform four linked calculations:

  1. sum catalytic effects separately for each copy and reaction;
  2. apply hard or soft catalytic feasibility boundaries;
  3. combine copy activities under the compensated or additive dosage rule; and
  4. translate the two required activities into relative fitness and then selection weight.

Specialization measures whether different copies disproportionately contribute to different reactions. Promiscuity measures joint activity within a copy. These are related but not interchangeable: a population can retain high total activity without dividing the reactions between copies.

5. introduceDuplication(): one origin or imposed retention

At DUP_INTRO_GENERATION, the function identifies genomes to receive the structural marker. The duplicated copy begins with the catalytic state already present on that chromosome. This models duplication of an existing enzyme rather than introduction of a blank copy.

The event record includes the immediate change in mean relative fitness and mean selection weight. Under additive dosage, this captures the initial benefit or cost caused by increased catalytic output before new mutations occur.

6. Wright–Fisher selection

fitnessEffect() returns the individual selection weight used by SLiM’s Wright–Fisher reproduction. Selection therefore acts every generation on the complete two-reaction phenotype. The two reactions are required functions; neither is treated as a neutral side activity.

7. late(): state restoration, events, and outputs

The main late() callback:

  • restores a saved ancestral population before post-duplication evolution;
  • registers and updates optional mutation-fate cohorts;
  • computes population metrics at output and event intervals;
  • records the first establishment, near-fixation, loss, specialization, persistent specialization, and fitness-target events;
  • writes generation-level trajectories;
  • saves an ancestral state at the end of burn-in when requested; and
  • writes one terminal summary before ending the simulation.

STOP_ON_DUPLICATION_LOSS is useful for large single-origin designs because no subsequent duplicate specialization is possible after the marker is absent. Retained-duplication runs continue through the declared endpoint.

8. Output files

Trajectory CSV

Contains generation, phase, time scaled by population size, mean and standard deviation of relative fitness and selection weight, both catalytic activities, specialization, promiscuity, duplicate and carrier frequencies, boundary metrics, and segregating catalytic mutation count.

Event CSV

Contains the generation and value associated with each first threshold crossing. A header-only event file is valid when no outcome threshold is reached.

Summary CSV

Contains the terminal state, absolute event generations, times since duplicate introduction, and final population metrics. This is the primary input for event-probability and time-to-outcome analyses.

Mutation origin and fate CSVs

When activated, these files connect each sampled mutation to its catalytic effects, genetic background, realized selection effect, maximum observed frequency, and terminal fate.

9. Portable R scripts

run_invasion_grid.R

Reads a complete CSV, validates required columns, creates a consistent output tree, and runs rows sequentially or with forked local workers. It is restart-safe: a row is reused only when required files contain complete data. Use this script for local grids:

Rscript scripts/run_invasion_grid.R config.csv --slim slim --workers 4 --output-root results

State-bank grids must finish before any grid that loads those states. Do not run save and load rows concurrently unless the states already exist.

run_invasion_row.R

Runs one one-based row from a grid. This was the portable unit used in array workflows:

Rscript scripts/run_invasion_row.R config.csv 1 --slim slim --output-root results

check_invasion_run.R

Counts complete summary and trajectory files and scans logs for error terms:

Rscript scripts/check_invasion_run.R results/RUN_SET EXPECTED_RUNS

The check reports COMPLETE, IN PROGRESS, or ATTENTION REQUIRED. A completed count is necessary but does not replace the experiment-specific validation and statistical analyses described in the article.

10. Frozen production configurations

The config/ directory preserves the rows, seeds, condition-specific burn-ins, state identifiers, and matched dosage settings used to reconstruct the reported experiments. The sequence is:

  1. stationarity calibration and targeted extensions;
  2. state-bank creation for stationary, 60N ridge, 80N ridge, and added-precision ancestors;
  3. retained-duplication and single-origin compensated experiments; and
  4. additive dosage experiments loaded from the same state bank and paired by seed.

The primary retained analysis and the larger dosage-matched retained control deliberately use different ridge-state durations, as explained in README.md. Preserve their labels and analyze them as separate declared contrasts.