nimmunize 1.0.0

Nigeria immunisation scheduling & survey analytics package

nimmunize

Nigeria immunisation scheduling & survey‑analytics toolkit Offline‑ready • FHIR‑friendly • GPL‑3

nimmunize turns Nigeria’s routine‑immunisation schedule into a living library and a set of command‑line tools

---

What it does — in one glance

Layer	Capability	Key APIs / CLI
Schedule engine	• Calculate next-due dose with volume, route & diseases prevented. • Flag overdue series and number of days late. • Surface rich poster metadata (title, url, image_url) for audit trails.	next_due() • overdue() • reference()
Survey analytics	• Bulk-audit CSV/Excel exports. • Compute coverage %, FIC, route-level coverage & disease-level protection. • Produce defaulter lists & “Fully immunised” rosters.	nimmunize survey … • audit() • metrics() • route_coverage() • disease_coverage()
Catch-up planner	Generate safe catch-up schedules that respect minimum ages & intervals (WHO algorithm).	catchup_plan() • nimmunize catchup … (coming soon)

Why another package?
Existing tools ignore Nigeria-specific schedules or hide logic in cloud dashboards. nimmunize is open, auditable, and runs entirely offline—crucial when power blinks or the modem dies.

---

Installation Installation

pip install nimmunize            # Python ≥ 3.9

Need dev extras? pip install nimmunize[dev] to get pytest, black, and pre‑commit hooks.

---

🚀 Quick start

1 · Library usage

from datetime import date
from nimmunize import next_due, overdue, disease_coverage

# Child record
child_dob = date(2024, 7, 15)
shots_taken = {"bcg": child_dob, "opv": [child_dob]}  # BCG + OPV0 at birth

# 1️⃣ Compute next doses (simple dictionary)
print(next_due(child_dob, shots_taken))

# 2️⃣ Same but ask for deep details (dosage / route / diseases)
print(next_due(child_dob, shots_taken, include_details=True)["opv"])

# 3️⃣ Were we late by 1 January 2025?
print(overdue(child_dob, shots_taken, as_of=date(2025, 1, 1)))

2 · Survey workflow

import nimmunize as ni

survey_df   = ni.load("baseline_clusters.xlsx")  # any .csv/.xls/.xlsx or DataFrame
annotated   = ni.audit(survey_df)                # adds missed_/delay_/next_due_ cols
print(ni.metrics(annotated))                     # {'coverage_%': …, 'FIC_%': …}
print(ni.route_coverage(annotated))              # {'Intramuscular': 88.4, 'Oral': 91.2, …}
print(ni.disease_coverage(annotated))            # {'polio': 89.6, 'measles': 82.3, …}
print("⚠️ Diseases <80 % protected:", ni.diseases_at_risk(annotated))

3 · CLI in two commands

# Bulk annotate a survey and print coverage dashboard
nimmunize survey data/cluster.csv -o cluster_audited.csv

# One‑off JSON catch‑up (verbose output)
nimmunize nextdose 2019-04-12 -t pentavalent 2019-10-27 -t opv 2019-10-27 --as-of 2025-05-01 --details

Run nimmunize --help for the full option tree.

---

Essentials

# SCHEDULING
next_due(dob, taken, *, as_of=None, include_details=False) -> {ag: date|dict}
overdue(dob, taken, *, as_of=None) -> {missed_<ag>, delay_<ag>}
reference() -> {'title', 'published', 'url', 'image_url'}

# SURVEY
load(path|DF, *, dob_col='dob') -> DataFrame
audit(df, *, as_of=None) -> DataFrame
metrics(df) -> {'coverage_%', 'FIC_%'}
route_coverage(df) -> {route: %}
disease_coverage(df) -> {disease: %}
diseases_at_risk(df, threshold=80) -> [disease]

# CATCH‑UP\ ncatchup_plan(dob, taken, *, as_of=None) -> {ag: [dates]}

All objects are plain Python & pandas—easy to feed into Streamlit, FastAPI, or Jupyter notebooks.

---

---

🗺️ Road‑map (public backlog)

• Detailed schedule with route & disease metadata.
• Disease‑level coverage & risk flags.
• CLI catch‑up planner (nimmunize catchup).
• Dash mini‑dashboard.
• nimmunizeR wrapper for the Stata/epi community.

Love a feature? Open an issue or up‑vote existing ones.

---

🧪 Contributing & dev setup

# After forking the repo
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]          # pytest, black, pre‑commit, isort, mypy
pre-commit install             # automatic lint on every git commit
pytest -q                      # run fast unit tests ✨

1. Branch off main → commit logically → open a PR.
2. Ensure pytest & flake8 pass.
3. Follow Conventional Commits for commit messages.

---

 Data sources & license

• Schedule data © NPHCDA Immunization Schedule (18 Dec 2024)
• Code licensed under GNU GPL v3—see LICENSE.
• By using the library you agree to verify clinical decisions with qualified healthcare professionals. No warranty.