jp-idwr-db 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

jp_idwr_db/__init__.py

@@ -25,5 +25,5 @@ __all__ = [
     "prefecture_map",
 ]
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __data_version__ = __version__

jp_idwr_db/config.py

@@ -25,7 +25,7 @@ class Config:
 
     cache_dir: Path = Path(user_cache_dir("jp_idwr_db"))
     rate_limit_per_minute: int = 20
-    user_agent: str = "jp_idwr_db/0.2.2 (+https://github.com/AlFontal/jp-idwr-db)"
+    user_agent: str = "jp_idwr_db/0.2.3 (+https://github.com/AlFontal/jp-idwr-db)"
     timeout_seconds: float = 30.0
     retries: int = 3
 

jp_idwr_db/data_manager.py

@@ -6,6 +6,7 @@ import hashlib
 import json
 import os
 import shutil
+import sys
 import zipfile
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as package_version
@@ -128,6 +129,15 @@ def ensure_data(version: str | None = None, force: bool = False) -> Path:
     if force and data_dir.exists():
         shutil.rmtree(data_dir)
     data_dir.mkdir(parents=True, exist_ok=True)
+    action = "Refreshing" if force else "Building"
+    print(
+        f"[jp_idwr_db] {action} local data cache for {resolved} at {data_dir}.",
+        file=sys.stderr,
+    )
+    print(
+        "[jp_idwr_db] This happens on first use and may take a moment.",
+        file=sys.stderr,
+    )
 
     archive_path, manifest_path = download_release_assets(resolved, data_dir)
     manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
@@ -159,4 +169,5 @@ def ensure_data(version: str | None = None, force: bool = False) -> Path:
         raise ValueError(f"Missing required datasets in cache: {sorted(missing_expected)}")
 
     marker.write_text("ok\n", encoding="utf-8")
+    print("[jp_idwr_db] Data cache ready.", file=sys.stderr)
     return data_dir

jp_idwr_db-0.2.3.dist-info/METADATA

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: jp-idwr-db
+Version: 0.2.3
+Summary: Japanese IDWR infectious disease database and analytics toolkit built on Polars.
+Project-URL: Homepage, https://github.com/AlFontal/jp-idwr-db
+Project-URL: Repository, https://github.com/AlFontal/jp-idwr-db
+Project-URL: Bug Tracker, https://github.com/AlFontal/jp-idwr-db/issues
+Author: jp-idwr-db contributors
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: epidemiology,infectious-disease,japan,polars,surveillance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+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 :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: fastexcel>=0.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: polars>=0.20
+Requires-Dist: pyarrow>=14.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: fastexcel>=0.10; extra == 'excel'
+Description-Content-Type: text/markdown
+
+# jp-idwr-db
+
+Python access to Japanese infectious disease surveillance data from NIID/JIHS.
+
+`jp-idwr-db` provides a Polars-first API for filtering and analysis.
+Parquet datasets are versioned as GitHub Release assets and downloaded to a local cache on first use.
+It is inspired by the R package `jpinfect`, but it is not an API-parity port and includes independently curated ingestion and coverage.
+
+NIID/JIHS surveillance data is public, but it is not exposed as a clean analytical API.
+To reconstruct usable time series, you typically need to navigate multiple archive structures, yearly directories,
+and week-level files with changing formats (Excel and CSV) across historical and modern reporting systems.
+
+This package exists to remove that friction: it consolidates those heterogeneous sources into standardized, queryable
+tables so you can move directly to epidemiological analysis instead of file discovery, parsing, and schema harmonization.
+
+## Install
+
+```bash
+pip install jp-idwr-db
+```
+
+## Data Download Model
+
+- Package wheels do not ship the large parquet tables.
+- On first call to `jp.load(...)` (or `jp.get_data(...)`), the package downloads versioned data assets from GitHub Releases.
+- Cache path defaults to:
+  - macOS: `~/Library/Caches/jp_idwr_db/data/<version>/`
+  - Linux: `~/.cache/jp_idwr_db/data/<version>/`
+  - Windows: `%LOCALAPPDATA%\\jp_idwr_db\\Cache\\data\\<version>\\`
+
+Prefetch explicitly:
+
+```bash
+python -m jp_idwr_db data download
+python -m jp_idwr_db data download --version v0.2.2 --force
+```
+
+Environment overrides:
+
+- `JPINFECT_DATA_VERSION`: choose a specific release tag (example: `v0.2.2`)
+- `JPINFECT_DATA_BASE_URL`: override asset host base URL
+- `JPINFECT_CACHE_DIR`: override local cache root
+
+## Quick Start
+
+To fetch the full unified dataset with a single call:
+
+```python
+import jp_idwr_db as jp
+import polars as pl
+
+df = (
+    jp.load("unified")
+    .select(["date", "prefecture", "category", "disease", "count", "source"])
+)
+print(df)
+```
+
+```text
+shape: (5_370_477, 6)
+┌────────────┬────────────┬──────────┬─────────────────────────────┬───────┬────────────────────┐
+│ date       ┆ prefecture ┆ category ┆ disease                     ┆ count ┆ source             │
+│ ---        ┆ ---        ┆ ---      ┆ ---                         ┆ ---   ┆ ---                │
+│ date       ┆ str        ┆ str      ┆ str                         ┆ f64   ┆ str                │
+╞════════════╪════════════╪══════════╪═════════════════════════════╪═══════╪════════════════════╡
+│ 1999-04-11 ┆ Aichi      ┆ total    ┆ AIDS                        ┆ 0.0   ┆ Confirmed cases    │
+│ 1999-04-11 ┆ Aichi      ┆ total    ┆ Acute poliomyelitis         ┆ 0.0   ┆ Confirmed cases    │
+│ 1999-04-11 ┆ Aichi      ┆ total    ┆ Acute viral hepatitis       ┆ 4.0   ┆ Confirmed cases    │
+│ 1999-04-11 ┆ Aichi      ┆ total    ┆ Amebiasis                   ┆ 0.0   ┆ Confirmed cases    │
+│ 1999-04-11 ┆ Aichi      ┆ total    ┆ Anthrax                     ┆ 0.0   ┆ Confirmed cases    │
+│ …          ┆ …          ┆ …        ┆ …                           ┆ …     ┆ …                  │
+│ 2026-02-09 ┆ Yamanashi  ┆ total    ┆ Viral hepatitis(excluding   ┆ 0.0   ┆ All-case reporting │
+│            ┆            ┆          ┆ hepa…                       ┆       ┆                    │
+│ 2026-02-09 ┆ Yamanashi  ┆ total    ┆ West Nile fever             ┆ 0.0   ┆ All-case reporting │
+│ 2026-02-09 ┆ Yamanashi  ┆ total    ┆ Western equine encephalitis ┆ 0.0   ┆ All-case reporting │
+│ 2026-02-09 ┆ Yamanashi  ┆ total    ┆ Yellow fever                ┆ 0.0   ┆ All-case reporting │
+│ 2026-02-09 ┆ Yamanashi  ┆ total    ┆ Zika virus infection        ┆ 0.0   ┆ All-case reporting │
+└────────────┴────────────┴──────────┴─────────────────────────────┴───────┴────────────────────┘
+```
+
+You can also filter at the source with `jp.get_data(...)`:
+
+```python
+
+# Fetch only tuberculosis data for 2024 in Tokyo, Osaka, and Hokkaido
+tb = (
+    jp.get_data(
+        disease="Tuberculosis", 
+        year=2024, 
+        prefecture=["Tokyo", "Osaka", "Hokkaido"])
+    .select(["date", "prefecture", "disease", "count", "source"])
+)
+print(tb)
+```
+
+```text
+shape: (156, 5)
+┌────────────┬────────────┬──────────────┬───────┬────────────────────┐
+│ date       ┆ prefecture ┆ disease      ┆ count ┆ source             │
+│ ---        ┆ ---        ┆ ---          ┆ ---   ┆ ---                │
+│ date       ┆ str        ┆ str          ┆ f64   ┆ str                │
+╞════════════╪════════════╪══════════════╪═══════╪════════════════════╡
+│ 2024-01-01 ┆ Hokkaido   ┆ Tuberculosis ┆ 2.0   ┆ All-case reporting │
+│ 2024-01-01 ┆ Osaka      ┆ Tuberculosis ┆ 3.0   ┆ All-case reporting │
+│ 2024-01-01 ┆ Tokyo      ┆ Tuberculosis ┆ 15.0  ┆ All-case reporting │
+│ 2024-01-08 ┆ Hokkaido   ┆ Tuberculosis ┆ 4.0   ┆ All-case reporting │
+│ 2024-01-08 ┆ Osaka      ┆ Tuberculosis ┆ 17.0  ┆ All-case reporting │
+│ …          ┆ …          ┆ …            ┆ …     ┆ …                  │
+│ 2024-12-16 ┆ Osaka      ┆ Tuberculosis ┆ 17.0  ┆ All-case reporting │
+│ 2024-12-16 ┆ Tokyo      ┆ Tuberculosis ┆ 41.0  ┆ All-case reporting │
+│ 2024-12-23 ┆ Hokkaido   ┆ Tuberculosis ┆ 5.0   ┆ All-case reporting │
+│ 2024-12-23 ┆ Osaka      ┆ Tuberculosis ┆ 16.0  ┆ All-case reporting │
+│ 2024-12-23 ┆ Tokyo      ┆ Tuberculosis ┆ 53.0  ┆ All-case reporting │
+└────────────┴────────────┴──────────────┴───────┴────────────────────┘
+```
+
+```python
+
+# Sentinel-only diseases from recent years in Tokyo prefecture
+sentinel_df = (
+    jp.get_data(
+        source="sentinel", 
+        year=(2024, 2026))
+    .select(["date", "prefecture", "disease", "count", "per_sentinel"])
+)
+print(sentinel_df)
+```
+
+```text
+shape: (2_052, 5)
+┌────────────┬────────────┬─────────────────────────────────┬─────────┬──────────────┐
+│ date       ┆ prefecture ┆ disease                         ┆ count   ┆ per_sentinel │
+│ ---        ┆ ---        ┆ ---                             ┆ ---     ┆ ---          │
+│ date       ┆ str        ┆ str                             ┆ f64     ┆ f64          │
+╞════════════╪════════════╪═════════════════════════════════╪═════════╪══════════════╡
+│ 2024-01-07 ┆ Tokyo      ┆ Acute hemorrhagic conjunctivit… ┆ null    ┆ null         │
+│ 2024-01-07 ┆ Tokyo      ┆ Aseptic meningitis              ┆ null    ┆ null         │
+│ 2024-01-07 ┆ Tokyo      ┆ Bacterial meningitis            ┆ null    ┆ null         │
+│ 2024-01-07 ┆ Tokyo      ┆ COVID-19                        ┆ 1365.0  ┆ 3.38         │
+│ 2024-01-07 ┆ Tokyo      ┆ Chickenpox                      ┆ 31.0    ┆ 0.12         │
+│ …          ┆ …          ┆ …                               ┆ …       ┆ …            │
+│ 2026-01-25 ┆ Tokyo      ┆ Influenza(excld. avian influen… ┆ 13082.0 ┆ 34.07        │
+│ 2026-01-25 ┆ Tokyo      ┆ Mumps                           ┆ 30.0    ┆ 0.12         │
+│ 2026-01-25 ┆ Tokyo      ┆ Mycoplasma pneumonia            ┆ 32.0    ┆ 1.28         │
+│ 2026-01-25 ┆ Tokyo      ┆ Pharyngoconjunctival fever      ┆ 115.0   ┆ 0.47         │
+│ 2026-01-25 ┆ Tokyo      ┆ Respiratory syncytial virus in… ┆ 242.0   ┆ 1.0          │
+└────────────┴────────────┴─────────────────────────────────┴─────────┴──────────────┘
+```
+
+## Main API
+
+Top-level API exported by `jp_idwr_db`:
+
+- `load(name)`
+- `get_data(...)`
+- `list_diseases(source="all")`
+- `list_prefectures()`
+- `get_latest_week()`
+- `prefecture_map()`
+- `attach_prefecture_id(df, prefecture_col="prefecture", id_col="prefecture_id")`
+- `merge(...)`, `pivot(...)`
+- `configure(...)`, `get_config()`
+
+
+## Datasets
+
+Use `jp.load(...)` with:
+
+- `"sex"`: historical sex-disaggregated surveillance
+- `"place"`: historical place-category surveillance
+- `"bullet"`: modern all-case weekly reports (rapid zensu)
+- `"sentinel"`: sentinel weekly reports (teitenrui; 2012+ in release data assets)
+- `"unified"`: deduplicated combined dataset (sex-total + modern bullet/sentinel, recommended)
+
+Detailed schema and coverage are documented in [DATASETS.md](./docs/DATASETS.md).
+
+## Optional Prefecture IDs
+
+Attach ISO prefecture IDs (JP-01 ... JP-47) only when needed:
+
+```python
+import jp_idwr_db as jp
+
+df_with_ids = (
+    jp.get_data(disease="Measles", year=2024)
+    .select(["prefecture", "disease", "count"])
+    .sort(["prefecture", "count"])
+    .unique(subset=["prefecture"], keep="first")
+    .pipe(jp.attach_prefecture_id)
+    .sort("prefecture")
+)
+print(df_with_ids)
+```
+
+```text
+shape: (48, 4)
+┌────────────┬─────────┬───────┬───────────────┐
+│ prefecture ┆ disease ┆ count ┆ prefecture_id │
+│ ---        ┆ ---     ┆ ---   ┆ ---           │
+│ str        ┆ str     ┆ f64   ┆ str           │
+╞════════════╪═════════╪═══════╪═══════════════╡
+│ Aichi      ┆ Measles ┆ 0.0   ┆ JP-23         │
+│ Akita      ┆ Measles ┆ 0.0   ┆ JP-05         │
+│ Aomori     ┆ Measles ┆ 0.0   ┆ JP-02         │
+│ Chiba      ┆ Measles ┆ 0.0   ┆ JP-12         │
+│ Ehime      ┆ Measles ┆ 0.0   ┆ JP-38         │
+│ …          ┆ …       ┆ …     ┆ …             │
+│ Toyama     ┆ Measles ┆ 0.0   ┆ JP-16         │
+│ Wakayama   ┆ Measles ┆ 0.0   ┆ JP-30         │
+│ Yamagata   ┆ Measles ┆ 0.0   ┆ JP-06         │
+│ Yamaguchi  ┆ Measles ┆ 0.0   ┆ JP-35         │
+│ Yamanashi  ┆ Measles ┆ 0.0   ┆ JP-19         │
+└────────────┴─────────┴───────┴───────────────┘
+```
+
+## Raw Download and Parsing
+
+Raw file workflows are available in `jp_idwr_db.io`:
+
+- `jp_idwr_db.io.download(...)`
+- `jp_idwr_db.io.download_recent(...)`
+- `jp_idwr_db.io.read(...)`
+
+These are useful for refreshing local raw weekly files or debugging parser behavior.
+
+## Data Wrangling Examples
+
+See [EXAMPLES.md](./docs/EXAMPLES.md) for Polars-first data wrangling recipes (grouping, trends, regional slices, source-aware filtering).
+
+Disease-by-disease temporal coverage is documented in [DISEASES.md](./docs/DISEASES.md).
+
+## Data Source
+
+NIID/JIHS infectious disease surveillance publications:
+
+- Historical annual archive files (`Syu_01_1`, `Syu_02_1`)
+- Rapid weekly CSV reports (`zensuXX.csv`, `teitenruiXX.csv`)
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+## Security and Integrity
+
+- Release assets include a `jp_idwr_db-manifest.json` with SHA256 checksums.
+- `ensure_data()` verifies archive checksum and each extracted parquet checksum before marking cache complete.
+- For PyPI publishing, prefer Trusted Publishing (OIDC) over long-lived API tokens.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](./LICENSE).

{jp_idwr_db-0.2.2.dist-info → jp_idwr_db-0.2.3.dist-info}/RECORD

@@ -1,9 +1,9 @@
-jp_idwr_db/__init__.py,sha256=ZLacAkYDdSYOEV5Z_cH7ByzTg9MvY-LC5crVMg3pnok,694
+jp_idwr_db/__init__.py,sha256=3Vpp0-ueVeXTtuzYjtUKCAzraljRGLMD2g4npas_liw,694
 jp_idwr_db/__main__.py,sha256=NczbhLtbnKQm-S4Tc-qARbWGm-s9DQqdx0utCN2e92o,139
 jp_idwr_db/api.py,sha256=Jx7DLmrM2whtbtnnmYlyX-NWuAtpUw4Jz53-3vSjIfs,6799
 jp_idwr_db/cli.py,sha256=taYLWVif3HFSfP9_P9E_nkIrc2L4hfR3-L4wcLY_D0E,1191
-jp_idwr_db/config.py,sha256=ipabkq7wPH8hE0uU9cgXmScL7UU5hU8_qACtgZT3IzA,1576
-jp_idwr_db/data_manager.py,sha256=OHZng1Z9AUHIhJwGRmvgXgy05iruHepQdNmBOkmEs3E,5542
+jp_idwr_db/config.py,sha256=lSTD3rv6vOy799NPR3eAvBvY-KR1wpdKBf9TnVi1Sb0,1576
+jp_idwr_db/data_manager.py,sha256=-Ryn8AaSxISmYVbBLjRr-pkQTJBqZzrgW0CB9DQMz3E,5903
 jp_idwr_db/datasets.py,sha256=Z9dUqqaNdBLUXJTeaGhI2qje2z9XxHZPEsx6_6yFjZs,3068
 jp_idwr_db/http.py,sha256=Y5IRu1Bi448_5kUGugbmryyCklmCc9xkQMTcJU8HX7I,7059
 jp_idwr_db/io.py,sha256=HUSJ0gW4py9uflCSTeGu5X27Lh1e3yITY2DlSARP0Vc,42362
@@ -16,8 +16,8 @@ jp_idwr_db/_internal/__init__.py,sha256=uIjX7aaqbJ2Acm2cEZ8QjgQqqFSmGFbCc-mmeCX_
 jp_idwr_db/_internal/download.py,sha256=APpS9MF2IuOxRqqp0BJbsSgHYkV2OauzH9BamZlqCOs,323
 jp_idwr_db/_internal/read.py,sha256=ZqsuzbyIS5LSFEXl3y9TiCoNxGV5IGueV4uQ6jZ5NnQ,274
 jp_idwr_db/_internal/validation.py,sha256=_Swb-kQgY8_u2aPvNxEh0NMV0a4PY_Moq3mnYxi27Jk,4646
-jp_idwr_db-0.2.2.dist-info/METADATA,sha256=EITWHxcCyNr7mDV_A4zNB_N0jsI6qdzWcWv1DHbxqcM,11951
-jp_idwr_db-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-jp_idwr_db-0.2.2.dist-info/entry_points.txt,sha256=haoRgws2bVbaX-yFyGkPTMcadVnKvKVP6CLIIjuNHy8,51
-jp_idwr_db-0.2.2.dist-info/licenses/LICENSE,sha256=bHrJGTGJC-W4DvVUSZGWxzgNdgTIUBxjJv-Y4twk68M,33429
-jp_idwr_db-0.2.2.dist-info/RECORD,,
+jp_idwr_db-0.2.3.dist-info/METADATA,sha256=RZmJu21QwFm-kIx91FM9cctxJsDL1EVpLXntaX4ZN2A,14508
+jp_idwr_db-0.2.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+jp_idwr_db-0.2.3.dist-info/entry_points.txt,sha256=haoRgws2bVbaX-yFyGkPTMcadVnKvKVP6CLIIjuNHy8,51
+jp_idwr_db-0.2.3.dist-info/licenses/LICENSE,sha256=bHrJGTGJC-W4DvVUSZGWxzgNdgTIUBxjJv-Y4twk68M,33429
+jp_idwr_db-0.2.3.dist-info/RECORD,,

jp_idwr_db-0.2.2.dist-info/METADATA

@@ -1,243 +0,0 @@
-Metadata-Version: 2.4
-Name: jp-idwr-db
-Version: 0.2.2
-Summary: Japanese IDWR infectious disease database and analytics toolkit built on Polars.
-Project-URL: Homepage, https://github.com/AlFontal/jp-idwr-db
-Project-URL: Repository, https://github.com/AlFontal/jp-idwr-db
-Project-URL: Bug Tracker, https://github.com/AlFontal/jp-idwr-db/issues
-Author: jp-idwr-db contributors
-License: GPL-3.0-or-later
-License-File: LICENSE
-Keywords: epidemiology,infectious-disease,japan,polars,surveillance
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
-Classifier: Programming Language :: Python :: 3
-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 :: Medical Science Apps.
-Requires-Python: >=3.10
-Requires-Dist: fastexcel>=0.10
-Requires-Dist: httpx>=0.27
-Requires-Dist: openpyxl>=3.1
-Requires-Dist: platformdirs>=4.2
-Requires-Dist: polars>=0.20
-Requires-Dist: pyarrow>=14.0
-Provides-Extra: dev
-Requires-Dist: mypy>=1.8; extra == 'dev'
-Requires-Dist: pre-commit>=3.7; extra == 'dev'
-Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
-Provides-Extra: excel
-Requires-Dist: fastexcel>=0.10; extra == 'excel'
-Description-Content-Type: text/markdown
-
-# jp-idwr-db
-
-Python access to Japanese infectious disease surveillance data from NIID/JIHS.
-
-`jp-idwr-db` provides a Polars-first API for filtering and analysis.
-Parquet datasets are versioned as GitHub Release assets and downloaded to a local cache on first use.
-It is inspired by the R package `jpinfect`, but it is not an API-parity port and includes independently curated ingestion and coverage.
-
-## Install
-
-```bash
-pip install jp-idwr-db
-```
-
-## Data Download Model
-
-- Package wheels do not ship the large parquet tables.
-- On first call to `jp.load(...)` (or `jp.get_data(...)`), the package downloads versioned data assets from GitHub Releases.
-- Cache path defaults to:
-  - macOS: `~/Library/Caches/jp_idwr_db/data/<version>/`
-  - Linux: `~/.cache/jp_idwr_db/data/<version>/`
-  - Windows: `%LOCALAPPDATA%\\jp_idwr_db\\Cache\\data\\<version>\\`
-
-Prefetch explicitly:
-
-```bash
-python -m jp_idwr_db data download
-python -m jp_idwr_db data download --version v0.1.0 --force
-```
-
-Environment overrides:
-
-- `JPINFECT_DATA_VERSION`: choose a specific release tag (example: `v0.1.0`)
-- `JPINFECT_DATA_BASE_URL`: override asset host base URL
-- `JPINFECT_CACHE_DIR`: override local cache root
-
-## Quick Start
-
-```python
-import jp_idwr_db as jp
-
-# Full unified dataset (recommended)
-df = jp.load("unified")
-print(df.select(["prefecture", "disease", "year", "week", "count", "source"]).head(8))
-```
-
-```text
-shape: (8, 6)
-┌────────────┬─────────────────────────────────┬──────┬──────┬───────┬───────────────────────┐
-│ prefecture ┆ disease                         ┆ year ┆ week ┆ count ┆ source                │
-│ ---        ┆ ---                             ┆ ---  ┆ ---  ┆ ---   ┆ ---                   │
-│ str        ┆ str                             ┆ i32  ┆ i32  ┆ f64   ┆ str                   │
-╞════════════╪═════════════════════════════════╪══════╪══════╪═══════╪═══════════════════════╡
-│ Tochigi    ┆ Lyme disease                    ┆ 2011 ┆ 24   ┆ 0.0   ┆ Confirmed cases       │
-│ Kochi      ┆ Avian influenza H5N1            ┆ 2008 ┆ 51   ┆ 0.0   ┆ Confirmed cases       │
-│ Hokkaido   ┆ Dengue fever                    ┆ 1999 ┆ 28   ┆ 0.0   ┆ Confirmed cases       │
-│ Tokyo      ┆ Congenital rubella syndrome     ┆ 2014 ┆ 41   ┆ 0.0   ┆ Confirmed cases       │
-│ Nagasaki   ┆ Severe Acute Respiratory Syndr… ┆ 2018 ┆ 4    ┆ 0.0   ┆ Confirmed cases       │
-│ Fukushima  ┆ Infectious gastroenteritis (on… ┆ 2019 ┆ 25   ┆ 145.0 ┆ Sentinel surveillance │
-│ Nara       ┆ Severe invasive streptococcal … ┆ 2003 ┆ 10   ┆ 0.0   ┆ Confirmed cases       │
-│ Mie        ┆ Plague                          ┆ 2006 ┆ 37   ┆ 0.0   ┆ Confirmed cases       │
-└────────────┴─────────────────────────────────┴──────┴──────┴───────┴───────────────────────┘
-```
-
-```python
-import jp_idwr_db as jp
-
-# Optional: attach ISO prefecture IDs (JP-01 ... JP-47) only when needed
-df_with_ids = jp.attach_prefecture_id(df, prefecture_col="prefecture", id_col="prefecture_id")
-print(df_with_ids.select(["prefecture", "prefecture_id"]).head())
-```
-
-```text
-shape: (5, 2)
-┌────────────┬───────────────┐
-│ prefecture ┆ prefecture_id │
-╞════════════╪═══════════════╡
-│ Tochigi    ┆ JP-09         │
-│ Kochi      ┆ JP-39         │
-│ Hokkaido   ┆ JP-01         │
-│ Tokyo      ┆ JP-13         │
-│ Nagasaki   ┆ JP-42         │
-└────────────┴───────────────┘
-```
-
-## Main API
-
-Top-level API exported by `jp_idwr_db`:
-
-- `load(name)`
-- `get_data(...)`
-- `list_diseases(source="all")`
-- `list_prefectures()`
-- `get_latest_week()`
-- `prefecture_map()`
-- `attach_prefecture_id(df, prefecture_col="prefecture", id_col="prefecture_id")`
-- `merge(...)`, `pivot(...)`
-- `configure(...)`, `get_config()`
-
-### Filtered Access with `get_data`
-
-```python
-import jp_idwr_db as jp
-
-# Tuberculosis rows for a year range
-tb = jp.get_data(disease="Tuberculosis", year=(2018, 2023))
-print(tb.select(["prefecture", "disease", "year", "week", "count", "source"]).head(8))
-```
-
-```text
-shape: (8, 6)
-┌────────────┬──────────────┬──────┬──────┬───────┬─────────────────┐
-│ prefecture ┆ disease      ┆ year ┆ week ┆ count ┆ source          │
-│ ---        ┆ ---          ┆ ---  ┆ ---  ┆ ---   ┆ ---             │
-│ str        ┆ str          ┆ i32  ┆ i32  ┆ f64   ┆ str             │
-╞════════════╪══════════════╪══════╪══════╪═══════╪═════════════════╡
-│ Hokkaido   ┆ Tuberculosis ┆ 2020 ┆ 12   ┆ 5.0   ┆ Confirmed cases │
-│ Oita       ┆ Tuberculosis ┆ 2023 ┆ 38   ┆ 6.0   ┆ Confirmed cases │
-│ Fukuoka    ┆ Tuberculosis ┆ 2021 ┆ 8    ┆ 12.0  ┆ Confirmed cases │
-│ Kagawa     ┆ Tuberculosis ┆ 2020 ┆ 19   ┆ 2.0   ┆ Confirmed cases │
-│ Chiba      ┆ Tuberculosis ┆ 2020 ┆ 19   ┆ 9.0   ┆ Confirmed cases │
-│ Kanagawa   ┆ Tuberculosis ┆ 2022 ┆ 17   ┆ 25.0  ┆ Confirmed cases │
-│ Okinawa    ┆ Tuberculosis ┆ 2021 ┆ 11   ┆ 4.0   ┆ Confirmed cases │
-│ Gifu       ┆ Tuberculosis ┆ 2018 ┆ 23   ┆ 7.0   ┆ Confirmed cases │
-└────────────┴──────────────┴──────┴──────┴───────┴─────────────────┘
-```
-
-```python
-import jp_idwr_db as jp
-
-# Sentinel-only diseases from recent years
-sentinel = jp.get_data(source="sentinel", year=(2023, 2026))
-print(sentinel.select(["prefecture", "disease", "year", "week", "count", "source"]).head(8))
-```
-
-```text
-shape: (8, 6)
-┌────────────┬─────────────────────────────────┬──────┬──────┬───────┬───────────────────────┐
-│ prefecture ┆ disease                         ┆ year ┆ week ┆ count ┆ source                │
-│ ---        ┆ ---                             ┆ ---  ┆ ---  ┆ ---   ┆ ---                   │
-│ str        ┆ str                             ┆ i32  ┆ i32  ┆ f64   ┆ str                   │
-╞════════════╪═════════════════════════════════╪══════╪══════╪═══════╪═══════════════════════╡
-│ Ishikawa   ┆ Respiratory syncytial virus in… ┆ 2024 ┆ 42   ┆ 813.0 ┆ Sentinel surveillance │
-│ Nara       ┆ Erythema infection              ┆ 2025 ┆ 31   ┆ 823.0 ┆ Sentinel surveillance │
-│ Saga       ┆ Mumps                           ┆ 2024 ┆ 26   ┆ 14.0  ┆ Sentinel surveillance │
-│ Hyogo      ┆ Pharyngoconjunctival fever      ┆ 2023 ┆ 19   ┆ 468.0 ┆ Sentinel surveillance │
-│ Miyazaki   ┆ Infectious gastroenteritis      ┆ 2026 ┆ 3    ┆ 339.0 ┆ Sentinel surveillance │
-│ Kagoshima  ┆ Infectious gastroenteritis (on… ┆ 2024 ┆ 9    ┆ null  ┆ Sentinel surveillance │
-│ Osaka      ┆ Mumps                           ┆ 2024 ┆ 49   ┆ 404.0 ┆ Sentinel surveillance │
-│ Aomori     ┆ Erythema infection              ┆ 2024 ┆ 10   ┆ 5.0   ┆ Sentinel surveillance │
-└────────────┴─────────────────────────────────┴──────┴──────┴───────┴───────────────────────┘
-```
-
-## Datasets
-
-Use `jp.load(...)` with:
-
-- `"sex"`: historical sex-disaggregated surveillance
-- `"place"`: historical place-category surveillance
-- `"bullet"`: modern all-case weekly reports (rapid zensu)
-- `"sentinel"`: sentinel weekly reports (teitenrui; 2012+ in release data assets)
-- `"unified"`: deduplicated combined dataset (sex-total + modern bullet/sentinel, recommended)
-
-Detailed schema and coverage are documented in [DATASETS.md](./docs/DATASETS.md).
-
-## Raw Download and Parsing
-
-Raw file workflows are available in `jp_idwr_db.io`:
-
-- `jp_idwr_db.io.download(...)`
-- `jp_idwr_db.io.download_recent(...)`
-- `jp_idwr_db.io.read(...)`
-
-These are useful for refreshing local raw weekly files or debugging parser behavior.
-
-## Data Wrangling Examples
-
-See [EXAMPLES.md](./docs/EXAMPLES.md) for Polars-first data wrangling recipes (grouping, trends, regional slices, source-aware filtering).
-
-Disease-by-disease temporal coverage is documented in [DISEASES.md](./docs/DISEASES.md).
-
-## Data Source
-
-NIID/JIHS infectious disease surveillance publications:
-
-- Historical annual archive files (`Syu_01_1`, `Syu_02_1`)
-- Rapid weekly CSV reports (`zensuXX.csv`, `teitenruiXX.csv`)
-
-## Development
-
-```bash
-uv sync --all-extras --dev
-uv run ruff check .
-uv run mypy src
-uv run pytest
-```
-
-## Security and Integrity
-
-- Release assets include a `jp_idwr_db-manifest.json` with SHA256 checksums.
-- `ensure_data()` verifies archive checksum and each extracted parquet checksum before marking cache complete.
-- For PyPI publishing, prefer Trusted Publishing (OIDC) over long-lived API tokens.
-
-## License
-
-GPL-3.0-or-later. See [LICENSE](./LICENSE).