Metadata-Version: 2.4
Name: us-home-safety-score
Version: 1.0.0
Summary: Compute residential Home Safety Scores (0-100, A-F) from federal data: EPA water violations, lead/copper levels, EPA radon zones, and FEMA flood claims. Python port of the npm package.
Author-email: Artem Akulov <artem@liraltd.com>
License-Expression: MIT
Project-URL: Homepage, https://zipcheckup.com
Project-URL: Repository, https://github.com/zipcheckup/us-home-safety-score
Project-URL: Issues, https://github.com/zipcheckup/us-home-safety-score/issues
Project-URL: npm package, https://www.npmjs.com/package/us-home-safety-score
Project-URL: Methodology, https://zipcheckup.com/about/home-safety-score/
Keywords: home-safety,water-quality,lead-risk,radon,flood-risk,epa,fema,sdwis,zip-code,environmental-health,public-health,residential-safety,safety-score,drinking-water
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# us-home-safety-score

Compute residential **Home Safety Scores** (0-100, A-F) from U.S. federal data. Zero dependencies. Pure Python 3.9+.

[![PyPI](https://img.shields.io/pypi/v/us-home-safety-score.svg)](https://pypi.org/project/us-home-safety-score/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

This is the Python port of the [`us-home-safety-score`](https://www.npmjs.com/package/us-home-safety-score) npm package. Both implementations produce **identical scores** for the same inputs (verified bit-for-bit across a 640-case grid, including rounding edge cases).

The **Home Safety Score** is a composite index that evaluates environmental risk for any U.S. ZIP code across four dimensions:

- **Water quality** — EPA SDWIS violation history
- **Lead exposure** — EPA Lead and Copper Rule sampling
- **Radon risk** — EPA county-level radon zones
- **Flood risk** — FEMA NFIP historical claims

Higher score = safer. It is the same algorithm used on [ZipCheckup.com](https://zipcheckup.com) to score tens of thousands of ZIP codes.

## Install

```bash
pip install us-home-safety-score
```

## Quick Start

```python
from us_home_safety_score import compute_safety_score

result = compute_safety_score({
    "totalViolations": 3,
    "healthViolations": 1,
    "leadLevel": 0.008,     # mg/L (90th percentile)
    "radonZone": 2,         # EPA zone: 1=High, 2=Moderate, 3=Low
    "floodClaims": 25,      # FEMA NFIP historical claims
})

print(result)
# {
#   'score': 67,
#   'grade': 'C',
#   'components': {
#     'water': {'score': 21, 'maxPoints': 25, 'weight': 0.25},
#     'lead':  {'score': 18, 'maxPoints': 25, 'weight': 0.25},
#     'radon': {'score': 13, 'maxPoints': 25, 'weight': 0.25},
#     'flood': {'score': 15, 'maxPoints': 25, 'weight': 0.25},
#   },
#   'componentCount': 4,
# }
```

> Field names use camelCase (`totalViolations`, `leadLevel`, `floodClaims`, …) to stay 1:1 with the npm package's input contract.

## Scoring

| Component | Weight | Max Points | Source |
|-----------|--------|-----------|--------|
| Water quality | 25% (or 33%) | 25 (or 33) | EPA SDWIS violations, past 5 years |
| Lead/copper | 25% (or 33%) | 25 (or 33) | EPA Lead and Copper Rule, 90th-percentile |
| Radon | 25% (or 33%) | 25 (or 33) | EPA county radon zones |
| Flood | 25% | 25 | FEMA NFIP claims count |

When FEMA flood data is unavailable, the score falls back to a **3-component** mode (each component worth 33 points instead of 25). Missing lead or radon data uses a neutral assumption (2/3 of max points) rather than penalizing or rewarding the location.

Grade thresholds: **A** ≥ 85, **B** ≥ 70, **C** ≥ 55, **D** ≥ 40, **F** < 40.

Full methodology: <https://zipcheckup.com/about/home-safety-score/>

## API

| Function | Returns |
|----------|---------|
| `compute_safety_score(data)` | `{score, grade, components, componentCount}` |
| `compute_lead_risk(data)` | `{risk, probability, exceedsActionLevel, description}` |
| `compute_flood_risk(data)` | `{risk, estimatedAnnualCost, claims, description}` |
| `compute_compliance_risk(data)` | `{risk, score, unresolved, description}` |
| `compute_energy_burden(data)` | `{burden, risk, description}` |
| `score_to_grade(score)` | `'A' … 'F'` |

```python
from us_home_safety_score import compute_lead_risk

compute_lead_risk({"leadLevel": 0.020})
# {'risk': 'high', 'probability': 0.85, 'exceedsActionLevel': True,
#  'description': 'Lead level exceeds the EPA action level (15 ppb). ...'}
```

## Data sources

- **EPA SDWIS** — Safe Drinking Water Information System (violations, Lead and Copper Rule sampling)
- **EPA Radon Zones** — county-level radon potential map
- **FEMA NFIP** — National Flood Insurance Program claims

This package contains only the **scoring logic** — you supply the federal data inputs. Pre-joined per-ZIP data is available via the [`us-water-quality-data`](https://pypi.org/project/us-water-quality-data/) package and the [ZipCheckup API](https://api.zipcheckup.com/v1/).

## License

MIT © [ZipCheckup](https://zipcheckup.com)
