Metadata-Version: 2.4
Name: cuckoo-sim
Version: 0.1.2
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
git clone <repo-url>
cd Data_And_Script/Model_Script
pip install -e .
```

## 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 path/to/Cuckoo/ -r path/to/Reeds/ -o path/to/OUT/ \
  -c1 Cuckoo_12.csv -r1 ReedsBird_1.csv -q a -N 300 -M 10
```

Key arguments:

| Flag | Description | Default |
|------|-------------|---------|
| `-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="path/to/Cuckoo_12.csv",
    reeds_file="path/to/ReedsBird_1.csv",
    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.
