Skip to main content

gamlss_diagnostics/
lib.rs

1#![forbid(unsafe_code)]
2//! Post-fit diagnostics utilities for Rust-native GAMLSS models.
3//!
4//! This crate is the intended home for diagnostics that are important for
5//! GAMLSS parity but should not be part of the core [`gamlss_core::Family`]
6//! contract.
7//!
8//! Current utilities include:
9//!
10//! - PIT/CDF residuals;
11//! - ordered multivariate Rosenblatt residuals;
12//! - CRPS summaries;
13//! - reusable diagnostics views for prediction rows.
14//!
15//! Planned utilities include:
16//!
17//! - randomized quantile residuals;
18//! - worm plot data;
19//! - centile curve data;
20//! - fitted parameter extraction helpers;
21//! - distribution-level prediction helpers.
22//!
23//! The public surface intentionally grows through small extension APIs.
24//! Distribution-specific capabilities should be expressed through extension
25//! traits such as [`gamlss_core::HasCdf`] and [`gamlss_core::HasQuantile`],
26//! while this crate provides post-fit utilities built on top of compiled model
27//! predictions.
28//!
29//! ```
30//! # use gamlss_core::{DenseDesign, Gamlss, Identity, Log, Mu, NoPenalty, ParameterBlock, ParameterBlocks, Sigma};
31//! # use gamlss_diagnostics::prelude::*;
32//! # use gamlss_family::Normal;
33//! # let y = [0.0, 1.0, -1.0];
34//! # let blocks = ParameterBlocks::new((
35//! #     ParameterBlock::<Mu, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
36//! #     ParameterBlock::<Sigma, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
37//! # ));
38//! # let model = Gamlss::try_new(Normal::<Identity, Log>::new(), blocks, &y)?;
39//! let parameters = [0.0, 0.0];
40//! let pit = model.pit_values(&parameters)?;
41//! let residuals = model.quantile_residuals(&parameters)?;
42//! # assert_eq!(pit.len(), residuals.len());
43//! # Ok::<_, gamlss_core::ModelError>(())
44//! ```
45
46use gamlss_core::{
47    Family, Gamlss, GamlssBlocks, HasCdf, HasCrps, HasMarginalCdf, HasObservationDimension,
48    HasRosenblattTransform, ModelError, ObservationView, PredictionView,
49};
50use gamlss_special::unit_normal_quantile;
51
52/// Common diagnostics imports.
53pub mod prelude {
54    pub use crate::{
55        CdfDiagnosticsExt, CrpsDiagnosticsExt, MarginalCdfDiagnosticsExt, PredictionDiagnosticsExt,
56        PredictionDiagnosticsView, PredictionRosenblattDiagnosticsExt, RosenblattDiagnosticsExt,
57    };
58}
59
60/// Validated diagnostics view over prediction rows and observations.
61///
62/// This view is built from a core [`PredictionView`] plus an observation view,
63/// validating the prediction observation length and observation invariants once.
64/// Reuse it when computing multiple diagnostics over the same prediction rows.
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub struct PredictionDiagnosticsView<'a, 'obs, F, PBlocks, PObs> {
67    prediction: PredictionView<'a, F, PBlocks>,
68    obs: &'obs PObs,
69}
70
71impl<'a, 'obs, F, PBlocks, PObs> PredictionDiagnosticsView<'a, 'obs, F, PBlocks, PObs>
72where
73    F: for<'row> Family<Observation<'row> = f64>,
74    PBlocks: GamlssBlocks<F>,
75    PObs: ObservationView<'obs, Observation = f64> + 'obs,
76{
77    fn new(
78        prediction: &PredictionView<'a, F, PBlocks>,
79        obs: &'obs PObs,
80    ) -> Result<Self, ModelError> {
81        validate_prediction_observations(prediction.nrows(), obs)?;
82        Ok(Self {
83            prediction: *prediction,
84            obs,
85        })
86    }
87
88    /// Number of prediction rows.
89    #[must_use]
90    #[inline]
91    pub const fn nrows(&self) -> usize {
92        self.prediction.nrows()
93    }
94
95    /// Returns PIT values for the validated prediction rows.
96    ///
97    /// # Errors
98    ///
99    /// Returns [`ModelError`] if `parameters` has the wrong length.
100    pub fn pit_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>
101    where
102        F: HasCdf,
103    {
104        let mut out = vec![0.0; self.nrows()];
105        self.pit_values_into(parameters, &mut out)?;
106        Ok(out)
107    }
108
109    /// Writes PIT values for the validated prediction rows into `out`.
110    ///
111    /// # Errors
112    ///
113    /// Returns [`ModelError`] if `parameters` or `out` have the wrong length.
114    pub fn pit_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError>
115    where
116        F: HasCdf,
117    {
118        self.diagnostic_values_into(parameters, out, |family, observation, theta| {
119            family.cdf(observation, theta)
120        })
121    }
122
123    /// Returns normalized quantile residuals for the validated prediction rows.
124    ///
125    /// # Errors
126    ///
127    /// Returns [`ModelError`] if `parameters` has the wrong length.
128    pub fn quantile_residuals(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>
129    where
130        F: HasCdf,
131    {
132        self.pit_values(parameters).map(normalize_pit_values)
133    }
134
135    /// Returns CRPS values for the validated prediction rows.
136    ///
137    /// # Errors
138    ///
139    /// Returns [`ModelError`] if `parameters` has the wrong length.
140    pub fn crps_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>
141    where
142        F: HasCrps,
143    {
144        let mut out = vec![0.0; self.nrows()];
145        self.crps_values_into(parameters, &mut out)?;
146        Ok(out)
147    }
148
149    /// Writes CRPS values for the validated prediction rows into `out`.
150    ///
151    /// # Errors
152    ///
153    /// Returns [`ModelError`] if `parameters` or `out` have the wrong length.
154    pub fn crps_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError>
155    where
156        F: HasCrps,
157    {
158        self.diagnostic_values_into(parameters, out, |family, observation, theta| {
159            family.crps(observation, theta)
160        })
161    }
162
163    fn diagnostic_values_into(
164        &self,
165        parameters: &[f64],
166        out: &mut [f64],
167        mut evaluate: impl FnMut(&F, f64, &F::Theta) -> f64,
168    ) -> Result<(), ModelError> {
169        validate_output_len(self.nrows(), out.len())?;
170        self.prediction.for_each_theta(parameters, |row, theta| {
171            out[row] = evaluate(
172                self.prediction.family(),
173                self.obs.observation_at(row),
174                &theta,
175            );
176        })
177    }
178}
179
180/// Explicit component-wise marginal PIT diagnostics for multivariate families.
181pub trait MarginalCdfDiagnosticsExt<F, Blocks> {
182    /// Returns marginal PIT values for one response coordinate.
183    ///
184    /// `observations` contains that coordinate in model row order. The explicit
185    /// scalar slice prevents a joint multivariate CDF from being mistaken for a
186    /// scalar PIT.
187    fn marginal_pit_values(
188        &self,
189        parameters: &[f64],
190        component: usize,
191        observations: &[f64],
192    ) -> Result<Vec<f64>, ModelError>;
193
194    /// Writes marginal PIT values into `out`.
195    fn marginal_pit_values_into(
196        &self,
197        parameters: &[f64],
198        component: usize,
199        observations: &[f64],
200        out: &mut [f64],
201    ) -> Result<(), ModelError>;
202}
203
204impl<F, Blocks, Obs> MarginalCdfDiagnosticsExt<F, Blocks> for Gamlss<F, Blocks, Obs>
205where
206    F: HasMarginalCdf + HasObservationDimension,
207    Blocks: GamlssBlocks<F>,
208    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
209{
210    fn marginal_pit_values(
211        &self,
212        parameters: &[f64],
213        component: usize,
214        observations: &[f64],
215    ) -> Result<Vec<f64>, ModelError> {
216        let mut out = vec![0.0; self.nobs()];
217        self.marginal_pit_values_into(parameters, component, observations, &mut out)?;
218        Ok(out)
219    }
220
221    fn marginal_pit_values_into(
222        &self,
223        parameters: &[f64],
224        component: usize,
225        observations: &[f64],
226        out: &mut [f64],
227    ) -> Result<(), ModelError> {
228        if component >= self.family().observation_dimension() {
229            return Err(ModelError::InvalidParameter {
230                parameter: "marginal PIT component",
231                expected: "inside the family observation dimension",
232            });
233        }
234        validate_output_len(self.nobs(), observations.len())?;
235        validate_output_len(self.nobs(), out.len())?;
236        self.for_each_theta(parameters, |row, theta| {
237            out[row] = self
238                .family()
239                .marginal_cdf(component, observations[row], &theta);
240        })
241    }
242}
243
244/// Ordered multivariate PIT diagnostics for a validated core [`PredictionView`].
245pub trait PredictionRosenblattDiagnosticsExt<F, PBlocks>
246where
247    F: HasRosenblattTransform,
248    PBlocks: GamlssBlocks<F>,
249{
250    /// Returns row-major Rosenblatt values with one contiguous coordinate block per row.
251    fn rosenblatt_values<'obs, PObs>(
252        &self,
253        parameters: &[f64],
254        obs: &'obs PObs,
255    ) -> Result<Vec<f64>, ModelError>
256    where
257        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs;
258
259    /// Writes row-major Rosenblatt values into `out`.
260    fn rosenblatt_values_into<'obs, PObs>(
261        &self,
262        parameters: &[f64],
263        obs: &'obs PObs,
264        out: &mut [f64],
265    ) -> Result<(), ModelError>
266    where
267        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs;
268}
269
270impl<F, PBlocks> PredictionRosenblattDiagnosticsExt<F, PBlocks> for PredictionView<'_, F, PBlocks>
271where
272    F: HasRosenblattTransform,
273    PBlocks: GamlssBlocks<F>,
274{
275    fn rosenblatt_values<'obs, PObs>(
276        &self,
277        parameters: &[f64],
278        obs: &'obs PObs,
279    ) -> Result<Vec<f64>, ModelError>
280    where
281        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs,
282    {
283        let len = checked_rosenblatt_len(self.nrows(), self.family().observation_dimension())?;
284        let mut out = vec![0.0; len];
285        self.rosenblatt_values_into(parameters, obs, &mut out)?;
286        Ok(out)
287    }
288
289    fn rosenblatt_values_into<'obs, PObs>(
290        &self,
291        parameters: &[f64],
292        obs: &'obs PObs,
293        out: &mut [f64],
294    ) -> Result<(), ModelError>
295    where
296        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs,
297    {
298        let nrows = self.nrows();
299        let actual = obs.len();
300        if actual != nrows {
301            return Err(ModelError::ResponseLength {
302                expected: nrows,
303                actual,
304            });
305        }
306        obs.validate()?;
307        let dimension = self.family().observation_dimension();
308        validate_output_len(checked_rosenblatt_len(nrows, dimension)?, out.len())?;
309
310        let family = self.family();
311        let mut transform_error = None;
312        self.for_each_theta(parameters, |row, theta| {
313            if transform_error.is_some() {
314                return;
315            }
316            let start = row * dimension;
317            transform_error = family
318                .rosenblatt_into(
319                    obs.observation_at(row),
320                    &theta,
321                    &mut out[start..start + dimension],
322                )
323                .err();
324        })?;
325        transform_error.map_or(Ok(()), Err)
326    }
327}
328
329/// Ordered multivariate PIT diagnostics for fitted GAMLSS models.
330pub trait RosenblattDiagnosticsExt<F, Blocks>
331where
332    F: HasRosenblattTransform,
333    Blocks: GamlssBlocks<F>,
334{
335    /// Returns row-major Rosenblatt values for the training observations.
336    ///
337    /// Coordinate order is the family observation order and therefore also the
338    /// conditioning order of the transform.
339    fn rosenblatt_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>;
340
341    /// Writes row-major Rosenblatt values for the training observations into `out`.
342    fn rosenblatt_values_into(&self, parameters: &[f64], out: &mut [f64])
343    -> Result<(), ModelError>;
344
345    /// Returns row-major Rosenblatt values for compatible prediction rows.
346    fn rosenblatt_values_with_blocks<'obs, PBlocks, PObs>(
347        &self,
348        parameters: &[f64],
349        blocks: &PBlocks,
350        obs: &'obs PObs,
351    ) -> Result<Vec<f64>, ModelError>
352    where
353        PBlocks: GamlssBlocks<F>,
354        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs;
355
356    /// Writes row-major Rosenblatt values for compatible prediction rows into `out`.
357    fn rosenblatt_values_with_blocks_into<'obs, PBlocks, PObs>(
358        &self,
359        parameters: &[f64],
360        blocks: &PBlocks,
361        obs: &'obs PObs,
362        out: &mut [f64],
363    ) -> Result<(), ModelError>
364    where
365        PBlocks: GamlssBlocks<F>,
366        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs;
367}
368
369impl<F, Blocks, Obs> RosenblattDiagnosticsExt<F, Blocks> for Gamlss<F, Blocks, Obs>
370where
371    F: HasRosenblattTransform,
372    Blocks: GamlssBlocks<F>,
373    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
374{
375    fn rosenblatt_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError> {
376        self.prediction_view(self.blocks())?
377            .rosenblatt_values(parameters, self.obs())
378    }
379
380    fn rosenblatt_values_into(
381        &self,
382        parameters: &[f64],
383        out: &mut [f64],
384    ) -> Result<(), ModelError> {
385        self.prediction_view(self.blocks())?
386            .rosenblatt_values_into(parameters, self.obs(), out)
387    }
388
389    fn rosenblatt_values_with_blocks<'obs, PBlocks, PObs>(
390        &self,
391        parameters: &[f64],
392        blocks: &PBlocks,
393        obs: &'obs PObs,
394    ) -> Result<Vec<f64>, ModelError>
395    where
396        PBlocks: GamlssBlocks<F>,
397        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs,
398    {
399        self.prediction_view(blocks)?
400            .rosenblatt_values(parameters, obs)
401    }
402
403    fn rosenblatt_values_with_blocks_into<'obs, PBlocks, PObs>(
404        &self,
405        parameters: &[f64],
406        blocks: &PBlocks,
407        obs: &'obs PObs,
408        out: &mut [f64],
409    ) -> Result<(), ModelError>
410    where
411        PBlocks: GamlssBlocks<F>,
412        PObs: ObservationView<'obs, Observation = F::Observation<'obs>> + 'obs,
413    {
414        self.prediction_view(blocks)?
415            .rosenblatt_values_into(parameters, obs, out)
416    }
417}
418
419/// Diagnostics extension for a validated core [`PredictionView`].
420pub trait PredictionDiagnosticsExt<F, PBlocks>
421where
422    F: for<'row> Family<Observation<'row> = f64>,
423    PBlocks: GamlssBlocks<F>,
424{
425    /// Adds validated prediction observations to this prediction view.
426    ///
427    /// # Errors
428    ///
429    /// Returns [`ModelError`] if `obs` has the wrong length or invalid
430    /// observation/weight values.
431    fn with_observations<'obs, PObs>(
432        &self,
433        obs: &'obs PObs,
434    ) -> Result<PredictionDiagnosticsView<'_, 'obs, F, PBlocks, PObs>, ModelError>
435    where
436        PObs: ObservationView<'obs, Observation = f64> + 'obs;
437}
438
439impl<F, PBlocks> PredictionDiagnosticsExt<F, PBlocks> for PredictionView<'_, F, PBlocks>
440where
441    F: for<'row> Family<Observation<'row> = f64>,
442    PBlocks: GamlssBlocks<F>,
443{
444    fn with_observations<'obs, PObs>(
445        &self,
446        obs: &'obs PObs,
447    ) -> Result<PredictionDiagnosticsView<'_, 'obs, F, PBlocks, PObs>, ModelError>
448    where
449        PObs: ObservationView<'obs, Observation = f64> + 'obs,
450    {
451        PredictionDiagnosticsView::new(self, obs)
452    }
453}
454
455/// CDF-based diagnostics for fitted GAMLSS models.
456pub trait CdfDiagnosticsExt<F, Blocks>
457where
458    F: HasCdf + for<'row> Family<Observation<'row> = f64>,
459    Blocks: GamlssBlocks<F>,
460{
461    /// Returns probability integral transform values for training rows.
462    ///
463    /// The returned vector has one value per training observation, in row
464    /// order. Invalid observation or parameter domains are represented by the
465    /// family CDF result, usually `NaN`, rather than an additional diagnostics
466    /// error.
467    ///
468    /// # Errors
469    ///
470    /// Returns [`ModelError`] if `parameters` has the wrong length.
471    fn pit_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>;
472
473    /// Writes PIT values for training rows into an existing output slice.
474    ///
475    /// # Errors
476    ///
477    /// Returns [`ModelError`] if `parameters` or `out` have the wrong length.
478    fn pit_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError>;
479
480    /// Returns PIT values for supplied compatible prediction blocks and observations.
481    ///
482    /// # Errors
483    ///
484    /// Returns [`ModelError`] if parameters, prediction blocks, or observations
485    /// are incompatible with the fitted model.
486    fn pit_values_with_blocks<'obs, PBlocks, PObs>(
487        &self,
488        parameters: &[f64],
489        blocks: &PBlocks,
490        obs: &'obs PObs,
491    ) -> Result<Vec<f64>, ModelError>
492    where
493        PBlocks: GamlssBlocks<F>,
494        PObs: ObservationView<'obs, Observation = f64> + 'obs;
495
496    /// Writes PIT values for supplied prediction rows into an existing output slice.
497    ///
498    /// # Errors
499    ///
500    /// Returns [`ModelError`] if parameters, prediction blocks, observations,
501    /// or `out` are incompatible with the fitted model.
502    fn pit_values_with_blocks_into<'obs, PBlocks, PObs>(
503        &self,
504        parameters: &[f64],
505        blocks: &PBlocks,
506        obs: &'obs PObs,
507        out: &mut [f64],
508    ) -> Result<(), ModelError>
509    where
510        PBlocks: GamlssBlocks<F>,
511        PObs: ObservationView<'obs, Observation = f64> + 'obs;
512
513    /// Returns normalized quantile residuals for training rows.
514    ///
515    /// For continuous distributions this is `Phi^-1(F(y_i; theta_i))`, where
516    /// `Phi^-1` is the inverse standard-normal CDF and `F` is the family CDF.
517    /// Non-finite and out-of-range PIT values propagate as `NaN`; PIT values at
518    /// unit interval boundaries map to infinities.
519    ///
520    /// # Errors
521    ///
522    /// Returns [`ModelError`] if `parameters` has the wrong length.
523    fn quantile_residuals(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError> {
524        self.pit_values(parameters).map(normalize_pit_values)
525    }
526
527    /// Returns normalized quantile residuals for supplied prediction rows.
528    ///
529    /// # Errors
530    ///
531    /// Returns [`ModelError`] if parameters, prediction blocks, or observations
532    /// are incompatible with the fitted model.
533    fn quantile_residuals_with_blocks<'obs, PBlocks, PObs>(
534        &self,
535        parameters: &[f64],
536        blocks: &PBlocks,
537        obs: &'obs PObs,
538    ) -> Result<Vec<f64>, ModelError>
539    where
540        PBlocks: GamlssBlocks<F>,
541        PObs: ObservationView<'obs, Observation = f64> + 'obs,
542    {
543        self.pit_values_with_blocks(parameters, blocks, obs)
544            .map(normalize_pit_values)
545    }
546}
547
548impl<F, Blocks, Obs> CdfDiagnosticsExt<F, Blocks> for Gamlss<F, Blocks, Obs>
549where
550    F: HasCdf + for<'row> Family<Observation<'row> = f64>,
551    Blocks: GamlssBlocks<F>,
552    for<'row> Obs: ObservationView<'row, Observation = f64>,
553{
554    fn pit_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError> {
555        let mut out = vec![0.0; self.nobs()];
556        self.pit_values_into(parameters, &mut out)?;
557        Ok(out)
558    }
559
560    fn pit_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError> {
561        diagnostic_values_into(self, parameters, out, |family, observation, theta| {
562            family.cdf(observation, theta)
563        })
564    }
565
566    fn pit_values_with_blocks<'obs, PBlocks, PObs>(
567        &self,
568        parameters: &[f64],
569        blocks: &PBlocks,
570        obs: &'obs PObs,
571    ) -> Result<Vec<f64>, ModelError>
572    where
573        PBlocks: GamlssBlocks<F>,
574        PObs: ObservationView<'obs, Observation = f64> + 'obs,
575    {
576        let prediction = self.prediction_view(blocks)?;
577        let diagnostics = prediction.with_observations(obs)?;
578        let mut out = vec![0.0; diagnostics.nrows()];
579        diagnostics.pit_values_into(parameters, &mut out)?;
580        Ok(out)
581    }
582
583    fn pit_values_with_blocks_into<'obs, PBlocks, PObs>(
584        &self,
585        parameters: &[f64],
586        blocks: &PBlocks,
587        obs: &'obs PObs,
588        out: &mut [f64],
589    ) -> Result<(), ModelError>
590    where
591        PBlocks: GamlssBlocks<F>,
592        PObs: ObservationView<'obs, Observation = f64> + 'obs,
593    {
594        let prediction = self.prediction_view(blocks)?;
595        prediction
596            .with_observations(obs)?
597            .pit_values_into(parameters, out)
598    }
599}
600
601/// CRPS-based diagnostics for fitted GAMLSS models.
602pub trait CrpsDiagnosticsExt<F, Blocks>
603where
604    F: HasCrps + for<'row> Family<Observation<'row> = f64>,
605    Blocks: GamlssBlocks<F>,
606{
607    /// Returns CRPS values for training rows.
608    ///
609    /// The returned vector has one value per training observation, in row
610    /// order. Invalid observation or parameter domains are represented by the
611    /// family CRPS result, usually `NaN`.
612    ///
613    /// # Errors
614    ///
615    /// Returns [`ModelError`] if `parameters` has the wrong length.
616    fn crps_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError>;
617
618    /// Writes CRPS values for training rows into an existing output slice.
619    ///
620    /// # Errors
621    ///
622    /// Returns [`ModelError`] if `parameters` or `out` have the wrong length.
623    fn crps_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError>;
624
625    /// Returns CRPS values for supplied compatible prediction blocks and observations.
626    ///
627    /// # Errors
628    ///
629    /// Returns [`ModelError`] if parameters, prediction blocks, or observations
630    /// are incompatible with the fitted model.
631    fn crps_values_with_blocks<'obs, PBlocks, PObs>(
632        &self,
633        parameters: &[f64],
634        blocks: &PBlocks,
635        obs: &'obs PObs,
636    ) -> Result<Vec<f64>, ModelError>
637    where
638        PBlocks: GamlssBlocks<F>,
639        PObs: ObservationView<'obs, Observation = f64> + 'obs;
640
641    /// Writes CRPS values for supplied prediction rows into an existing output slice.
642    ///
643    /// # Errors
644    ///
645    /// Returns [`ModelError`] if parameters, prediction blocks, observations,
646    /// or `out` are incompatible with the fitted model.
647    fn crps_values_with_blocks_into<'obs, PBlocks, PObs>(
648        &self,
649        parameters: &[f64],
650        blocks: &PBlocks,
651        obs: &'obs PObs,
652        out: &mut [f64],
653    ) -> Result<(), ModelError>
654    where
655        PBlocks: GamlssBlocks<F>,
656        PObs: ObservationView<'obs, Observation = f64> + 'obs;
657
658    /// Returns the arithmetic mean of [`Self::crps_values`].
659    ///
660    /// # Errors
661    ///
662    /// Returns [`ModelError`] if `parameters` has the wrong length.
663    #[allow(clippy::cast_precision_loss)]
664    fn mean_crps(&self, parameters: &[f64]) -> Result<f64, ModelError> {
665        let values = self.crps_values(parameters)?;
666        Ok(values.iter().sum::<f64>() / values.len() as f64)
667    }
668
669    /// Returns the observation-weighted mean CRPS for training rows.
670    ///
671    /// If all observation weights are zero, returns `NaN`.
672    ///
673    /// # Errors
674    ///
675    /// Returns [`ModelError`] if `parameters` has the wrong length.
676    fn weighted_mean_crps(&self, parameters: &[f64]) -> Result<f64, ModelError>;
677}
678
679impl<F, Blocks, Obs> CrpsDiagnosticsExt<F, Blocks> for Gamlss<F, Blocks, Obs>
680where
681    F: HasCrps + for<'row> Family<Observation<'row> = f64>,
682    Blocks: GamlssBlocks<F>,
683    for<'row> Obs: ObservationView<'row, Observation = f64>,
684{
685    fn crps_values(&self, parameters: &[f64]) -> Result<Vec<f64>, ModelError> {
686        let mut out = vec![0.0; self.nobs()];
687        self.crps_values_into(parameters, &mut out)?;
688        Ok(out)
689    }
690
691    fn crps_values_into(&self, parameters: &[f64], out: &mut [f64]) -> Result<(), ModelError> {
692        diagnostic_values_into(self, parameters, out, |family, observation, theta| {
693            family.crps(observation, theta)
694        })
695    }
696
697    fn crps_values_with_blocks<'obs, PBlocks, PObs>(
698        &self,
699        parameters: &[f64],
700        blocks: &PBlocks,
701        obs: &'obs PObs,
702    ) -> Result<Vec<f64>, ModelError>
703    where
704        PBlocks: GamlssBlocks<F>,
705        PObs: ObservationView<'obs, Observation = f64> + 'obs,
706    {
707        let prediction = self.prediction_view(blocks)?;
708        let diagnostics = prediction.with_observations(obs)?;
709        let mut out = vec![0.0; diagnostics.nrows()];
710        diagnostics.crps_values_into(parameters, &mut out)?;
711        Ok(out)
712    }
713
714    fn crps_values_with_blocks_into<'obs, PBlocks, PObs>(
715        &self,
716        parameters: &[f64],
717        blocks: &PBlocks,
718        obs: &'obs PObs,
719        out: &mut [f64],
720    ) -> Result<(), ModelError>
721    where
722        PBlocks: GamlssBlocks<F>,
723        PObs: ObservationView<'obs, Observation = f64> + 'obs,
724    {
725        let prediction = self.prediction_view(blocks)?;
726        prediction
727            .with_observations(obs)?
728            .crps_values_into(parameters, out)
729    }
730
731    fn weighted_mean_crps(&self, parameters: &[f64]) -> Result<f64, ModelError> {
732        let family = self.family();
733        let obs = self.obs();
734        let mut weighted_sum = 0.0;
735        let mut weight_sum = 0.0;
736
737        self.for_each_theta(parameters, |row, theta| {
738            let weight = obs.weight_at(row);
739            if weight == 0.0 {
740                return;
741            }
742
743            let value = family.crps(obs.observation_at(row), &theta);
744            weighted_sum = weight.mul_add(value, weighted_sum);
745            weight_sum += weight;
746        })?;
747
748        Ok(weighted_sum / weight_sum)
749    }
750}
751
752fn diagnostic_values_into<F, Blocks, Obs>(
753    model: &Gamlss<F, Blocks, Obs>,
754    parameters: &[f64],
755    out: &mut [f64],
756    mut evaluate: impl FnMut(&F, f64, &F::Theta) -> f64,
757) -> Result<(), ModelError>
758where
759    F: for<'row> Family<Observation<'row> = f64>,
760    Blocks: GamlssBlocks<F>,
761    for<'row> Obs: ObservationView<'row, Observation = f64>,
762{
763    validate_output_len(model.nobs(), out.len())?;
764    let family = model.family();
765    let obs = model.obs();
766    model.for_each_theta(parameters, |row, theta| {
767        out[row] = evaluate(family, obs.observation_at(row), &theta);
768    })
769}
770
771fn validate_prediction_observations<'obs, Obs>(
772    expected: usize,
773    obs: &'obs Obs,
774) -> Result<(), ModelError>
775where
776    Obs: ObservationView<'obs, Observation = f64> + 'obs,
777{
778    let actual = obs.len();
779    if actual != expected {
780        return Err(ModelError::ResponseLength { expected, actual });
781    }
782    obs.validate()
783}
784
785const fn validate_output_len(expected: usize, actual: usize) -> Result<(), ModelError> {
786    if actual == expected {
787        Ok(())
788    } else {
789        Err(ModelError::ResponseLength { expected, actual })
790    }
791}
792
793fn checked_rosenblatt_len(nrows: usize, dimension: usize) -> Result<usize, ModelError> {
794    nrows
795        .checked_mul(dimension)
796        .ok_or(ModelError::ArithmeticOverflow {
797            context: "row-major Rosenblatt diagnostics length",
798        })
799}
800
801fn normalize_pit_values(mut values: Vec<f64>) -> Vec<f64> {
802    for value in &mut values {
803        *value = unit_normal_quantile(*value);
804    }
805    values
806}
807
808#[cfg(test)]
809mod tests {
810    use approx::assert_relative_eq;
811    use gamlss_core::{
812        CholeskyScale, DenseDesign, Gamlss, Identity, LinearPredictorBlock, Log,
813        LowerTriangularParameterBlock, ModelError, Mu, NoPenalty, ParameterBlock, ParameterBlocks,
814        Sigma, VectorParameterBlock,
815    };
816    use gamlss_family::{MvNormalCholeskyDefault, Normal};
817
818    use super::{
819        CdfDiagnosticsExt, CrpsDiagnosticsExt, PredictionDiagnosticsExt,
820        PredictionRosenblattDiagnosticsExt, RosenblattDiagnosticsExt, normalize_pit_values,
821    };
822
823    type TestModel<'a> = Gamlss<
824        Normal<Identity, Log>,
825        ParameterBlocks<(
826            ParameterBlock<Mu, LinearPredictorBlock<DenseDesign>, NoPenalty>,
827            ParameterBlock<Sigma, LinearPredictorBlock<DenseDesign>, NoPenalty>,
828        )>,
829        &'a [f64],
830    >;
831
832    type WeightedTestModel<'a> = Gamlss<
833        Normal<Identity, Log>,
834        ParameterBlocks<(
835            ParameterBlock<Mu, LinearPredictorBlock<DenseDesign>, NoPenalty>,
836            ParameterBlock<Sigma, LinearPredictorBlock<DenseDesign>, NoPenalty>,
837        )>,
838        (&'a [f64], &'a [f64]),
839    >;
840
841    fn normal_intercept_model(y: &[f64]) -> TestModel<'_> {
842        let blocks = ParameterBlocks::new((
843            ParameterBlock::<Mu, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
844            ParameterBlock::<Sigma, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
845        ));
846
847        Gamlss::try_new(Normal::<Identity, Log>::new(), blocks, y).expect("valid normal model")
848    }
849
850    fn weighted_normal_intercept_model<'a>(
851        y: &'a [f64],
852        weights: &'a [f64],
853    ) -> WeightedTestModel<'a> {
854        let blocks = ParameterBlocks::new((
855            ParameterBlock::<Mu, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
856            ParameterBlock::<Sigma, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
857        ));
858
859        Gamlss::try_new_weighted(Normal::<Identity, Log>::new(), blocks, y, weights)
860            .expect("valid weighted normal model")
861    }
862
863    #[test]
864    fn pit_values_use_training_observations_and_fitted_parameters() {
865        let y = [0.0, 1.0, -1.0];
866        let model = normal_intercept_model(&y);
867
868        let pit = model.pit_values(&[0.0, 0.0]).expect("valid parameters");
869        let mut pit_into = vec![f64::NAN; y.len()];
870        model
871            .pit_values_into(&[0.0, 0.0], &mut pit_into)
872            .expect("valid parameters");
873
874        assert_relative_eq!(pit[0], 0.5, epsilon = 1.0e-7);
875        assert_relative_eq!(pit[1], 0.841_344_746, epsilon = 1.0e-7);
876        assert_relative_eq!(pit[2], 0.158_655_254, epsilon = 1.0e-7);
877        assert_eq!(pit_into, pit);
878    }
879
880    #[test]
881    fn quantile_residuals_transform_pit_values_to_standard_normal_scale() {
882        let y = [-1.0, 0.0, 1.0];
883        let model = normal_intercept_model(&y);
884
885        let residuals = model
886            .quantile_residuals(&[0.0, 0.0])
887            .expect("valid parameters");
888
889        assert_relative_eq!(residuals[0], -1.0, epsilon = 1.0e-6);
890        assert_relative_eq!(residuals[1], 0.0, epsilon = 1.0e-6);
891        assert_relative_eq!(residuals[2], 1.0, epsilon = 1.0e-6);
892    }
893
894    #[test]
895    fn quantile_residuals_map_invalid_and_boundary_pit_values() {
896        let residuals = normalize_pit_values(vec![f64::NAN, -0.1, 0.0, 1.0, 1.1]);
897
898        assert!(residuals[0].is_nan());
899        assert!(residuals[1].is_nan());
900        assert!(residuals[2].is_infinite());
901        assert!(residuals[2].is_sign_negative());
902        assert!(residuals[3].is_infinite());
903        assert!(residuals[3].is_sign_positive());
904        assert!(residuals[4].is_nan());
905    }
906
907    #[test]
908    fn pit_values_reject_wrong_parameter_length() {
909        let y = [0.0];
910        let model = normal_intercept_model(&y);
911
912        assert_eq!(
913            model.pit_values(&[]).unwrap_err(),
914            ModelError::BetaLength {
915                expected: 2,
916                actual: 0
917            }
918        );
919        assert_eq!(
920            model.pit_values_into(&[0.0, 0.0], &mut []).unwrap_err(),
921            ModelError::ResponseLength {
922                expected: 1,
923                actual: 0
924            }
925        );
926    }
927
928    #[test]
929    fn crps_values_use_training_observations_and_fitted_parameters() {
930        let y = [0.0, 1.0];
931        let model = normal_intercept_model(&y);
932
933        let crps = model.crps_values(&[0.0, 0.0]).expect("valid parameters");
934        let mut crps_into = vec![f64::NAN; y.len()];
935        model
936            .crps_values_into(&[0.0, 0.0], &mut crps_into)
937            .expect("valid parameters");
938
939        assert_relative_eq!(crps[0], 0.233_694_977_255_109_13, epsilon = 1.0e-12);
940        assert_relative_eq!(crps[1], 0.602_441_357_627_616_5, epsilon = 1.0e-12);
941        assert_eq!(crps_into, crps);
942        assert_relative_eq!(
943            model.mean_crps(&[0.0, 0.0]).expect("valid parameters"),
944            crps[0].midpoint(crps[1]),
945            epsilon = 1.0e-12
946        );
947    }
948
949    #[test]
950    fn diagnostics_with_blocks_match_training_helpers_for_training_blocks() {
951        let y = [-1.0, 0.0, 1.0];
952        let model = normal_intercept_model(&y);
953        let parameters = [0.0, 0.0];
954        let obs = &y[..];
955        let prediction = model.prediction_view(model.blocks()).unwrap();
956        let diagnostics = prediction.with_observations(&obs).unwrap();
957
958        assert_eq!(
959            model
960                .pit_values_with_blocks(&parameters, model.blocks(), &obs)
961                .unwrap(),
962            model.pit_values(&parameters).unwrap()
963        );
964        assert_eq!(
965            diagnostics.pit_values(&parameters).unwrap(),
966            model.pit_values(&parameters).unwrap()
967        );
968        assert_eq!(
969            model
970                .quantile_residuals_with_blocks(&parameters, model.blocks(), &obs)
971                .unwrap(),
972            model.quantile_residuals(&parameters).unwrap()
973        );
974        assert_eq!(
975            diagnostics.quantile_residuals(&parameters).unwrap(),
976            model.quantile_residuals(&parameters).unwrap()
977        );
978        assert_eq!(
979            model
980                .crps_values_with_blocks(&parameters, model.blocks(), &obs)
981                .unwrap(),
982            model.crps_values(&parameters).unwrap()
983        );
984        assert_eq!(
985            diagnostics.crps_values(&parameters).unwrap(),
986            model.crps_values(&parameters).unwrap()
987        );
988
989        let mut pit = vec![f64::NAN; diagnostics.nrows()];
990        diagnostics.pit_values_into(&parameters, &mut pit).unwrap();
991        assert_eq!(pit, model.pit_values(&parameters).unwrap());
992
993        let mut crps = vec![f64::NAN; diagnostics.nrows()];
994        diagnostics
995            .crps_values_into(&parameters, &mut crps)
996            .unwrap();
997        assert_eq!(crps, model.crps_values(&parameters).unwrap());
998    }
999
1000    #[test]
1001    fn diagnostics_with_blocks_reject_observation_row_mismatch() {
1002        let y = [0.0, 1.0];
1003        let model = normal_intercept_model(&y);
1004        let obs = &[0.0][..];
1005
1006        assert_eq!(
1007            model
1008                .pit_values_with_blocks(&[0.0, 0.0], model.blocks(), &obs)
1009                .unwrap_err(),
1010            ModelError::ResponseLength {
1011                expected: 2,
1012                actual: 1
1013            }
1014        );
1015    }
1016
1017    #[test]
1018    fn weighted_mean_crps_uses_observation_weights() {
1019        let y = [0.0, 1.0];
1020        let weights = [0.0, 2.0];
1021        let model = weighted_normal_intercept_model(&y, &weights);
1022        let crps = model.crps_values(&[0.0, 0.0]).unwrap();
1023
1024        assert_relative_eq!(
1025            model.weighted_mean_crps(&[0.0, 0.0]).unwrap(),
1026            crps[1],
1027            epsilon = 1.0e-12
1028        );
1029    }
1030
1031    #[test]
1032    fn weighted_mean_crps_skips_zero_weighted_observations_before_crps() {
1033        let y = [f64::NAN, 1.0];
1034        let weights = [0.0, 2.0];
1035        let model = weighted_normal_intercept_model(&y, &weights);
1036
1037        assert_relative_eq!(
1038            model.weighted_mean_crps(&[0.0, 0.0]).unwrap(),
1039            0.602_441_357_627_616_5,
1040            epsilon = 1.0e-12
1041        );
1042    }
1043
1044    #[test]
1045    fn weighted_mean_crps_returns_nan_when_all_weights_are_zero() {
1046        let y = [0.0, 1.0];
1047        let weights = [0.0, 0.0];
1048        let model = weighted_normal_intercept_model(&y, &weights);
1049
1050        assert!(model.weighted_mean_crps(&[0.0, 0.0]).unwrap().is_nan());
1051    }
1052
1053    #[test]
1054    fn crps_values_reject_wrong_parameter_length() {
1055        let y = [0.0];
1056        let model = normal_intercept_model(&y);
1057
1058        assert_eq!(
1059            model.crps_values(&[]).unwrap_err(),
1060            ModelError::BetaLength {
1061                expected: 2,
1062                actual: 0
1063            }
1064        );
1065        assert_eq!(
1066            model.crps_values_into(&[0.0, 0.0], &mut []).unwrap_err(),
1067            ModelError::ResponseLength {
1068                expected: 1,
1069                actual: 0
1070            }
1071        );
1072    }
1073
1074    #[test]
1075    fn rosenblatt_diagnostics_use_row_major_coordinate_order() {
1076        let y = [[0.0, 0.0], [1.0, 1.5]];
1077        let n = y.len();
1078        let mu = VectorParameterBlock::<Mu, 2, _, _>::new(
1079            [
1080                LinearPredictorBlock::new(DenseDesign::intercept(n)),
1081                LinearPredictorBlock::new(DenseDesign::intercept(n)),
1082            ],
1083            NoPenalty,
1084            0,
1085        );
1086        let cholesky = LowerTriangularParameterBlock::<CholeskyScale, 2, _, _>::new(
1087            vec![
1088                LinearPredictorBlock::new(DenseDesign::intercept(n)),
1089                LinearPredictorBlock::new(DenseDesign::intercept(n)),
1090                LinearPredictorBlock::new(DenseDesign::intercept(n)),
1091            ],
1092            NoPenalty,
1093            0,
1094        );
1095        let blocks = ParameterBlocks::new((mu, cholesky));
1096        let model = Gamlss::try_new_with_observations(
1097            MvNormalCholeskyDefault::<2>::new(),
1098            blocks,
1099            y.as_slice(),
1100        )
1101        .unwrap();
1102        let parameters = [0.0, 0.0, 0.0, 0.5, 0.0];
1103
1104        let values = model.rosenblatt_values(&parameters).unwrap();
1105        assert_eq!(values.len(), 4);
1106        assert_relative_eq!(values[0], 0.5, epsilon = 1.0e-12);
1107        assert_relative_eq!(values[1], 0.5, epsilon = 1.0e-12);
1108        assert_relative_eq!(values[2], 0.841_344_746, epsilon = 1.0e-9);
1109        assert_relative_eq!(values[3], 0.841_344_746, epsilon = 1.0e-9);
1110
1111        let prediction = model.prediction_view(model.blocks()).unwrap();
1112        assert_eq!(
1113            prediction
1114                .rosenblatt_values(&parameters, &y.as_slice())
1115                .unwrap(),
1116            values
1117        );
1118        assert_eq!(
1119            model
1120                .rosenblatt_values_with_blocks(&parameters, model.blocks(), &y.as_slice())
1121                .unwrap(),
1122            values
1123        );
1124        assert_eq!(
1125            model
1126                .rosenblatt_values_into(&parameters, &mut [0.0; 3])
1127                .unwrap_err(),
1128            ModelError::ResponseLength {
1129                expected: 4,
1130                actual: 3,
1131            }
1132        );
1133    }
1134
1135    #[test]
1136    fn diagnostics_prelude_exposes_extension_traits() {
1137        use crate::prelude::*;
1138
1139        let y = [0.0];
1140        let model = normal_intercept_model(&y);
1141
1142        assert_relative_eq!(
1143            model.pit_values(&[0.0, 0.0]).unwrap()[0],
1144            0.5,
1145            epsilon = 1.0e-7
1146        );
1147        assert_relative_eq!(
1148            model.quantile_residuals(&[0.0, 0.0]).unwrap()[0],
1149            0.0,
1150            epsilon = 1.0e-6
1151        );
1152        assert_relative_eq!(
1153            model.mean_crps(&[0.0, 0.0]).unwrap(),
1154            0.233_694_977_255_109_13,
1155            epsilon = 1.0e-12
1156        );
1157    }
1158}