gam_models/
transformation_normal.rs

1//! Conditional transformation model: estimate h(y|x) such that h(Y|x) ~ N(0,1).
2//!
3//! Given a response variable y and covariates x with a pre-built covariate design
4//! operator, this family estimates a smooth monotone transformation h(y | x) mapping
5//! the conditional distribution of Y|x onto a standard normal.
6//!
7//! The response-direction basis is `[1, I_1(y), ..., I_K(y)]`, tensored with an
8//! arbitrary covariate design operator. Column 0 is an unconstrained location
9//! component `b(x)`. The I-spline columns are shape components with squared
10//! covariate-side coefficients, giving the SCOP representation
11//! `h(y, x) = b(x) + ε·(y−median_y) + Σ_k I_k(y) γ_k(x)^2` and
12//! `h'(y, x) = ε + Σ_k M_k(y) γ_k(x)^2`. Monotonicity is structural:
13//! the fixed derivative floor `ε` keeps the change-of-variables log-density
14//! away from the `log(0)` singularity, while the non-negative M-spline basis
15//! and squared covariate-side coefficients supply the learned shape.
16//!
17//! The log-likelihood per observation is the finite-support normalized
18//! change-of-variables density for a standard normal target:
19//!
20//!   ℓ_i = -½ h_i² + log(h'_i) - log(Φ(h_U(x_i)) - Φ(h_L(x_i)))
21//!
22//! where `h_i = b(x_i) + ε·(y_i−median_y) + Σ_k I_k(y_i) γ_k(x_i)^2`
23//! and `h'_i = ε + Σ_k M_k(y_i) γ_k(x_i)^2`. The endpoint normalizer is
24//! required because the I-spline response basis saturates at finite support
25//! values rather than mapping onto the full real line.
26
27mod endpoint_normalizer;
28
29// Shared imports re-exported so every concern submodule pulls them through
30// `use super::*;` without re-listing. `pub(crate)` lets the child globs see them.
31pub(crate) use endpoint_normalizer::{
32    LogNormalCdfDiffDerivatives, endpoint_chain_first, endpoint_chain_fourth,
33    endpoint_chain_second, endpoint_chain_third, log_normal_cdf_diff,
34    log_normal_cdf_diff_derivatives,
35};
36
37pub(crate) use crate::custom_family::{
38    BlockWorkingSet, BlockwiseFitOptions, CustomFamily, CustomFamilyBlockPsiDerivative,
39    CustomFamilyPsiDerivativeOperator, CustomFamilyWarmStart, ExactNewtonJointGradientEvaluation,
40    ExactNewtonJointHessianWorkspace, FamilyEvaluation, JointHessianSourcePreference,
41    MaterializablePsiDerivativeOperator, MaterializationIntent, ParameterBlockSpec,
42    ParameterBlockState, PenaltyMatrix, evaluate_custom_family_joint_hyper,
43    evaluate_custom_family_joint_hyper_efs, fit_custom_family, fit_custom_family_fixed_log_lambdas,
44};
45pub(crate) use crate::fit_orchestration::drivers::{
46    ExactJointHyperSetup, freeze_term_collection_from_design,
47    optimize_spatial_length_scale_exact_joint, spatial_length_scale_term_indices,
48};
49pub(crate) use crate::inference::model::{
50    TRANSFORMATION_SCORE_PIT_CLIP_EPS, TransformationScoreCalibration,
51};
52pub(crate) use crate::model_types::UnifiedFitResult;
53pub(crate) use crate::penalized_projection::solve_penalizedweighted_projection;
54pub(crate) use crate::probability::standard_normal_quantile;
55pub(crate) use crate::spatial_psi_bridge::build_block_spatial_psi_derivatives;
56pub(crate) use gam_linalg::faer_ndarray::{fast_ab, fast_abt, fast_atb};
57pub(crate) use gam_linalg::matrix::{
58    DenseDesignMatrix, DenseDesignOperator, DesignMatrix, LinearOperator, SymmetricMatrix,
59    dense_rowwise_kronecker,
60};
61pub(crate) use gam_problem::{
62    ExactNewtonJointPsiSecondOrderTerms, ExactNewtonJointPsiTerms, ExactNewtonJointPsiWorkspace,
63};
64pub(crate) use gam_solve::pirls::LinearInequalityConstraints;
65pub(crate) use gam_terms::basis::initializewiggle_knots_from_seed;
66pub(crate) use gam_terms::basis::{
67    BasisOptions, Dense, KnotSource, create_basis, create_difference_penalty_matrix,
68    create_ispline_derivative_dense,
69};
70pub(crate) use gam_terms::smooth::{
71    SpatialLengthScaleOptimizationOptions, SpatialLogKappaCoords, TermCollectionDesign,
72    TermCollectionSpec,
73};
74// #1521: relocated DOWN into gam_terms::smooth (was drivers::build_term_collection_design).
75pub(crate) use gam_problem::{
76    DriftDerivResult, HyperOperator, ProjectedFactorCache, ProjectedFactorKey,
77};
78pub(crate) use gam_runtime::resource::{MatrixMaterializationError, ResourcePolicy};
79pub(crate) use gam_terms::smooth::build_term_collection_design;
80pub(crate) use ndarray::{Array1, Array2, ArrayView1, ArrayView2, ArrayViewMut2, s};
81pub(crate) use std::cell::RefCell;
82pub(crate) use std::sync::{Arc, Mutex, OnceLock};
83
84mod config;
85mod custom_family;
86mod error;
87mod family;
88mod fit;
89mod kronecker_design;
90mod operators;
91mod penalty_scaling;
92mod psi_operator;
93mod response_basis;
94mod scop_curvature;
95mod scop_density;
96mod scop_psi;
97mod warm_start;
98
99pub use config::*;
100pub use error::*;
101pub use family::*;
102pub use fit::*;
103pub(crate) use kronecker_design::*;
104pub(crate) use operators::*;
105pub(crate) use penalty_scaling::*;
106pub use psi_operator::*;
107pub use response_basis::effective_response_num_internal_knots;
108pub(crate) use response_basis::{
109    assert_rowwise_kronecker_dimensions, build_response_basis, response_endpoint_value_bases,
110    response_floor_offsets,
111};
112pub use scop_density::*;
113pub(crate) use warm_start::*;
114
115#[cfg(test)]
116mod tests;
gam_models/transformation_normal.rs

gam_models/
transformation_normal.rs
