minte 1.0.0__tar.gz

minte-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

minte-1.0.0/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: minte
+Version: 1.0.0
+Summary: Malaria Intervention Emulator (MINTe) - Neural network-based malaria scenario predictions
+Project-URL: Homepage, https://github.com/CosmoNaught/minte
+Project-URL: Documentation, https://github.com/CosmoNaught/minte#readme
+Project-URL: Repository, https://github.com/CosmoNaught/minte
+Project-URL: Issues, https://github.com/CosmoNaught/minte/issues
+Author-email: Cosmo Santoni <cosmo.santoni@imperial.ac.uk>
+License: MIT
+Keywords: emulator,malaria,neural-network,public-health,simulation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: estimint>=1.0.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scikit-learn==1.6.1
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=2.0.0; extra == 'xgboost'
+Description-Content-Type: text/markdown
+
+# MINTe - Malaria Intervention Emulator
+
+A Python package for neural network-based malaria scenario predictions, enabling rapid evaluation of intervention strategies including ITNs (Insecticide-Treated Nets), IRS (Indoor Residual Spraying), and LSM (Larval Source Management).
+
+## Features
+
+- **Fast Scenario Predictions**: Run thousands of malaria intervention scenarios in seconds using pre-trained LSTM models
+- **Multiple Predictors**: Predict both prevalence and clinical cases
+- **Flexible Net Types**: Support for various ITN types (pyrethroid-only, PBO, pyrrole, PPF)
+- **Model Caching**: Efficient caching of loaded models for faster subsequent runs
+- **Visualization**: Built-in plotting utilities for results visualization
+- **Web Interface Support**: Lightweight controller for web application integration
+
+## Installation
+
+### Using uv (Recommended)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:
+
+```bash
+# On macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# On Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then create a new project and install MINTer:
+
+```bash
+# Create a new project directory
+mkdir my-malaria-project
+cd my-malaria-project
+
+# Initialize a new Python project with uv
+uv init
+
+# Add MINTer as a dependency (from local path)
+uv add /path/to/minte
+
+# Or if published to PyPI (future):
+# uv add minte
+```
+
+### Development Installation
+
+For development, clone the repository and install in editable mode:
+
+```bash
+# Clone the repository
+git clone https://github.com/CosmoNaught/minte.git
+cd minte
+
+# Create virtual environment and install with uv
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+### Using pip
+
+```bash
+pip install minte
+
+# Or for development:
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import numpy as np
+from minte import run_minter_scenarios
+
+# Define a single scenario
+results = run_minter_scenarios(
+    res_use=[0.3],           # Current resistance level
+    py_only=[0.4],           # Pyrethroid-only net coverage
+    py_pbo=[0.3],            # PBO net coverage
+    py_pyrrole=[0.2],        # Pyrrole net coverage
+    py_ppf=[0.1],            # PPF net coverage
+    prev=[0.25],             # Current prevalence
+    Q0=[0.92],               # Indoor biting proportion
+    phi=[0.85],              # Bednet usage proportion
+    season=[1],              # Seasonality indicator
+    routine=[0.1],           # Routine treatment coverage
+    irs=[0.0],               # Current IRS coverage
+    irs_future=[0.3],        # Future IRS coverage
+    lsm=[0.0],               # LSM coverage
+    predictor=["prevalence", "cases"],
+)
+
+# Access results
+print(results.prevalence.head())
+print(results.cases.head())
+```
+
+### Running Multiple Scenarios
+
+```python
+import numpy as np
+from minte import run_minter_scenarios
+
+# Define multiple scenarios
+n_scenarios = 100
+results = run_minter_scenarios(
+    res_use=np.random.uniform(0.1, 0.8, n_scenarios),
+    py_only=np.random.uniform(0, 0.5, n_scenarios),
+    py_pbo=np.random.uniform(0, 0.3, n_scenarios),
+    py_pyrrole=np.random.uniform(0, 0.2, n_scenarios),
+    py_ppf=np.random.uniform(0, 0.1, n_scenarios),
+    prev=np.random.uniform(0.1, 0.5, n_scenarios),
+    Q0=np.full(n_scenarios, 0.92),
+    phi=np.full(n_scenarios, 0.85),
+    season=np.ones(n_scenarios),
+    routine=np.full(n_scenarios, 0.1),
+    irs=np.zeros(n_scenarios),
+    irs_future=np.random.uniform(0, 0.5, n_scenarios),
+    lsm=np.zeros(n_scenarios),
+    scenario_tag=[f"Scenario_{i}" for i in range(n_scenarios)],
+    benchmark=True,
+)
+```
+
+### Using the Emulator Directly
+
+```python
+import pandas as pd
+from minte import run_malaria_emulator, create_scenarios
+
+# Create scenarios DataFrame
+scenarios = create_scenarios(
+    eir=[50, 100, 150],
+    dn0_use=[0.5, 0.4, 0.3],
+    dn0_future=[0.6, 0.5, 0.4],
+    Q0=[0.92, 0.92, 0.92],
+    phi_bednets=[0.85, 0.85, 0.85],
+    seasonal=[1, 1, 1],
+    routine=[0.1, 0.1, 0.1],
+    itn_use=[0.6, 0.5, 0.4],
+    irs_use=[0.0, 0.0, 0.0],
+    itn_future=[0.7, 0.6, 0.5],
+    irs_future=[0.3, 0.3, 0.3],
+    lsm=[0.0, 0.0, 0.0],
+)
+
+# Run emulator
+results = run_malaria_emulator(
+    scenarios=scenarios,
+    predictor="prevalence",
+    benchmark=True,
+)
+```
+
+### Visualization
+
+```python
+from minte import create_scenario_plots
+
+# Create plots from results
+plots = create_scenario_plots(
+    results.prevalence,
+    output_dir="plots/",
+    plot_type="both",
+)
+```
+
+### Web Controller
+
+For web applications, use the simplified controller:
+
+```python
+from minte import run_mintweb_controller
+
+results = run_mintweb_controller(
+    res_use=[0.3],
+    py_only=[0.4],
+    py_pbo=[0.3],
+    py_pyrrole=[0.2],
+    py_ppf=[0.1],
+    prev=[0.25],
+    Q0=[0.92],
+    phi=[0.85],
+    season=[1],
+    routine=[0.1],
+    irs=[0.0],
+    irs_future=[0.3],
+    lsm=[0.0],
+    clean_output=True,
+    tabulate=True,
+)
+```
+
+## Model Files
+
+The package requires trained model files to run predictions. These should be placed in the `src/minte/models/` directory (or specify a custom path) with the following structure:
+
+```
+models/
+├── prevalence/
+│   ├── lstm_best.pt          # PyTorch LSTM checkpoint
+│   ├── gru_best.pt           # (optional) GRU checkpoint  
+│   ├── static_scaler.pkl     # sklearn StandardScaler
+│   └── args.json             # Training arguments
+└── cases/
+    ├── lstm_best.pt
+    ├── gru_best.pt           # (optional)
+    ├── static_scaler.pkl
+    └── args.json
+```
+
+### Converting from R Package Files
+
+If you have the original R package files, you'll need to:
+
+1. **Model files (`.pt`, `.pkl`)**: These are already Python-compatible and can be copied directly.
+
+2. **RDS data files** (e.g., `itn_dn0.rds`): Convert to CSV using one of these methods:
+
+**Method 1: Using the included script (requires rpy2)**
+```bash
+pip install rpy2
+python scripts/convert_rds.py path/to/itn_dn0.rds src/minte/data/itn_dn0.csv
+```
+
+**Method 2: Using R directly**
+```r
+# In R console:
+data <- readRDS("path/to/itn_dn0.rds")
+write.csv(data, "src/minte/data/itn_dn0.csv", row.names = FALSE)
+```
+
+### Expected Data File Locations
+
+```
+src/minte/
+├── data/
+│   └── itn_dn0.csv           # ITN parameters (resistance vs dn0)
+└── models/
+    ├── prevalence/
+    │   └── ...
+    └── cases/
+        └── ...
+```
+
+## Configuration
+
+### Model Caching
+
+Models are cached by default for faster subsequent runs:
+
+```python
+from minte import preload_all_models, clear_cache, get_cache_info
+
+# Preload all models
+preload_all_models(verbose=True)
+
+# Check what's cached
+print(get_cache_info())
+
+# Clear cache if needed
+clear_cache()
+```
+
+### Device Selection
+
+By default, the package uses CUDA if available:
+
+```python
+from minte import load_emulator_models
+
+# Force CPU
+models = load_emulator_models(device="cpu")
+
+# Force CUDA
+models = load_emulator_models(device="cuda")
+```
+
+## API Reference
+
+### Main Functions
+
+- `run_minter_scenarios()`: Main entry point for running intervention scenarios
+- `run_malaria_emulator()`: Direct emulator interface for scenario predictions
+- `run_mintweb_controller()`: Simplified web interface controller
+- `create_scenario_plots()`: Create visualizations from results
+
+### Utility Functions
+
+- `calculate_overall_dn0()`: Calculate net effectiveness from resistance and coverage
+- `preload_all_models()`: Pre-load models into cache
+- `create_scenarios()`: Helper to create scenarios DataFrame
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Code Formatting
+
+```bash
+uv run black src/
+uv run ruff check src/
+```
+
+### Type Checking
+
+```bash
+uv run mypy src/
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Citation
+
+If you use MINTer in your research, please cite:
+
+```bibtex
+@software{minte,
+  title = {MINTer: Malaria Intervention Emulator},
+  author = {Cosmo Santoni},
+  year = {2025},
+  url = {https://github.com/CosmoNaught/minte}
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

minte-1.0.0/README.md

@@ -0,0 +1,336 @@
+# MINTe - Malaria Intervention Emulator
+
+A Python package for neural network-based malaria scenario predictions, enabling rapid evaluation of intervention strategies including ITNs (Insecticide-Treated Nets), IRS (Indoor Residual Spraying), and LSM (Larval Source Management).
+
+## Features
+
+- **Fast Scenario Predictions**: Run thousands of malaria intervention scenarios in seconds using pre-trained LSTM models
+- **Multiple Predictors**: Predict both prevalence and clinical cases
+- **Flexible Net Types**: Support for various ITN types (pyrethroid-only, PBO, pyrrole, PPF)
+- **Model Caching**: Efficient caching of loaded models for faster subsequent runs
+- **Visualization**: Built-in plotting utilities for results visualization
+- **Web Interface Support**: Lightweight controller for web application integration
+
+## Installation
+
+### Using uv (Recommended)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:
+
+```bash
+# On macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# On Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then create a new project and install MINTer:
+
+```bash
+# Create a new project directory
+mkdir my-malaria-project
+cd my-malaria-project
+
+# Initialize a new Python project with uv
+uv init
+
+# Add MINTer as a dependency (from local path)
+uv add /path/to/minte
+
+# Or if published to PyPI (future):
+# uv add minte
+```
+
+### Development Installation
+
+For development, clone the repository and install in editable mode:
+
+```bash
+# Clone the repository
+git clone https://github.com/CosmoNaught/minte.git
+cd minte
+
+# Create virtual environment and install with uv
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+### Using pip
+
+```bash
+pip install minte
+
+# Or for development:
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import numpy as np
+from minte import run_minter_scenarios
+
+# Define a single scenario
+results = run_minter_scenarios(
+    res_use=[0.3],           # Current resistance level
+    py_only=[0.4],           # Pyrethroid-only net coverage
+    py_pbo=[0.3],            # PBO net coverage
+    py_pyrrole=[0.2],        # Pyrrole net coverage
+    py_ppf=[0.1],            # PPF net coverage
+    prev=[0.25],             # Current prevalence
+    Q0=[0.92],               # Indoor biting proportion
+    phi=[0.85],              # Bednet usage proportion
+    season=[1],              # Seasonality indicator
+    routine=[0.1],           # Routine treatment coverage
+    irs=[0.0],               # Current IRS coverage
+    irs_future=[0.3],        # Future IRS coverage
+    lsm=[0.0],               # LSM coverage
+    predictor=["prevalence", "cases"],
+)
+
+# Access results
+print(results.prevalence.head())
+print(results.cases.head())
+```
+
+### Running Multiple Scenarios
+
+```python
+import numpy as np
+from minte import run_minter_scenarios
+
+# Define multiple scenarios
+n_scenarios = 100
+results = run_minter_scenarios(
+    res_use=np.random.uniform(0.1, 0.8, n_scenarios),
+    py_only=np.random.uniform(0, 0.5, n_scenarios),
+    py_pbo=np.random.uniform(0, 0.3, n_scenarios),
+    py_pyrrole=np.random.uniform(0, 0.2, n_scenarios),
+    py_ppf=np.random.uniform(0, 0.1, n_scenarios),
+    prev=np.random.uniform(0.1, 0.5, n_scenarios),
+    Q0=np.full(n_scenarios, 0.92),
+    phi=np.full(n_scenarios, 0.85),
+    season=np.ones(n_scenarios),
+    routine=np.full(n_scenarios, 0.1),
+    irs=np.zeros(n_scenarios),
+    irs_future=np.random.uniform(0, 0.5, n_scenarios),
+    lsm=np.zeros(n_scenarios),
+    scenario_tag=[f"Scenario_{i}" for i in range(n_scenarios)],
+    benchmark=True,
+)
+```
+
+### Using the Emulator Directly
+
+```python
+import pandas as pd
+from minte import run_malaria_emulator, create_scenarios
+
+# Create scenarios DataFrame
+scenarios = create_scenarios(
+    eir=[50, 100, 150],
+    dn0_use=[0.5, 0.4, 0.3],
+    dn0_future=[0.6, 0.5, 0.4],
+    Q0=[0.92, 0.92, 0.92],
+    phi_bednets=[0.85, 0.85, 0.85],
+    seasonal=[1, 1, 1],
+    routine=[0.1, 0.1, 0.1],
+    itn_use=[0.6, 0.5, 0.4],
+    irs_use=[0.0, 0.0, 0.0],
+    itn_future=[0.7, 0.6, 0.5],
+    irs_future=[0.3, 0.3, 0.3],
+    lsm=[0.0, 0.0, 0.0],
+)
+
+# Run emulator
+results = run_malaria_emulator(
+    scenarios=scenarios,
+    predictor="prevalence",
+    benchmark=True,
+)
+```
+
+### Visualization
+
+```python
+from minte import create_scenario_plots
+
+# Create plots from results
+plots = create_scenario_plots(
+    results.prevalence,
+    output_dir="plots/",
+    plot_type="both",
+)
+```
+
+### Web Controller
+
+For web applications, use the simplified controller:
+
+```python
+from minte import run_mintweb_controller
+
+results = run_mintweb_controller(
+    res_use=[0.3],
+    py_only=[0.4],
+    py_pbo=[0.3],
+    py_pyrrole=[0.2],
+    py_ppf=[0.1],
+    prev=[0.25],
+    Q0=[0.92],
+    phi=[0.85],
+    season=[1],
+    routine=[0.1],
+    irs=[0.0],
+    irs_future=[0.3],
+    lsm=[0.0],
+    clean_output=True,
+    tabulate=True,
+)
+```
+
+## Model Files
+
+The package requires trained model files to run predictions. These should be placed in the `src/minte/models/` directory (or specify a custom path) with the following structure:
+
+```
+models/
+├── prevalence/
+│   ├── lstm_best.pt          # PyTorch LSTM checkpoint
+│   ├── gru_best.pt           # (optional) GRU checkpoint  
+│   ├── static_scaler.pkl     # sklearn StandardScaler
+│   └── args.json             # Training arguments
+└── cases/
+    ├── lstm_best.pt
+    ├── gru_best.pt           # (optional)
+    ├── static_scaler.pkl
+    └── args.json
+```
+
+### Converting from R Package Files
+
+If you have the original R package files, you'll need to:
+
+1. **Model files (`.pt`, `.pkl`)**: These are already Python-compatible and can be copied directly.
+
+2. **RDS data files** (e.g., `itn_dn0.rds`): Convert to CSV using one of these methods:
+
+**Method 1: Using the included script (requires rpy2)**
+```bash
+pip install rpy2
+python scripts/convert_rds.py path/to/itn_dn0.rds src/minte/data/itn_dn0.csv
+```
+
+**Method 2: Using R directly**
+```r
+# In R console:
+data <- readRDS("path/to/itn_dn0.rds")
+write.csv(data, "src/minte/data/itn_dn0.csv", row.names = FALSE)
+```
+
+### Expected Data File Locations
+
+```
+src/minte/
+├── data/
+│   └── itn_dn0.csv           # ITN parameters (resistance vs dn0)
+└── models/
+    ├── prevalence/
+    │   └── ...
+    └── cases/
+        └── ...
+```
+
+## Configuration
+
+### Model Caching
+
+Models are cached by default for faster subsequent runs:
+
+```python
+from minte import preload_all_models, clear_cache, get_cache_info
+
+# Preload all models
+preload_all_models(verbose=True)
+
+# Check what's cached
+print(get_cache_info())
+
+# Clear cache if needed
+clear_cache()
+```
+
+### Device Selection
+
+By default, the package uses CUDA if available:
+
+```python
+from minte import load_emulator_models
+
+# Force CPU
+models = load_emulator_models(device="cpu")
+
+# Force CUDA
+models = load_emulator_models(device="cuda")
+```
+
+## API Reference
+
+### Main Functions
+
+- `run_minter_scenarios()`: Main entry point for running intervention scenarios
+- `run_malaria_emulator()`: Direct emulator interface for scenario predictions
+- `run_mintweb_controller()`: Simplified web interface controller
+- `create_scenario_plots()`: Create visualizations from results
+
+### Utility Functions
+
+- `calculate_overall_dn0()`: Calculate net effectiveness from resistance and coverage
+- `preload_all_models()`: Pre-load models into cache
+- `create_scenarios()`: Helper to create scenarios DataFrame
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Code Formatting
+
+```bash
+uv run black src/
+uv run ruff check src/
+```
+
+### Type Checking
+
+```bash
+uv run mypy src/
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Citation
+
+If you use MINTer in your research, please cite:
+
+```bibtex
+@software{minte,
+  title = {MINTer: Malaria Intervention Emulator},
+  author = {Cosmo Santoni},
+  year = {2025},
+  url = {https://github.com/CosmoNaught/minte}
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

minte-1.0.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "minte"
+version = "1.0.0"
+description = "Malaria Intervention Emulator (MINTe) - Neural network-based malaria scenario predictions"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Cosmo Santoni", email = "cosmo.santoni@imperial.ac.uk" }
+]
+keywords = ["malaria", "simulation", "emulator", "neural-network", "public-health"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+dependencies = [
+    "numpy>=1.24.0",
+    "pandas>=2.0.0",
+    "torch>=2.0.0",
+    "scikit-learn==1.6.1",
+    "matplotlib>=3.7.0",
+    "scipy>=1.10.0",
+    "joblib>=1.3.0",
+    "estimint>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+xgboost = [
+    "xgboost>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CosmoNaught/minte"
+Documentation = "https://github.com/CosmoNaught/minte#readme"
+Repository = "https://github.com/CosmoNaught/minte"
+Issues = "https://github.com/CosmoNaught/minte/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/minte"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.hatch.build]
+include = [
+    "src/minte/**/*.py",
+    "src/minte/**/*.csv",
+    "src/minte/**/*.json",
+    "src/minte/**/*.pkl",
+    "src/minte/**/*.pt",
+    "src/minte/py.typed",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4"]
+ignore = ["E501"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]