Metadata-Version: 2.4
Name: ghana-flood-predictor
Version: 0.2.0
Summary: Python client for the Ghana Flood Warning System API
Author: ikdonkoh
License: CC-BY-NC-4.0
Project-URL: Homepage, https://ikdonkoh-flood-warning-prediction.hf.space
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: pandas>=1.5
Dynamic: license-file

# ghana-flood-predictor

Python client for the **Accra Flood Warning System** — predict flood risk from hourly weather data.

## Installation

```bash
pip install ghana-flood-predictor
```

## Quick Start

```python
from ghana_flood_predictor import FloodClient

client = FloodClient()

# Option 1 — one-liner using historical data
result = client.predict_from_datetime("2023-06-15T14:00:00")
print(f"Flood probability: {result['probability']:.1%}")
print(f"Flood warning:     {result['flood_warning']}")

# Option 2 — supply your own weather data
meta = client.metadata()
seq_len = meta["seq_len"]

sequence = [
    {
        "rainfall": 12.5,
        "temperature": 28.0,
        "humidity": 85.0,
        "wind_speed": 3.2,
        "hour": 14,
        "month": 6,
    }
    for _ in range(seq_len)
]

result = client.predict(sequence)
print(f"Flood probability: {result['probability']:.1%}")
print(f"Flood warning:     {result['flood_warning']}")
```

## Methods

### `client.metadata()`
Returns model info including `seq_len`, `threshold`, and `latest_datetime`.

### `client.weather(target_datetime, hours=None)`
Fetch historical weather sequence ending at `target_datetime`.

```python
data = client.weather("2023-06-15T14:00:00")
# data["sequence"] → list of hourly weather dicts
```

### `client.predict(sequence, horizon_hours=1)`
Predict flood risk from hourly weather sequence.

**Each item in sequence:**
| Field | Type | Description |
|---|---|---|
| `rainfall` | float | Rainfall in mm |
| `temperature` | float | Temperature in °C |
| `humidity` | float | Humidity in % |
| `wind_speed` | float | Wind speed in m/s |
| `hour` | int | Hour of day (0–23) |
| `month` | int | Month (1–12) |

**Returns:**
| Field | Type | Description |
|---|---|---|
| `probability` | float | Flood probability (0–1) |
| `flood_warning` | bool | True if flood predicted |
| `threshold_used` | float | Decision threshold |
| `horizon_hours` | float | Forecast horizon |

### `client.predict_from_datetime(target_datetime, horizon_hours=1)`
Convenience method — fetches weather history and predicts in one call.

```python
result = client.predict_from_datetime("2023-06-15T14:00:00")
print(result["probability"])   # 0.87
print(result["flood_warning"]) # True
```

## Full Example

```python
from ghana_flood_predictor import FloodClient

client = FloodClient()

# Check model info
meta = client.metadata()
print(f"Sequence length needed: {meta['seq_len']} hours")
print(f"Alert threshold: {meta['threshold']}")

# Predict using historical data
result = client.predict_from_datetime("2023-06-15T14:00:00")
print(f"Probability : {result['probability']:.1%}")
print(f"Flood warning: {result['flood_warning']}")
```

## License
MIT
