Metadata-Version: 2.3
Name: health-code
Version: 0.1.4
Summary: print_unique and a simple annual mortality disclosure script.
Requires-Dist: polars>=1.36.1,<1.42
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# health-code

A `print_unique` helper and one editable Python script for the national mortality release.

```bash
uv pip install --upgrade health-code
health-example prepare_mortality_disclosure.py
```

Edit the paths, date, placeholder column names, and annual filename pattern at the top of the copied script. Run it with `uv run python prepare_mortality_disclosure.py`.

The script appends 2001–2024 and writes two CSVs. Supply unweighted `deaths` and `n`, plus unrounded `n_weighted` and `mortality_rate_reweighted`. It calculates:

```python
survivors = n - deaths
mortality_rate = deaths / n
deaths_reweighted = mortality_rate_reweighted * n_weighted
```

The weighted input must be an **unsmoothed proportion (0–1)** equal to `sum(weight * death_indicator) / sum(weight)`, with `n_weighted` equal to that same denominator. The product then recovers weighted deaths up to floating-point precision; fractional weighted deaths are retained. A smoothed, standardized, rounded, or per-100,000 rate is not a suitable input.

The outputs are:

```text
20261026/
  support/national_mortality_20261026_support_CUI_SP-CENS_T13T26.csv
  for_release/national_mortality_20261026_T13T26.csv
```

Support preserves unrounded inputs and adds survivors, the unrounded deaths/n rate, and recovered weighted deaths. The release keeps rows and:

- Displays unweighted counts below 15 as the string `<15`.
- Rounds larger counts to the nearest 10, 50, 100, 500, or 1,000 according to their size; counts of a million or more use four significant digits.
- Calculates the released mortality rate from **rounded deaths / rounded n**, then rounds that quotient to four significant digits.
- Rounds the supplied weighted mortality rate, recovered weighted deaths, and weighted population separately to four significant digits. The weighted rate is not recomputed from rounded weighted counts.
- Removes redundant `.0` endings from rounded values.
- Puts `D` in both mortality rates and weighted deaths when unweighted observations, deaths, or survivors are below 15, including zero; puts `D` in weighted population when observations are below 15. Withholding weighted deaths alongside the weighted rate prevents reconstructing that suppressed rate from the weighted numerator and denominator.
- Omits survivors from the release.

It expects complete aggregate inputs with positive n and n_weighted, actual unweighted deaths, and the matching weighted rate described above. Any pre-existing unweighted mortality column is ignored. The script uses your existing weighted estimates; it does not estimate weights or smooth rates. Rerunning replaces the two output files.

Rounding follows the [Census Methods Handbook, pp. 27–29](https://www2.census.gov/adrm/FSRDC/Resources/FSRDC-Disclosure-Avoidance-Methods-Handbook.pdf). Count ties below a million round half to even; four-significant-digit rounding uses Polars. The zero-count rate screen is this product's conservative choice. Prior-release/complementary suppression review and Census clearance still apply.

```python
from health import print_unique
print_unique(df, "year")
```

Version 0.1.4 adds weighted mortality and recovered weighted deaths. The output names `mortality_rate`, `mortality_rate_reweighted`, and `n_weighted` correspond to Ines’s `mr`, `mr_reweighted`, and `n_reweighted`. Version 0.1.3 added unweighted mortality from counts. Version 0.1.2 removed the earlier disclosure helper API, XLSX output, optional inventory, and validation framework. The disclosure code is entirely in the example script; `health-example` simply copies it for editing.
