Introduction¶

This is the documentation for stdferdowsim, a library of population genetic simulation models for creatures and heroes from Persian mythology, Ferdowsi’s Shahnameh (Book of Kings), and Zoroastrian cosmology.

Purpose¶

stdferdowsim is a fork catalog of stdpopsim: it shares the same API and simulation engines but replaces the species catalog with 36 fictional taxa from Persian mythology.

Primary use case: benchmarking admixture-graph inference methods and testing population-genetic tools that must handle non-tree-like (reticulate) demographic histories.

Unlike the companion catalogs, stdferdowsim focuses on scenarios where the true demographic history is not a simple bifurcating tree:

Pulse admixture — discrete gene flow events between diverged lineages.
Ghost populations — extinct lineages that contributed ancestry before disappearing, leaving no sampled descendants.
5–8 population models — testing graph inference at scales beyond the usual 2–4 demes.
Extinction and recolonization — populations that go fully extinct and are refounded from neighbouring demes.
Asymmetric migration reversal — directionality of gene flow that changes over time.
Silk Road stepping-stone models — 8-deme geographic models along historical trade routes.

These scenarios are central to modern population genetics (e.g. ancient DNA, admixture-graph methods like qpAdm, TreeMix, momi2) but are poorly represented in existing simulation benchmarks.

Model complexity taxonomy¶

Every species in stdferdowsim has exactly 10 demographic models, organized by increasing topological complexity:

Level 1 — 1-population constant (36 models). Constant_1F10.
Level 2 — 1-population three-epoch with bottleneck (36 models). ThreeEpoch_1F10.
Level 3 — 2-population split with symmetric migration (36 models). TwoPopSplit_2F10.
Level 4 — 3-population ghost admixture (36 models). Two sampled populations + one extinct ghost that contributes pulse admixture. GhostAdmixture_3F10.
Level 5 — 3-population bidirectional admixture (36 models). Complex admixture graph not representable as a tree. ThreePopAdmix_3F10.
Level 6 — 4-population stepping-stone (36 models). Four populations arranged geographically across the Iranian plateau. FourRegion_4F10.
Level 7 — 5-population admixture graph (36 models). Five populations (Iran, Turan, Rum, Hind, Chin) with pulse admixture. FiveRealm_5F10.
Level 8 — 6-population extinction/recolonization (36 models). Six populations with local extinction and refounding. SixPopExtRecolon_6F10.
Level 9 — 2-population asymmetric migration reversal (36 models). Migration direction changes over time. AsymReversal_2F10.
Level 10 — 8-population Silk Road stepping-stone (36 models). Eight cities along Silk Road trade routes with stepping-stone migration. SilkRoad_8F10.

Species categories¶

The 36 species are grouped into thematic categories:

Shahnameh Creatures & Heroes (16 species): Simurgh (SimAvi), Div (DivMaz), Azhdaha dragon (AzhDra), Rostam-lineage (RosHer), Rakhsh (RakEqu), Zal (ZalAlb), Rudabeh (RudSim), Esfandiyar (EsfSmi), Jamshid (JamPis), Kayanian (KayDyn), Bahram (BahFir), Pahlavan (PahDiv), Sorcerer (SorWiz), Div-e Sepid (DouGia), Afrasiyab (AfrHor), Turanian (TurNom).
Spirits, Jinn & Peris (7 species): Jinn (PriJin), Peri (PerPar), Al (AlDem), Ghoul (GhoUnd), Daeva (DaeWar), Druj (DraAng), Gul-spirit (GulRos).
Mythical Birds & Beasts (6 species): Huma (HumBir), Manticore (ManTig), Senmurv (SenBir), Chamrosh (ChaGri), Shahbaz (ShaSha), Gavaevodata (GavPri).
Zoroastrian Cosmology (5 species): Faravahar (FarGlo), Mithra (MitSol), Yazata (YazGua), Zoroaster-lineage (ZorPri), Khidr (KhiWis).
Cross-cultural & Regional (2 species): Nart-spirit (NarHer), Marduk-spirit (MarMor).

First steps¶

Head to the Installation page to get stdferdowsim installed on your computer.

Skim the Catalog to see all 36 species and 360 demographic models.

Read the Tutorials to see some examples of stdferdowsim in action.

Citations¶

stdferdowsim is built on the stdpopsim framework. If you use the simulation framework, please cite:

Jeffrey R Adrion et al. (2020), A community-maintained standard library of population genetic models, eLife 9:e54967; doi: https://doi.org/10.7554/eLife.54967

M Elise Lauterbur et al. (2023), Expanding the stdpopsim species catalog, and lessons learned for realistic genome simulations, eLife 12:RP84874; doi: https://doi.org/10.7554/eLife.84874

Licence and usage¶

stdferdowsim is available under the GPLv3 public license. The terms of this license can be read here.