Metadata-Version: 2.4
Name: cuckoo-sim
Version: 0.1.3
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib

# 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

```bash
pip install cuckoo-sim
```

Or install from source in editable mode:

```bash
pip install -e <path_to_this_directory>
```

## Quick Start

### GUI

```bash
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

```bash
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

```python
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.

```bibtex
@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.
