Variance component conversion utilities.
Pure math: converts theta (Cholesky factors) and sigma to named variance components for use in bootstrap DataFrames and diagnostics.
Functions:
| Name | Description |
|---|---|
theta_to_variance_components | Convert theta parameters to named variance components. |
Functions¶
theta_to_variance_components¶
theta_to_variance_components(theta: np.ndarray, sigma: float, group_names: list[str], random_names: list[str] | dict[str, list[str]], re_structure: str | list[str] | dict[str, str]) -> tuple[list[str], list[float]]Convert theta parameters to named variance components.
This function converts the raw Cholesky factor (theta) and residual standard deviation (sigma) to interpretable variance component values with standardized naming for use in bootstrap DataFrames.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
theta | ndarray | Optimized theta parameters (Cholesky factors, relative scale). | required |
sigma | float | Residual standard deviation. | required |
group_names | list[str] | Names of grouping factors (e.g., [“Subject”]). | required |
random_names | list[str] | dict[str, list[str]] | Names of random effects per group. For single-structure models: list of names applied to all groups. For mixed-structure models: dict mapping group to names. | required |
re_structure | str | list[str] | dict[str, str] | Random effects structure. “intercept”, “slope”, “diagonal” for single structure. List or dict for mixed structures. | required |
Returns:
| Type | Description |
|---|---|
list[str] | Tuple of (term_names, values) where: |
list[float] | - term_names: List of standardized term names |
tuple[list[str], list[float]] | - values: List of corresponding SD or correlation values |
Random effect SDs: “{Group}:{RE_name}_sd”
Random effect SDs: “{Group}:{RE_name}_sd” e.g., “Subject:Intercept_sd”, “Subject:Days_sd”
Correlations: “{Group}:corr_{RE1}:{RE2}” e.g., “Subject:corr_Intercept:Days”
Residual SD: “Residual_sd”
Examples:
>>> import numpy as np
>>> theta = np.array([0.967, 0.015, 0.231]) # 2x2 Cholesky
>>> sigma = 25.59
>>> group_names = ["Subject"]
>>> random_names = ["Intercept", "Days"]
>>> re_structure = "slope"
>>> names, values = theta_to_variance_components(
... theta, sigma, group_names, random_names, re_structure
... )
>>> names
['Subject:Intercept_sd', 'Subject:Days_sd', 'Subject:corr_Intercept:Days', 'Residual_sd']