cuckoo-sim 0.1.3

No project description provided

cuckoo-sim

Agent-based simulation of cuckoo brood parasitism — modeling the co-evolutionary arms race between cuckoo parasites and their reed warbler host species. Tracks population dynamics, egg-laying strategies, and host detection abilities over many generations.

Installation

pip install cuckoo-sim

Or install from source in editable mode:

pip install -e <path_to_this_directory>

Quick Start

GUI

cuckoo-gui

Opens a Tkinter interface with two tabs:

• Configure & Run — set input CSVs, population parameters, spatial grid, and run simulations
• Results — plot population time series, trait evolution, and spatial maps

CLI

cuckoo-sim \
  -c <cuckoo_csv_directory> \
  -r <reeds_csv_directory> \
  -o <output_directory> \
  -c1 <cuckoo_csv_filename> \
  -r1 <reeds_csv_filename> \
  -q a -N 300 -M 10

Key arguments:

Flag	Description	Default
-c	Directory containing cuckoo CSV file
-r	Directory containing reeds CSV file
-o	Output directory for results
-c1	Cuckoo species CSV filename
-r1	Reeds species CSV filename
-q	Simulation mode (a = standard, b = grid search)	a
-N	Number of simulated years	300
-M	Number of iterations	10
-P	Crowding penalty coefficient	0.9
-D	Detection cost on breeding	0.15
-pm	Penalty mode (exponential / logistic)	exponential
-gw, -gh	Spatial grid width/height	200
-s1..-s4	Sigma values for trait variation	0.02 / 1.0

Python API

from cuckoo_sim import SimConfig, run_simulation, aggregate_time_series

config = SimConfig(
    cuckoo_file="<cuckoo_csv_filepath>",
    reeds_file="<reeds_csv_filepath>",
    years=100,
    iterations=5,
    grid_width=100,
    grid_height=100,
)

results = run_simulation(config)
agg = aggregate_time_series(results)

for species, data in agg.items():
    print(f"{species}: final mean pop = {data['Total']['mean'][-1]:.0f}")

Citation

If you use this software in your research, please cite:

Wang, W., Van Deelen, T., Wei, F., Li, S., & Wang, L. (2025). Anthropogenic habitat loss and fragmentation may alter coevolutionary progress as examined in a brood parasitism model. Ecology and Evolution, 15(7), e71721.

@article{wang2025anthropogenic,
  title={Anthropogenic Habitat Loss and Fragmentation May Alter Coevolutionary Progress as Examined in a Brood Parasitism Model},
  author={Wang, Wei and Van Deelen, Timothy and Wei, Fuwen and Li, Sheng and Wang, Luping},
  journal={Ecology and Evolution},
  volume={15},
  number={7},
  pages={e71721},
  year={2025},
  publisher={Wiley Online Library}
}

Dependencies

Python 3.6+, numpy, scipy, matplotlib, tkinter.