Metadata-Version: 2.4
Name: pedgrowth
Version: 1.0.0
Summary: Pedgrowth: pediatric WHO, CDC, and INTERGROWTH z-scores with reproducible references
Author: Eyal Rahmani
Maintainer: Eyal Rahmani
License-Expression: MIT
Project-URL: Homepage, https://github.com/erknet/pedgrowth
Project-URL: Repository, https://github.com/erknet/pedgrowth
Project-URL: Issues, https://github.com/erknet/pedgrowth/issues
Project-URL: WHO growth standards, https://www.who.int/tools/child-growth-standards
Project-URL: CDC growth charts, https://www.cdc.gov/growthcharts/
Keywords: pediatric,growth,anthropometry,WHO,CDC,INTERGROWTH,z-score
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Provides-Extra: who2006
Requires-Dist: pedgrowth-data-who2006==1.0.0; extra == "who2006"
Provides-Extra: who2007
Requires-Dist: pedgrowth-data-who2007==1.0.0; extra == "who2007"
Provides-Extra: who
Requires-Dist: pedgrowth-data-who2006==1.0.0; extra == "who"
Requires-Dist: pedgrowth-data-who2007==1.0.0; extra == "who"
Provides-Extra: cdc
Requires-Dist: pedgrowth-data-cdc==1.0.0; extra == "cdc"
Provides-Extra: intergrowth
Requires-Dist: pedgrowth-data-intergrowth==1.0.0; extra == "intergrowth"
Provides-Extra: all
Requires-Dist: pedgrowth-data-who2006==1.0.0; extra == "all"
Requires-Dist: pedgrowth-data-who2007==1.0.0; extra == "all"
Requires-Dist: pedgrowth-data-cdc==1.0.0; extra == "all"
Requires-Dist: pedgrowth-data-intergrowth==1.0.0; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: refresh
Requires-Dist: openpyxl>=3.1; extra == "refresh"
Requires-Dist: requests>=2.31; extra == "refresh"
Provides-Extra: numpy
Requires-Dist: numpy>=1.26; extra == "numpy"
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Requires-Dist: numpy>=1.26; extra == "pandas"
Provides-Extra: scipy
Requires-Dist: numpy>=1.26; extra == "scipy"
Requires-Dist: scipy>=1.12; extra == "scipy"
Provides-Extra: vector
Requires-Dist: numpy>=1.26; extra == "vector"
Requires-Dist: scipy>=1.12; extra == "vector"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: mypy>=1.14; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: numpy>=1.26; extra == "dev"
Requires-Dist: scipy>=1.12; extra == "dev"
Requires-Dist: scipy-stubs>=1.15; extra == "dev"
Requires-Dist: types-setuptools>=75; extra == "dev"
Requires-Dist: types-openpyxl>=3.1; extra == "dev"
Requires-Dist: types-requests>=2.31; extra == "dev"
Dynamic: license-file

# pedgrowth — extensible pediatric growth engine

A monorepo of five **independent Python distributions**, not a single runtime package containing every scientific dataset.

~~~text
packages/
  pedgrowth/                    # MIT calculation engine, contracts, plugin discovery
    pyproject.toml
    src/pedgrowth/
  pedgrowth-data-who2006/       # WHO 2006 tables, reference policy and plan
    pyproject.toml
    src/pedgrowth/data/who2006/
  pedgrowth-data-who2007/       # WHO 2007 tables and plan
    pyproject.toml
    src/pedgrowth/data/who2007/
  pedgrowth-data-cdc/           # CDC tables and clinical/fallback plans
    pyproject.toml
    src/pedgrowth/data/cdc/
  pedgrowth-data-intergrowth/   # INTERGROWTH equations and plan
    pyproject.toml
    src/pedgrowth/data/intergrowth/
tests/                           # Scientific oracles, fixtures, tests
validation/source_data/          # Audited source snapshots, outside runtime
scripts/                         # Builds, checks, versioning, R reproducibility
docs/                            # Usage, extension and licensing documents
~~~

The MIT core contains **no tests, WHO/CDC tables, INTERGROWTH implementations, reference coefficients, or test datasets**. Providers own their tables, selection rules, plans, source metadata, and packaging. Extensions automatically register themselves through Python entry points; the engine never imports provider packages directly.

## Installation

Python 3.11+. The calculation engine has no mandatory third-party dependencies.

The distributions have **not been published to PyPI**. For the current
research checkout, install the core and whichever independently packaged
providers you need. When released, you will be able to install `pedgrowth`,
the optional `pedgrowth[numpy]` or `pedgrowth[pandas]` extras, and provider
packages such as `pedgrowth-data-cdc` separately.

The four scientific provider distributions are *research-only* while their
source-data redistribution rights are reviewed. From the **monorepo root**:

~~~bash
python -m pip install -e './packages/pedgrowth[dev,pandas]'
python -m pip install -e ./packages/pedgrowth-data-who2006 -e ./packages/pedgrowth-data-who2007 \
  -e ./packages/pedgrowth-data-cdc -e ./packages/pedgrowth-data-intergrowth
python -m pytest -q
~~~

Alternatively, build the independent packages into a private local wheelhouse:

~~~bash
python scripts/build_distributions.py --mode local --output-dir .local/split-distributions
python scripts/check_data_distributions.py .local/split-distributions
~~~

## Automatic reference initialization

WHO 2006 and WHO 2007 provider wheels contain only code and audited source
manifests, **not** protected coefficient tables. On first use of `WhoPlan()`
or `Who2007Plan()`, the corresponding extension downloads the pinned
official WHO spreadsheets, validates their hashes, converts them to LMSB
and caches them outside `site-packages`. INTERGROWTH reconstructs and verifies
its 43 regression parameters from the pinned upstream equation sources.
CDC now also downloads its pinned official CSV references on demand,
without bundling numerical datasets; successful initialization is then offline.

Downloading all installed provider resources in advance is optional:

~~~python
from pedgrowth.data import download_missing_dependencies

download_missing_dependencies()
~~~

This is not necessary for normal calculations; importing the extension or
enumerating registered plans does not download anything. After initialization
the same references are available offline. See
[Automatic reference acquisition](../../docs/AUTOMATIC_REFERENCE_ACQUISITION.md).

## Discover registered providers and plans

~~~python
from pedgrowth import available_providers, available_plans, create_plan

print(available_providers())  # installed providers only
print(available_plans())  # installed named selection policies
clinical_plan = create_plan("cdc_clinical")
~~~

The installed providers may offer these names: **who**, **who2007**, **cdc**, **cdc_clinical**, **cdc_with_who_fallback**, **who_with_cdc_fallback**, and **intergrowth**. WHO 2007 covers older children and adolescents; it does not replace WHO 2006 below age five.

## Plan-based calculation

~~~python
from pedgrowth import AgeDefinition, AgeType, AgeUnit, GrowthChartsCalculator, Sex
from pedgrowth.data.cdc import CdcClinicalPlan

calc = GrowthChartsCalculator(plan=CdcClinicalPlan())
result = calc.calculate(
    indicator="wfa",
    measurement=12.0,
    sex=Sex.Male,
    age=24.0,
    age_definition=AgeDefinition(AgeType.CHRONOLOGICAL, AgeUnit.MONTHS),
)
print(result.zscore, result.reference_id)
~~~

Another installed extension supplies its own plans:

~~~python
from pedgrowth.data.who2006 import WhoPlan
from pedgrowth.data.intergrowth import IntergrowthPlan

who = GrowthChartsCalculator(plan=WhoPlan())
preterm = GrowthChartsCalculator(plan=IntergrowthPlan())
result = preterm.calculate(
    indicator="wfa",
    measurement=2.0,
    sex="M",
    age=35.0,
    age_definition=AgeDefinition(AgeType.POSTMENSTRUAL, AgeUnit.WEEKS),
)
~~~

## Table-based calculation

~~~python
from pedgrowth.data.cdc.tables import CdcWeightForAge

calc = GrowthChartsCalculator(table=CdcWeightForAge())
result = calc.calculate(
    indicator="wfa",
    measurement=18.0,
    sex="M",
    age=48,
    age_definition=AgeDefinition(AgeType.CHRONOLOGICAL, AgeUnit.MONTHS),
)
~~~

Direct equation tables also belong to their provider:

~~~python
from pedgrowth.data.intergrowth import IntergrowthPretermWeightForLength

calc = GrowthChartsCalculator(table=IntergrowthPretermWeightForLength())
result = calc.calculate(indicator="wfl", measurement=2.7, sex="F", coordinate=48.0)
~~~

## NumPy and pandas

~~~python
from pedgrowth import AgeDefinition, AgeType, AgeUnit, GrowthChartsCalculator
from pedgrowth.data.cdc import CdcClinicalPlan

calculator = GrowthChartsCalculator(plan=CdcClinicalPlan())
scores, reference_ids = calculator.calculate_numpy(
    indicator="wfa",
    measurements=[10, 12, 14],
    sexes=["M", "F", "M"],
    ages=[12, 24, 36],
    age_definition=AgeDefinition(AgeType.CHRONOLOGICAL, AgeUnit.MONTHS),
    errors="coerce",
)
~~~

The built-in WHO, CDC and INTERGROWTH plans **vectorize reference selection** using NumPy eligibility masks, then the engine groups selected LMS tables for vectorized numerical evaluation. A custom scalar-only `ReferencePlan` may still use per-row selection for compatibility. The pandas adapter is **pedgrowth.pandas_integration.calculate_typed_dataframe**.

## Adding a new external reference

Each extension is an ordinary Python project with its own pyproject.toml and source tree. It supplies ReferenceTable subclasses, ReferencePlan factories, immutable source manifests, and an entry-point registration callback:

~~~python
# your_provider/__init__.py
from pedgrowth import ReferenceProvider


def register(registry):
    registry.register(
        ReferenceProvider(
            name="my-study",
            family="my-study",
            module=__name__,
            tables=(MyReferenceTable,),
            plans={"my-study": MyStudyPlan},
        )
    )
~~~

~~~toml
# pyproject.toml for the new distribution
[project.entry-points."pedgrowth.references"]
my-study = "your_provider:register"
~~~

Automatic entry-point registration also allows `create_plan("cdc_clinical")` without explicitly importing CDC. Direct class imports require the corresponding extension distribution; the core never bundles provider implementations. The core requires **no modifications**. For custom CSV tables, registration, age/coordinate policy hooks and scientific manifests, see [Extending References](../../docs/EXTENDING_REFERENCES.md).

## Licensing and numerical validation

The core calculation engine is MIT. The WHO/CDC/INTERGROWTH provider distributions are separate artifacts, with file-specific rights evidence and their original scientific sources, and remain blocked for publication until their provider data licenses are resolved. The development monorepo includes research snapshots and needs its own rights review before public release.

See [Licensing and Release](../../docs/PROVIDER_LICENSE_RELEASE.md), the [40-reference licensing matrix](../../docs/REFERENCE_LICENSE_MATRIX.json), and [scientific readiness](../../docs/SCIENTIFIC_READINESS.md). Independent numerical fixtures and R oracle generation stay in tests/, validation/, and scripts/ only.

Research calculations are not certified clinical advice; choose the age definition, population, reference, and measurement protocol deliberately.
