health-code 0.1.0__tar.gz

health_code-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.3
+Name: health-code
+Version: 0.1.0
+Summary: Small helpers for preparing rounded, masked mortality tables for disclosure review.
+Requires-Dist: polars>=1.36.1,<1.42
+Requires-Dist: xlsxwriter>=3.2,<4
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# health-code
+
+Small helpers for preparing a rounded, masked mortality table for disclosure review.
+Install the distribution `health-code`; import it as `health`.
+
+```python
+from health import print_unique   # also: from health.helpers import print_unique
+```
+
+`print_unique` is copied, with the same signature and behavior, from the LTC code package
+(`ltc_code.helpers.print_unique`) so you do not need to install LTC.
+
+## Install
+
+From PyPI:
+
+```bash
+uv pip install health-code
+```
+
+From a local wheel:
+
+```bash
+uv build                      # writes dist/health_code-0.1.0-py3-none-any.whl
+uv pip install dist/health_code-0.1.0-py3-none-any.whl
+```
+
+Python 3.9 or newer. Dependencies: polars, xlsxwriter.
+
+## The example
+
+After installing, copy the example script next to your work (it refuses to overwrite):
+
+```bash
+health-example my_scripts/        # or: health-example my_scripts/prepare_table.py
+```
+
+Edit the `Settings` block at the top and run it. It does this:
+
+1. Reads one parquet per year, 2001..2024, from `INPUT_FOLDER`. The file name comes from
+   `FILENAME_PATTERN`, e.g. `mortality_{year}.parquet`. All 24 files must exist.
+2. Keeps only the eight columns in `COLUMN_MAP` and renames them to `year`, `sex`,
+   `income_percentile`, `age`, `mortality_rate`, `deaths`, `n`, `n_weighted`. Replace the
+   `*_placeholder` names with your real column names.
+3. Fails on: a missing file, a missing column, different column types across files, a row whose
+   year is not its file's year, missing values, duplicate keys, ages outside `AGES`, a rate outside
+   0..1, `deaths > n`, `n <= 0`, or non-positive `n_weighted`.
+4. Rounds and masks (below) and writes the request folder.
+
+You must set `RATE_KIND` (`"weighted"` or `"unweighted"`) and `REQUEST_DATE` (`YYYYMMDD`). Neither
+has a default, because a wrong guess would change what is released.
+
+The same steps are available as functions: `read_annual_parquets`, `prepare_disclosure`,
+`write_disclosure`, and `round_count`.
+
+## What gets written
+
+Layout follows the FSRDC Disclosure Avoidance Review Procedures Handbook v7.0.0 (2026-08-03),
+section III.C:
+
+```text
+YYYYMMDD/
+  output/Table_1_T13T26.xlsx                      the file to submit (rounded, masked)
+  support/Table_1_support_CUI_SP-CENS_T13T26.csv  exact combined data
+  support/estimate_inventory_T13T26.xlsx          row and estimate counts
+  support/rounding/README.txt                     how to run the official rounder
+```
+
+- Every xlsx has a first sheet named `CUI` holding only the CUI header text.
+- The release is xlsx only, so the same estimates are not submitted in two formats. For a CSV copy
+  (for your own use), set `RELEASE_CSV_FOLDER` to a folder outside the request folder.
+- The support CSV holds exact counts, survivors and the suppression flags. It is for the `support`
+  folder only. Only the eight mapped columns ever reach any output file.
+- `estimate_inventory_T13T26.xlsx` leaves prior releases as `UNKNOWN`; fill them in from your
+  project's output tracking sheet.
+- Existing files are never replaced unless `OVERWRITE = True`. Nothing is deleted.
+- `support/rounding/` is left for you: run the Census program `drb_rounder.py` following the DRB
+  Rounder Tutorial on RDC Docs and keep its `_rounded.xlsx` output. This package does not fake it.
+
+## Rounding and masking rules
+
+From the FSRDC Disclosure Avoidance Methods Handbook (guidance current as of 2026-05-01),
+section V.B. Each count is rounded by **its own size**:
+
+| count | rounded to |
+| --- | --- |
+| under 15 | suppressed |
+| 15 to 99 | nearest 10 |
+| 100 to 999 | nearest 50 |
+| 1,000 to 9,999 | nearest 100 |
+| 10,000 to 99,999 | nearest 500 |
+| 100,000 to 999,999 | nearest 1,000 |
+| 1,000,000 or more | four significant figures |
+
+Exact ties: counts below 1,000,000 round half to even (25 -> 20, as in
+`oi_tools.drb.round_count_column`); four-significant-figure rounding at 1,000,000 or more rounds
+ties away from zero (1,234,500 -> 1,235,000). The handbook does not specify tie-breaking, so run
+the official Census rounder before release. Weighted `n_weighted` is rounded to four significant
+figures.
+
+- `"unweighted"`: released rate = rounded `deaths` / rounded `n`, to four significant figures.
+- `"weighted"`: released rate = your input rate to four significant figures. Deaths are never rebuilt
+  from a weighted rate.
+
+**Suppression (a chosen conservative policy, not a universal Census minimum).** A row's four numbers
+(`n`, `deaths`, `mortality_rate`, `n_weighted`) are all set to blank when `n < 15`, `deaths < 15`,
+`n - deaths < 15`, or an optional `EXTRA_SUPPRESS` condition is true. Zeros are suppressed too.
+Keys stay, so the table keeps its shape, and the release has no column saying why a row is blank.
+
+This package is not an approval. It does not check prior releases, the 30:1 volume rule, the
+required minimum entity counts for your geography, or anything the disclosure officer reviews.
+Run the official `drb_rounder.py` and follow your FSRDC administrator's current instructions.
+
+Why not depend on `oi-tools`: it requires Python 3.10 or newer and this package targets 3.9. The
+count rounding is a few lines of polars, and the tests check its thresholds against an independent
+reference. `round_proportion_column` in `oi-tools` is not used (outdated rule).
+
+## Develop
+
+```bash
+uv sync
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Tests use synthetic data only.

health_code-0.1.0/README.md

@@ -0,0 +1,126 @@
+# health-code
+
+Small helpers for preparing a rounded, masked mortality table for disclosure review.
+Install the distribution `health-code`; import it as `health`.
+
+```python
+from health import print_unique   # also: from health.helpers import print_unique
+```
+
+`print_unique` is copied, with the same signature and behavior, from the LTC code package
+(`ltc_code.helpers.print_unique`) so you do not need to install LTC.
+
+## Install
+
+From PyPI:
+
+```bash
+uv pip install health-code
+```
+
+From a local wheel:
+
+```bash
+uv build                      # writes dist/health_code-0.1.0-py3-none-any.whl
+uv pip install dist/health_code-0.1.0-py3-none-any.whl
+```
+
+Python 3.9 or newer. Dependencies: polars, xlsxwriter.
+
+## The example
+
+After installing, copy the example script next to your work (it refuses to overwrite):
+
+```bash
+health-example my_scripts/        # or: health-example my_scripts/prepare_table.py
+```
+
+Edit the `Settings` block at the top and run it. It does this:
+
+1. Reads one parquet per year, 2001..2024, from `INPUT_FOLDER`. The file name comes from
+   `FILENAME_PATTERN`, e.g. `mortality_{year}.parquet`. All 24 files must exist.
+2. Keeps only the eight columns in `COLUMN_MAP` and renames them to `year`, `sex`,
+   `income_percentile`, `age`, `mortality_rate`, `deaths`, `n`, `n_weighted`. Replace the
+   `*_placeholder` names with your real column names.
+3. Fails on: a missing file, a missing column, different column types across files, a row whose
+   year is not its file's year, missing values, duplicate keys, ages outside `AGES`, a rate outside
+   0..1, `deaths > n`, `n <= 0`, or non-positive `n_weighted`.
+4. Rounds and masks (below) and writes the request folder.
+
+You must set `RATE_KIND` (`"weighted"` or `"unweighted"`) and `REQUEST_DATE` (`YYYYMMDD`). Neither
+has a default, because a wrong guess would change what is released.
+
+The same steps are available as functions: `read_annual_parquets`, `prepare_disclosure`,
+`write_disclosure`, and `round_count`.
+
+## What gets written
+
+Layout follows the FSRDC Disclosure Avoidance Review Procedures Handbook v7.0.0 (2026-08-03),
+section III.C:
+
+```text
+YYYYMMDD/
+  output/Table_1_T13T26.xlsx                      the file to submit (rounded, masked)
+  support/Table_1_support_CUI_SP-CENS_T13T26.csv  exact combined data
+  support/estimate_inventory_T13T26.xlsx          row and estimate counts
+  support/rounding/README.txt                     how to run the official rounder
+```
+
+- Every xlsx has a first sheet named `CUI` holding only the CUI header text.
+- The release is xlsx only, so the same estimates are not submitted in two formats. For a CSV copy
+  (for your own use), set `RELEASE_CSV_FOLDER` to a folder outside the request folder.
+- The support CSV holds exact counts, survivors and the suppression flags. It is for the `support`
+  folder only. Only the eight mapped columns ever reach any output file.
+- `estimate_inventory_T13T26.xlsx` leaves prior releases as `UNKNOWN`; fill them in from your
+  project's output tracking sheet.
+- Existing files are never replaced unless `OVERWRITE = True`. Nothing is deleted.
+- `support/rounding/` is left for you: run the Census program `drb_rounder.py` following the DRB
+  Rounder Tutorial on RDC Docs and keep its `_rounded.xlsx` output. This package does not fake it.
+
+## Rounding and masking rules
+
+From the FSRDC Disclosure Avoidance Methods Handbook (guidance current as of 2026-05-01),
+section V.B. Each count is rounded by **its own size**:
+
+| count | rounded to |
+| --- | --- |
+| under 15 | suppressed |
+| 15 to 99 | nearest 10 |
+| 100 to 999 | nearest 50 |
+| 1,000 to 9,999 | nearest 100 |
+| 10,000 to 99,999 | nearest 500 |
+| 100,000 to 999,999 | nearest 1,000 |
+| 1,000,000 or more | four significant figures |
+
+Exact ties: counts below 1,000,000 round half to even (25 -> 20, as in
+`oi_tools.drb.round_count_column`); four-significant-figure rounding at 1,000,000 or more rounds
+ties away from zero (1,234,500 -> 1,235,000). The handbook does not specify tie-breaking, so run
+the official Census rounder before release. Weighted `n_weighted` is rounded to four significant
+figures.
+
+- `"unweighted"`: released rate = rounded `deaths` / rounded `n`, to four significant figures.
+- `"weighted"`: released rate = your input rate to four significant figures. Deaths are never rebuilt
+  from a weighted rate.
+
+**Suppression (a chosen conservative policy, not a universal Census minimum).** A row's four numbers
+(`n`, `deaths`, `mortality_rate`, `n_weighted`) are all set to blank when `n < 15`, `deaths < 15`,
+`n - deaths < 15`, or an optional `EXTRA_SUPPRESS` condition is true. Zeros are suppressed too.
+Keys stay, so the table keeps its shape, and the release has no column saying why a row is blank.
+
+This package is not an approval. It does not check prior releases, the 30:1 volume rule, the
+required minimum entity counts for your geography, or anything the disclosure officer reviews.
+Run the official `drb_rounder.py` and follow your FSRDC administrator's current instructions.
+
+Why not depend on `oi-tools`: it requires Python 3.10 or newer and this package targets 3.9. The
+count rounding is a few lines of polars, and the tests check its thresholds against an independent
+reference. `round_proportion_column` in `oi-tools` is not used (outdated rule).
+
+## Develop
+
+```bash
+uv sync
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Tests use synthetic data only.

health_code-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "health-code"
+version = "0.1.0"
+description = "Small helpers for preparing rounded, masked mortality tables for disclosure review."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "polars>=1.36.1,<1.42",
+    "xlsxwriter>=3.2,<4",
+]
+
+[project.scripts]
+health-example = "health.cli:main"
+
+[dependency-groups]
+dev = [
+    "openpyxl>=3.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# The distribution is health-code on PyPI; the import name is health.
+module-name = "health"
+source-exclude = ["**/.DS_Store", "**/__pycache__/**", "**/*.pyc", "AUTH_STATUS.md", "BUILD_REPORT.md"]
+wheel-exclude = ["**/.DS_Store", "**/__pycache__/**", "**/*.pyc"]

health_code-0.1.0/src/health/__init__.py

@@ -0,0 +1,19 @@
+"""Small helpers for preparing rounded, masked mortality tables for disclosure review."""
+
+from health.disclosure import (
+    prepare_disclosure,
+    read_annual_parquets,
+    round_count,
+    write_disclosure,
+)
+from health.helpers import print_unique
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "print_unique",
+    "read_annual_parquets",
+    "prepare_disclosure",
+    "write_disclosure",
+    "round_count",
+]

health_code-0.1.0/src/health/cli.py

@@ -0,0 +1,35 @@
+"""health-example PATH: copy the example script out of the installed package."""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from importlib.resources import as_file, files
+
+EXAMPLE_NAME = "prepare_mortality_disclosure.py"
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if len(argv) != 1:
+        print("usage: health-example PATH   (a folder, or a new .py file name)")
+        return 2
+    raw = argv[0]
+    target = Path(raw).expanduser()
+    # A trailing separator means "folder", even if it does not exist yet (Path drops it).
+    if target.is_dir() or raw.endswith(("/", os.sep)) or (os.altsep and raw.endswith(os.altsep)):
+        target = target / EXAMPLE_NAME
+    if target.exists():
+        print(f"Refusing to overwrite {target}. Pick another name or delete it first.")
+        return 1
+    target.parent.mkdir(parents=True, exist_ok=True)
+    source = files("health") / "examples" / EXAMPLE_NAME
+    with as_file(source) as src:
+        shutil.copyfile(src, target)
+    print(f"Copied example to {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

health_code-0.1.0/src/health/disclosure.py

@@ -0,0 +1,331 @@
+"""Read annual mortality parquets, validate them, round/mask them, and write a disclosure package.
+
+Rounding follows the FSRDC Disclosure Avoidance Methods Handbook (guidance current as of
+2026-05-01), section V.B. The count rounding matches oi_tools.drb.round_count_column
+(oi-tools 0.14.1). It is reimplemented here with polars only because oi-tools needs
+Python 3.10+ and this package targets 3.9+. tests/test_disclosure.py checks the thresholds.
+
+This code is not an approval. The official drb_rounder.py check and the disclosure
+officer's review still apply.
+"""
+
+from pathlib import Path
+from typing import Dict, Iterable, Optional, Tuple
+
+import polars as pl
+import xlsxwriter
+
+# The canonical names every mapped input is renamed to.
+KEY_COLUMNS = ["year", "sex", "income_percentile", "age"]
+NUMERIC_COLUMNS = ["mortality_rate", "deaths", "n", "n_weighted"]
+CANONICAL_COLUMNS = KEY_COLUMNS + NUMERIC_COLUMNS
+
+# Chosen conservative policy (not a universal Census minimum): a row is masked entirely
+# when n, deaths or n - deaths is below this. Zeros are suppressed too.
+MIN_COUNT = 15
+# Counts above this are rejected, so counts never lose precision as floats (2**53 is about 9e15).
+MAX_COUNT = 10**12
+EXCEL_MAX_DATA_ROWS = 1_048_575
+
+CUI_TEXT = (
+    "CUI//SP-CENS. Disclosure Prohibited: T13 U.S.C. "
+    "Federal Tax Information Protected by Title 26 U.S.C."
+)
+CUI_TAG = "CUI_SP-CENS_T13T26"
+
+ROUNDING_README = """\
+This folder is for the official Census rounding check. It is empty on purpose.
+
+Run the Census program drb_rounder.py on the xlsx in ../../output, following the
+DRB Rounder Tutorial on RDC Docs (rdcdoc.cods.census.gov). It writes
+"[output name]_rounded.xlsx". Keep that file as supporting evidence.
+
+The health package rounds the table itself, but that is not the official check and
+does not replace it.
+"""
+
+
+def round_count(col) -> pl.Expr:
+    """Round an unweighted count using its OWN size (Methods Handbook V.B.3).
+
+    <15 -> null, 15..99 -> nearest 10, 100..999 -> nearest 50, 1,000..9,999 -> nearest 100,
+    10,000..99,999 -> nearest 500, 100,000..999,999 -> nearest 1,000, >=1,000,000 -> four
+    significant figures. Exact ties round half to even below 1,000,000 (as oi_tools does) and
+    away from zero at 1,000,000 and above (1,234,500 -> 1,235,000), because polars
+    `round_sig_figs` is used there. The handbook does not specify ties; use the official
+    Census rounder for the release. Returns Int64.
+    """
+    x = pl.col(col) if isinstance(col, str) else col
+    f = x.cast(pl.Float64)
+    near = lambda step: (f / step).round(0, mode="half_to_even") * step  # noqa: E731
+    return (
+        pl.when(x < 15).then(None)
+        .when(x < 100).then(near(10))
+        .when(x < 1_000).then(near(50))
+        .when(x < 10_000).then(near(100))
+        .when(x < 100_000).then(near(500))
+        .when(x < 1_000_000).then(near(1_000))
+        .otherwise(f.round_sig_figs(4).round(0))  # .round(0) removes float noise like 999999999999.9
+        .cast(pl.Int64)
+    )
+
+
+def _check_columns(have, want, what: str) -> None:
+    missing = [c for c in want if c not in have]
+    if missing:
+        raise ValueError(f"{what}: missing columns {missing}. Columns present: {sorted(have)}")
+
+
+def read_annual_parquets(
+    input_folder,
+    filename_pattern: str,
+    years: Iterable[int],
+    column_map: Dict[str, str],
+) -> pl.DataFrame:
+    """Read one parquet per year, keep only the mapped columns, rename them, and concatenate.
+
+    column_map maps source column name -> canonical name (all eight canonical names needed).
+    Other columns in the files are never read into the result.
+    """
+    years = list(years)
+    if "{year}" not in filename_pattern:
+        raise ValueError(f"filename_pattern must contain '{{year}}', got {filename_pattern!r}")
+    if sorted(column_map.values()) != sorted(CANONICAL_COLUMNS):
+        raise ValueError(
+            f"column_map must map exactly one source column to each of {CANONICAL_COLUMNS}; "
+            f"got targets {sorted(column_map.values())}"
+        )
+    if len(set(column_map)) != len(column_map):
+        raise ValueError("column_map has duplicate source columns")
+    input_folder = Path(input_folder)
+    if not input_folder.is_dir():
+        raise FileNotFoundError(f"Input folder does not exist: {input_folder}")
+
+    paths = {y: input_folder / filename_pattern.format(year=y) for y in years}
+    missing = [p.name for p in paths.values() if not p.is_file()]
+    if missing:
+        raise FileNotFoundError(f"{len(missing)} expected file(s) missing in {input_folder}: {missing}")
+
+    frames = []
+    first_schema = None
+    for year, path in paths.items():
+        lf = pl.scan_parquet(path)
+        _check_columns(lf.collect_schema().names(), list(column_map), path.name)
+        df = lf.select([pl.col(src).alias(dst) for src, dst in column_map.items()]).collect()
+        schema = dict(df.schema)
+        if first_schema is None:
+            first_schema = schema
+        elif schema != first_schema:
+            diff = {c: (str(first_schema[c]), str(schema[c])) for c in schema if schema[c] != first_schema[c]}
+            raise ValueError(f"{path.name}: column types differ from the first file (first, this): {diff}")
+        if not df.schema["year"].is_integer():
+            raise ValueError(f"{path.name}: year column must be an integer type, got {df.schema['year']}")
+        bad = df.filter(pl.col("year").is_null() | (pl.col("year") != year)).height
+        if bad:
+            raise ValueError(f"{path.name}: {bad} row(s) have a year other than {year}")
+        frames.append(df)
+    return pl.concat(frames, how="vertical")
+
+
+def _validate(df, years, ages, percentiles, unexpected_percentiles) -> pl.DataFrame:
+    _check_columns(df.columns, CANONICAL_COLUMNS, "data")
+    df = df.select(CANONICAL_COLUMNS)
+
+    # Required fields: no nulls anywhere.
+    nulls = {c: df[c].null_count() for c in CANONICAL_COLUMNS if df[c].null_count()}
+    if nulls:
+        raise ValueError(f"Missing values in required columns (counts): {nulls}")
+
+    # Numeric types: counts must be integers (or integer-valued floats) within MAX_COUNT.
+    for c in ["n", "deaths"]:
+        dtype = df.schema[c]
+        if dtype.is_float():
+            f = df[c]
+            if not f.is_finite().all() or (f != f.floor()).any():
+                raise ValueError(f"{c} must be whole numbers (finite, no fractions)")
+        elif not dtype.is_integer():
+            raise ValueError(f"{c} must be an integer type, got {dtype}")
+        if df[c].max() > MAX_COUNT or df[c].min() < 0:
+            raise ValueError(f"{c} outside 0..{MAX_COUNT}")
+        df = df.with_columns(pl.col(c).cast(pl.Int64))
+    for c in ["mortality_rate", "n_weighted"]:
+        dtype = df.schema[c]
+        if not (dtype.is_float() or dtype.is_integer()):
+            raise ValueError(f"{c} must be numeric, got {dtype}")
+        df = df.with_columns(pl.col(c).cast(pl.Float64))
+        if not df[c].is_finite().all():
+            raise ValueError(f"{c} has non-finite values")
+    if df["n"].min() <= 0:
+        raise ValueError("n must be positive")
+    if (df["deaths"] > df["n"]).any():
+        raise ValueError("deaths must not exceed n")
+    if df["mortality_rate"].min() < 0 or df["mortality_rate"].max() > 1:
+        raise ValueError("mortality_rate must be a probability between 0 and 1")
+    if df["n_weighted"].min() <= 0:
+        raise ValueError("n_weighted must be positive")
+
+    # Domains of the key columns.
+    if years is not None:
+        found = set(df["year"].unique().to_list())
+        if found != set(years):
+            raise ValueError(f"years differ from expected: missing {sorted(set(years) - found)}, unexpected {sorted(found - set(years))}")
+    if ages is not None:
+        bad = sorted(set(df["age"].unique().to_list()) - set(ages))
+        if bad:
+            raise ValueError(f"ages outside the expected range: {bad}")
+    if percentiles is not None:
+        bad = sorted(set(df["income_percentile"].unique().to_list()) - set(percentiles))
+        if bad:
+            if unexpected_percentiles == "drop":
+                print(f"Dropping {df.filter(pl.col('income_percentile').is_in(bad)).height} row(s) with income_percentile in {bad}")
+                df = df.filter(~pl.col("income_percentile").is_in(bad))
+            else:
+                raise ValueError(f"unexpected income_percentile values: {bad} (set unexpected_percentiles='drop' to drop them)")
+
+    # Keys must be unique.
+    dup = df.select(KEY_COLUMNS).is_duplicated().sum()
+    if dup:
+        raise ValueError(f"{dup} rows share a duplicate key ({', '.join(KEY_COLUMNS)})")
+    return df
+
+
+def prepare_disclosure(
+    df: pl.DataFrame,
+    rate_kind: Optional[str],
+    years: Optional[Iterable[int]] = None,
+    ages: Optional[Iterable[int]] = range(30, 96),
+    percentiles: Optional[Iterable] = None,
+    unexpected_percentiles: str = "error",
+    extra_suppress: Optional[pl.Expr] = None,
+) -> Tuple[pl.DataFrame, pl.DataFrame]:
+    """Validate the canonical table, then return (support, release).
+
+    rate_kind (required): "unweighted" releases rounded deaths / rounded n, rounded to four
+    significant figures. "weighted" releases the input rate rounded to four significant figures
+    (deaths are never rebuilt from a weighted rate). Input rates must be probabilities in 0..1.
+
+    percentiles: None accepts any income_percentile value (zero is kept, not dropped). Pass the
+    allowed values to check them; unexpected ones then raise, or are dropped with
+    unexpected_percentiles="drop". ages defaults to 30..95; None turns the age check off.
+
+    Suppression (chosen conservative policy, not a universal Census minimum): the whole row's
+    four numbers are set to null when n < 15, deaths < 15 or n - deaths < 15, which includes
+    zeros, or when extra_suppress (an optional polars Boolean expression over the canonical
+    columns, e.g. pl.col("age") > 90) is true. Keys stay. The release has no reason columns.
+
+    support keeps exact values, survivors (n - deaths) and the suppression flags. It is for the
+    support folder only, never for output.
+    """
+    if rate_kind not in ("weighted", "unweighted"):
+        raise ValueError(
+            f"rate_kind must be 'weighted' or 'unweighted' (got {rate_kind!r}). It decides how the "
+            "released rate is built, so there is no default: choose it from how mortality_rate was made."
+        )
+    df = _validate(df, None if years is None else list(years), None if ages is None else list(ages),
+                   None if percentiles is None else list(percentiles), unexpected_percentiles)
+    df = df.sort(KEY_COLUMNS)
+
+    flags = [
+        (pl.col("n") < MIN_COUNT).alias("suppress_n"),
+        (pl.col("deaths") < MIN_COUNT).alias("suppress_deaths"),
+        ((pl.col("n") - pl.col("deaths")) < MIN_COUNT).alias("suppress_survivors"),
+    ]
+    if extra_suppress is not None:
+        flags.append(extra_suppress.alias("suppress_extra"))
+    else:
+        flags.append(pl.lit(False).alias("suppress_extra"))
+    support = df.with_columns((pl.col("n") - pl.col("deaths")).alias("survivors")).with_columns(flags)
+    if support["suppress_extra"].dtype != pl.Boolean or support["suppress_extra"].null_count():
+        raise ValueError("extra_suppress must be a Boolean expression with no missing values")
+    support = support.with_columns(
+        pl.any_horizontal("suppress_n", "suppress_deaths", "suppress_survivors", "suppress_extra").alias("suppressed")
+    )
+
+    n_r, d_r = round_count("n"), round_count("deaths")
+    if rate_kind == "unweighted":
+        rate = (d_r.cast(pl.Float64) / n_r.cast(pl.Float64)).round_sig_figs(4)
+    else:
+        rate = pl.col("mortality_rate").round_sig_figs(4)
+    rounded = support.with_columns(
+        n_r.alias("n"), d_r.alias("deaths"), rate.alias("mortality_rate"),
+        pl.col("n_weighted").round_sig_figs(4),
+    )
+    release = rounded.select(
+        KEY_COLUMNS
+        + [pl.when(pl.col("suppressed")).then(None).otherwise(pl.col(c)).alias(c) for c in ["n", "deaths", "mortality_rate", "n_weighted"]]
+    )
+    if release["mortality_rate"].max() is not None and release["mortality_rate"].max() > 1:
+        raise ValueError("a rounded rate exceeds 1; check the inputs")
+    support = support.select(
+        KEY_COLUMNS + ["n", "deaths", "survivors", "mortality_rate", "n_weighted"]
+        + ["suppress_n", "suppress_deaths", "suppress_survivors", "suppress_extra", "suppressed"]
+    )
+    return support, release
+
+
+def _write_xlsx(path: Path, df: pl.DataFrame, sheet: str) -> None:
+    """Workbook with a CUI cover tab first (header text only), then the table."""
+    if df.height > EXCEL_MAX_DATA_ROWS:
+        raise ValueError(f"{path.name}: {df.height} rows do not fit in one Excel sheet")
+    wb = xlsxwriter.Workbook(str(path))
+    wb.add_worksheet("CUI").write(0, 0, CUI_TEXT)
+    df.write_excel(workbook=wb, worksheet=sheet, autofit=False)
+    wb.close()
+
+
+def write_disclosure(
+    support: pl.DataFrame,
+    release: pl.DataFrame,
+    request_folder,
+    table_name: str = "Table_1",
+    release_csv_folder=None,
+    overwrite: bool = False,
+) -> Dict[str, Path]:
+    """Write the FSRDC request layout (Procedures Handbook v7.0.0, III.C) under request_folder.
+
+    request_folder/output/{table}_T13T26.xlsx              the only file meant to be emailed
+    request_folder/support/{table}_support_CUI_SP-CENS_T13T26.csv   exact combined data
+    request_folder/support/estimate_inventory_T13T26.xlsx   counts of released estimates
+    request_folder/support/rounding/README.txt              how to run the official rounder
+
+    Name request_folder with the request date, YYYYMMDD. The release is xlsx only, so the same
+    estimates are not submitted twice in two formats. A release CSV is written only if
+    release_csv_folder is given, and that folder must be outside request_folder.
+    Existing files are never replaced unless overwrite=True; nothing is deleted.
+    """
+    root = Path(request_folder)
+    targets = {
+        "release_xlsx": root / "output" / f"{table_name}_T13T26.xlsx",
+        "support_csv": root / "support" / f"{table_name}_support_{CUI_TAG}.csv",
+        "inventory_xlsx": root / "support" / "estimate_inventory_T13T26.xlsx",
+        "rounding_readme": root / "support" / "rounding" / "README.txt",
+    }
+    if release_csv_folder is not None:
+        csv_dir = Path(release_csv_folder).resolve()
+        if csv_dir == root.resolve() or root.resolve() in csv_dir.parents:
+            raise ValueError("release_csv_folder must be outside the request folder, so CSV and xlsx are not both submitted")
+        targets["release_csv"] = csv_dir / f"{table_name}_{CUI_TAG}.csv"
+    existing = [str(p) for p in targets.values() if p.exists()]
+    if existing and not overwrite:
+        raise FileExistsError(f"Refusing to overwrite existing files (pass overwrite=True): {existing}")
+
+    for p in targets.values():
+        p.parent.mkdir(parents=True, exist_ok=True)
+    _write_xlsx(targets["release_xlsx"], release, table_name)
+    support.write_csv(targets["support_csv"])
+    if "release_csv" in targets:
+        release.write_csv(targets["release_csv"])
+
+    n_cells = int(sum(release[c].is_not_null().sum() for c in NUMERIC_COLUMNS))
+    inventory = pl.DataFrame({
+        "table": [table_name],
+        "rows_total": [release.height],
+        "rows_suppressed": [int(support["suppressed"].sum())],
+        "rows_released": [int(release.height - support["suppressed"].sum())],
+        "numeric_columns_per_row": [len(NUMERIC_COLUMNS)],
+        "estimates_released_nonnull": [n_cells],
+        "prior_releases_of_this_sample": ["UNKNOWN - fill in from the project's output tracking sheet"],
+    })
+    _write_xlsx(targets["inventory_xlsx"], inventory, "inventory")
+    targets["rounding_readme"].write_text(ROUNDING_README)
+    return targets

health_code-0.1.0/src/health/examples/prepare_mortality_disclosure.py

@@ -0,0 +1,94 @@
+# --- Import necessary packages ---
+import re
+from pathlib import Path
+
+import polars as pl
+
+from health import prepare_disclosure, print_unique, read_annual_parquets, write_disclosure
+
+###########################################################
+# Settings: edit this section, nothing below needs to change
+###########################################################
+
+# Folder holding the 24 annual parquet files.
+INPUT_FOLDER = Path("PATH/TO/INPUT_FOLDER")
+
+# File name of each year's file; {year} is replaced by 2001, 2002, ..., 2024.
+FILENAME_PATTERN = "mortality_{year}.parquet"
+YEARS = list(range(2001, 2025))
+
+# Column names in your files (left) and the canonical names this script uses (right).
+# Only these eight columns are read. Replace the placeholder names with your real ones.
+COLUMN_MAP = {
+    "year_placeholder": "year",
+    "sex_placeholder": "sex",
+    "income_percentile_placeholder": "income_percentile",
+    "age_placeholder": "age",
+    "mortality_rate_placeholder": "mortality_rate",
+    "deaths_placeholder": "deaths",
+    "n_placeholder": "n",
+    "n_weighted_placeholder": "n_weighted",
+}
+
+# How mortality_rate was built. You must choose: "weighted" or "unweighted".
+#   "unweighted": the released rate is rounded deaths / rounded n.
+#   "weighted":   the released rate is your rate rounded to four significant figures.
+RATE_KIND = None
+
+# Ages and income percentiles allowed. PERCENTILES = None accepts any value (including 0).
+AGES = range(30, 96)
+PERCENTILES = None
+
+# Optional extra rule: also mask the rows where this Boolean expression is true.
+EXTRA_SUPPRESS = None  # e.g. pl.col("age") > 90
+
+# Request date as YYYYMMDD (the FSRDC request folder name) and where the request folders live.
+REQUEST_DATE = None
+OUTPUT_ROOT = Path("PATH/TO/disclosure")
+
+# Name of the table. The file to submit will be output/Table_1_T13T26.xlsx.
+TABLE_NAME = "Table_1"
+
+# Optional: a folder OUTSIDE the request folder for a rounded CSV copy. None writes no CSV.
+RELEASE_CSV_FOLDER = None
+
+# False refuses to replace files that already exist.
+OVERWRITE = False
+
+if REQUEST_DATE is None or not re.fullmatch(r"\d{8}", str(REQUEST_DATE)):
+    raise ValueError("Set REQUEST_DATE to the request date as YYYYMMDD, e.g. '20261101'.")
+
+###########################################################
+# Read, check, round and mask
+###########################################################
+
+# Read the 24 files; this fails if a file, a column or a year is wrong.
+data = read_annual_parquets(INPUT_FOLDER, FILENAME_PATTERN, YEARS, COLUMN_MAP)
+print_unique(data, "year")
+
+# Validate (unique keys, ranges, no missing values), then build the exact and the release tables.
+support, release = prepare_disclosure(
+    data,
+    rate_kind=RATE_KIND,
+    years=YEARS,
+    ages=AGES,
+    percentiles=PERCENTILES,
+    extra_suppress=EXTRA_SUPPRESS,
+)
+print(f"{support['suppressed'].sum()} of {support.height} rows masked")
+
+###########################################################
+# Write the request folder
+###########################################################
+
+# output/ has the xlsx to submit; support/ has the exact data, inventory and rounding notes.
+paths = write_disclosure(
+    support,
+    release,
+    OUTPUT_ROOT / str(REQUEST_DATE),
+    table_name=TABLE_NAME,
+    release_csv_folder=RELEASE_CSV_FOLDER,
+    overwrite=OVERWRITE,
+)
+for name, path in paths.items():
+    print(f"{name}: {path}")

health_code-0.1.0/src/health/helpers.py

@@ -0,0 +1,30 @@
+from typing import Union
+
+import polars as pl
+
+
+# Copied from ltc_code.helpers.print_unique (LTC code package, by William Ratnavale),
+# with the same signature and behavior, so health does not need to import ltc_code.
+# Define a function that prints the unique values of a specified column for a lazy or data frame and its counts
+def print_unique(
+    df: Union[pl.DataFrame, pl.LazyFrame],
+    col: str,
+    ) -> pl.DataFrame:
+    out = (
+        df
+        .group_by(col)
+        .len()
+        .sort("len", descending=True)
+    )
+    # execute if lazyframe
+    if isinstance(out, pl.LazyFrame):
+        out = out.collect()
+    # if # unique vals > max table height then print them all in a loop
+    n = out.height
+    if n <= 15:
+        print(out)
+    else:
+        print(f"{n} unique values in '{col}':")
+        for row in out.iter_rows(named=True):
+            print(f"{row[col]}: {row['len']}")
+    return out