NHANES (design-correct survey analysis)

Rules for valid NHANES estimation that this server enforces. Read before analyzing.

Build an analysis-ready dataset: DEMO universe (all participants, needed for valid domain estimation) left-joined to the requested tables on SEQN, for one or more cycles. tables: base names without cycle suffix, e.g. ["BMX", "TCHOL", "BPQ"] (DEMO is always included). variables: columns to keep from those tables (default: all). Weight/design variables are always kept. The analysis weight is chosen and rescaled automatically -> column WT_ANALYSIS. Subsample weights carried by a file (fasting WTSAF2YR, phlebotomy WTPH2YR, surplus serum WTSSMC2Y/4Y, ...) are detected. weight: optional weight kind to force, e.g. 'WTSSMC' or 'WTMEC' (without the 2YR/4YR suffix). The server warns if it is less restrictive than the automatic choice.

Create a variable from an expression over existing columns, e.g. name='OBESE', expression='BMXBMI >= 30' (booleans become 0/1). missing: 'any' -> result missing if ANY referenced column is missing (default, conservative); 'all' -> missing only if ALL referenced columns are missing (for OR-type definitions); 'none' -> no propagation. Missing-aware functions: coalesce(a, b, ...), fillna(x, value), isna(x), notna(x), where(cond, a, b). Columns used only inside them are exempt from the missing rule. Design columns (WT_ANALYSIS, strata, PSU, SEQN, CYCLE) cannot be overwritten here; use set_weight.

Columns, non-missing counts, weight choice, derived-variable definitions and warnings.

Codebook entry (label, question text, target population, value codes) plus observed distribution. Flags codes that look like refused/don't-know so they can be set to missing.

Write the analytic dataset (with WT_ANALYSIS, SDMVSTRA_U, SDMVPSU) to CSV plus a provenance sidecar.

Add a per-person 0/1 indicator from a file with several rows per participant (e.g. RXQ_RX prescriptions, DR1IFF foods). Flag = 1 if ANY row's value in ANY of `columns` matches the regex `pattern` (case-insensitive), e.g. table='RXQ_RX', columns=['RXDRSC1','RXDRSC2','RXDRSC3'], pattern='^G40' for ICD-10 epilepsy as the reason for use. People absent from the file are missing.

List NHANES cycles this server supports, their file-name conventions and weight rules.

List data files for a cycle and component (Demographics, Dietary, Examination, Laboratory, Questionnaire).

Search NHANES variable names/descriptions (regex, case-insensitive) across cycles/components. Defaults to the 2017-2018 cycle and all components.

Recode sentinel values (e.g. 7, 9, 77, 99 for refused/don't know) to missing.

Replace the analysis weight with a custom expression over existing columns, e.g. 'coalesce(WTSSMC4Y * 4/6, WTSSMC2Y * 2/6)'. Use only when build_dataset cannot select the right weight. The change is recorded and reported (weight kind 'CUSTOM' + a warning) in every later result. Negative or missing weights become 0 (out of sample).

Present design-based results: headline estimate, subgroup panels, the analysis plan (so the user can check how the question was interpreted), server warnings, NCHS benchmarks and provenance. Returns a text summary plus structured data; when the optional NHANES Results Explorer add-on is installed, MCP Apps hosts also render it as an interactive view. Same estimation arguments as survey_estimate (dataset_id, variable, statistic, domain, age_adjust); by: one panel per grouping variable, e.g. ['RIAGENDR', 'RIDRETH3', 'AGEGRP'] (age-adjustment is skipped for age groupings -- names starting with AGE or RIDAGE, or containing _AGE -- whose panels are age-specific). title / question / outcome_label / population_label / rationale: plain-language analysis plan. group_names: {"AGEGRP": "Age group"}; group_labels: {"AGEGRP": {"1": "20-39", ...}} (common NHANES demographics are labeled automatically). benchmarks: published comparators, e.g. [{"label": "Obesity 2021-23", "published": 40.3, "source_label": "NCHS Data Brief 508", "source_url": "https://...", "by": "RIAGENDR", "level": "1"}] (published in percent for proportions; omit by/level for the overall estimate).

Survey-weighted Cox proportional hazards model (Breslow ties, Binder linearized variance; same estimator as SUDAAN SURVIVAL / R svycoxph). Typical use with include_mortality=True: time='PERMTH_INT' (or PERMTH_EXM), event='MORTSTAT', domain including 'ELIGSTAT == 1'. Categorical predictors must be dummy-coded first with derive_variable.

Design-based estimate (Taylor linearization) of a mean, proportion (0/1 variable) or total. domain: expression defining the subpopulation, e.g. 'RIDAGEYR >= 20 & RIDEXPRG != 1' (the design is NOT subset; out-of-domain records get zero weight). by: grouping variables, e.g. ['RIAGENDR']. age_adjust: a preset name ('nchs_adults_20plus': 2000 census, 20-39/40-59/60+) or a custom standard {"groups": [[6,11],[12,19],[20,29]], "population": [24.6, 32.5, 38.3]} (or "proportions"), optionally "age_var" (default RIDAGEYR) and "note" naming the source of the standard. Proportions come with Korn-Graubard CIs and NCHS reliability flags.

Weighted distribution of a categorical variable (Table 1 style): for each level, unweighted n, weighted percent, SE and Korn-Graubard CI, within the domain and optionally by group. labels: optional {code: label} map, e.g. {"1": "Male", "2": "Female"}.

Survey-weighted linear ('gaussian') or logistic ('binomial') regression with design-based SEs. Categorical predictors must be dummy-coded first with derive_variable.