Metadata-Version: 2.4
Name: stdferdowsim
Version: 0.1.0
Summary: A library of population genetic simulation models for Persian mythology and the Shahnameh
Home-page: https://github.com/kevinkorfmann/stdferdowsim
Author: stdferdowsim contributors
Author-email: popgen_benchmark@lists.uoregon.edu
License: GPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: msprime>=1.0.4
Requires-Dist: attrs>=19.1.0
Requires-Dist: appdirs
Requires-Dist: humanize
Requires-Dist: pyslim>=1.0.4
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: pytest-cov>=7; extra == "dev"
Requires-Dist: pytest-xdist>=3; extra == "dev"
Requires-Dist: flake8>=7; extra == "dev"
Requires-Dist: coverage>=7; extra == "dev"
Requires-Dist: biopython; extra == "dev"
Requires-Dist: kastore; extra == "dev"
Requires-Dist: scipy; extra == "dev"
Requires-Dist: scikit-allel; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-issues; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
Requires-Dist: demesdraw; extra == "docs"
Requires-Dist: matplotlib; extra == "docs"

# stdferdowsim

[![PyPI version](https://img.shields.io/pypi/v/stdferdowsim?color=C47A2B)](https://pypi.org/project/stdferdowsim/)
[![PyPI downloads](https://img.shields.io/pypi/dm/stdferdowsim?color=B8860B)](https://pypi.org/project/stdferdowsim/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/stdferdowsim?color=8B6914)](https://pypi.org/project/stdferdowsim/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-DAA520.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docs](https://img.shields.io/github/actions/workflow/status/kevinkorfmann/stdferdowsim/docs.yml?branch=main&label=docs&color=CD853F)](https://stdferdowsim.readthedocs.io/en/latest/)

**Install:** `pip install stdferdowsim` · **Docs:** [stdferdowsim.readthedocs.io](https://stdferdowsim.readthedocs.io/en/latest/)

A community-maintained library of population genetic simulation models for
**Persian mythology, the Shahnameh, and Zoroastrian cosmology**.

**36 species · 360 demographic models** emphasizing admixture graphs, ghost populations, and non-tree-like histories.

<p align="center">
  <img src="docs/_static/ferdowsi_placeholder.png" alt="Ferdowsi" width="200"/>
  <br><em>Placeholder for Ferdowsi portrait — to be replaced</em>
</p>

> See also: [**stdgrimmsim**](https://github.com/kevinkorfmann/stdgrimmsim) — diverse training data from German folklore (32 species, 134 models) · [**stdvoidsim**](https://github.com/kevinkorfmann/stdvoidsim) — stress-testing with extreme Lovecraftian scenarios (40 species, 82 models).

## Purpose

`stdferdowsim` is a *fork catalog* of [stdpopsim](https://stdpopsim.org): it shares the same API and simulation engines (msprime, SLiM) but replaces the species catalog with fictional taxa from Persian mythology.

**Primary use case: benchmarking admixture-graph inference** — testing methods that must infer non-tree-like histories including pulse admixture, ghost populations, extinction-recolonization, and complex reticulate topologies with 5-8 populations.

| | stdferdowsim | stdgrimmsim | stdvoidsim |
|---|---|---|---|
| **Focus** | Admixture graphs & reticulate histories | Diverse training data & benchmarking | Stress-testing & identifiability limits |
| **Species** | 36 (Persian mythology) | 32 (German folklore) | 40 (Cthulhu Mythos) |
| **Models** | 360 (1- to 8-population) | 134 (1- to 4-population) | 82 (1- and 2-population) |
| **Key feature** | Ghost pops, pulse admixture, 5-8 demes | 4-cluster rate architecture | Extreme parameters (Ne=1 to 10^6) |
| **Parameter range** | Moderate to deep-time | Moderate, plausible | Extreme |
| **Ploidy** | All diploid | All diploid | Diploid to hexaploid |

## What makes stdferdowsim unique

Unlike the other catalogs, every species in stdferdowsim includes models with:

- **Pulse admixture events** — not just continuous migration, but discrete gene flow pulses
- **Ghost populations** — extinct lineages that contributed ancestry before disappearing
- **5-8 population models** — far beyond the 4-pop maximum in stdgrimmsim
- **Extinction and recolonization** — populations that die out and are re-founded
- **Asymmetric migration reversal** — migration direction changes over time
- **Silk Road stepping-stone models** — 8-deme geographic models along trade routes

## Model Complexity Taxonomy

| Level | Type | Count | Examples |
|-------|------|-------|----------|
| **1** | 1-population constant | 36 | `Constant_1F10` |
| **2** | 1-population piecewise (3 epochs) | 36 | `ThreeEpoch_1F10` |
| **3** | 2-population split + migration | 36 | `TwoPopSplit_2F10` |
| **4** | 3-population ghost admixture | 36 | `GhostAdmixture_3F10` |
| **5** | 3-population bidirectional admixture | 36 | `ThreePopAdmix_3F10` |
| **6** | 4-population stepping-stone | 36 | `FourRegion_4F10` |
| **7** | 5-population admixture graph | 36 | `FiveRealm_5F10` |
| **8** | 6-population extinction/recolonization | 36 | `SixPopExtRecolon_6F10` |
| **9** | 2-population migration reversal | 36 | `AsymReversal_2F10` |
| **10** | 8-population Silk Road | 36 | `SilkRoad_8F10` |

## Available Species

### Shahnameh Creatures & Heroes

| ID | Species | Common Name | Ne | Gen Time | Models |
|--------|-------------------------------|--------------------------|----------|----------|--------|
| SimAvi | *Simurgh avianus* | Simurgh (mythical bird) | 15,000 | 200 yr | 10 |
| DivMaz | *Divus mazandarensis* | Div (demon of Mazandaran) | 50,000 | 80 yr | 10 |
| AzhDra | *Azhdaha draconius* | Azhdaha (dragon) | 5,000 | 500 yr | 10 |
| RosHer | *Rostam heroicus* | Rostam-lineage (hero dynasty) | 25,000 | 35 yr | 10 |
| RakEqu | *Rakhsh equinus* | Rakhsh (mythical steed) | 3,000 | 25 yr | 10 |
| ZalAlb | *Zal albinus* | Zal (raised by Simurgh) | 20,000 | 35 yr | 10 |
| RudSim | *Rudabeh simurghica* | Rudabeh-lineage | 18,000 | 30 yr | 10 |
| EsfSmi | *Esfandiyar smithius* | Esfandiyar (bronze-bodied) | 32,000 | 30 yr | 10 |
| JamPis | *Jamshid pishdadius* | Jamshid (Pishdadian age) | 60,000 | 100 yr | 10 |
| KayDyn | *Kayanian dynasticus* | Kayanian (heroic dynasty) | 45,000 | 30 yr | 10 |
| BahFir | *Bahram firesteed* | Bahram-kind | 35,000 | 30 yr | 10 |
| PahDiv | *Pahlavan divanus* | Pahlavan (hero-monster hybrid) | 28,000 | 35 yr | 10 |
| SorWiz | *Sorcerer wizardus* | Sorcerer (jadugar) | 30,000 | 50 yr | 10 |
| DouGia | *Dough giant* | Div-e Sepid (White Demon) | 4,000 | 120 yr | 10 |
| AfrHor | *Afrasiyab horrens* | Afrasiyab (Turanian warlord) | 65,000 | 28 yr | 10 |
| TurNom | *Turanian nomadicus* | Turanian (steppe nomad) | 120,000 | 22 yr | 10 |

### Spirits, Jinn & Peris

| ID | Species | Common Name | Ne | Gen Time | Models |
|--------|-------------------------------|--------------------------|----------|----------|--------|
| PriJin | *Jinnus persicus* | Jinn (elemental spirit) | 200,000 | 30 yr | 10 |
| PerPar | *Peri paradisi* | Peri (fairy/angel spirit) | 100,000 | 40 yr | 10 |
| AlDem | *Al daemonius* | Al (nocturnal demon) | 70,000 | 20 yr | 10 |
| GhoUnd | *Ghoul underworld* | Ghoul (desert undead) | 40,000 | 25 yr | 10 |
| DaeWar | *Daeva warrior* | Daeva (war demon) | 90,000 | 50 yr | 10 |
| DraAng | *Druj angra* | Druj (demon of deceit) | 150,000 | 25 yr | 10 |
| GulRos | *Gulistan rosagarden* | Gul-spirit (rose guardian) | 55,000 | 20 yr | 10 |

### Mythical Birds & Beasts

| ID | Species | Common Name | Ne | Gen Time | Models |
|--------|-------------------------------|--------------------------|----------|----------|--------|
| HumBir | *Huma paradisica* | Huma (bird of paradise) | 8,000 | 150 yr | 10 |
| ManTig | *Manticore persicus* | Manticore (martyaxwar) | 12,000 | 60 yr | 10 |
| SenBir | *Senmurv birddog* | Senmurv (dog-bird hybrid) | 10,000 | 45 yr | 10 |
| ChaGri | *Chamrosh griffinus* | Chamrosh (dog-eagle) | 7,000 | 40 yr | 10 |
| ShaSha | *Shahbaz shahinus* | Shahbaz (royal falcon) | 6,000 | 15 yr | 10 |
| GavPri | *Gavaevodata primus* | Gavaevodata (primordial bull) | 2,000 | 300 yr | 10 |

### Zoroastrian Cosmology

| ID | Species | Common Name | Ne | Gen Time | Models |
|--------|-------------------------------|--------------------------|----------|----------|--------|
| FarGlo | *Faravahar glorius* | Faravahar (guardian spirit) | 80,000 | 60 yr | 10 |
| MitSol | *Mithra solarius* | Mithra (solar deity) | 1,000 | 800 yr | 10 |
| YazGua | *Yazata guardian* | Yazata (divine being) | 3,000 | 500 yr | 10 |
| ZorPri | *Zoroaster primus* | Zoroaster-lineage | 10,000 | 100 yr | 10 |
| KhiWis | *Khidr wisdomus* | Khidr (immortal sage) | 500 | 1,000 yr | 10 |

### Cross-cultural & Regional

| ID | Species | Common Name | Ne | Gen Time | Models |
|--------|-------------------------------|--------------------------|----------|----------|--------|
| NarHer | *Nart heronius* | Nart-spirit (Caucasian-Iranian) | 22,000 | 28 yr | 10 |
| MarMor | *Marduk mortalis* | Marduk-spirit (Mesopotamian) | 75,000 | 45 yr | 10 |

## Quick Start

```python
import stdferdowsim

# Get the Simurgh species
species = stdferdowsim.get_species("SimAvi")

# Use the ghost admixture model (non-tree-like history)
model = species.get_demographic_model("GhostAdmixture_3F10")

# Set up a generic contig of 100kb
contig = species.get_contig(length=100_000)

# Simulate with msprime
engine = stdferdowsim.get_engine("msprime")
ts = engine.simulate(model, contig, samples={"Main": 20, "Secondary": 10}, seed=42)

print(f"Trees: {ts.num_trees}, Mutations: {ts.num_mutations}")
```

## CLI Usage

```bash
# Level 1: single-population constant
stdferdowsim SimAvi -d Constant_1F10 -o simurgh.trees -L 100000 Main:10

# Ghost admixture (3 pops, one extinct)
stdferdowsim DivMaz -d GhostAdmixture_3F10 -o div_ghost.trees -L 100000 Main:10 Secondary:10

# Five-realm admixture graph
stdferdowsim RosHer -d FiveRealm_5F10 -o five_realm.trees -L 50000 Iran:5 Turan:5 Rum:5 Hind:5 Chin:5

# Eight-population Silk Road
stdferdowsim PriJin -d SilkRoad_8F10 -o silk_road.trees -L 50000 Ray:5 Isfahan:5 Shiraz:5 Tabriz:5 Mashad:5 Merv:5 Balkh:5 Samarkand:5
```

## Installation

```bash
pip install stdferdowsim
```

From source (editable):

```bash
pip install -e .
```

## Citation

This project is a fork of [stdpopsim](https://stdpopsim.org). If you use the simulation framework, please cite:

* [Adrion, et al. (2020)](https://doi.org/10.7554/eLife.54967) — A community-maintained standard library of population genetic models.
* [Lauterbur, et al. (2023)](https://doi.org/10.7554/eLife.84874) — Expanding the stdpopsim species catalog.

*"Be not content with the stories that come before you. Unfold your own myth." — Rumi*
