Skip to content

CHS: integrate out missing observed factors; post-#92 CHS follow-ups #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hmgaudecker wants to merge 18 commits into
base: main
Choose a base branch
from
Open

CHS: integrate out missing observed factors; post-#92 CHS follow-ups #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
99821f8
Snapshot gpu-01 working tree used for health-cognition estimation runs
hmgaudecker Oct 8, 2026
cadcaaa
Drop the CHS criterion sanitizer
hmgaudecker Oct 9, 2026
6c3188c
Reset underflowed mixture components to the dominant one in the CHS u…
hmgaudecker Oct 10, 2026
06f8ab9
Raise on a non-finite CHS criterion; forward error_handling to optimagic
hmgaudecker Oct 10, 2026
409350a
Let estimate_chs tighten lower bounds on chosen parameters
hmgaudecker Oct 11, 2026
af53b2c
Reject probit/Tobit measurements in CHS instead of treating them as G…
hmgaudecker Oct 12, 2026
f96a086
Let estimate_chs replace bounds and start on linear equality constraints
hmgaudecker Oct 12, 2026
1c5bb8e
Add upper_bounds to estimate_chs
hmgaudecker Oct 12, 2026
f6ba3f5
CHS: integrate out missing observed factors using data-supplied moments
hmgaudecker Oct 14, 2026
ef557a7
Require chs_options in get_maximization_inputs and the CHS state filters
hmgaudecker Oct 14, 2026
c162965
Move split_dataset onto CHSEstimationOptions so estimate_chs can use it
hmgaudecker Oct 14, 2026
69bae86
Missing observed factors: endogenous guard, root precision, shared co…
hmgaudecker Oct 15, 2026
83074da
Transition plots: compute ranges of factors the caller did not supply
hmgaudecker Oct 15, 2026
471ab0c
Measurement correlations: one column per measurement loading on sever…
hmgaudecker Oct 16, 2026
7eec297
Factor-distribution contours: put the first factor on the x axis
hmgaudecker Oct 16, 2026
5d26103
Transition plots, average over draws: draw from complete rows
hmgaudecker Oct 16, 2026
5acd0a3
Format the estimator prerequisites table
hmgaudecker Oct 18, 2026
a53ee7a
ModelSpec.from_dict: reject unrecognized top-level keys
hmgaudecker Oct 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/getting_started/tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -534,7 +534,7 @@
],
"source": [
"chs_filtered = get_individual_states_from_params(\n",
" model_spec=model, data=data, params=chs_params\n",
" model_spec=model, data=data, params=chs_params, chs_options=chs_options\n",
")\n",
"chs_states = chs_filtered[\"unanchored_states\"][\"states\"]\n",
"chs_decomp = decompose_measurement_variance(\n",
Expand Down
4 changes: 2 additions & 2 deletions docs/how_to_guides/how_to_visualize_pairwise_factor_distribution.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
"id": "2",
"metadata": {},
"outputs": [],
"source": "model = MODEL2\nparams = pd.read_csv(REGRESSION_VAULT / \"one_stage_anchoring.csv\")\nparams = params.set_index([\"category\", \"period\", \"name1\", \"name2\"])\n\ndata = pd.read_stata(TEST_DATA_DIR / \"model2_simulated_data.dta\")\ndata = data.set_index([\"caseid\", \"period\"])\n\nfiltered = get_individual_states_from_params(model_spec=model, data=data, params=params)\nstates = filtered[\"anchored_states\"][\"states\"]"
"source": "model = MODEL2\nparams = pd.read_csv(REGRESSION_VAULT / \"one_stage_anchoring.csv\")\nparams = params.set_index([\"category\", \"period\", \"name1\", \"name2\"])\n\ndata = pd.read_stata(TEST_DATA_DIR / \"model2_simulated_data.dta\")\ndata = data.set_index([\"caseid\", \"period\"])\n\nfiltered = get_individual_states_from_params(\n model_spec=model, data=data, params=params, chs_options=MODEL2_CHS_OPTIONS\n)\nstates = filtered[\"anchored_states\"][\"states\"]"
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -254,7 +254,7 @@
"id": "20",
"metadata": {},
"outputs": [],
"source": "params = get_maximization_inputs(\n model_spec=model, data=data, chs_options=MODEL2_CHS_OPTIONS\n)[\"params_template\"]\nparams[\"value\"] = 0.1\nfiltered = get_individual_states_from_params(model_spec=model, data=data, params=params)\nstates = filtered[\"anchored_states\"][\"states\"]"
"source": "params = get_maximization_inputs(\n model_spec=model, data=data, chs_options=MODEL2_CHS_OPTIONS\n)[\"params_template\"]\nparams[\"value\"] = 0.1\nfiltered = get_individual_states_from_params(\n model_spec=model, data=data, params=params, chs_options=MODEL2_CHS_OPTIONS\n)\nstates = filtered[\"anchored_states\"][\"states\"]"
},
{
"cell_type": "code",
Expand Down
4 changes: 2 additions & 2 deletions docs/how_to_guides/how_to_visualize_transition_equations.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"id": "0",
"metadata": {},
"outputs": [],
"source": "import pandas as pd\n\nfrom skillmodels.common.config import REGRESSION_VAULT, TEST_DATA_DIR\nfrom skillmodels.common.individual_states import get_individual_states_from_params\nfrom skillmodels.common.visualize_transition_equations import (\n combine_transition_plots,\n get_transition_plots,\n)\nfrom skillmodels.test_data.model2 import MODEL2"
"source": "import pandas as pd\n\nfrom skillmodels.common.config import REGRESSION_VAULT, TEST_DATA_DIR\nfrom skillmodels.common.individual_states import get_individual_states_from_params\nfrom skillmodels.common.visualize_transition_equations import (\n combine_transition_plots,\n get_transition_plots,\n)\nfrom skillmodels.test_data.model2 import MODEL2, MODEL2_CHS_OPTIONS"
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -37,7 +37,7 @@
"id": "2",
"metadata": {},
"outputs": [],
"source": "model = MODEL2\n\nparams = pd.read_csv(REGRESSION_VAULT / \"one_stage_anchoring.csv\")\nparams = params.set_index([\"category\", \"period\", \"name1\", \"name2\"])\n\ndata = pd.read_stata(TEST_DATA_DIR / \"model2_simulated_data.dta\")\ndata = data.set_index([\"caseid\", \"period\"])\n\nfiltered = get_individual_states_from_params(model_spec=model, data=data, params=params)\nstates = filtered[\"anchored_states\"][\"states\"]"
"source": "model = MODEL2\n\nparams = pd.read_csv(REGRESSION_VAULT / \"one_stage_anchoring.csv\")\nparams = params.set_index([\"category\", \"period\", \"name1\", \"name2\"])\n\ndata = pd.read_stata(TEST_DATA_DIR / \"model2_simulated_data.dta\")\ndata = data.set_index([\"caseid\", \"period\"])\n\nfiltered = get_individual_states_from_params(\n model_spec=model, data=data, params=params, chs_options=MODEL2_CHS_OPTIONS\n)\nstates = filtered[\"anchored_states\"][\"states\"]"
},
{
"cell_type": "markdown",
Expand Down
28 changes: 14 additions & 14 deletions docs/reference_guides/estimator_prerequisites.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,20 @@ three estimators.

## Prerequisites matrix

| Dimension | CHS | AF | AMN |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Estimator | Joint maximum likelihood with square-root Gaussian-component filtering. | Sequential period-by-period likelihood with Halton integration. | Three stages: Gaussian-mixture EM → minimum distance → simulate-and-regress. |
| Latent distribution | Finite mixture of Gaussian initial states via `ModelSpec.n_mixtures`; Gaussian component filtering thereafter. | Initial finite mixture plus sequentially carried distributions; Halton nodes approximate the integrals. | Stage-1 Gaussian mixture over the augmented measurement vector; `n_mixtures` sets the component count. |
| Measurement families | **Gaussian only** (standard Kalman update). Probit/Tobit measurements are not consumed by the CHS path. | **Initial period only**: probit/Tobit measurement families are honoured at the period-0 measurement system; transition periods ($t \geq 1$) fall back to an all-Gaussian measurement kernel. | **Gaussian only**: `estimate_amn` raises `NotImplementedError` if `ModelSpec.measurement_models` declares any probit/Tobit measurement. |
| Missing data | Gaussian measurement updates skip individually missing measurements. | Measurement masks skip missing rows in the per-step likelihood contributions. | `mixture_em_method="complete_case"` (default) or `"missing_data"` (marginalises over missing entries under MAR); never-observed columns require `allow_never_observed_measurements=True`. |
| Endogenous investment | Reconstructed endogenous factors plus a full `CorrectionSpec` control-function basis. | Reconstructed endogenous investment with independent shocks (source/destination calendar adapter); rejects `CorrectionSpec` / nonzero `kappa`. | Endogenous investment in Stage 3; correction support is a linearised control-function term, narrower than CHS. |
| Corrections | Full `CorrectionSpec` / `kappa` polynomial basis in the processed transition DAG. | Not implemented — the validator raises if a `CorrectionSpec` is attached. | Linear `cf` term only; a higher-order `kappa_terms` request raises. |
| Custom transitions | Built-ins and `@register_params` callables. | Built-ins and `@register_params` callables. | Built-ins and `@register_params` callables via the Stage-3 generic NLS path, but `log_ces` / `log_ces_with_constant` reject fixed parameters there. |
| `fixed_params` | Honoured through the shared parameter index. | Honoured (with public `constraints=` limited to `select_by_loc` equality groups). | Honoured only for the categories each stage estimates (Stage-2 loadings/intercepts/SDs, Stage-3 `transition`); other categories raise. `start_params` and `constraints` raise. |
| Normalization | Shared `Normalizations` / `fixed_params` / equality constraints. The checker is a precheck, not an identification proof. | Same public `ModelSpec`, with the AF-specific source/destination calendar and `af_state_role` metadata. | Stage-2 imposes its own structural moment restrictions and a mean-zero mixture convention. |
| Anchoring | Supported through `get_maximization_inputs` / the CHS path. | Not part of the AF likelihood; downstream visualization only. | Not wired through the AMN stages (the result reports unanchored scales). |
| Cost / scaling | Potentially expensive joint ML; the JAX square-root filter helps numerical stability. | Sequential but quadrature-heavy; cost grows with node count and state dimension. | Fast when the stages are well behaved; the cluster bootstrap is expensive because it re-estimates every stage. |
| Use it for | Likelihood benchmark, anchoring, correction-heavy models, Gaussian measurement systems. | Sequential AF-style models, initial-period limited measurements, period-by-period diagnostics. | Mixture-heavy Gaussian-measurement models, fast start values for CHS, Stage-1/2 structural diagnostics. |
| Dimension | CHS | AF | AMN |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Estimator | Joint maximum likelihood with square-root Gaussian-component filtering. | Sequential period-by-period likelihood with Halton integration. | Three stages: Gaussian-mixture EM → minimum distance → simulate-and-regress. |
| Latent distribution | Finite mixture of Gaussian initial states via `ModelSpec.n_mixtures`; Gaussian component filtering thereafter. | Initial finite mixture plus sequentially carried distributions; Halton nodes approximate the integrals. | Stage-1 Gaussian mixture over the augmented measurement vector; `n_mixtures` sets the component count. |
| Measurement families | **Gaussian only** (standard Kalman update): `get_maximization_inputs` / `estimate_chs` raise `NotImplementedError` if `ModelSpec.measurement_models` declares any probit/Tobit measurement. | **Initial period only**: probit/Tobit measurement families are honoured at the period-0 measurement system; transition periods ($t \geq 1$) fall back to an all-Gaussian measurement kernel. | **Gaussian only**: `estimate_amn` raises `NotImplementedError` if `ModelSpec.measurement_models` declares any probit/Tobit measurement. |
| Missing data | Gaussian measurement updates skip individually missing measurements. | Measurement masks skip missing rows in the per-step likelihood contributions. | `mixture_em_method="complete_case"` (default) or `"missing_data"` (marginalises over missing entries under MAR); never-observed columns require `allow_never_observed_measurements=True`. |
| Endogenous investment | Reconstructed endogenous factors plus a full `CorrectionSpec` control-function basis. | Reconstructed endogenous investment with independent shocks (source/destination calendar adapter); rejects `CorrectionSpec` / nonzero `kappa`. | Endogenous investment in Stage 3; correction support is a linearised control-function term, narrower than CHS. |
| Corrections | Full `CorrectionSpec` / `kappa` polynomial basis in the processed transition DAG. | Not implemented — the validator raises if a `CorrectionSpec` is attached. | Linear `cf` term only; a higher-order `kappa_terms` request raises. |
| Custom transitions | Built-ins and `@register_params` callables. | Built-ins and `@register_params` callables. | Built-ins and `@register_params` callables via the Stage-3 generic NLS path, but `log_ces` / `log_ces_with_constant` reject fixed parameters there. |
| `fixed_params` | Honoured through the shared parameter index. | Honoured (with public `constraints=` limited to `select_by_loc` equality groups). | Honoured only for the categories each stage estimates (Stage-2 loadings/intercepts/SDs, Stage-3 `transition`); other categories raise. `start_params` and `constraints` raise. |
| Normalization | Shared `Normalizations` / `fixed_params` / equality constraints. The checker is a precheck, not an identification proof. | Same public `ModelSpec`, with the AF-specific source/destination calendar and `af_state_role` metadata. | Stage-2 imposes its own structural moment restrictions and a mean-zero mixture convention. |
| Anchoring | Supported through `get_maximization_inputs` / the CHS path. | Not part of the AF likelihood; downstream visualization only. | Not wired through the AMN stages (the result reports unanchored scales). |
| Cost / scaling | Potentially expensive joint ML; the JAX square-root filter helps numerical stability. | Sequential but quadrature-heavy; cost grows with node count and state dimension. | Fast when the stages are well behaved; the cluster bootstrap is expensive because it re-estimates every stage. |
| Use it for | Likelihood benchmark, anchoring, correction-heavy models, Gaussian measurement systems. | Sequential AF-style models, initial-period limited measurements, period-by-period diagnostics. | Mixture-heavy Gaussian-measurement models, fast start values for CHS, Stage-1/2 structural diagnostics. |

## Reading the matrix

Expand Down
Loading
Loading