Metadata-Version: 2.4
Name: demovuln
Version: 0.1.0
Summary: Demographic vulnerability metrics for matrix population models under temporally structured perturbations.
Author-email: Alex Giménez-Romero <alex.gimenez@csic.es>
License: MIT
Project-URL: Homepage, https://github.com/agimenezromero/demovuln
Project-URL: Repository, https://github.com/agimenezromero/demovuln
Project-URL: Documentation, https://demovuln.readthedocs.io
Project-URL: Issues, https://github.com/agimenezromero/demovuln/issues
Keywords: matrix population models,demography,life history,population ecology,perturbations,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# demovuln

`demovuln` is a Python package for simulating temporally structured demographic perturbations in matrix population models and estimating integrated population vulnerability.

The package is designed for comparative demographic analyses in which perturbations differ in magnitude, duration, and recurrence. It provides tools to simulate individual perturbation trajectories, evaluate full perturbation grids, and compute an integrated vulnerability metric based on population reduction relative to an unperturbed baseline.

## Installation

For local development:

```bash
git clone https://github.com/agimenezromero/demovuln.git
cd demovuln
python -m pip install -e ".[dev,docs]"
```

After publication on PyPI, the package will be installable with:

```bash
pip install demovuln
```

## Basic usage

```python
import numpy as np
from demovuln import MatrixPopulationModel, simulate_dynamics

A = np.array([
    [0.0, 2.0],
    [0.4, 0.7],
])

model = MatrixPopulationModel(A)

result = simulate_dynamics(
    model,
    target="adult_survival",
    magnitude=0.25,
    duration=1,
    period=3,
    t_max=50,
    recovery_steps=10,
)

print(result.reduction)
print(result.abundance)
```

## Perturbation-grid analysis

```python
import numpy as np
from demovuln import MatrixPopulationModel, PerturbationGrid, run_grid

A = np.array([
    [0.0, 2.0],
    [0.4, 0.7],
])

model = MatrixPopulationModel(A)

grid = PerturbationGrid(
    magnitudes=np.linspace(0, 1, 11),
    durations=[0, 1, 2, 3],
    periods=[1, 2, 3, 5, 10],
)

out = run_grid(
    model,
    target="adult_survival",
    grid=grid,
    t_max=50,
    recovery_steps=10,
)

print(out.vulnerability)
print(out.table.head())
```

## Demographic targets

The package supports perturbations to:

- `adult_survival`
- `juvenile_survival`
- `fecundity`
- `all`
- `custom`

By default, adult stages are inferred as source-stage columns with at least one fecundity entry, and juvenile stages are inferred as the remaining source-stage columns. These definitions can be specified explicitly:

```python
model = MatrixPopulationModel(
    A,
    adult_stages=[1],
    juvenile_stages=[0],
)
```

Custom perturbation targets can be defined with Boolean masks:

```python
custom_mask = np.array([
    [False, False],
    [True, False],
])

result = simulate_dynamics(
    model,
    target="custom",
    custom_mask=custom_mask,
    magnitude=0.5,
    duration=1,
    period=3,
    t_max=50,
)
```

## Conceptual summary

For a given perturbation regime, population reduction is computed as:

```text
rho = 100 * (1 - N_perturbed(T) / N_baseline(T))
```

where `N_perturbed(T)` is the final population size under perturbed dynamics and `N_baseline(T)` is the final population size under the unperturbed baseline.

Integrated vulnerability is the mean population reduction across the simulated perturbation space:

```text
Phi = mean(rho)
```

## Development checks

Run:

```bash
pytest
python examples/basic_usage.py
ruff check demovuln tests examples
sphinx-build -W -b html docs docs/_build/html
```

## Documentation

Local documentation can be built with:

```bash
sphinx-build -b html docs docs/_build/html
```

Then open:

```bash
xdg-open docs/_build/html/index.html
```

## Citation

Citation metadata are provided in `CITATION.cff`.

## License

This package is distributed under the MIT License.
