diff --git a/CHANGELOG.md b/CHANGELOG.md index edf0e0f..2e48f76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. ## [Unreleased] ### Added +- Clarified model-selection documentation so README and user-facing guides explain that `--model` selects both the epidemiological model and the generated script (`si.py`, `sir.py`, or `seir.py`) - Comprehensive documentation overhaul - Updated pyproject.toml with proper package description - Completely rewrote README.md with installation instructions, prerequisites, troubleshooting, advanced usage, and comprehensive examples diff --git a/README.md b/README.md index 83023a2..47b4c41 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Once installed, you can run `laser-init` from the command line: laser-init NGA 2 2000 2025 ``` -This will create a directory `NGA/2000/` with all necessary data files and a ready-to-run SEIR model script. +This will create a directory `NGA/2000/` with all necessary data files and a ready-to-run model script. By default this is `seir.py`; use `--model SI` or `--model SIR` to generate `si.py` or `sir.py` instead. ## Basic Usage @@ -115,11 +115,13 @@ total 12440 - **`config.yaml`**: Configuration file referencing data files and model parameters -- **`seir.py`**: Ready-to-run SEIR model script +- **Model script**: One of `si.py`, `sir.py`, or `seir.py`, depending on `--model` + - Default output: `seir.py` - Run with: `python3 ./seir.py` or `python3 ./seir.py --config config.yaml` + - If you generated a different model, run `python3 ./si.py` or `python3 ./sir.py` instead - Requires `laser.generic` package -- **`plot.py`**: Supporting script, called from `seir.py`, for generating simulation result plots +- **`plot.py`**: Supporting script, called from the generated model script, for generating simulation result plots - **Demographic data files**: - `age_dist.csv`: Population age distribution for the start year @@ -147,6 +149,8 @@ laser-init NGA 2 2000 2025 --model SIR # Susceptible-Infectious-Recovered laser-init NGA 2 2000 2025 --model SEIR # Susceptible-Exposed-Infectious-Recovered ``` +This option also determines the generated script name: `si.py`, `sir.py`, or `seir.py`. + - **SI**: Simple model with susceptible and infectious states - **SIR**: Adds recovery (immunity) to the model - **SEIR**: Includes an exposed (latent) period before infectiousness @@ -257,6 +261,8 @@ cd NGA/2000 python3 ./seir.py ``` +If you generated a different model with `--model`, run the matching script instead: `python3 ./si.py` or `python3 ./sir.py`. + The model will: 1. Load configuration and data from `config.yaml` 2. Initialize the population across administrative units @@ -353,7 +359,7 @@ done The generated model scripts are fully editable Python files. Common modifications: -1. **Change initial seed locations**: Edit the seeding logic in `seir.py` +1. **Change initial seed locations**: Edit the seeding logic in the generated model script (`si.py`, `sir.py`, or `seir.py`) 2. **Modify transmission parameters**: Adjust `r0`, `beta`, or duration parameters 3. **Add interventions**: Insert intervention logic into the model components (see [LASER documentation](https://laser.idmod.org/laser-generic)) 4. **Customize plots**: Modify `plot.py` or import it and call specific plot functions diff --git a/docs/configuration.md b/docs/configuration.md index 58c035c..2154c59 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -110,7 +110,7 @@ simulation: ### Running with Custom Config -The generated model scripts accept a `--config` option: +The generated model scripts (`si.py`, `sir.py`, or `seir.py`) accept a `--config` option: ```shell # Use default config.yaml in same directory @@ -343,7 +343,7 @@ NGA/ └── 2000/ ├── NGA_admin2.gpkg # Geospatial data ├── config.yaml # Run configuration - ├── seir.py # Model script + ├── seir.py # Model script by default; may be si.py or sir.py with --model ├── plot.py # Plotting script ├── age_dist.csv # Demographics ├── cxr.csv # Birth/death rates @@ -464,6 +464,8 @@ python3 ./seir.py python3 ./seir.py --data-dir /full/path/to/NGA/2000 ``` +If you generated an SI or SIR model, use `python3 ./si.py` or `python3 ./sir.py` for those commands. + ## Next Steps - [User Guide](userguide.md) - Comprehensive workflows and tutorials diff --git a/docs/index.md b/docs/index.md index b7798c5..ecdc44d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,7 +40,7 @@ This creates a complete modeling environment in `NGA/2000/` with: - GeoPackage with administrative boundaries and population - Demographic data files (birth rates, death rates, age distribution) -- Ready-to-run SEIR model script +- Ready-to-run model script (`seir.py` by default, or `si.py` / `sir.py` with `--model`) - Validation plots and PDF report - Configuration file for easy customization diff --git a/docs/models.md b/docs/models.md index 539d798..3189b81 100644 --- a/docs/models.md +++ b/docs/models.md @@ -378,18 +378,24 @@ cd KEN/2010 python3 ./seir.py ``` +If you generated a different model with `--model`, run `python3 ./si.py` or `python3 ./sir.py` instead. + ### With Custom Config ```shell python3 ./seir.py --config custom_config.yaml ``` +Use the matching script name here if you generated `si.py` or `sir.py`. + ### With Custom Data Directory ```shell python3 ./seir.py --data-dir /path/to/data ``` +Use the matching script name here if you generated `si.py` or `sir.py`. + ### Output Models generate plots in the output directory: diff --git a/docs/quickstart.md b/docs/quickstart.md index 15aff8c..f7f2ed8 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -46,7 +46,7 @@ You should see: ```text NGA_admin2.gpkg # GeoPackage with boundaries and population config.yaml # Model configuration -seir.py # Ready-to-run SEIR model +seir.py # Ready-to-run model script (default; use --model for si.py or sir.py) plot.py # Plotting utilities age_dist.csv # Age distribution data cxr.csv # Birth and death rates @@ -67,6 +67,8 @@ Execute the generated model: python3 ./seir.py ``` +If you generated a different model with `--model`, run `python3 ./si.py` or `python3 ./sir.py` instead. + The model will: 1. Load configuration and data @@ -124,7 +126,7 @@ simulation: gravity_c: 2 ``` -### Model Script (seir.py) +### Model Script (`si.py`, `sir.py`, or `seir.py`) The generated Python script is fully editable. Common customizations: @@ -237,7 +239,7 @@ If processing fails with memory errors: ### Model Fails to Run -If `python3 ./seir.py` fails: +If the generated model script fails: - Ensure you're in the environment where `laser-init` is installed - Check that `laser.generic` is installed: `pip list | grep laser` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 970b1f8..ded5b98 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -360,10 +360,12 @@ Common issues and solutions when using `laser-init`. 3. **Run with verbose output**: ```shell - python seir.py --help # See available options + python seir.py --help # See available options for the default model script python seir.py --config config.yaml # Explicit config ``` + If you generated a different model, replace `seir.py` with `si.py` or `sir.py`. + 4. **Check Python version**: ```shell python --version # Should be 3.10+ diff --git a/docs/userguide.md b/docs/userguide.md index 2f3d6d3..2700747 100644 --- a/docs/userguide.md +++ b/docs/userguide.md @@ -89,6 +89,8 @@ cd KEN/2010 python3 ./seir.py ``` +If you selected a different model with `--model`, run the matching script instead: `python3 ./si.py` or `python3 ./sir.py`. + The simulation will run and generate output plots showing disease spread across Kenya's districts. ## Understanding the Workflow @@ -157,7 +159,7 @@ KEN/ └── 2010/ ├── KEN_admin2.gpkg # Geospatial data (main input) ├── config.yaml # Model configuration - ├── seir.py # SEIR model script + ├── seir.py # Model script by default; may be si.py or sir.py with --model ├── plot.py # Plotting utilities ├── age_dist.csv # Age distribution ├── cxr.csv # Crude birth/death rates @@ -310,6 +312,8 @@ python3 ./seir.py # Results are saved as PNG files in the current directory ``` +Use `python3 ./si.py` or `python3 ./sir.py` here if you generated one of those model variants. + ### Workflow 2: Comparing Data Sources Test different shapefile sources to find the best coverage: @@ -397,6 +401,8 @@ done echo "Parameter sweep complete!" ``` +If you are sweeping an SI or SIR run, substitute `si.py` or `sir.py` in the copy and execution commands. + ### Workflow 6: Integration with Custom Analysis Use `laser-init` data in custom scripts: @@ -438,7 +444,7 @@ print("Custom analysis saved to custom_analysis.png") ### Understanding Model Outputs -After running the generated model script (e.g., `seir.py`), you'll find several output plots: +After running the generated model script (for example, `seir.py`), you'll find several output plots: 1. **Stacked Compartments**: Shows S, E, I, R populations over time - Look for epidemic peak timing @@ -512,13 +518,15 @@ Then rerun: python3 ./seir.py --config config.yaml ``` +If you generated `si.py` or `sir.py`, rerun that script instead. + ### Editing Model Scripts -The generated Python3 ./scripts are fully editable. Common modifications: +The generated model scripts are fully editable. Common modifications: #### Change Initial Seeding -In `seir.py`, find the seeding logic: +In the generated model script, find the seeding logic: ```python # Default: Seed largest population center @@ -547,7 +555,7 @@ scenario.at[seed_idx, "I"] = 100 #### Modify Transmission Parameters ```python -# Location in seir.py +# Location in the generated model script params = PropertySet(config["simulation"]) # Add custom parameters