gamlss_formula/
lib.rs

1#![forbid(unsafe_code)]
2//! Experimental optional typed formula/builder layer for compiling user model
3//! specifications into typed `gamlss-core` models.
4//!
5//! `gamlss-formula` is a boundary layer: it reads user data through
6//! [`DataView`], fits term metadata once, materializes predictor designs, and
7//! returns a [`BuiltModel`] artifact. Optimizers, fitting loops, diagnostics,
8//! dataframe ownership, and string formula parsing are intentionally outside
9//! this crate.
10//!
11//! This crate is not the primary API of the project. The current primary path is
12//! the lower-level typed API in `gamlss-core`, `gamlss-family`, `gamlss-spline`,
13//! and `gamlss-transform`. `gamlss-formula` is an experimental convenience layer
14//! for curated high-level workflows and is not expected to cover every
15//! distribution, link, or parameterization available in the lower-level crates.
16//!
17//! # Example
18//!
19//! ```
20//! use gamlss_core::Objective;
21//! use gamlss_formula::prelude::*;
22//!
23//! # #[derive(Debug)]
24//! # struct TestData {
25//! #     y: Vec<f64>,
26//! #     x: Vec<f64>,
27//! # }
28//! # impl DataView for TestData {
29//! #     fn nrows(&self) -> usize { self.y.len() }
30//! #     fn f64_col(&self, col: &Col<f64>) -> Result<NumericCol<'_>, FormulaError> {
31//! #         match col.name() {
32//! #             "y" => Ok(NumericCol::Borrowed(&self.y)),
33//! #             "x" => Ok(NumericCol::Borrowed(&self.x)),
34//! #             name => Err(FormulaError::UnknownColumn(name.to_owned())),
35//! #         }
36//! #     }
37//! # }
38//! let data = TestData {
39//!     y: vec![0.0, 1.0, 2.0],
40//!     x: vec![0.0, 1.0, 2.0],
41//! };
42//!
43//! let y = col::<f64>("y");
44//! let x = col::<f64>("x");
45//! let mut built = normal()
46//!     .response(y)
47//!     .mu(intercept() + linear(x))
48//!     .sigma(intercept())
49//!     .build(&data)?;
50//!
51//! let theta = vec![0.0, 0.5, -0.2];
52//! assert!(built.model_mut().value(&theta)?.is_finite());
53//! # Ok::<_, Box<dyn std::error::Error>>(())
54//! ```
55
56mod compile;
57mod data;
58mod error;
59mod penalty;
60mod predictor;
61mod schema;
62mod spec;
63mod terms;
64
65pub use data::{BoolCol, CatCol, Category, Col, DataView, NumericCol, NumericResponse, col};
66pub use error::FormulaError;
67pub use penalty::FormulaPenalty;
68pub use predictor::FormulaPredictorBlock;
69pub use schema::{BuiltModel, ModelSchema, ParameterTerms, PredictionDesign, ResponseSchema};
70pub use spec::{
71    BetaBlocks, BetaSpec, BuiltBeta, BuiltGamma, BuiltInverseGaussian, BuiltLogNormal, BuiltNormal,
72    BuiltWeibull, CompiledBeta, CompiledGamma, CompiledInverseGaussian, CompiledLogNormal,
73    CompiledNormal, CompiledWeibull, FormulaBlock, GammaBlocks, GammaSpec, InverseGaussianBlocks,
74    InverseGaussianSpec, LogNormalBlocks, LogNormalSpec, ModelSpec, NormalBlocks, NormalSpec,
75    WeibullBlocks, WeibullSpec, beta, gamma, inverse_gaussian, log_normal, normal, weibull,
76};
77pub use terms::{
78    CyclicPSplineTerm, FittedTerm, FourierTerm, MonotoneTerm, PSplineTerm, TensorPSplineTerm,
79    TermExpr, TermSpec, cyclic_pspline, factor, fourier, indicator, interaction, intercept, linear,
80    monotone, no_intercept, offset, pspline, tensor_pspline,
81};
82
83/// Common imports for the typed formula layer.
84pub mod prelude {
85    pub use crate::{
86        BetaSpec, BoolCol, BuiltBeta, BuiltGamma, BuiltInverseGaussian, BuiltLogNormal, BuiltModel,
87        BuiltNormal, BuiltWeibull, CatCol, Category, Col, CompiledBeta, CompiledGamma,
88        CompiledInverseGaussian, CompiledLogNormal, CompiledNormal, CompiledWeibull,
89        CyclicPSplineTerm, DataView, FittedTerm, FormulaError, FormulaPenalty,
90        FormulaPredictorBlock, FourierTerm, GammaSpec, InverseGaussianSpec, LogNormalSpec,
91        ModelSchema, ModelSpec, MonotoneTerm, NormalSpec, NumericCol, NumericResponse, PSplineTerm,
92        ParameterTerms, PredictionDesign, ResponseSchema, TensorPSplineTerm, TermExpr, TermSpec,
93        WeibullSpec, beta, col, cyclic_pspline, factor, fourier, gamma, indicator, interaction,
94        intercept, inverse_gaussian, linear, log_normal, monotone, no_intercept, normal, offset,
95        pspline, tensor_pspline, weibull,
96    };
97}
98
99#[cfg(test)]
100mod tests;
gamlss_formula/lib.rs

gamlss_formula/
lib.rs
