.. _sec_introduction:

============
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.

See also:

- `stdgrimmsim <https://github.com/kevinkorfmann/stdgrimmsim>`_ --- diverse
  training data from German folklore (32 species, 134 models across 4 complexity
  levels).
- `stdvoidsim <https://github.com/kevinkorfmann/stdvoidsim>`_ --- stress-testing
  with extreme Lovecraftian scenarios (40 species, 82 models; Ne from 1 to 10^6).


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 :ref:`Installation <sec_installation>` page to get ``stdferdowsim``
   installed on your computer.

 - Skim the :ref:`Catalog <sec_catalog>` to see all 36 species and 360 demographic
   models.

 - Read the :ref:`Tutorials <sec_tutorial>` 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 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_.