Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,177 @@
+# Vaccine Stock-Out Prediction Models
+
+A comprehensive machine learning system for predicting vaccine stock-out risks across multiple countries and supply chain levels.
+
+## Overview
+
+This model collection provides stock-out risk predictions for 8 different vaccine types used in immunization programs worldwide. The models are trained on historical data from multiple countries and can predict stock-out risks at different supply chain levels (Central, Subnational, Local Distribution).
+
+## Supported Vaccines
+
+- **BCG** (Bacille Calmette-Guérin) - Tuberculosis vaccine
+- **HepB** (Hepatitis B) - Hepatitis B vaccine
+- **bOPV** (bivalent Oral Polio Vaccine) - Polio vaccine
+- **Penta** (Pentavalent) - Combined vaccine (DTP + HepB + Hib)
+- **PCV** (Pneumococcal Conjugate Vaccine) - Pneumococcal disease vaccine
+- **Rota** (Rotavirus) - Rotavirus vaccine
+- **IPV** (Inactivated Polio Vaccine) - Injectable polio vaccine
+- **TT/Td/DT** (Tetanus Toxoid/Tetanus-Diphtheria) - Tetanus and diphtheria vaccines
+
+## Features
+
+- **Multi-country support**: Models trained on data from multiple countries
+- **Supply chain levels**: Supports Central, Subnational, and Local Distribution levels
+- **Population-based**: Considers population size and demographics
+- **Geographic factors**: Incorporates latitude, longitude, and distance metrics
+- **Utilization patterns**: Uses historical utilization data for predictions
+- **Risk assessment**: Provides both binary risk classification and probability scores
+
+## Usage
+
+### Basic Usage
+
+```python
+from vaccine_stockout_predictor import VaccineStockoutPredictor
+
+# Initialize the predictor
+predictor = VaccineStockoutPredictor()
+
+# Make a prediction
+result = predictor.predict_stockout_risk(
+    country_name="Afghanistan",
+    sc_level="Subnational",
+    store_name="Kabul",
+    vaccine_type="BCG",
+    current_stock=50000
+)
+
+print(result)
+```
+
+### Example Output
+
+```json
+{
+  "vaccine_type": "BCG",
+  "country": "Afghanistan",
+  "sc_level": "Subnational",
+  "store": "Kabul",
+  "current_stock": 50000,
+  "min_stock": 71980,
+  "max_stock": 863763,
+  "utilization": 0.063,
+  "stockout_risk": 0,
+  "risk_probability": 0.12,
+  "risk_level": "Low",
+  "recommendation": "Stock level adequate. Monitor regularly."
+}
+```
+
+### Batch Predictions
+
+```python
+# Multiple predictions
+predictions = [
+    {
+        "country_name": "Afghanistan",
+        "sc_level": "Subnational",
+        "store_name": "Kabul",
+        "vaccine_type": "BCG",
+        "current_stock": 50000
+    },
+    {
+        "country_name": "Angola",
+        "sc_level": "Central",
+        "store_name": "Luanda",
+        "vaccine_type": "HepB",
+        "current_stock": 10000
+    }
+]
+
+results = predictor.batch_predict(predictions)
+```
+
+## Model Information
+
+### Training Data
+- **Countries**: Multiple countries including Afghanistan, Angola, and others
+- **Time period**: Historical data covering multiple years
+- **Features**: Population, geographic location, utilization patterns, supply chain metrics
+- **Target**: Binary classification (0 = Low risk, 1 = High risk of stock-out)
+
+### Model Performance
+- **Algorithm**: Machine learning models optimized for each vaccine type
+- **Validation**: Cross-validated performance metrics
+- **Features**: Population, distance, utilization, geographic coordinates
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Data Requirements
+
+The models require the following information for predictions:
+
+- **Country Name**: Must match available countries in reference data
+- **Supply Chain Level**: Central, Subnational, or LD (Local Distribution)
+- **Store Name**: Must exist in the reference database
+- **Vaccine Type**: One of the 8 supported vaccine types
+- **Current Stock**: Current inventory level
+
+## Available Data
+
+Use the following methods to explore available data:
+
+```python
+predictor = VaccineStockoutPredictor()
+
+# Get available vaccines
+vaccines = predictor.get_available_vaccines()
+print(f"Available vaccines: {vaccines}")
+
+# Get available countries
+countries = predictor.get_available_countries()
+print(f"Available countries: {countries}")
+
+# Get stores in a country
+stores = predictor.get_available_stores("Afghanistan", "Subnational")
+print(f"Stores in Afghanistan (Subnational): {stores[:5]}")
+```
+
+## Risk Levels
+
+- **Low Risk (0)**: Adequate stock levels, low probability of stock-out
+- **High Risk (1)**: Insufficient stock levels, high probability of stock-out
+
+## Recommendations
+
+The system provides automated recommendations based on:
+- Current stock levels vs. minimum/maximum thresholds
+- Predicted risk probability
+- Historical utilization patterns
+
+## Limitations
+
+- Models are trained on historical data and may not account for sudden changes
+- Predictions assume normal supply chain operations
+- Geographic and demographic factors may vary over time
+- Emergency situations may require manual intervention
+
+## Contributing
+
+This model collection is designed for public health applications. For improvements or additional features, please ensure compatibility with existing immunization programs.
+
+## License
+
+This project is intended for public health and immunization program support.
+
+## Citation
+
+If you use this model in your research or applications, please cite:
+
+```
+Vaccine Stock-Out Prediction Models (2024)
+Multi-country machine learning models for immunization supply chain management
+```