diff --git a/docs/_ext/family_contracts.py b/docs/_ext/family_contracts.py index 680e159b..1f2b3d72 100644 --- a/docs/_ext/family_contracts.py +++ b/docs/_ext/family_contracts.py @@ -6,9 +6,18 @@ def parameterization_notes(name, backend): special = "" if backend == 'statistical' and name == 'bccg_lss': - special += "Natural columns are ``mu, sigma, nu`` with log/log/identity predictors. Mu is not generally the response mean or exact median. Positive responses require a Jacobian and a truncated-normal normalizer. At nu=0 the law is lognormal. Mean is infinite for -1<=nu<0; variance is NaN there and infinite for -2<=nu<-1. Finite moment quadrature has explicit numerical limits, including negative-power variance below sigma=sqrt(machine epsilon). At least three distinct positive-weight responses are required; this necessary guard does not establish estimability of arbitrary formulas.\n\n" + special += ( + "* **Parameters.** Natural columns ``mu, sigma, nu`` use log, log and identity links. Positive responses require a Jacobian and truncated-normal normalizer. At ``nu=0`` the law is lognormal.\n" + "* **Moments.** Compute the mean and median from the response law. The mean is infinite for ``-1 <= nu < 0``. Variance is ``NaN`` there and infinite for ``-2 <= nu < -1``. Finite quadrature has numerical limits, including negative-power variance below ``sigma=sqrt(machine epsilon)``.\n" + "* **Fitting.** Supply at least three distinct positive-weight responses. Formula estimability also depends on the fitted design.\n\n" + ) if backend == "statistical" and name == "beinf_lss": - special += "Four formula keys are ``mu, phi, pi0, pi1``. Natural columns are ``mu, phi, pi0, pi1, pi_interior``; raw columns are logit(mu), log(phi), log(pi0/pi_interior), log(pi1/pi_interior). The last two are coupled category log ratios, not independent probability logits. Components contain exactly four predictors; the interior probability depends on both atom predictors and has no separate term. Full covariance is retained for all five natural errors. R BEINF uses sigma=1/sqrt(1+phi), nu=pi0/pi_interior, tau=pi1/pi_interior. All components and distinct interior observations are required for fitting; neural fitting uses its normalized likelihood. The saved gamlss.dist 6.1.1 variance hook adds rather than subtracts squared mean; NAMpy uses the normalized mixture variance and records this discrepancy.\n\n" + special += ( + "* **Predictors.** Formula keys ``mu, phi, pi0, pi1`` map to ``logit(mu)``, ``log(phi)``, ``log(pi0/pi_interior)`` and ``log(pi1/pi_interior)``. The atom predictors are coupled category log ratios.\n" + "* **Natural output.** All five natural-parameter standard errors use the full covariance. The columns are ``mu, phi, pi0, pi1, pi_interior``. The fifth column depends on both atom predictors and has no separate additive term.\n" + "* **Fitting.** All components and distinct interior observations are required. Neural fitting uses its normalized likelihood.\n" + "* **R mapping.** R BEINF uses ``sigma=1/sqrt(1+phi)``, ``nu=pi0/pi_interior`` and ``tau=pi1/pi_interior``. NAMpy uses the normalized mixture variance. The saved gamlss.dist 6.1.1 variance hook adds the squared mean where that variance subtracts it.\n\n" + ) if backend == "statistical" and name == "zaga_lss": special += "Natural columns are ``mu, sigma, pi0`` with log/log/logit links. Mu is the positive Gamma mean, sigma its coefficient of variation, and pi0 the exact zero probability (gamlss.dist ZAGA calls it nu). The whole-response mean is (1-pi0)*mu. Log probability reports mass at zero and density elsewhere. Finite-logit fitting requires both components and distinct positive observations; exact zero/one atom probabilities are available only for probability queries. Neural ZAGA fitting uses its normalized likelihood.\n\n" if backend == "statistical" and name == "betabinomial_lss": @@ -149,9 +158,17 @@ def mathematical_contract(name, backend): reference = {"bccg_lss": "BCCG", "student_lss": "TF", "beta_lss": "BE", "nb_lss": "NBI", "lognormal_lss": "LOGNO", "weibull_lss": "WEI", "betabinomial_lss": "BB", "zaga_lss": "ZAGA", "beinf_lss": "BEINF"}[name] text += f"Distribution reference: `gamlss.dist::{reference} `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting.\n\n" if name == 'bccg_lss': - text += "Fixed smoothing and automatic joint REML with outer_newton, bfgs and efs are validated, including three smoothed predictors. Analytic likelihood derivatives through order four include the truncated-normal normalizer and the zero-power limit. Outer gradients/Hessians are checked with offsets and nonunit/zero weights; selected endpoints are compared to an independent derivative-free REML profile. Other method labels retain mgcv general-family coercion to REML, not separate ML/GCV/UBRE/NCV criteria. The optim route lacks family-defined null deviance scaling; magic and nlm.fd are also unavailable. Neural fitting, alternate links, censoring/truncation and deviance residuals remain unsupported. Generic conditional and approximate smoothing-uncertainty covariance transport are available; simulation/refit centile bands are not. Tight stopping rules may report nonconvergence at a float64 plateau; such fits remain ineligible for family ranking. This is distinct from mgcv's existing censored bcg likelihood.\n\n" + text += ( + "* **Fit.** Fixed smoothing and joint REML with ``outer_newton``, ``bfgs`` or ``efs`` are validated, including fits with three smoothed predictors. General-family method aliases resolve to REML. ``optim``, ``magic`` and ``nlm.fd`` are unavailable.\n" + "* **Numerical checks.** Derivatives through order four include the normalizer and zero-power limit. Outer checks cover offsets and nonunit or zero weights. An independent derivative-free REML profile checks selected endpoints.\n" + "* **Inference and limits.** Conditional and approximate smoothing-adjusted covariance are available. Simulation or refit centile bands, neural fitting, alternate links, censoring, truncation and deviance residuals are outside this route. Use the separate censored ``bcg`` likelihood for its own supported scope. Fits that stop at a nonconverged float64 plateau are ineligible for family ranking.\n\n" + ) if name in {"lognormal_lss", "weibull_lss", "betabinomial_lss", "zaga_lss", "beinf_lss"}: - text += "Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force.\n\n" + text += ( + "* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported.\n" + "* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable.\n" + "* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations.\n\n" + ) elif backend == "statistical": text += "References: `mgcv distribution-family definitions `_. NAMpy fitting support is listed below.\n\n" if name in {"gammals", "shash", "bcg"}: diff --git a/docs/_ext/feature_reference.py b/docs/_ext/feature_reference.py index 944b7b4f..8319c765 100644 --- a/docs/_ext/feature_reference.py +++ b/docs/_ext/feature_reference.py @@ -387,7 +387,12 @@ def generate_smooths(root): ) text += ( heading("Outputs", "-") - + "The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately.\n\n" + + table(["Operation", "Result"], [ + ("Formula term", "Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic."), + ("``predict(type='terms')``", "Floating array with ``n`` rows and one column per retained term for a scalar predictor."), + ("``lpmatrix``", "Full floating model design of shape ``(n, p)``, including the other terms."), + ]) + + "The scalar Gaussian examples produce response predictions of shape ``(n,)``.\n\n" ) if name in {"te", "ti", "t2"}: text += "Before identifiability constraints, the tensor has the product of the marginal basis dimensions, not a single k columns. Marginal/term constraints and retained t2 blocks determine the final coefficient count.\n\n" @@ -396,7 +401,12 @@ def generate_smooths(root): ) runtime += ( heading("Outputs", "-") - + "``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError.\n\n" + + table(["Operation", "Result"], [ + ("``fit(X, feature_names)``", "Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term."), + ("``transform_new(X_new)``", "Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution."), + ("``penalties``", "List of floating penalty matrices, each of shape ``(p_term, p_term)``."), + ]) + + "Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``.\n\n" + module_notes(cls) ) default_basis = inspect.signature(cls).parameters.get("basis") @@ -1592,7 +1602,15 @@ def generate_neural_extensions(root): ) text += heading("Returns and fitted outputs", "-") if name == "NeuralEnsemble": - text += "Construction returns an unfitted ensemble; ``fit`` accepts data, explicit validation rows, offsets and weights, returns self and exposes ``estimators_``. Regression predict returns the mean member response, shaped like a member's predictions. Classification predict_proba averages probabilities in ``classes_`` order, and predict returns the most probable class. score returns R² or accuracy, respectively. ``predict_components`` returns ``AdditivePrediction`` containing the mean link-scale contributions. ``predict_component_uncertainty`` returns ``EnsembleAdditivePrediction`` containing mean components and between-member variation; missing selected terms contribute zero for that member. Variation across members measures training/selection variability and is not automatically a calibrated confidence interval.\n\n" + text += table(["Operation", "Result"], [ + ("``fit``", "Fits the members and exposes them in ``estimators_``. Accepts explicit validation data, offsets and weights, and returns the ensemble."), + ("``predict``", "Mean member response for regression or most probable class for classification."), + ("``predict_proba``", "Mean member probabilities in ``classes_`` order."), + ("``predict_components``", "Mean link-scale contributions as ``AdditivePrediction``."), + ("``predict_component_uncertainty``", "Mean contributions and between-member variation as ``EnsembleAdditivePrediction``. Missing selected terms contribute zero for that member."), + ("``score``", "R² for regression and accuracy for classification."), + ]) + text += "Between-member variation describes training or selection variability. Calibrated confidence intervals require a separate inference method.\n\n" elif name in {"NeuralEstimatorFamily", "estimator_family"}: text += "Returns a NeuralEstimatorFamily record containing task-specific estimator classes or None for unavailable tasks. This record contains no fitted predictions. Instantiate one of its available classes and call fit to obtain a model.\n\n" else: diff --git a/docs/_ext/public_reference.py b/docs/_ext/public_reference.py index b44e11ac..9977adef 100644 --- a/docs/_ext/public_reference.py +++ b/docs/_ext/public_reference.py @@ -372,7 +372,12 @@ def estimator_text(cls, spec, objective): elif objective == "classification": shape = "``predict`` returns class labels; ``predict_proba`` returns ``(n_samples, n_classes)`` probabilities in ``classes_`` order. Component extraction describes all actual logits; probabilities are queried separately. ``score`` returns mean classification accuracy (higher is better), with optional sample weights." else: - shape = "``predict`` returns the family-defined point prediction; ``predict_parameters`` returns natural distribution parameters and ``predict_link`` returns additive predictors. Quantile-loss families instead return the explicitly fitted quantile vector and do not provide a full probability law or natural parameter matrix. For fixed scalar families, natural columns follow ``parameter_names_``. Categorical and ordinal outputs instead have one probability per class; multivariate families depend on configured dimension, and quantiles have one column per requested level. Raw width follows ``family_.param_count``. ``predict_point`` returns the family-defined point prediction. ``score`` returns negative mean family loss (higher is better); evaluation loss is lower-is-better." + shape = ( + "* **Output columns.** Natural parameters follow ``parameter_names_``. Categorical and ordinal responses have one probability per class. " + "Multivariate response width follows the configured dimension. Raw predictor width is ``family_.param_count``.\n" + "* **Quantile loss.** ``predict`` returns one column per fitted quantile level. Probability-law and natural-parameter methods require a distributional family.\n" + "* **Scoring.** ``score`` is negative mean family loss, so higher is better. Lower evaluation loss is better.\n" + ) if spec.name == "nodegam": lines.append( "NODE-GAM contributions require an interpretable selector state. The short runnable example explicitly completes annealing (anneal_steps=1) in a single-layer unary model. Validate additive reconstruction before interpreting contributions from partially trained or more complex selector configurations.\n" @@ -490,7 +495,11 @@ def survival_estimator_text(cls, *, neural): text = ":ref:`Survival workflow and limitations `.\n\n" text += "Constructor parameters\n~~~~~~~~~~~~~~~~~~~~~~\n\n" + table(["Parameter", "Default", "Meaning"], rows) text += "Full shared fit contract\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n" - text += "``fit(X, SurvivalTarget, sample_weight=..., offset=...)`` keeps event status separate from weights. Piecewise offsets are known scalar log-rate offsets per subject; parametric offsets have shape (n_subjects,2), one per parameter predictor. New prediction subjects need explicit offsets if the fit used them. Targets contain time, event (0/1), optional entry and unique subject IDs. Entry conditions the likelihood. Piecewise models also accept LongitudinalSurvivalTarget with contiguous start/stop records, one terminal event, and constant per-subject case weights across records. score divides by total subject weight. Shared predict_trajectory evaluates explicitly supplied future covariate paths; ordinary predict_distribution keeps its constant-covariate interpretation.\n\n" + text += ( + "* **Targets and weights.** ``fit(X, SurvivalTarget, sample_weight=..., offset=...)`` takes time, event (0/1), optional entry, and unique subject IDs. Entry conditions the likelihood. ``score`` normalizes by total subject weight.\n" + "* **Offsets.** Supply one log-rate offset per subject for piecewise fits or an ``(n_subjects, 2)`` array for parametric fits. Supply new offsets at prediction if the fit used them.\n" + "* **Longitudinal records.** Piecewise fits accept contiguous start/stop histories with one terminal event and constant weight within a subject. Use ``predict_trajectory`` for explicit future paths and ``predict_distribution`` for constant covariates.\n\n" + ) if neural: text += "Static fits can split subjects automatically; longitudinal fits require explicit disjoint whole-subject X_val/y_val. No automatic record split or longitudinal warm start is supported. Preprocessing fits only training records; likelihood normalization uses independent subjects, not record counts. Piecewise predictor/component arrays are (n_subjects,n_intervals); Weibull/lognormal arrays are (n_subjects,2). Weibull links are log scale/log shape; lognormal links are location/log SD. Native/fixed routes, custom samplers, distributed training, and supervised preprocessing are unsupported.\n\n" else: @@ -505,16 +514,50 @@ def survival_estimator_text(cls, *, neural): (family.name, ", ".join(sorted(family.supported_smoothing_optimizers))) for family in (CensoredWeibull, CensoredLogNormal) ]) + text += ( + "**Smooth baseline.** ``baseline='smooth'`` fits a right-endpoint time spline with piecewise-constant integration. " + "Use at least ``k`` distinct endpoints and positive exposure in each interval. Coupled smooth intervals can have zero events if the fit converges. " + "Use ``temporal_formula`` for identified ``ti(survival_time, covariate, ...)`` interactions.\n\n" + ) text += "Predictions and supported operations\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n" - text += "``predict`` and ``predict_survival`` require explicit times and return (n_subjects,n_times). ``predict_link`` returns interval log hazards or latent-parameter predictors; ``predict_hazard`` returns rates, never exposure-adjusted Poisson means. ``predict_distribution`` returns SurvivalPrediction supporting log survival, cumulative hazard, quantiles, median and RMST. Piecewise RMST is exact; Weibull/lognormal RMST uses controlled adaptive quadrature. RMST supports scalar or subject-specific conditioning landmarks. Pre-landmark curve cells are NaN. Unreached piecewise quantiles are NaN; piecewise tails beyond cuts are unavailable. Parametric tails are model-based extrapolation.\n\n" - if not neural: - text += "baseline='smooth' uses the existing penalized Poisson GAM with a right-endpoint time spline. Integration remains piecewise constant. At least k distinct interval endpoints and positive exposure in every interval are required; unlike independent interval intercepts, coupled smooth baselines can have zero events in an interval. Fitted endpoints must still converge. Neural models retain their existing interval-specific heads; matched spline-baseline smoothing is not supplied. temporal_formula accepts identified ti(survival_time, covariate, ...) terms with a smooth statistical baseline; exposure integration and neural interval-head semantics are unchanged.\n\n" - text += "Shared survival_residuals preserves entry conditioning and Cox-Snell censoring flags. survival_curve computes entry-aware KM/NA descriptive estimates. concordance_index requires an explicit risk direction. brier_score requires an explicit training CensoringDistribution; its result provides finite-grid integrated Brier errors. Longitudinal targets reduce outcomes and case weights to one per subject; predictions and risk values must follow subject_ids order and use explicitly supplied complete paths. IPCW and concordance currently reject delayed entry. These functions consume the shared predictions from either backend and do not alter estimator score semantics.\n\n" - text += "prepare_survival_effects evaluates reference predictors plus selected centered terms before survival transformation, retaining offsets, interval baselines, categorical/interaction coordinates and conditioning metadata. These contrasts do not form an additive decomposition of probabilities. prepare_survival_curve_interval supports statistical pointwise or finite-grid simultaneous joint coefficient inference with Bayesian or available smoothing-corrected covariance. Simultaneous curve coverage is joint across all valid subjects/times, on the log cumulative-hazard scale. prepare_survival_effect_interval uses paired reference-plus-term draws; simultaneous coverage includes all selected terms/subjects/times jointly on the survival-difference scale. Critical values use R type-8 quantiles of maximum standardized deviations. Single neural fits reject coefficient/effect intervals. combine_survival_predictions averages response-level survival and labels empirical between-fit ranges separately. No function infers replication or subject alignment.\n\n" - text += "prepare_survival_hazard_interval and prepare_survival_rmst_interval reuse joint draws for statistical pointwise or finite-grid simultaneous intervals. Hazard bands calibrate log hazard jointly across valid subjects/times; parametric time-zero limits remain unavailable. RMST integrates each draw from fixed landmarks to explicit restriction horizons, with exact piecewise or controlled parametric integration. Bounds respect remaining-lifetime support; simultaneous scope is all valid subjects/horizons, in time units. Earlier cells are NaN. Separate functional calls do not claim joint coverage across different quantities. Single neural fits reject hazard/RMST coefficient intervals.\n\n" - text += "bootstrap_survival performs ordinary uniform whole-subject pairs refits with fresh estimators/preprocessing on both engines. Its pointwise percentile intervals reuse shared survival/hazard/RMST operations and carry subject_bootstrap source metadata. Neural routes require fixed external validation data with disjoint explicit source IDs, reject warm starts/execution objects, and distinguish fixed-seed sampling uncertainty from combined independent-seed training/sampling variation. Failures are recorded or raised without replacement; intervals refuse failed attempts. Predictions remain on a fixed cohort; the source estimator is not refitted. For longitudinal targets resampling selects complete histories, with fresh occurrence IDs and retained source-subject maps. prediction_trajectory supplies fixed future paths; effects can prepare path-specific contrasts with fixed reference trajectories. Bootstrap, coefficient and between-fit sources are never relabeled as one another. Finite-grid simultaneous bootstrap bands reuse shared survival/hazard/RMST inference calculations. Paired effect contrasts are declared before refitting through effects, use a fixed reference cohort, and support pointwise percentiles or joint calibration over all selected terms/subjects/times. Coverage and uncertainty sources remain explicit; missing term layouts and degenerate draws disagreeing with the fitted estimate reject inference. BCa/nested-studentized/basic, continuous-time coverage and reference-population resampling remain unsupported.\n\n" - text += "Post-fit conformal lower event-time bounds are available through nampy.calibration on both backends. Conservative observed-time and administrative-cutoff/known-selection routes have different assumptions and labels; these do not calibrate entire survival curves. See /user_guide/calibration.\n\n" - text += "Unsupported routes\n~~~~~~~~~~~~~~~~~~\n\nCensored EFS/optim/magic/nlm.fd, separate censored ML/LAML/GCV/UBRE/NCV criteria, neural/longitudinal Cox (the separate CoxGAM supports static fixed and eligible automatic smoothing), parametric time-varying covariates, recurrent events, competing risks, left/interval censoring, zero-event saturated interval-factor boundary fits, delayed-entry IPCW/concordance, conditional censoring models, dynamic AUC, Uno concordance, randomized censor-aware PIT, continuous-time bands, single-fit neural coefficient/effect/hazard/RMST intervals and simultaneous inference from replicated fits remain unavailable. Survival coefficient simulation also rejects transformed coefficients and nonidentity/wider prediction-coordinate maps. Censored EFS has not passed the independent REML-profile endpoint gate. Parametric fitting requires two distinct positive-weight exact events. Neural survival retains gradient training only. Save/load uses the current trusted fitted-state artifact without migration shims.\n" + text += table(["Operation", "Result"], [ + ("``predict`` / ``predict_survival``", "Survival probabilities at explicit times, shaped ``(n_subjects, n_times)``."), + ("``predict_link``", "Interval log hazards or latent distribution parameter predictors."), + ("``predict_hazard``", "Event rates per unit time, before exposure adjustment."), + ("``predict_distribution``", "A ``SurvivalPrediction`` with log survival, cumulative hazard, quantiles, median and restricted mean survival time (RMST)."), + ("``predict_trajectory``", "Predictions along explicitly supplied future covariate paths for piecewise models."), + ]) + text += ( + "* **RMST and conditioning.** Piecewise integration is exact. Weibull and lognormal integration uses adaptive quadrature. " + "RMST accepts a common or subject-specific landmark. Pre-landmark curve cells are ``NaN``.\n" + "* **Tail behavior.** Piecewise predictions stop at the final cut and unreached quantiles are ``NaN``. " + "Weibull and lognormal tails extrapolate from the fitted distribution.\n\n" + "Diagnostics and evaluation\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n" + "* ``survival_residuals`` returns entry-conditioned Cox–Snell residuals with censoring flags.\n" + "* ``survival_curve`` estimates entry-aware Kaplan–Meier survival and Nelson–Aalen cumulative hazard.\n" + "* ``concordance_index`` requires an explicit risk direction. ``brier_score`` takes a censoring distribution fitted on training data " + "and can integrate errors over a finite grid. Both reject delayed entry.\n" + "* For longitudinal evaluation, use one outcome and case weight per subject and align predictions to ``subject_ids`` using complete paths.\n\n" + "Effects and uncertainty\n^^^^^^^^^^^^^^^^^^^^^^^\n\n" + "* **Effects.** ``prepare_survival_effects`` adds selected centered terms to the reference predictor before transforming to survival. " + "Interpret the result as a probability contrast.\n" + "* **Statistical coefficient intervals.** Use ``prepare_survival_curve_interval``, ``prepare_survival_effect_interval``, " + "``prepare_survival_hazard_interval`` or ``prepare_survival_rmst_interval`` for pointwise intervals or simultaneous bands on a declared grid. " + "Joint coverage is scoped to the requested quantity. Single-fit neural models use the bootstrap route for uncertainty.\n" + "* **Subject bootstrap.** ``bootstrap_survival`` refits on resampled subjects or complete histories and evaluates a fixed cohort. " + "It supports pointwise percentiles and finite-grid simultaneous bands. Neural refits require fixed, disjoint external validation subjects.\n" + "* **Replicated fits.** ``combine_survival_predictions`` averages survival on an aligned cohort and reports empirical between-fit ranges.\n" + "* **Calibration.** Conformal calibration provides lower event-time bounds under route-specific assumptions.\n\n" + "See the :doc:`/howto/survival` guide for inference scales, bootstrap requirements and integration details.\n\n" + "Unsupported routes\n~~~~~~~~~~~~~~~~~~\n\n" + "* **Event and censoring models.** Recurrent events, competing risks, left or interval censoring, parametric time-varying covariates, " + "and neural or longitudinal Cox. Use ``CoxGAM`` for static Cox regression.\n" + "* **Fitting.** Censored EFS, optim, magic and nlm.fd, separate censored ML, LAML, GCV, UBRE and NCV, " + "and zero-event saturated interval-factor fits. Parametric fits require two distinct positive-weight exact events.\n" + "* **Evaluation and inference.** Delayed-entry IPCW or concordance, conditional censoring models, dynamic AUC, Uno concordance, " + "randomized censor-aware PIT, continuous-time bands and simultaneous inference from replicated fits. Coefficient simulation requires " + "untransformed coefficients and an identity prediction-coordinate map.\n" + ) return text @@ -536,8 +579,22 @@ def cox_estimator_text(cls): return (":ref:`Cox scope and survival workflow `.\n\n" + "Constructor parameters\n~~~~~~~~~~~~~~~~~~~~~~\n\n" + table(["Parameter", "Default", "Meaning"], rows) - + "fit(X, SurvivalTarget, strata=..., offset=...) supports static right-censored records with fixed spline penalties. Risk sets include all tied event/censor records before the event contribution, following upstream mgcv coxlpl/coxpp conventions. predict_distribution returns shared step-cumulative-hazard predictions on common requested-stratum follow-up support; predict(..., times=...) returns survival. RMST integrates those steps exactly. predict_components describes log relative hazard, not survival. score is per-subject partial likelihood, not normalized event-time density; do not rank it against full survival likelihoods.\n\n" - + "Automatic REML reuses the existing general-family solver with exact risk-set derivatives through fourth order. Newton/BFGS are supported for one stratum; stratified automatic fitting requires BFGS because strict Newton coefficient convergence has not passed its endpoint gate. predict_standard_error follows mgcv coxpp/coxpred, including baseline and coefficient terms. predict_interval returns approximate pointwise Wald survival limits. diagnostics returns source Schoenfeld and unscaled drift-corrected cumulative-score data, plus baseline-consistent martingale/deviance residuals. bootstrap_survival re-estimates coefficients, baseline and eligible smoothing; stratified calls require aligned fit_context and prediction_context strata. RMST and finite-grid simultaneous uncertainty are available through bootstrap. Delayed entry, longitudinal/neural Cox, case weights, alternate ties, continuous hazard density, analytic simultaneous/conditional curve intervals and coefficient-only substitutions remain unsupported. Version-4 trusted fitted-state save/load preserves supported predictions/inference.\n") + + "Fitting and risk sets\n~~~~~~~~~~~~~~~~~~~~~\n\n" + + "* ``fit(X, SurvivalTarget, strata=..., offset=...)`` accepts static right-censored records. Risk sets include tied event and censor records before the event contribution, following mgcv.\n" + + "* Fixed spline penalties are supported. Automatic REML uses exact risk-set derivatives through order four. Use Newton or BFGS for one stratum and BFGS for stratified automatic fits.\n\n" + + "Predictions and diagnostics\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n" + + table(["Operation", "Result"], [ + ("``predict_distribution``", "Step cumulative-hazard predictions on common follow-up support across requested strata. RMST integrates the steps exactly."), + ("``predict(..., times=...)``", "Survival probabilities on the supplied grid."), + ("``predict_components``", "Additive contributions to log relative hazard."), + ("``score``", "Per-subject partial likelihood. Compare Cox fits on the same risk sets and keep full event-time likelihoods separate."), + ("``predict_standard_error`` / ``predict_interval``", "Baseline and coefficient uncertainty following mgcv coxpp/coxpred, with approximate pointwise Wald survival limits."), + ("``diagnostics``", "Schoenfeld and unscaled drift-corrected cumulative-score data, plus baseline-consistent martingale and deviance residuals."), + ]) + + "Uncertainty and limits\n~~~~~~~~~~~~~~~~~~~~~~\n\n" + + "* ``bootstrap_survival`` refits coefficients, baseline and eligible smoothing. Use it for RMST and finite-grid simultaneous uncertainty. Stratified calls require aligned ``fit_context`` and ``prediction_context`` strata.\n" + + "* The fitted scope excludes delayed entry, longitudinal and neural Cox, case weights, alternate tie methods, and continuous hazard density. Analytic simultaneous or conditional curve intervals and coefficient-only substitutions are unavailable.\n" + + "* Trusted fitted-state save/load preserves predictions and supported inference.\n") def calibrated_quantile_text(cls): @@ -559,7 +616,9 @@ def calibrated_quantile_text(cls): for name, parameter in inspect.signature(cls).parameters.items()] return (":ref:`Calibrated quantile inference `.\n\n" + table(["Parameter", "Default", "Meaning"], rows) - + "Unweighted independent rows, identity link, supplied or adaptive ELF bandwidth and spline penalties. The qgam 2.0.1 calFast criterion selects a scalar loss scale by matching posterior and shrinkage-sandwich quantile-function variances. predict_interval returns approximate pointwise conditional-quantile intervals, distinct from future-response conformal intervals. predict_components reconstructs the conditional quantile. score is negative mean pinball loss.\n\n" + + "Fitting and prediction\n~~~~~~~~~~~~~~~~~~~~~~\n\n" + + "* **Fit.** Use unweighted independent rows, an identity link, spline penalties and a supplied or adaptive ELF bandwidth. qgam's calFast selects a scalar loss scale by matching posterior and shrinkage-sandwich quantile-function variances.\n" + + "* **Predict.** ``predict_interval`` gives approximate pointwise intervals for the conditional quantile. Use conformal intervals for future-response coverage. ``predict_components`` reconstructs the conditional quantile. ``score`` is negative mean pinball loss.\n\n" + "Fitted state includes ``loss_scale_``, ``posterior_covariance_``, ``sandwich_covariance_``, ``calibration_loss_`` and the scalar ``calibration_profile_``. Failed refits preserve the successful fitted model; set_params invalidates it. Trusted save/load preserves supported predictions and intervals.\n\n" + "fit_levels shares Gaussian/SHASH preparation across independently calibrated levels; quantiles can cross and their inference is not joint. Covariate-dependent loss scales, weighted/bootstrap calibration, simultaneous bands, noncrossing multiple quantiles and likelihood/AIC inference are unsupported. The existing QuantileGAM fitting route is unchanged.\n") diff --git a/docs/_ext/statistical_helpers_reference.py b/docs/_ext/statistical_helpers_reference.py index f1457d3e..10b1a0fe 100644 --- a/docs/_ext/statistical_helpers_reference.py +++ b/docs/_ext/statistical_helpers_reference.py @@ -86,15 +86,18 @@ } -def field_list(entries): - """Definition lists keep parameters/outputs detailed without output tables.""" - text = "" - for name, kind, default, meaning in entries: - text += f"``{name}`` — Type: {kind}\n " - if default is not None: - text += f"Default: ``{default}``. " - text += meaning + "\n\n" - return text +def field_table(entries): + """Give each helper field a label, description, and separate metadata.""" + from public_reference import table + + if any(default is not None for _, _, default, _ in entries): + return table(["Field", "Type", "Default", "Meaning"], [ + (f"``{name}``", kind, f"``{default}``" if default is not None else "—", meaning) + for name, kind, default, meaning in entries + ]) + return table(["Field", "Type", "Meaning"], [ + (f"``{name}``", kind, meaning) for name, kind, _, meaning in entries + ]) def contract(obj, parameters, outputs, *, spelling=None, level="-"): @@ -106,12 +109,12 @@ def contract(obj, parameters, outputs, *, spelling=None, level="-"): + f".. code-block:: python\n\n {name}{inspect.signature(obj)}\n\n" + heading("Parameters", level) + ( - field_list(parameters) + field_table(parameters) if parameters else "The constructor takes no arguments.\n\n" ) + heading("Outputs", level) - + field_list(outputs) + + field_table(outputs) ) @@ -227,7 +230,7 @@ def generate_links(root): text += f" family.link{inspect.signature(demo.link.__call__)}\n" for name in ["inverse_link", "mu_eta", "d2link", "d3link", "d4link"]: text += f" family.{name}{inspect.signature(getattr(demo, name))}\n" - text += "\n" + field_list( + text += "\n" + field_table( [ ( "mu", @@ -243,7 +246,7 @@ def generate_links(root): ), ] ) - text += heading("Outputs", "-") + field_list( + text += heading("Outputs", "-") + field_table( [ ( "family.link(mu)", diff --git a/docs/_includes/quasi_configuration.inc b/docs/_includes/quasi_configuration.inc index de96629e..17a26e5f 100644 --- a/docs/_includes/quasi_configuration.inc +++ b/docs/_includes/quasi_configuration.inc @@ -7,8 +7,10 @@ The quasi model specifies a link and a mean-variance relation separately: g(\mu)=\eta,\qquad\operatorname{Var}(Y\mid x)=\phi V(\mu). -``variance`` selects exactly one of the following forms; whitespace is removed -from the option string before matching: +Variance functions +~~~~~~~~~~~~~~~~~~ + +``variance`` selects one of these forms. Whitespace is removed before matching. * ``'constant'``: :math:`V(\mu)=1`; real means are permitted. * ``'mu'``: :math:`V(\mu)=\mu`; require :math:`\mu>0`. @@ -16,8 +18,10 @@ from the option string before matching: * ``'mu^2'``: :math:`V(\mu)=\mu^2`; require :math:`\mu>0`. * ``'mu^3'``: :math:`V(\mu)=\mu^3`; require :math:`\mu>0`. -``power`` selects a **link exponent**, not a variance exponent. Its actual -constructor dispatch is +Link exponent +~~~~~~~~~~~~~ + +``power`` controls the link exponent independently of ``variance``. .. math:: @@ -46,14 +50,16 @@ The separate ``quasipoisson`` and ``quasibinomial`` factory mappings accept only ``link`` and retain their named variance functions; custom variance/power options belong to general ``quasi``. -For direct ``QuasiFamily(...)`` construction, ``**kwargs`` accepts the inherited -``eps`` float, default ``1e-9``. It is a numerical safeguard, not dispersion or -response noise, and not every link uses it instead of machine epsilon. The -options-mapping factory accepts only ``name``, ``link``, ``variance`` and -``power`` for this family; it rejects an ``eps`` key. The named quasi classes -also forward inherited ``eps`` and numeric ``power`` in direct construction, -subject to the same link/power compatibility rules; their factory mappings -remain restricted to ``name`` and ``link``. +Constructor and factory options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* **Direct construction.** ``QuasiFamily(...)`` accepts inherited ``eps`` via + ``**kwargs``, default ``1e-9``. It safeguards link calculations where used. + The named quasi classes also forward ``eps`` and numeric ``power`` subject + to the link compatibility rules. +* **Factory mappings.** General ``quasi`` accepts ``name``, ``link``, + ``variance`` and ``power``. ``quasipoisson`` and ``quasibinomial`` accept + ``name`` and ``link``. The quasi objective supplies estimating equations rather than a normalized response law. Its scale and supported extended-quasi smoothing criteria are diff --git a/docs/_includes/soap_domain_details.inc b/docs/_includes/soap_domain_details.inc index 81508839..70015fce 100644 --- a/docs/_includes/soap_domain_details.inc +++ b/docs/_includes/soap_domain_details.inc @@ -72,14 +72,16 @@ would have a nonzero fixed boundary contribution. In contrast, ``fs`` or ``sz`` with no factor delegates to the ordinary soap constructor and retains its offsets and explicit term smoothing parameters. -Matrix-valued paired coordinates and summation weights are supported for +**Matrix-valued coordinates.** Paired coordinates and summation weights are supported for ``fs(sf)``, ``sz(sf)``, ``sz(sw)`` and fully known ``sz(so)`` with scalar categorical factors. For example, use ``s(X,Y,group,bs='fs',by=L, xt={'bs':'sf','bnd':boundary})`` with array-valued ``X``, ``Y`` and ``L`` cells and a categorical ``group`` column. Boundary and knot names must match -the coordinate names. A group that varies across quadrature columns can instead -use explicit categorical rows, as described below. Classless character arrays -are not silently converted to factors. Analytic soap derivatives remain unavailable. +the coordinate names. + +**Factors within a row.** When groups vary across quadrature columns, supply +explicit categorical rows. Use declared factor levels in place of plain +character arrays. Analytic soap derivatives are unavailable. See ``examples/example_soap_compositions.py`` for runnable recipes. The static reference tests cover basis and penalty matrices, domains with holes, known boundaries, fitting, prediction uncertainty, and persistence. diff --git a/docs/_includes/statistical_family_details.inc b/docs/_includes/statistical_family_details.inc index 3af3da49..b80b19fa 100644 --- a/docs/_includes/statistical_family_details.inc +++ b/docs/_includes/statistical_family_details.inc @@ -104,7 +104,7 @@ Scaled Student t family single-predictor ``mgcv::scat`` family. Import it from ``nampy.gam.families`` or use ``family="scat"`` in ``GAM``. -``theta`` contains the degrees of freedom and scale, in that order. Two +**Ancillary parameters.** ``theta`` contains the degrees of freedom and scale, in that order. Two positive values fix both parameters. Any negative entry requests estimation of both parameters, using their absolute values as constructor initial values. ``None`` or a zero entry selects the upstream default working parameters. @@ -118,7 +118,7 @@ these constructor values with working parameters degrees of freedom is at or below ``min_df``, the constructor warns and resets ``min_df`` to ``0.9 * abs(theta[0])``, following upstream. -The location predictor supports ``identity``, ``log`` and ``inverse`` links. +**Links and variance.** The location predictor supports ``identity``, ``log`` and ``inverse`` links. With degrees of freedom ``nu`` and scale ``sigma``, the conditional variance is ``sigma**2 * nu / (nu - 2)`` when ``nu > 2``. The scale in ``theta`` is a distribution parameter, distinct from the optional GAM dispersion argument. @@ -126,11 +126,14 @@ distribution parameter, distinct from the optional GAM dispersion argument. The implementation follows mgcv 1.9-4 ``R/efam.r::scat``, including its observed and Fisher derivatives. See the `upstream scat documentation `_. -Fixed smoothing and ``ML``/``REML`` selection support fixed or estimated + +**Smoothing selection.** Fixed smoothing and ``ML``/``REML`` selection support fixed or estimated ancillary parameters. With ``optimize_smoothing=False``, an explicitly selected ``ML`` or ``REML`` criterion still governs ancillary estimation; ``smoothing_method="fixed"`` uses REML. ``LAML`` is a REML alias. ``GCV.Cp``, ``P-ML`` and ``P-REML`` use the -upstream extended-family REML route. Unsupported criteria such as NCV +upstream extended-family REML route. + +**Fit restrictions.** Unsupported criteria such as NCV raise an explicit error, including with fixed smoothing parameters. Joint estimation with the ``efs`` optimizer is unsupported and raises an explicit error. ``ML`` with zero observation weights is also explicitly guarded: @@ -141,14 +144,14 @@ estimated ancillary parameters. The fixed-penalty offset parameterization has not been ported for joint fitting and smoothing-uncertainty corrections; zero ``min_sp`` retains the ordinary supported path. -Rank-deficient designs that drop coefficients are rejected when fitting +**Rank and covariance.** Rank-deficient designs that drop coefficients are rejected when fitting requires outer-parameter uncertainty corrections. The upstream correction attempts Cholesky factorization of the full singular coefficient Hessian; rounding can change whether that correction is included, affecting AIC and unconditional covariance across platforms. Conditional fitting with both ancillary parameters and smoothing fixed remains available. -The default external dispersion is one. A positive ``GAM(scale=...)`` +**External dispersion.** The default external dispersion is one. A positive ``GAM(scale=...)`` override follows the upstream criterion and covariance scaling. For fixed ancillary parameters and fixed smoothing, ``scale=2`` doubles the conditional coefficient covariance without changing coefficients or distribution @@ -156,7 +159,7 @@ parameters. When smoothing or ancillary parameters are estimated, the external dispersion can change their optimum; it is not merely a multiplier on the reported standard errors. -Outer ``bfgs``, ``optim`` and ``nlm`` routes have endpoint references for +**Alternative optimizers.** Outer ``bfgs``, ``optim`` and ``nlm`` routes have endpoint references for identity-link, positive-weight models with one cubic smooth and fixed or estimated ancillary parameters. ``optim`` comparisons use matching ``control={"epsilon": 1e-10, "optim": {"factr": 10}}`` to resolve a flat @@ -164,7 +167,7 @@ ancillary-parameter optimum. BFGS retains its path-dependent approximate Hessian; the final derivative-free ``nlm`` and ``optim`` fits do not supply a smoothing-parameter uncertainty correction. -Conditional and unconditional coefficient covariance, effective degrees of +**Inference and residuals.** Conditional and unconditional coefficient covariance, effective degrees of freedom, prediction standard errors, likelihood, AIC and BIC are available. Unconditional corrections require an outer-parameter Hessian: they are absent when both ancillary parameters and all smoothing parameters are @@ -182,7 +185,7 @@ Hurdle Poisson family mgcv's single-predictor ``ziP`` family. Public names ``"ziP"`` and ``"zip"`` resolve to the same family. Only the identity link is supported. -The fitted latent value ``gamma`` is the logarithm of a Poisson intensity +**Predictor and response scales.** The fitted latent value ``gamma`` is the logarithm of a Poisson intensity ``lambda = exp(gamma)``. The probability of a positive count is ``p = 1 - exp(-exp(theta[0] + (b + exp(theta[1])) * gamma))``. Conditional on presence, counts have a zero-truncated Poisson distribution. @@ -191,7 +194,7 @@ Conditional on presence, counts have a zero-truncated Poisson distribution. fitted values remain on the latent log-intensity scale. Response standard errors describe the expected count, not an interval for a new observation. -A supplied ``theta`` pair fixes both working parameters, even when entries +**Ancillary parameters.** A supplied ``theta`` pair fixes both working parameters, even when entries are zero or negative. Omitting ``theta`` estimates both, starting from ``[0, 0]``. ``getTheta()`` returns the working intercept and log slope; ``getTheta(trans=True)`` returns the intercept and ``b + exp(theta[1])``. @@ -199,17 +202,19 @@ are zero or negative. Omitting ``theta`` estimates both, starting from following mgcv. Larger ``b`` enforces stronger dependence between intensity and the probability of presence. -The response must contain nonnegative integer counts; binary data containing +**Counts and diagnostics.** The response must contain nonnegative integer counts; binary data containing both zero and one are rejected. The public model is a count regressor. Deviance, working, and response residuals are supported. Pearson and quantile residuals are explicitly unavailable. Reported deviance includes the family-specific saturated-likelihood correction; adjusted R-squared is not reported for this family. -The reference scope covers fixed and estimated ancillary parameters, fixed +**Fitting support.** The reference scope covers fixed and estimated ancillary parameters, fixed smoothing, ML/REML (including the LAML alias), offsets, multiple smooths, no-intercept and parametric-only formulas, and unit observation weights. -Positive external dispersion overrides are covered, including scale two. Nonunit or zero +Positive external dispersion overrides are covered, including scale two. + +**Weights and rank.** Nonunit or zero prior weights are explicitly guarded: mgcv's ``ziP`` deviance ignores weights while its derivatives and AIC use them, so the ordinary weighted-GLM contract does not apply. Positive ``min_sp`` and joint estimation with ``efs`` are @@ -242,7 +247,7 @@ Censored normal family ``("cnorm", {"theta": 1})`` also resolve the family. It is a regression family; the response's second column is a censor bound, not a class label. -The reference scope covers fixed or estimated response SD, fixed smoothing +**Fitting support.** The reference scope covers fixed or estimated response SD, fixed smoothing or ML/REML smoothing selection, including joint objective gradients and Hessians. Identity, log and square-root links have family-kernel references; fixed-SD, fixed-smoothing fits also cover positive precision weights and @@ -251,14 +256,14 @@ no-intercept and parametric-only fits, conditional rank-deficient fits, BFGS/optim/nlm endpoints, and fixed-SD EFS. These targeted checks do not establish cross-platform CI acceptance. -For conditional fits with exactly aliased columns, the retained coefficient +**Aliased designs.** For conditional fits with exactly aliased columns, the retained coefficient can differ across numerical factorizations. Their parity checks compare estimable coefficient effects and covariance kernels, including predictions that preserve the training alias relation. Raw covariance coordinates and predictions outside that relation are not uniquely identified; no parity claim is made for such nonestimable newdata. -A vector response represents exact observations. A two-column response, +**Censoring input.** A vector response represents exact observations. A two-column response, provided as ``cbind(value, bound)`` in a formula or an explicit ``(n, 2)`` array, encodes each observation as follows: @@ -288,19 +293,21 @@ For a negative supplied value, mgcv 1.9-4 actually retains that value as the initial *log standard deviation*, despite the manual's negative-SD wording. ``getTheta()`` returns working log SD and ``getTheta(trans=True)`` returns SD. -The source uses observation weights as precision: each row's SD is +**Precision weights.** The source uses observation weights as precision: each row's SD is ``exp(theta_working) / sqrt(weight)``. They are not frequency weights. Zero weights are rejected during fitting: upstream mixed-censor interval observations can produce undefined derivatives and an error, even though some uncensored zero-weight fits converge. They are not automatically -omitted rows. Positive ``min_sp`` is also unsupported, and estimated SD with +omitted rows. + +**Selection limits.** Positive ``min_sp`` is also unsupported, and estimated SD with the ``efs`` optimizer is guarded. Estimated SD with nonunit external dispersion is also guarded: a captured upstream failed outer fit returns coefficients from a different parameter state. Fixed-SD fits accept positive external dispersion. Rank-deficient outer uncertainty retains the shared extended-family guard. The executable example uses unit weights. -The implementation preserves two mgcv 1.9-4 AIC quirks: its exact-observation +**Likelihood reporting.** The implementation preserves two mgcv 1.9-4 AIC quirks: its exact-observation branch omits the log-SD Jacobian after standardizing, and its later ``bound <= 0`` branch also replaces contributions from nonpositive exact or finite interval bounds. Consequently source-compatible AIC and derived @@ -327,24 +334,28 @@ uncensored logistic standard deviation is ``scale * pi / sqrt(3)``. The family describes a continuous logistic response, with one additive location predictor. Supported links are identity, log and square root. -Responses use the same explicit paired encoding as ``cnorm`` above: +**Censoring input.** Responses use the same explicit paired encoding as ``cnorm`` above: equal values are exact observations, distinct finite values define an interval in either order, and infinite second bounds define one-sided censoring. Predictions return the latent logistic location and need no -censor bounds. Observation weights are precision, giving each row a scale +censor bounds. + +**Scale and weights.** Observation weights are precision, giving each row a scale ``exp(theta_working) / sqrt(weight)``. A positive constructor ``theta`` fixes scale; zero or ``None`` estimates it from working value zero; negative ``theta`` starts estimation at ``log(abs(theta))``. This last convention differs from the source ``cnorm`` constructor. -Static R references cover all returned deviance derivative fields through +**Validated fits.** Static R references cover all returned deviance derivative fields through fourth order, saturation derivatives, tails, precision weights, mixed censoring, fixed/estimated scale, fixed smoothing and ML/REML selection, offsets, two smooths, parametric-only fits, covariance, EDF, likelihood criteria, predictions, residuals, persistence and additive reconstruction. Fixed- and estimated-scale optimizers have targeted references, including weighted ancillary estimation, successful estimated-scale nlm fits, and -nonidentity REML/BFGS and ML/optim fits. EFS estimates scale inside each PIRLS +nonidentity REML/BFGS and ML/optim fits. + +**EFS.** EFS estimates scale inside each PIRLS iteration using the source ``estimate.theta`` update, and retains the accepted EFS fit rather than estimating theta again in a final solve. EFS references cover exact and mixed-censored responses, all three links, @@ -352,7 +363,7 @@ positive precision weights and positive external dispersion. EFS supplies no smoothing-parameter covariance or unconditional uncertainty correction. The example is ``examples/example_clog_gam.py``. -In captured fixed-scale nlm/optim cases the smooth reaches its linear null +**Optimizer endpoints.** In captured fixed-scale nlm/optim cases the smooth reaches its linear null space. Large raw smoothing parameters are not compared across endpoints; fitted effects, covariance, criterion, and the limiting EDF retain their original tolerances. Other accepted cases compare smoothing parameters @@ -381,7 +392,7 @@ Remaining restrictions have distinct causes: retain the documented extended-family restrictions. These do not imply that every upstream composition or dataset is rejected. -The port retains source arithmetic and formulas, including interval +**Likelihood reporting.** The port retains source arithmetic and formulas, including interval derivative expressions and the unusual ``aic`` hook, which is independent of fitted location. Consequently reported source-compatible AIC and derived log likelihood are not substitutes for an independently normalized logistic @@ -404,7 +415,7 @@ unequal pair denotes the discrete event ``min(value,bound) < Y <= max(value,boun For example, ``[2, 4]`` includes counts three and four. Predictions return the underlying mean, with standard errors for that mean. -The source likelihood, deviance, saturated likelihood and derivative hooks +**Weights and numerical evaluation.** The source likelihood, deviance, saturated likelihood and derivative hooks ignore observation weights. They are not frequency-weighted Poisson hooks; nonunit-weight reference fits retain this source convention. Density and tail probabilities follow the scalar R Mathlib ``dpois``/``ppois`` branches, including @@ -412,7 +423,7 @@ extreme-tail and degenerate-mean cases. Location derivatives through fourth order, the discrete saturated-likelihood correction, residuals and null calculations use those source probabilities. -Actual-mgcv fixtures cover exact/mixed responses, all three links, fixed +**Fitting support.** Actual-mgcv fixtures cover exact/mixed responses, all three links, fixed smoothing, ML/REML selection, positive external dispersion and observation weights, coefficients, covariance, EDF, likelihood criteria, residuals and predictions/SE. The alternative ``bfgs``, ``optim``, ``nlm`` and ``efs`` routes have direct @@ -434,13 +445,13 @@ transforms the second entry to SD. The default estimates both parameters, starting at working values ``[1, 0]``. Positive precision weights replace log SD by ``logSD - log(weight)/2``. -Censoring uses explicit paired response data. Nonpositive second-column +**Censoring input.** Censoring uses explicit paired response data. Nonpositive second-column values denote left censoring, positive unequal finite endpoints denote an interval, and ``+Inf`` denotes right censoring. Source initialization uses the input response scale. Predictions describe the transformed Gaussian location; they do not apply an inverse Box-Cox mean correction. -The source fixed constructor has a specific failure: positive +**Fixed parameters.** The source fixed constructor has a specific failure: positive ``theta=[lambda, sd]`` stores three working entries, ``[lambda, log(lambda), log(sd)]``. Its fitted source call fails with an ``ls$lsth2`` indexing error. NAMpy rejects this malformed fitted state with @@ -460,11 +471,12 @@ constructor repair is performed. A nonpositive second constructor entry starts estimation and retains that entry as the initial working log SD, following source initialization order. -References cover the near-zero-lambda expansions, all censor blocks, fourth +**Fitting support.** References cover the near-zero-lambda expansions, all censor blocks, fourth location and second ancillary derivatives, exact and mixed responses, precision weights, offsets, fixed/estimated ancillary parameters, and fixed/ML/REML smoothing. Estimated-parameter vector fits cover all three links. -EFS uses the two-parameter source ``estimate.theta`` update inside PIRLS; + +**EFS.** EFS uses the two-parameter source ``estimate.theta`` update inside PIRLS; fixed/estimated ancillary vector and mixed-response endpoints have direct references. Theta-update references also cover external dispersion one/two; the captured scale-two source updates warn about step failure and retain their @@ -473,7 +485,7 @@ smoothing parameter: the all-fixed-SP source call errors. Positive ``min_sp`` and rank-deficient outer-uncertainty combinations retain the extended-family guards described above. -Source AIC omits scale/Box-Cox Jacobians and is not an independently normalized +**Likelihood reporting.** Source AIC omits scale/Box-Cox Jacobians and is not an independently normalized Box-Cox density. Source saturated-likelihood derivative arrays are zero despite the value's ancillary dependence. Exactly transformed censor endpoints can produce source NaNs in signed density differences; those NaNs remain visible. @@ -604,21 +616,21 @@ positive ``b``. ``GAMLSS.predict`` returns ``(mu, sigma, epsilon, delta)``; CDF/log-CDF and inverse-transform simulation hooks are present. Source GAM response prediction returns ``(mu, log_sigma, epsilon, log_delta)``. -The fitting likelihood includes the source ridge +**Fitting criterion.** The fitting likelihood includes the source ridge ``-phi_pen * log(delta)**2`` (``phiPen`` is an accepted alias). Public normalized density scoring omits that estimation ridge. All analytic derivatives through fourth order are supplied. Fixed SP, Newton-selected REML and EFS references cover initialization, covariance, criterion/EDF, AIC/logLik, predictions/SE, residuals and summary tables. -The EFS parity captures provide the same explicit initial smoothing parameters +**EFS initialization.** The EFS parity captures provide the same explicit initial smoothing parameters to both implementations. Source ``initial.spg`` uses the initially reparameterized design with the original penalty coordinates: an arbitrary eigenvector sign can change its starting parameters and the finite EFS endpoint. Static source sign-transport checks record this dependence and verify common-start prediction, covariance, penalty and EDF invariants. -Nonzero offsets are rejected. The source fitting likelihood's bin lookup +**Prediction and residual limits.** Nonzero offsets are rejected. The source fitting likelihood's bin lookup excludes a lower ``-Inf`` endpoint: an exactly zero standardized residual therefore produces positive-infinite source likelihood. The normalized density and residual expression stay finite there. Residual centering retains the @@ -637,22 +649,25 @@ identity. Source response values are ``(mu, theta, rho)``; source logistic power map confines ``p`` to the supplied bounds. ``predict_point`` returns mean ``mu``. -Source ``available.derivs=0`` supplies the analytic likelihood gradient and +**Smoothing selection.** Source ``available.derivs=0`` supplies the analytic likelihood gradient and Hessian; third/fourth likelihood arrays and a numerical outer-derivative fallback are unavailable. Smoothing selection automatically uses EFS, including when another optimizer was requested. Fixed-SP and selected-EFS fits have direct references for covariance, criterion/EDF, AIC/logLik, -predictions/SE, all three residual types and summary tables. The source null +predictions/SE, all three residual types and summary tables. + +**Null deviance.** The source null fit retains its independent bounds ``a=1.001, b=1.999``; null postprocessing uses each observation's fitted dispersion. Prior weights enter deviance residuals and null deviance, although the fitting likelihood ignores them. -The source formula-list setup rejects an external fixed-SP vector when a +**Fixed smoothing in formula lists.** The source formula-list setup rejects an external fixed-SP vector when a parametric-only middle predictor precedes another smooth. Equivalent source captures fix the parameters inside their ``s(..., sp=...)`` terms. All three predictor offsets, zero/positive responses, custom power bounds and both source initialization branches have kernel references. -Selected-EFS parity uses the same explicit initial smoothing parameters in + +**EFS initialization.** Selected-EFS parity uses the same explicit initial smoothing parameters in both implementations. As for ``shash``, source ``initial.spg`` depends on arbitrary initial penalty eigenvector signs; its uncontrolled finite EFS endpoint need not agree across platforms. Common-start references compare diff --git a/docs/api/gam.rst b/docs/api/gam.rst index ddb1e5b6..36d85052 100644 --- a/docs/api/gam.rst +++ b/docs/api/gam.rst @@ -41,17 +41,16 @@ Spherical smooths ----------------- Use ``s(latitude, longitude, bs="sos")`` for an isotropic smooth on a -sphere. Coordinates are supplied in degrees, latitude first and longitude -second. The default ``m=0`` is the second-order Wendelberger spline; integer -orders from ``-2`` through ``4`` select the upstream Duchon or Wahba kernel -branches. SOS margins in ``te`` and ``ti`` must be grouped with ``d=2``. -The array API cannot express this joint two-coordinate term, so SOS models use -the formula interface. The ``m=-1`` null space is four-dimensional; combining -that order with an ``fs`` factor smooth is rejected because the corresponding -upstream penalty split is LAPACK-orientation dependent. Upstream SOS smooths -also do not define derivative matrices. ``model.plot(scheme=0)`` and -``scheme=1`` provide rotated hemisphere displays; ``theta`` and ``phi`` -control the view, with numerical grids checked against mgcv. +sphere. Supply latitude first and longitude second, both in degrees. + +* **Basis.** ``m=0`` selects the second-order Wendelberger spline. Integer + orders from ``-2`` through ``4`` select the upstream Duchon or Wahba branches. +* **Composition.** Use the formula interface and group ``sos`` tensor margins + in ``te`` or ``ti`` with ``d=2``. The four-dimensional ``m=-1`` null space + makes its ``fs`` penalty split LAPACK-dependent, so that fit is guarded. +* **Prediction and display.** Upstream supplies no derivative matrices. + ``model.plot(scheme=0)`` and ``scheme=1`` show rotated hemispheres. Set + ``theta`` and ``phi`` to change the view. Shape-constrained smooths ------------------------- diff --git a/docs/api/gam_smooths.rst b/docs/api/gam_smooths.rst index 897e566b..6886f469 100644 --- a/docs/api/gam_smooths.rst +++ b/docs/api/gam_smooths.rst @@ -48,60 +48,68 @@ Omitting ``by`` uses unit weights. For a surface, ``sum_j L[i,j] * f(X[i,j], Z[i,j])``; all coordinate and weight matrices must have matching shapes. +Basis and weight conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The same weighted or unit-weight summation is supported by ``cr``, ``cc``, ``ps``, ``cp``, ``bs``, ``ds``, ``gp`` and ``sos``. Duchon and GP terms accept paired multivariate locations; spherical terms use paired -latitude/longitude matrices. Penalties are scaled on the underlying pointwise -basis before summation. Constant row sums retain the upstream centering -constraint even when the individual quadrature weights vary. -Repeated coordinates follow mgcv's setup packing rule: coordinates are pooled -in column-major order and packed to their first occurrences when fewer than -90% of the point tuples are unique. Penalty scaling and centering use that -setup basis; prediction expands the pointwise basis before summation. All ``cs`` -matrix fits are rejected, including distinct locations: unequal null-space -shrinkage penalties have an unresolved portable eigenvector-orientation parity -issue. Scalar ``cs`` terms remain supported. - -Adaptive ``ad`` terms support weighted or unit-weight one-dimensional -matrices and unit-weight paired two-dimensional matrices. Weighted 2D -adaptive matrix fits are rejected: mgcv 1.9-4 loses the ``by`` variable in -prediction for this construction, so its fitted and predicted values differ. - -Soap ``so``/``sf``/``sw`` terms also support paired location matrices and -weighted sums. Known-boundary ``so``/``sf`` matrix fitting is rejected because -upstream ``smoothCon`` cannot aggregate the constructor's boundary offset. -``sw`` has no boundary offset and supports this case. - -Random-effect ``re`` and full/reduced-rank ``mrf`` terms accept array-valued -categorical cells as well. Their factor levels are pooled across all cells; -string labels such as ``"01"`` and ``"1"`` remain distinct. -Numeric and categorical random-effect interactions retain pointwise products -before summation. For example, ``s(region, by=L, bs='re')`` accepts a -``region`` column whose cells are lists of labels, while ``s(X, region, -by=L, bs='re')`` sums numeric-by-factor random effects at paired locations. -MRF terms retain their required adjacency or penalty specification and reject -unknown regions; random effects give unseen levels zero contribution. - -``fs`` terms with ``xt={'bs': 'cr'}`` or ``xt={'bs': 'ps'}`` accept matrix -metric locations and a scalar factor per observation. They support weighted, -unit and constant-row-sum functionals, including repeated paired locations. -Matrix ``fs`` with its default ``tp`` base remains rejected because its -multiple independently penalized null directions have unresolved parity. -Univariate ``tp`` with ``m=1`` has a single null direction and is supported, -for example ``s(X, group, bs='fs', k=6, m=1, by=L)``. The requested ``m`` -is passed to thin-plate bases inside both ``fs`` and ``sz``. -Alternatively specify an accepted base explicitly, for example -``s(X, group, bs='fs', k=7, xt={'bs': 'cr'}, by=L)``. - -``sz`` matrix functionals support ``tp`` (one or two metric coordinates), -``cr`` and ``ps`` bases, with one or more scalar factor columns per observation. -Unit, varying and constant-row-sum weights follow upstream constraint handling; -repeated-location ``cr``/``ps`` cases are also validated. Paired matrix soap -coordinates with scalar factors support ``fs(sf)``, ``sz(sf/sw)`` and fully -known-boundary ``sz(so)``; their source offset conventions are described above. +latitude and longitude matrices. + +* **Penalty and centering.** Penalties are scaled on the pointwise basis before + summation. Constant row sums retain the upstream centering constraint even + when individual weights vary. +* **Repeated locations.** The setup pools coordinates in column-major order. + When fewer than 90% of point tuples are unique, it packs them to their first + occurrences. Prediction expands the pointwise basis before summation. +* **Shrinkage cubics.** Matrix ``cs`` fits, including distinct locations, are + guarded because unequal null-space shrinkage depends on eigenvector + orientation. Scalar ``cs`` remains supported. + +Adaptive and bounded surfaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Operation + - Result + * - Adaptive ``ad`` + - Supports weighted or unit-weight 1D matrices and unit-weight paired 2D matrices. Weighted 2D prediction loses the ``by`` variable in mgcv 1.9-4 and is guarded. + * - Soap ``so`` / ``sf`` / ``sw`` + - Supports paired location matrices and weighted sums. For known boundaries, use ``sw``. Upstream ``smoothCon`` cannot aggregate the boundary offsets of ``so`` or ``sf``. + +Random effects and grouped smooths +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* **Random effects and MRF.** ``re`` and full- or reduced-rank ``mrf`` accept + array-valued categorical cells. Factor levels are pooled across cells, and + labels such as ``"01"`` and ``"1"`` stay distinct. MRF requires an adjacency + or penalty specification and rejects unknown regions. Random effects give + unseen levels zero contribution. +* **Numeric-by-factor random effects.** ``s(region, by=L, bs='re')`` accepts + lists of region labels. ``s(X, region, by=L, bs='re')`` multiplies the + numeric and categorical effects at each paired location before summing. +* **Factor smooths.** For ``fs``, use ``xt={'bs': 'cr'}`` or ``xt={'bs': 'ps'}`` + with matrix locations and a scalar factor per observation. Both bases support + varying, unit and constant-row-sum weights, including repeated locations. + For ``tp``, use one metric coordinate and ``m=1``, as in + ``s(X, group, bs='fs', k=6, m=1, by=L)``. Matrix ``fs`` rejects the default + ``tp`` because parity is unresolved for its independent null penalties. +* **Sum-to-zero factor smooths.** For ``sz``, matrix functionals support ``tp`` + with one or two metric coordinates, ``cr`` and ``ps``, with one or more + scalar factors per observation. Unit, varying and constant-row-sum weights + follow upstream constraints. Repeated ``cr`` and ``ps`` locations are also + validated. Both ``fs`` and ``sz`` pass ``m`` to their ``tp`` bases. +* **Soap bases.** With paired matrix coordinates and scalar factors, use + ``fs(sf)``, ``sz(sf/sw)`` or ``sz(so)`` with a fully known boundary. See the + source offset conventions above. + +Matrix-valued factors +~~~~~~~~~~~~~~~~~~~~~ To supply a matrix-valued factor, store each row as a ``pandas.Categorical`` -with the same declared categories and ordered flag. For example: +with the same declared categories and ordered flag. .. code-block:: python @@ -113,41 +121,44 @@ with the same declared categories and ordered flag. For example: ``groups`` has the same row count and quadrature width as the metric matrices. Each location may have its own factor level. The categorical rows carry the equivalent of R's factor-plus-dim metadata; plain arrays of labels do not. -With matrix-valued factors, ``fs`` supports single-penalty ``sf``, ``tp`` with -``m=1`` in one dimension, and ``ps`` with ``m=[2,1]``. Multiple independent null -penalties remain guarded: matching the function space alone does not preserve -the independently weighted null-space penalty operator across representations. -``sz`` supports the documented ``cr/ps/tp`` and soap bases. -With multiple matrix-valued factors, every joint training group must be -observed; empty joint groups remain guarded pending matching rank and side -conditions. Both this restriction and the multi-null ``fs`` restriction are -NAMpy parity limitations, rather than upstream input rejections. -Use at least two columns: upstream converts a one-column factor matrix to a -numeric vector. Prediction may change the quadrature width while preserving -the factor levels and pairing with the metric coordinates and weights. + +* **Factor smooths.** For ``fs``, use single-penalty ``sf``, one-dimensional ``tp`` with + ``m=1``, or ``ps`` with ``m=[2,1]``. Multiple independent null penalties + require parity of the penalty operator as well as the function space. +* **Sum-to-zero factor smooths.** For ``sz``, use ``cr``, ``ps``, ``tp`` or soap bases. +* **Multiple factors.** Every joint training group must be observed. Empty + joint groups and multi-null ``fs`` are guarded by NAMpy's parity checks. +* **Width.** Use at least two columns because upstream converts a one-column + factor matrix to a numeric vector. At prediction, width may change if + factor levels and pairing with metric locations and weights are preserved. + See ``examples/example_matrix_factor.py`` for a complete soap fit. -``te``, ``ti`` and ``t2`` support paired matrix coordinates with tested -``cr``, ``ps``, ``tp``, ``ds``, ``gp``, ``sf`` and ``sw`` margins. -``te`` and ``ti`` additionally support ``bs`` margins. -Matrix ``t2`` also supports ``bs`` margins when each B-spline null space has -at most one dimension, such as ``m=[[3, 1], [3, 1]]``, or when only the -highest range-space order is retained, such as ``ord=[2]`` for two margins. -These cases avoid the ambiguous null-space metric. Mixed range/null terms -with multidimensional ``bs`` null spaces remain rejected because portable -null-space normalization parity is unresolved. ``te``/``ti`` with ``bs`` -and ordinary scalar-input ``t2`` remain supported; matrix ``t2`` with tested -``cr``, ``ds``, ``gp``, ``tp`` and ``ps`` margins remains supported. -They sum pointwise tensor products, rather than multiplying separately summed -margins. Numeric, factor and mixed ``re`` margins also support these tensor -constructors with ordinary or matrix inputs. Their default identity precision -or a single supplied precision is supported; multiple precision matrices are -rejected as tensor margins, following upstream. For example, -``te(X, region, bs=['cr', 're'], k=[7, 6], by=L)`` sums paired smooth and random -effect products. Linked matrix-valued tensor ``id`` groups remain unsupported. +Tensor-product functionals +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tensor functionals sum pointwise tensor products across paired locations. + +* **Tested margins.** ``te``, ``ti`` and ``t2`` support ``cr``, ``ps``, ``tp``, + ``ds``, ``gp``, ``sf`` and ``sw``. ``te`` and ``ti`` also support ``bs``. +* **B-spline tensors.** Matrix inputs to ``t2`` support ``bs`` when each null space has at + most one dimension (for example ``m=[[3, 1], [3, 1]]``), or when only the + highest range-space order is retained (``ord=[2]`` for two margins). Mixed + range/null blocks with multidimensional ``bs`` null spaces remain guarded + pending portable normalization. Ordinary scalar-input ``t2`` is supported. +* **Random-effect margins.** Numeric, factor and mixed ``re`` support ordinary + or matrix inputs with identity or a single supplied precision matrix. + Upstream excludes multiple precisions as tensor margins. + ``te(X, region, bs=['cr', 're'], k=[7, 6], by=L)`` sums paired smooth and + random-effect products. +* **Linked IDs.** Linked matrix-valued tensor ``id`` groups are unsupported. + The runnable ``examples/example_matrix_functionals.py`` demonstrates a thin-plate surface and a tensor functional with prediction standard errors. +Fitting and prediction +~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: python import pandas as pd @@ -163,15 +174,14 @@ thin-plate surface and a tensor functional with prediction standard errors. smoothing_method='reml', optimize_smoothing=True, ).fit(data=data) -The quadrature weights define the functional predictor; ``sample_weight`` -continues to weight observations. Zero quadrature rows contribute no smooth -value. Identifiability depends on whether the sums of the quadrature weights -are constant across observations, following mgcv. Prediction reuses the fitted -basis and accepts new location matrices, including a different number of -quadrature points, or individual scalar locations. Prediction standard errors, -formula offsets and model persistence use the same interfaces as scalar -smooths. Linked matrix-valued ``tp``/``ts`` terms are tested; linked pooling -remains restricted for some other bases. +* **Weights.** Quadrature weights define the functional predictor and + ``sample_weight`` weights observations. Zero quadrature rows contribute zero. + Identifiability follows mgcv's constant-row-sum rule. +* **New locations.** Prediction reuses the fitted basis and accepts matrices + with a different number of quadrature points or individual scalar locations. +* **Shared interfaces.** Prediction standard errors, offsets and persistence + use the scalar-smooth interfaces. Linked matrix ``tp`` and ``ts`` are tested. + Pooling remains restricted for some other bases. See :doc:`../notebooks/functional_inputs` for a functional-regression example. diff --git a/docs/extension_reference/smooths/AdaptiveSmoothTerm.rst b/docs/extension_reference/smooths/AdaptiveSmoothTerm.rst index 65ed8a75..cf02339a 100644 --- a/docs/extension_reference/smooths/AdaptiveSmoothTerm.rst +++ b/docs/extension_reference/smooths/AdaptiveSmoothTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/AlternativeTensorProductSplineTerm.rst b/docs/extension_reference/smooths/AlternativeTensorProductSplineTerm.rst index c6750d3e..6a4425b5 100644 --- a/docs/extension_reference/smooths/AlternativeTensorProductSplineTerm.rst +++ b/docs/extension_reference/smooths/AlternativeTensorProductSplineTerm.rst @@ -101,7 +101,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/BivariateShapePSplineTerm.rst b/docs/extension_reference/smooths/BivariateShapePSplineTerm.rst index 7685c5b5..ee1e26d4 100644 --- a/docs/extension_reference/smooths/BivariateShapePSplineTerm.rst +++ b/docs/extension_reference/smooths/BivariateShapePSplineTerm.rst @@ -85,7 +85,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/CubicSplineTerm.rst b/docs/extension_reference/smooths/CubicSplineTerm.rst index 3887fdb5..763d28cc 100644 --- a/docs/extension_reference/smooths/CubicSplineTerm.rst +++ b/docs/extension_reference/smooths/CubicSplineTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/DerivativeBSplineTerm1D.rst b/docs/extension_reference/smooths/DerivativeBSplineTerm1D.rst index a3035cd2..a260dc98 100644 --- a/docs/extension_reference/smooths/DerivativeBSplineTerm1D.rst +++ b/docs/extension_reference/smooths/DerivativeBSplineTerm1D.rst @@ -89,7 +89,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/DuchonSplineTerm.rst b/docs/extension_reference/smooths/DuchonSplineTerm.rst index 64308c34..043d995d 100644 --- a/docs/extension_reference/smooths/DuchonSplineTerm.rst +++ b/docs/extension_reference/smooths/DuchonSplineTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/FSmoothInteractionTerm.rst b/docs/extension_reference/smooths/FSmoothInteractionTerm.rst index f5fa6e95..c94cc092 100644 --- a/docs/extension_reference/smooths/FSmoothInteractionTerm.rst +++ b/docs/extension_reference/smooths/FSmoothInteractionTerm.rst @@ -81,4 +81,17 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. diff --git a/docs/extension_reference/smooths/GaussianProcessTerm.rst b/docs/extension_reference/smooths/GaussianProcessTerm.rst index 3c7919e1..25efc28d 100644 --- a/docs/extension_reference/smooths/GaussianProcessTerm.rst +++ b/docs/extension_reference/smooths/GaussianProcessTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/InteractionTensorProductSplineTerm.rst b/docs/extension_reference/smooths/InteractionTensorProductSplineTerm.rst index c664ac51..eb89ea30 100644 --- a/docs/extension_reference/smooths/InteractionTensorProductSplineTerm.rst +++ b/docs/extension_reference/smooths/InteractionTensorProductSplineTerm.rst @@ -97,7 +97,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/MarkovRandomFieldTerm.rst b/docs/extension_reference/smooths/MarkovRandomFieldTerm.rst index 87abb1b9..e4814c0d 100644 --- a/docs/extension_reference/smooths/MarkovRandomFieldTerm.rst +++ b/docs/extension_reference/smooths/MarkovRandomFieldTerm.rst @@ -81,7 +81,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/PSplineTerm1D.rst b/docs/extension_reference/smooths/PSplineTerm1D.rst index 7c6f42c8..a75bdedd 100644 --- a/docs/extension_reference/smooths/PSplineTerm1D.rst +++ b/docs/extension_reference/smooths/PSplineTerm1D.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/RandomEffectTerm.rst b/docs/extension_reference/smooths/RandomEffectTerm.rst index 7f034184..cbaa41d6 100644 --- a/docs/extension_reference/smooths/RandomEffectTerm.rst +++ b/docs/extension_reference/smooths/RandomEffectTerm.rst @@ -81,7 +81,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/SZSmoothInteractionTerm.rst b/docs/extension_reference/smooths/SZSmoothInteractionTerm.rst index 10637efd..d445e097 100644 --- a/docs/extension_reference/smooths/SZSmoothInteractionTerm.rst +++ b/docs/extension_reference/smooths/SZSmoothInteractionTerm.rst @@ -81,4 +81,17 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. diff --git a/docs/extension_reference/smooths/ShapeConstrainedAdaptiveTerm.rst b/docs/extension_reference/smooths/ShapeConstrainedAdaptiveTerm.rst index c2bb0506..37d5d084 100644 --- a/docs/extension_reference/smooths/ShapeConstrainedAdaptiveTerm.rst +++ b/docs/extension_reference/smooths/ShapeConstrainedAdaptiveTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/ShapeConstrainedBSplineTerm.rst b/docs/extension_reference/smooths/ShapeConstrainedBSplineTerm.rst index 7ffbc542..2d6f8dbf 100644 --- a/docs/extension_reference/smooths/ShapeConstrainedBSplineTerm.rst +++ b/docs/extension_reference/smooths/ShapeConstrainedBSplineTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/ShapeConstrainedPSplineTerm.rst b/docs/extension_reference/smooths/ShapeConstrainedPSplineTerm.rst index c0c4e4f6..05b96854 100644 --- a/docs/extension_reference/smooths/ShapeConstrainedPSplineTerm.rst +++ b/docs/extension_reference/smooths/ShapeConstrainedPSplineTerm.rst @@ -85,7 +85,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/SoapFilmTerm.rst b/docs/extension_reference/smooths/SoapFilmTerm.rst index 2c13d052..0a345ccb 100644 --- a/docs/extension_reference/smooths/SoapFilmTerm.rst +++ b/docs/extension_reference/smooths/SoapFilmTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/SphericalSplineTerm.rst b/docs/extension_reference/smooths/SphericalSplineTerm.rst index 79451fe3..44bb4e63 100644 --- a/docs/extension_reference/smooths/SphericalSplineTerm.rst +++ b/docs/extension_reference/smooths/SphericalSplineTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/TensorProductSplineTerm.rst b/docs/extension_reference/smooths/TensorProductSplineTerm.rst index 7f254412..85a10d27 100644 --- a/docs/extension_reference/smooths/TensorProductSplineTerm.rst +++ b/docs/extension_reference/smooths/TensorProductSplineTerm.rst @@ -93,7 +93,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/smooths/ThinPlateSplineTerm.rst b/docs/extension_reference/smooths/ThinPlateSplineTerm.rst index 88dd80b3..8c822074 100644 --- a/docs/extension_reference/smooths/ThinPlateSplineTerm.rst +++ b/docs/extension_reference/smooths/ThinPlateSplineTerm.rst @@ -97,7 +97,20 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Outputs ------- -``fit(X, feature_names)`` accepts a numeric/categorical design with n rows and its d column names, initializes the term, and returns the same term instance. ``transform_new(X_new)`` returns a floating NumPy array of shape (n_new, p_term) in the fitted constraint coordinates. ``penalties`` is a list of floating square arrays, each (p_term, p_term). Multiplying the design by its coefficient vector gives the link contribution of shape (n_new,). Invalid feature names, dimensions and basis-specific domains raise ValueError; unsupported compositions raise NotImplementedError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit(X, feature_names)`` + - Initializes the term from ``n`` design rows and their ``d`` column names. Returns the fitted term. + * - ``transform_new(X_new)`` + - Floating NumPy design of shape ``(n_new, p_term)`` in fitted constraint coordinates. Multiply by the term coefficients for its link contribution. + * - ``penalties`` + - List of floating penalty matrices, each of shape ``(p_term, p_term)``. + +Invalid inputs raise ``ValueError``. Unsupported compositions raise ``NotImplementedError``. Implementation notes -------------------- diff --git a/docs/extension_reference/statistical/DaviesAlgorithm.rst b/docs/extension_reference/statistical/DaviesAlgorithm.rst index 55a3d907..4009c94b 100644 --- a/docs/extension_reference/statistical/DaviesAlgorithm.rst +++ b/docs/extension_reference/statistical/DaviesAlgorithm.rst @@ -30,8 +30,16 @@ The constructor takes no arguments. Outputs ------- -``constructor`` — Type: DaviesAlgorithm instance - Creates a numerical integration object; no probabilities are computed until davies is called. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``constructor`` + - DaviesAlgorithm instance + - Creates a numerical integration object; no probabilities are computed until davies is called. Integration method ------------------ @@ -46,41 +54,66 @@ Signature Parameters ~~~~~~~~~~ -``lb`` — Type: array-like[float], length r - Default: ``required``. Weights of the chi-square terms; signed weights are permitted. - -``nc`` — Type: array-like[float], length r - Default: ``required``. Finite nonnegative noncentralities, with no implicit scalar repetition at this low level. - -``n`` — Type: array-like[int], length r - Default: ``required``. Nonnegative integer degrees of freedom. The method casts to integer dtype; supply integers rather than relying on truncation. - -``r`` — Type: int > 0 - Default: ``required``. Number of chi-square components, matching all three array lengths. - -``sigma`` — Type: float >= 0 - Default: ``required``. Standard-normal multiplier, not its variance. - -``c_val`` — Type: float - Default: ``required``. One threshold q; call separately for several thresholds. - -``lim`` — Type: int > 0 - Default: ``required``. Integration-term budget, corresponding to nlim on the wrapper. - -``acc`` — Type: float > 0 - Default: ``required``. Requested numerical probability accuracy, corresponding to tol on the wrapper. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``lb`` + - array-like[float], length r + - ``required`` + - Weights of the chi-square terms; signed weights are permitted. + * - ``nc`` + - array-like[float], length r + - ``required`` + - Finite nonnegative noncentralities, with no implicit scalar repetition at this low level. + * - ``n`` + - array-like[int], length r + - ``required`` + - Nonnegative integer degrees of freedom. The method casts to integer dtype; supply integers rather than relying on truncation. + * - ``r`` + - int > 0 + - ``required`` + - Number of chi-square components, matching all three array lengths. + * - ``sigma`` + - float >= 0 + - ``required`` + - Standard-normal multiplier, not its variance. + * - ``c_val`` + - float + - ``required`` + - One threshold q; call separately for several thresholds. + * - ``lim`` + - int > 0 + - ``required`` + - Integration-term budget, corresponding to nlim on the wrapper. + * - ``acc`` + - float > 0 + - ``required`` + - Requested numerical probability accuracy, corresponding to tol on the wrapper. Outputs ~~~~~~~ -``probability`` — Type: float, shape () - Lower-tail probability on a successful evaluation; negative sentinels are possible on failed paths. - -``trace`` — Type: list[float], length 7 - Zero-based entries: [0] absolute-value sum/error diagnostic; [1] total integration terms; [2] number of integrations; [3] main integration interval; [4] initial truncation point; [5] convergence-factor SD; [6] parameter-search cycle count. Failed paths can contain partial/zero entries. - -``ifault`` — Type: int, shape () - Local return codes: 0 nominal completion, 1 insufficient integration budget/accuracy, 2 possible round-off error, 3 invalid component parameters. Also check probability range as explained above. These values are numerical diagnostics, not hypothesis-test outcomes. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``probability`` + - float, shape () + - Lower-tail probability on a successful evaluation; negative sentinels are possible on failed paths. + * - ``trace`` + - list[float], length 7 + - Zero-based entries: [0] absolute-value sum/error diagnostic; [1] total integration terms; [2] number of integrations; [3] main integration interval; [4] initial truncation point; [5] convergence-factor SD; [6] parameter-search cycle count. Failed paths can contain partial/zero entries. + * - ``ifault`` + - int, shape () + - Local return codes: 0 nominal completion, 1 insufficient integration budget/accuracy, 2 possible round-off error, 3 invalid component parameters. Also check probability range as explained above. These values are numerical diagnostics, not hypothesis-test outcomes. diff --git a/docs/extension_reference/statistical/exclude_too_far.rst b/docs/extension_reference/statistical/exclude_too_far.rst index 2fe5555b..42600719 100644 --- a/docs/extension_reference/statistical/exclude_too_far.rst +++ b/docs/extension_reference/statistical/exclude_too_far.rst @@ -25,20 +25,40 @@ Signature Parameters ---------- -``g1; g2`` — Type: array-like[float], each flattened to (n_grid,) - Default: ``required``. Paired grid coordinates. Lengths must agree; each grid axis must have finite nonzero range for the normalization to be defined. - -``d1; d2`` — Type: array-like[float], each flattened to (n_data,) - Default: ``required``. Paired observed coordinates; equal lengths and at least one finite observed point. They are normalized using grid bounds, not their own bounds. - -``dist`` — Type: float >= 0 - Default: ``required``. Euclidean exclusion radius after scaling the grid axes to [0,1]. It is dimensionless, not a raw distance in either input unit. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``g1; g2`` + - array-like[float], each flattened to (n_grid,) + - ``required`` + - Paired grid coordinates. Lengths must agree; each grid axis must have finite nonzero range for the normalization to be defined. + * - ``d1; d2`` + - array-like[float], each flattened to (n_data,) + - ``required`` + - Paired observed coordinates; equal lengths and at least one finite observed point. They are normalized using grid bounds, not their own bounds. + * - ``dist`` + - float >= 0 + - ``required`` + - Euclidean exclusion radius after scaling the grid axes to [0,1]. It is dimensionless, not a raw distance in either input unit. Outputs ------- -``return value`` — Type: numpy.ndarray[bool], shape (n_grid,) - True marks a grid point whose nearest observed point is strictly farther than dist. False retains it. Reshape explicitly to a mesh shape if needed. Inputs are copied; unequal paired lengths or negative dist raise ValueError. Degenerate/empty/nonfinite grids are not comprehensively validated by the implementation. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - numpy.ndarray[bool], shape (n_grid,) + - True marks a grid point whose nearest observed point is strictly farther than dist. False retains it. Reshape explicitly to a mesh shape if needed. Inputs are copied; unequal paired lengths or negative dist raise ValueError. Degenerate/empty/nonfinite grids are not comprehensively validated by the implementation. diff --git a/docs/extension_reference/statistical/liu2.rst b/docs/extension_reference/statistical/liu2.rst index 8585b1bb..68036275 100644 --- a/docs/extension_reference/statistical/liu2.rst +++ b/docs/extension_reference/statistical/liu2.rst @@ -27,23 +27,44 @@ Signature Parameters ---------- -``x`` — Type: float | one-dimensional array-like[float], shape () or (n,) - Default: ``required``. Threshold(s) at which the tail probability is evaluated. Use scalar or 1D input; arbitrary multi-axis input is not supported by the Davies wrapper. - -``lb`` — Type: array-like[float], flattened shape (r,) - Default: ``required``. Weights of independent chi-square variables. Davies supports signed weights; at least one nonzero weight is required. For the intended Liu approximation use nonnegative weights with at least one positive entry. - -``df`` — Type: array-like[float] | None, scalar/length 1 or (r,) - Default: ``None``. Degrees of freedom, default ones. A single value is repeated. psum_chisq rounds with NumPy rint and requires positive integer results; liu2 uses supplied real values directly and only checks matching lengths. Supply positive degrees of freedom. - -``lower_tail`` — Type: bool - Default: ``False``. False requests the upper-tail moment approximation; True requests its CDF for positive thresholds. Nonpositive-threshold behavior is noted below. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``x`` + - float | one-dimensional array-like[float], shape () or (n,) + - ``required`` + - Threshold(s) at which the tail probability is evaluated. Use scalar or 1D input; arbitrary multi-axis input is not supported by the Davies wrapper. + * - ``lb`` + - array-like[float], flattened shape (r,) + - ``required`` + - Weights of independent chi-square variables. Davies supports signed weights; at least one nonzero weight is required. For the intended Liu approximation use nonnegative weights with at least one positive entry. + * - ``df`` + - array-like[float] | None, scalar/length 1 or (r,) + - ``None`` + - Degrees of freedom, default ones. A single value is repeated. psum_chisq rounds with NumPy rint and requires positive integer results; liu2 uses supplied real values directly and only checks matching lengths. Supply positive degrees of freedom. + * - ``lower_tail`` + - bool + - ``False`` + - False requests the upper-tail moment approximation; True requests its CDF for positive thresholds. Nonpositive-threshold behavior is noted below. Outputs ------- -``return value`` — Type: float for scalar input; numpy.ndarray[float64] of shape (n,) for vector input - Tail probability/approximation in input threshold order. The wrapper can return NaN when numerical evaluation fails. No trace attributes are attached; use DaviesAlgorithm.davies for raw integration diagnostics. See the numerical/fallback behavior below before interpreting a returned value. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - float for scalar input; numpy.ndarray[float64] of shape (n,) for vector input + - Tail probability/approximation in input threshold order. The wrapper can return NaN when numerical evaluation fails. No trace attributes are attached; use DaviesAlgorithm.davies for raw integration diagnostics. See the numerical/fallback behavior below before interpreting a returned value. diff --git a/docs/extension_reference/statistical/n_free_smoothing_params.rst b/docs/extension_reference/statistical/n_free_smoothing_params.rst index 171191ac..03fc7017 100644 --- a/docs/extension_reference/statistical/n_free_smoothing_params.rst +++ b/docs/extension_reference/statistical/n_free_smoothing_params.rst @@ -23,14 +23,32 @@ Signature Parameters ---------- -``model`` — Type: fitted core ``nampy.gam.GAM`` - Default: ``required``. Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``model`` + - fitted core ``nampy.gam.GAM`` + - ``required`` + - Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. Outputs ------- -``return value`` — Type: int >= 0, shape () - Count of entries not marked fixed in ``smoothing_fixed_mask_``; with no mask, count of model smoothing coordinates. A fixed-SP solve can still have entries marked free: ``optimize_smoothing=False`` does not change this bookkeeping count into zero. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - int >= 0, shape () + - Count of entries not marked fixed in ``smoothing_fixed_mask_``; with no mask, count of model smoothing coordinates. A fixed-SP solve can still have entries marked free: ``optimize_smoothing=False`` does not change this bookkeeping count into zero. diff --git a/docs/extension_reference/statistical/optimizer_endpoint_diagnostics.rst b/docs/extension_reference/statistical/optimizer_endpoint_diagnostics.rst index 9972361c..705262ff 100644 --- a/docs/extension_reference/statistical/optimizer_endpoint_diagnostics.rst +++ b/docs/extension_reference/statistical/optimizer_endpoint_diagnostics.rst @@ -25,68 +25,88 @@ Signature Parameters ---------- -``model`` — Type: fitted core ``nampy.gam.GAM`` - Default: ``required``. Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. - -``conv_tol`` — Type: float > 0 - Default: ``1e-6``. Projected-gradient stationarity tolerance, scaled by 1 + abs(criterion score). Supply a positive finite value; this helper does not implement a general input validator. - -``fd_step`` — Type: float > 0 - Default: ``1e-3``. Candidate central-difference step along a common log-smoothing shift. Bound distances can reduce it; no feasible positive step gives None finite-difference diagnostics. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``model`` + - fitted core ``nampy.gam.GAM`` + - ``required`` + - Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. + * - ``conv_tol`` + - float > 0 + - ``1e-6`` + - Projected-gradient stationarity tolerance, scaled by 1 + abs(criterion score). Supply a positive finite value; this helper does not implement a general input validator. + * - ``fd_step`` + - float > 0 + - ``1e-3`` + - Candidate central-difference step along a common log-smoothing shift. Bound distances can reduce it; no feasible positive step gives None finite-difference diagnostics. Outputs ------- -``return value`` — Type: dict[str, object] | None - None for a fixed/no-selected criterion, no penalties, or no free smoothing coordinates. An unfitted core model raises an error. Otherwise the fields below describe the current endpoint, not a newly fitted model. - -``criterion_name; criterion_backend`` — Type: str; str | None - Resolved fitted criterion and its available ML/REML backend. A None backend for a non-likelihood criterion does not itself indicate fit failure. - -``optimizer_success; optimizer_message`` — Type: bool | None; str | None - Recorded optimizer result, or None when no result record exists. Recorded success and stationarity diagnostics answer different questions. - -``n_free_smoothing_params`` — Type: int s - Number of free log smoothing coordinates. - -``log_smoothing_params; gradient; projected_gradient`` — Type: list[float], each length s - Current free log penalties, raw criterion gradient, and bound-projected gradient in the same coordinate order. - -``bounds`` — Type: list[list[float]], shape (s,2) - min_sp-derived lower log bounds and unbounded upper ends. Infinite entries are possible. This is not a complete echo of every numerical optimizer's sp_log_bounds. - -``gradient_inf_norm; projected_gradient_inf_norm`` — Type: float - Largest absolute raw/projected gradient coordinate. - -``stationary_by_raw_gradient; stationary_by_projected_gradient; boundary_limited`` — Type: bool - Tolerance decisions. boundary_limited indicates a projected stationary endpoint whose raw gradient still exceeds tolerance at a reported bound. - -``at_lower_bound; at_upper_bound`` — Type: list[bool], each length s - Whether coordinates meet the reported bound tests. - -``hessian; hessian_eigenvalues; min_abs_hessian_eigenvalue`` — Type: list[list[float]] (s,s) | None; list[float] (s,) | None; float | None - Criterion curvature, its symmetric eigenvalues and the smallest eigenvalue magnitude. None means unavailable curvature, not zero curvature. - -``shared_shift_directional_derivative; shared_shift_curvature`` — Type: float; float | None - Gradient and analytic curvature along the normalized all-ones direction in free log-penalty coordinates. - -``shared_shift_fd_step; shared_shift_fd_slope; shared_shift_fd_curvature`` — Type: float | None - Feasible central-difference step and slope/curvature checks. These can be absent at a bound. - -``flat_ridge_suspected`` — Type: bool - Heuristic combining small projected gradient and weak Hessian/shared-direction curvature. It is not a proof of model nonidentifiability. - -``factor_smooth_shared_ridge_stabilized; factor_smooth_shared_ridge_shift`` — Type: bool; float | None - Factor-smooth stabilization flag and optional shift, where supplied by the route. - -``joint_gaussian_reml_outer; joint_negbin_reml_outer; joint_negbin_efs_outer; joint_negbin_postprocessed; joint_negbin_flat_ridge_stabilized`` — Type: bool - Route-specific flags for joint scale/negative-binomial nuisance fitting and postprocessing. - -``joint_log_theta; joint_negbin_initial_log_theta; family_theta`` — Type: float | None - Optional current/initial log nuisance dispersion and natural scalar family theta. - -``joint_negbin_optimizer_message; joint_negbin_optimizer_fun; joint_negbin_optimizer_nfev; joint_negbin_optimizer_njev`` — Type: str | None; float | None; int | None; int | None - Optional joint negative-binomial optimizer message, objective and evaluation counts. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - dict[str, object] | None + - None for a fixed/no-selected criterion, no penalties, or no free smoothing coordinates. An unfitted core model raises an error. Otherwise the fields below describe the current endpoint, not a newly fitted model. + * - ``criterion_name; criterion_backend`` + - str; str | None + - Resolved fitted criterion and its available ML/REML backend. A None backend for a non-likelihood criterion does not itself indicate fit failure. + * - ``optimizer_success; optimizer_message`` + - bool | None; str | None + - Recorded optimizer result, or None when no result record exists. Recorded success and stationarity diagnostics answer different questions. + * - ``n_free_smoothing_params`` + - int s + - Number of free log smoothing coordinates. + * - ``log_smoothing_params; gradient; projected_gradient`` + - list[float], each length s + - Current free log penalties, raw criterion gradient, and bound-projected gradient in the same coordinate order. + * - ``bounds`` + - list[list[float]], shape (s,2) + - min_sp-derived lower log bounds and unbounded upper ends. Infinite entries are possible. This is not a complete echo of every numerical optimizer's sp_log_bounds. + * - ``gradient_inf_norm; projected_gradient_inf_norm`` + - float + - Largest absolute raw/projected gradient coordinate. + * - ``stationary_by_raw_gradient; stationary_by_projected_gradient; boundary_limited`` + - bool + - Tolerance decisions. boundary_limited indicates a projected stationary endpoint whose raw gradient still exceeds tolerance at a reported bound. + * - ``at_lower_bound; at_upper_bound`` + - list[bool], each length s + - Whether coordinates meet the reported bound tests. + * - ``hessian; hessian_eigenvalues; min_abs_hessian_eigenvalue`` + - list[list[float]] (s,s) | None; list[float] (s,) | None; float | None + - Criterion curvature, its symmetric eigenvalues and the smallest eigenvalue magnitude. None means unavailable curvature, not zero curvature. + * - ``shared_shift_directional_derivative; shared_shift_curvature`` + - float; float | None + - Gradient and analytic curvature along the normalized all-ones direction in free log-penalty coordinates. + * - ``shared_shift_fd_step; shared_shift_fd_slope; shared_shift_fd_curvature`` + - float | None + - Feasible central-difference step and slope/curvature checks. These can be absent at a bound. + * - ``flat_ridge_suspected`` + - bool + - Heuristic combining small projected gradient and weak Hessian/shared-direction curvature. It is not a proof of model nonidentifiability. + * - ``factor_smooth_shared_ridge_stabilized; factor_smooth_shared_ridge_shift`` + - bool; float | None + - Factor-smooth stabilization flag and optional shift, where supplied by the route. + * - ``joint_gaussian_reml_outer; joint_negbin_reml_outer; joint_negbin_efs_outer; joint_negbin_postprocessed; joint_negbin_flat_ridge_stabilized`` + - bool + - Route-specific flags for joint scale/negative-binomial nuisance fitting and postprocessing. + * - ``joint_log_theta; joint_negbin_initial_log_theta; family_theta`` + - float | None + - Optional current/initial log nuisance dispersion and natural scalar family theta. + * - ``joint_negbin_optimizer_message; joint_negbin_optimizer_fun; joint_negbin_optimizer_nfev; joint_negbin_optimizer_njev`` + - str | None; float | None; int | None; int | None + - Optional joint negative-binomial optimizer message, objective and evaluation counts. diff --git a/docs/extension_reference/statistical/psum_chisq.rst b/docs/extension_reference/statistical/psum_chisq.rst index 829819f0..10c511d8 100644 --- a/docs/extension_reference/statistical/psum_chisq.rst +++ b/docs/extension_reference/statistical/psum_chisq.rst @@ -27,35 +27,60 @@ Signature Parameters ---------- -``q`` — Type: float | one-dimensional array-like[float], shape () or (n,) - Default: ``required``. Threshold(s) at which the tail probability is evaluated. Use scalar or 1D input; arbitrary multi-axis input is not supported by the Davies wrapper. - -``lb`` — Type: array-like[float], flattened shape (r,) - Default: ``required``. Weights of independent chi-square variables. Davies supports signed weights; at least one nonzero weight is required. For the intended Liu approximation use nonnegative weights with at least one positive entry. - -``df`` — Type: array-like[float] | None, scalar/length 1 or (r,) - Default: ``None``. Degrees of freedom, default ones. A single value is repeated. psum_chisq rounds with NumPy rint and requires positive integer results; liu2 uses supplied real values directly and only checks matching lengths. Supply positive degrees of freedom. - -``nc`` — Type: array-like[float] | None, scalar/length 1 or (r,) - Default: ``None``. Noncentralities, default zeros; a single value is repeated. Supply finite nonnegative values. Mismatched vector lengths raise ValueError. - -``sigz`` — Type: float - Default: ``0.0``. Multiplier of an independent standard normal term. Nonpositive values are treated as zero. - -``lower_tail`` — Type: bool - Default: ``False``. False requests the upper tail; True requests the CDF on a successful Davies evaluation. Read the fallback qualification below. - -``tol`` — Type: float > 0 - Default: ``2e-5``. Requested numerical integration accuracy; not a statistical confidence level. - -``nlim`` — Type: int > 0 - Default: ``100000``. Maximum integration-term budget passed to Davies. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``q`` + - float | one-dimensional array-like[float], shape () or (n,) + - ``required`` + - Threshold(s) at which the tail probability is evaluated. Use scalar or 1D input; arbitrary multi-axis input is not supported by the Davies wrapper. + * - ``lb`` + - array-like[float], flattened shape (r,) + - ``required`` + - Weights of independent chi-square variables. Davies supports signed weights; at least one nonzero weight is required. For the intended Liu approximation use nonnegative weights with at least one positive entry. + * - ``df`` + - array-like[float] | None, scalar/length 1 or (r,) + - ``None`` + - Degrees of freedom, default ones. A single value is repeated. psum_chisq rounds with NumPy rint and requires positive integer results; liu2 uses supplied real values directly and only checks matching lengths. Supply positive degrees of freedom. + * - ``nc`` + - array-like[float] | None, scalar/length 1 or (r,) + - ``None`` + - Noncentralities, default zeros; a single value is repeated. Supply finite nonnegative values. Mismatched vector lengths raise ValueError. + * - ``sigz`` + - float + - ``0.0`` + - Multiplier of an independent standard normal term. Nonpositive values are treated as zero. + * - ``lower_tail`` + - bool + - ``False`` + - False requests the upper tail; True requests the CDF on a successful Davies evaluation. Read the fallback qualification below. + * - ``tol`` + - float > 0 + - ``2e-5`` + - Requested numerical integration accuracy; not a statistical confidence level. + * - ``nlim`` + - int > 0 + - ``100000`` + - Maximum integration-term budget passed to Davies. Outputs ------- -``return value`` — Type: float for scalar input; numpy.ndarray[float64] of shape (n,) for vector input - Tail probability/approximation in input threshold order. The wrapper can return NaN when numerical evaluation fails. No trace attributes are attached; use DaviesAlgorithm.davies for raw integration diagnostics. See the numerical/fallback behavior below before interpreting a returned value. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - float for scalar input; numpy.ndarray[float64] of shape (n,) for vector input + - Tail probability/approximation in input threshold order. The wrapper can return NaN when numerical evaluation fails. No trace attributes are attached; use DaviesAlgorithm.davies for raw integration diagnostics. See the numerical/fallback behavior below before interpreting a returned value. diff --git a/docs/extension_reference/statistical/resolve_smoothing_method.rst b/docs/extension_reference/statistical/resolve_smoothing_method.rst index cfa24121..4ec56836 100644 --- a/docs/extension_reference/statistical/resolve_smoothing_method.rst +++ b/docs/extension_reference/statistical/resolve_smoothing_method.rst @@ -23,17 +23,36 @@ Signature Parameters ---------- -``model`` — Type: fitted core ``nampy.gam.GAM`` - Default: ``required``. Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. - -``method`` — Type: str | None - Default: ``required (None is allowed)``. None or 'auto' selects a supported default. Strings are lowercased; GCV.Cp/GACV.Cp and likelihood spellings follow criterion normalization. Unsupported names raise ValueError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``model`` + - fitted core ``nampy.gam.GAM`` + - ``required`` + - Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. + * - ``method`` + - str | None + - ``required (None is allowed)`` + - None or 'auto' selects a supported default. Strings are lowercased; GCV.Cp/GACV.Cp and likelihood spellings follow criterion normalization. Unsupported names raise ValueError. Outputs ------- -``return value`` — Type: str, scalar - Resolved method name. auto prefers available REML, then known-scale ubreaic, then GCV, then fixed. Extended-family predictive criterion spellings can normalize to reml; the result is a criterion name, not an optimizer or a completed fit. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - str, scalar + - Resolved method name. auto prefers available REML, then known-scale ubreaic, then GCV, then fixed. Extended-family predictive criterion spellings can normalize to reml; the result is a criterion name, not an optimizer or a completed fit. diff --git a/docs/extension_reference/statistical/supports_smoothing_method.rst b/docs/extension_reference/statistical/supports_smoothing_method.rst index adff954c..15438e27 100644 --- a/docs/extension_reference/statistical/supports_smoothing_method.rst +++ b/docs/extension_reference/statistical/supports_smoothing_method.rst @@ -23,17 +23,36 @@ Signature Parameters ---------- -``model`` — Type: fitted core ``nampy.gam.GAM`` - Default: ``required``. Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. - -``method`` — Type: str - Default: ``required``. Canonical lower-case method: fixed, gcv, gacv, ubre, aic, ubreaic, ml, reml, p-ml, p-reml, laml, ncv or qncv. This helper does not lowercase or resolve aliases; unknown values raise ValueError. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``model`` + - fitted core ``nampy.gam.GAM`` + - ``required`` + - Use a fitted core model, or ``estimator.gam_`` from a wrapper. Required compiled/fitted state is read from this object; passing a wrapper directly is not supported. + * - ``method`` + - str + - ``required`` + - Canonical lower-case method: fixed, gcv, gacv, ubre, aic, ubreaic, ml, reml, p-ml, p-reml, laml, ncv or qncv. This helper does not lowercase or resolve aliases; unknown values raise ValueError. Outputs ------- -``return value`` — Type: bool, shape () - Reports this model/family criterion capability, including scale, transformed-coefficient/observation and derivative guards. It does not certify every optimizer, formula composition or convergence condition; fitting performs further validation. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - bool, shape () + - Reports this model/family criterion capability, including scale, transformed-coefficient/observation and derivative guards. It does not certify every optimizer, formula composition or convergence condition; fitting performs further validation. diff --git a/docs/neural_reference/extensions/NeuralEnsemble.rst b/docs/neural_reference/extensions/NeuralEnsemble.rst index 6b92456c..9a04ed43 100644 --- a/docs/neural_reference/extensions/NeuralEnsemble.rst +++ b/docs/neural_reference/extensions/NeuralEnsemble.rst @@ -49,7 +49,26 @@ Dimensions: ``n`` rows, ``d`` input columns, ``p`` fitted coefficients, ``q`` re Returns and fitted outputs -------------------------- -Construction returns an unfitted ensemble; ``fit`` accepts data, explicit validation rows, offsets and weights, returns self and exposes ``estimators_``. Regression predict returns the mean member response, shaped like a member's predictions. Classification predict_proba averages probabilities in ``classes_`` order, and predict returns the most probable class. score returns R² or accuracy, respectively. ``predict_components`` returns ``AdditivePrediction`` containing the mean link-scale contributions. ``predict_component_uncertainty`` returns ``EnsembleAdditivePrediction`` containing mean components and between-member variation; missing selected terms contribute zero for that member. Variation across members measures training/selection variability and is not automatically a calibrated confidence interval. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - ``fit`` + - Fits the members and exposes them in ``estimators_``. Accepts explicit validation data, offsets and weights, and returns the ensemble. + * - ``predict`` + - Mean member response for regression or most probable class for classification. + * - ``predict_proba`` + - Mean member probabilities in ``classes_`` order. + * - ``predict_components`` + - Mean link-scale contributions as ``AdditivePrediction``. + * - ``predict_component_uncertainty`` + - Mean contributions and between-member variation as ``EnsembleAdditivePrediction``. Missing selected terms contribute zero for that member. + * - ``score`` + - R² for regression and accuracy for classification. + +Between-member variation describes training or selection variability. Calibrated confidence intervals require a separate inference method. :ref:`Custom architecture contract ` · :doc:`All training arguments ` · :doc:`Neural distributions <../families/index>` diff --git a/docs/scripts/build_reference_manual.py b/docs/scripts/build_reference_manual.py index 96b7e395..483efe31 100644 --- a/docs/scripts/build_reference_manual.py +++ b/docs/scripts/build_reference_manual.py @@ -377,25 +377,12 @@ def _remember(page: Page) -> Page: def ensure_generated_fragments() -> None: - """Write the reference fragments Sphinx creates when a builder starts. - - Those fragments are not checked in. The manual test runs before the docs - build, so a clean checkout does not have them yet. - """ + """Refresh the generated reference fragments before reading them.""" directory = DOCS / "_generated" / "reference" sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "_ext")) - statistical = ( - "SurvivalGAM.inc", - "CoxGAM.inc", - "CalibratedQuantileGAM.inc", - "GAMRegressor.inc", - "GAMClassifier.inc", - "GAMLSS.inc", - ) - if any(not (directory / name).is_file() for name in statistical): - from public_reference import generate + from public_reference import generate - generate(DOCS.parent) + generate(DOCS.parent) if any( not (directory / name).is_file() for name in ("GAM_core_parameters.inc", "neural_fit_contract.inc") @@ -655,6 +642,23 @@ def _is_argument_table(headers: list[str]) -> bool: def _render_table(table: Table) -> str: + if table.headers == ["Operation", "Result"]: + header = r"\textbf{Operation} & \textbf{Result} \\ \hline" + rows = [rf"{latex_inline(name)} & {latex_inline(result)} \\" for name, result in table.rows] + return "\n".join([ + r"\begingroup\small", + r"\setlength{\LTpre}{0.4em}\setlength{\LTpost}{0.4em}", + r"\renewcommand{\arraystretch}{1.3}", + r"\begin{longtable}{@{}>{\raggedright\arraybackslash}p{0.32\linewidth}" + r">{\raggedright\arraybackslash}p{\dimexpr0.68\linewidth-2\tabcolsep\relax}@{}}", + header, + r"\endfirsthead", + header, + r"\endhead", + *rows, + r"\end{longtable}", + r"\endgroup", + ]) argument_names = _is_argument_table(table.headers) lines = [] for row in table.rows: @@ -791,7 +795,8 @@ def render_blocks(blocks: list, *, topic: bool) -> list[str]: rendered.append(rf"{latex_inline(block.text)}\par") elif isinstance(block, Heading): title = SECTION_TITLES.get(block.text, block.text) - rendered.append(rf"\Rdsection{{{latex_inline(title)}}}") + command = "Rdsubsection" if block.level > 3 else "Rdsection" + rendered.append(rf"\{command}{{{latex_inline(title)}}}") elif isinstance(block, Bullets): lines = [r"\begin{itemize}[leftmargin=1.35em,itemsep=0.22em,topsep=0.4em,parsep=0.05em]"] lines.extend(rf"\item {latex_inline(item)}" for item in block.items) @@ -984,6 +989,7 @@ def render_manual(pages: list[Page], version: str, built_on: str) -> str: \\setmathfont{{latinmodern-math.otf}} \\usepackage[margin=2.8cm,top=2.35cm,bottom=2.4cm,headheight=16.5pt,headsep=9pt]{{geometry}} \\usepackage{{graphicx}} +\\usepackage{{array,longtable}} \\usepackage{{enumitem}} \\providecommand{{\\UseTaggingSocket}}[1]{{}} \\providecommand{{\\SuspendTagging}}[1]{{}} @@ -1006,7 +1012,7 @@ def render_manual(pages: list[Page], version: str, built_on: str) -> str: \\definecolor{{coderule}}{{HTML}}{{2C5F73}} \\hypersetup{{colorlinks=true,linkcolor=ink,urlcolor=accent,pdftitle={{NAMpy Reference Manual}}}} {pygments_preamble()} -\\fvset{{fontsize=\\small,breaklines=true,breakindent=1.7em,breaksymbol=\\textcolor{{mist}}{{\\scriptsize\\ensuremath{{\\hookrightarrow}}}}}} +\\fvset{{fontsize=\\small,breaklines=true,breakindent=1.7em,breaksymbolleft={{}},breaksymbolright={{}}}} \\newenvironment{{Rdcode}} {{\\VerbatimEnvironment \\begin{{snugshade}} @@ -1043,7 +1049,8 @@ def render_manual(pages: list[Page], version: str, built_on: str) -> str: \\newcommand{{\\Rdlink}}[2]{{\\hyperlink{{#1}}{{\\textcolor{{accent}}{{#2}}}}}} \\newcommand{{\\Rdext}}[2]{{\\href{{#1}}{{\\textcolor{{accent}}{{#2}}}}}} \\newcommand{{\\Rdcaption}}[1]{{\\par\\vspace{{0.45em}}\\noindent{{\\color{{mist}}\\footnotesize #1}}\\par\\nopagebreak\\vspace{{0.18em}}}} -\\newcommand{{\\Rdsection}}[1]{{\\par\\vspace{{1.05em}}\\noindent{{\\color{{accent}}\\bfseries #1}}\\par\\nopagebreak\\vspace{{0.28em}}}} +\\newcommand{{\\Rdsection}}[1]{{\\par\\Needspace{{4\\baselineskip}}\\vspace{{1.05em}}\\noindent{{\\color{{accent}}\\bfseries #1}}\\par\\nopagebreak\\vspace{{0.28em}}}} +\\newcommand{{\\Rdsubsection}}[1]{{\\par\\Needspace{{3\\baselineskip}}\\vspace{{0.64em}}\\noindent{{\\color{{slate}}\\bfseries #1}}\\par\\nopagebreak\\vspace{{0.14em}}}} \\setcounter{{tocdepth}}{{1}} \\begin{{document}} \\thispagestyle{{empty}} diff --git a/docs/statistical_reference/families/bccg_lss.rst b/docs/statistical_reference/families/bccg_lss.rst index 54096c4b..44a3658e 100644 --- a/docs/statistical_reference/families/bccg_lss.rst +++ b/docs/statistical_reference/families/bccg_lss.rst @@ -11,11 +11,15 @@ bccg_lss * **Conditional mean:** :math:`E[Y]=M_1,\quad M_k=\mu^k E[U^{k/\nu}\mid U>0],\quad U\sim N(1,\sigma^2\nu^2)\quad(\nu\ne0)` * **Conditional variance:** :math:`\operatorname{Var}(Y)=M_2-M_1^2\text{ where finite};\quad\nu<0:\ M_k<\infty\iff\nu<-k` -Natural columns are ``mu, sigma, nu`` with log/log/identity predictors. Mu is not generally the response mean or exact median. Positive responses require a Jacobian and a truncated-normal normalizer. At nu=0 the law is lognormal. Mean is infinite for -1<=nu<0; variance is NaN there and infinite for -2<=nu<-1. Finite moment quadrature has explicit numerical limits, including negative-power variance below sigma=sqrt(machine epsilon). At least three distinct positive-weight responses are required; this necessary guard does not establish estimability of arbitrary formulas. +* **Parameters.** Natural columns ``mu, sigma, nu`` use log, log and identity links. Positive responses require a Jacobian and truncated-normal normalizer. At ``nu=0`` the law is lognormal. +* **Moments.** Compute the mean and median from the response law. The mean is infinite for ``-1 <= nu < 0``. Variance is ``NaN`` there and infinite for ``-2 <= nu < -1``. Finite quadrature has numerical limits, including negative-power variance below ``sigma=sqrt(machine epsilon)``. +* **Fitting.** Supply at least three distinct positive-weight responses. Formula estimability also depends on the fitted design. Distribution reference: `gamlss.dist::BCCG `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic joint REML with outer_newton, bfgs and efs are validated, including three smoothed predictors. Analytic likelihood derivatives through order four include the truncated-normal normalizer and the zero-power limit. Outer gradients/Hessians are checked with offsets and nonunit/zero weights; selected endpoints are compared to an independent derivative-free REML profile. Other method labels retain mgcv general-family coercion to REML, not separate ML/GCV/UBRE/NCV criteria. The optim route lacks family-defined null deviance scaling; magic and nlm.fd are also unavailable. Neural fitting, alternate links, censoring/truncation and deviance residuals remain unsupported. Generic conditional and approximate smoothing-uncertainty covariance transport are available; simulation/refit centile bands are not. Tight stopping rules may report nonconvergence at a float64 plateau; such fits remain ineligible for family ranking. This is distinct from mgcv's existing censored bcg likelihood. +* **Fit.** Fixed smoothing and joint REML with ``outer_newton``, ``bfgs`` or ``efs`` are validated, including fits with three smoothed predictors. General-family method aliases resolve to REML. ``optim``, ``magic`` and ``nlm.fd`` are unavailable. +* **Numerical checks.** Derivatives through order four include the normalizer and zero-power limit. Outer checks cover offsets and nonunit or zero weights. An independent derivative-free REML profile checks selected endpoints. +* **Inference and limits.** Conditional and approximate smoothing-adjusted covariance are available. Simulation or refit centile bands, neural fitting, alternate links, censoring, truncation and deviance residuals are outside this route. Use the separate censored ``bcg`` likelihood for its own supported scope. Fits that stop at a nonconverged float64 plateau are ineligible for family ranking. Box-Cox Cole-Green regression models positive responses with three predictors for mu, sigma and a real transformation power nu. Mu is diff --git a/docs/statistical_reference/families/bcg.rst b/docs/statistical_reference/families/bcg.rst index 4e531c02..dbf7399c 100644 --- a/docs/statistical_reference/families/bcg.rst +++ b/docs/statistical_reference/families/bcg.rst @@ -170,13 +170,13 @@ transforms the second entry to SD. The default estimates both parameters, starting at working values ``[1, 0]``. Positive precision weights replace log SD by ``logSD - log(weight)/2``. -Censoring uses explicit paired response data. Nonpositive second-column +**Censoring input.** Censoring uses explicit paired response data. Nonpositive second-column values denote left censoring, positive unequal finite endpoints denote an interval, and ``+Inf`` denotes right censoring. Source initialization uses the input response scale. Predictions describe the transformed Gaussian location; they do not apply an inverse Box-Cox mean correction. -The source fixed constructor has a specific failure: positive +**Fixed parameters.** The source fixed constructor has a specific failure: positive ``theta=[lambda, sd]`` stores three working entries, ``[lambda, log(lambda), log(sd)]``. Its fitted source call fails with an ``ls$lsth2`` indexing error. NAMpy rejects this malformed fitted state with @@ -196,11 +196,12 @@ constructor repair is performed. A nonpositive second constructor entry starts estimation and retains that entry as the initial working log SD, following source initialization order. -References cover the near-zero-lambda expansions, all censor blocks, fourth +**Fitting support.** References cover the near-zero-lambda expansions, all censor blocks, fourth location and second ancillary derivatives, exact and mixed responses, precision weights, offsets, fixed/estimated ancillary parameters, and fixed/ML/REML smoothing. Estimated-parameter vector fits cover all three links. -EFS uses the two-parameter source ``estimate.theta`` update inside PIRLS; + +**EFS.** EFS uses the two-parameter source ``estimate.theta`` update inside PIRLS; fixed/estimated ancillary vector and mixed-response endpoints have direct references. Theta-update references also cover external dispersion one/two; the captured scale-two source updates warn about step failure and retain their @@ -209,7 +210,7 @@ smoothing parameter: the all-fixed-SP source call errors. Positive ``min_sp`` and rank-deficient outer-uncertainty combinations retain the extended-family guards described above. -Source AIC omits scale/Box-Cox Jacobians and is not an independently normalized +**Likelihood reporting.** Source AIC omits scale/Box-Cox Jacobians and is not an independently normalized Box-Cox density. Source saturated-likelihood derivative arrays are zero despite the value's ancillary dependence. Exactly transformed censor endpoints can produce source NaNs in signed density differences; those NaNs remain visible. diff --git a/docs/statistical_reference/families/beinf_lss.rst b/docs/statistical_reference/families/beinf_lss.rst index b41200f2..088b0a9e 100644 --- a/docs/statistical_reference/families/beinf_lss.rst +++ b/docs/statistical_reference/families/beinf_lss.rst @@ -11,11 +11,16 @@ beinf_lss * **Conditional mean:** :math:`m=\mathbb E[Y\mid x]=\pi_1+\pi_I\mu` * **Conditional variance:** :math:`\operatorname{Var}(Y\mid x)=\pi_I\left[\frac{\mu(1-\mu)}{1+\phi}+(\mu-m)^2\right]+\pi_0m^2+\pi_1(1-m)^2` -Four formula keys are ``mu, phi, pi0, pi1``. Natural columns are ``mu, phi, pi0, pi1, pi_interior``; raw columns are logit(mu), log(phi), log(pi0/pi_interior), log(pi1/pi_interior). The last two are coupled category log ratios, not independent probability logits. Components contain exactly four predictors; the interior probability depends on both atom predictors and has no separate term. Full covariance is retained for all five natural errors. R BEINF uses sigma=1/sqrt(1+phi), nu=pi0/pi_interior, tau=pi1/pi_interior. All components and distinct interior observations are required for fitting; neural fitting uses its normalized likelihood. The saved gamlss.dist 6.1.1 variance hook adds rather than subtracts squared mean; NAMpy uses the normalized mixture variance and records this discrepancy. +* **Predictors.** Formula keys ``mu, phi, pi0, pi1`` map to ``logit(mu)``, ``log(phi)``, ``log(pi0/pi_interior)`` and ``log(pi1/pi_interior)``. The atom predictors are coupled category log ratios. +* **Natural output.** All five natural-parameter standard errors use the full covariance. The columns are ``mu, phi, pi0, pi1, pi_interior``. The fifth column depends on both atom predictors and has no separate additive term. +* **Fitting.** All components and distinct interior observations are required. Neural fitting uses its normalized likelihood. +* **R mapping.** R BEINF uses ``sigma=1/sqrt(1+phi)``, ``nu=pi0/pi_interior`` and ``tau=pi1/pi_interior``. NAMpy uses the normalized mixture variance. The saved gamlss.dist 6.1.1 variance hook adds the squared mean where that variance subtracts it. Distribution reference: `gamlss.dist::BEINF `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force. +* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported. +* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable. +* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations. Inflated beta regression models exact zeros and ones separately from continuous proportions inside the unit interval. Mu and phi diff --git a/docs/statistical_reference/families/betabinomial_lss.rst b/docs/statistical_reference/families/betabinomial_lss.rst index 3f955bbe..bf2fbdd2 100644 --- a/docs/statistical_reference/families/betabinomial_lss.rst +++ b/docs/statistical_reference/families/betabinomial_lss.rst @@ -15,7 +15,9 @@ Natural columns are ``mu, kappa``, with logit/log links. Supply ``context={'tria Distribution reference: `gamlss.dist::BB `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force. +* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported. +* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable. +* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations. Beta-binomial regression mixes binomial success probabilities with a beta law. It describes counts with a known denominator and additional diff --git a/docs/statistical_reference/families/clog.rst b/docs/statistical_reference/families/clog.rst index 8a13e4cd..438d99ce 100644 --- a/docs/statistical_reference/families/clog.rst +++ b/docs/statistical_reference/families/clog.rst @@ -164,24 +164,28 @@ uncensored logistic standard deviation is ``scale * pi / sqrt(3)``. The family describes a continuous logistic response, with one additive location predictor. Supported links are identity, log and square root. -Responses use the same explicit paired encoding as ``cnorm`` above: +**Censoring input.** Responses use the same explicit paired encoding as ``cnorm`` above: equal values are exact observations, distinct finite values define an interval in either order, and infinite second bounds define one-sided censoring. Predictions return the latent logistic location and need no -censor bounds. Observation weights are precision, giving each row a scale +censor bounds. + +**Scale and weights.** Observation weights are precision, giving each row a scale ``exp(theta_working) / sqrt(weight)``. A positive constructor ``theta`` fixes scale; zero or ``None`` estimates it from working value zero; negative ``theta`` starts estimation at ``log(abs(theta))``. This last convention differs from the source ``cnorm`` constructor. -Static R references cover all returned deviance derivative fields through +**Validated fits.** Static R references cover all returned deviance derivative fields through fourth order, saturation derivatives, tails, precision weights, mixed censoring, fixed/estimated scale, fixed smoothing and ML/REML selection, offsets, two smooths, parametric-only fits, covariance, EDF, likelihood criteria, predictions, residuals, persistence and additive reconstruction. Fixed- and estimated-scale optimizers have targeted references, including weighted ancillary estimation, successful estimated-scale nlm fits, and -nonidentity REML/BFGS and ML/optim fits. EFS estimates scale inside each PIRLS +nonidentity REML/BFGS and ML/optim fits. + +**EFS.** EFS estimates scale inside each PIRLS iteration using the source ``estimate.theta`` update, and retains the accepted EFS fit rather than estimating theta again in a final solve. EFS references cover exact and mixed-censored responses, all three links, @@ -189,7 +193,7 @@ positive precision weights and positive external dispersion. EFS supplies no smoothing-parameter covariance or unconditional uncertainty correction. The example is ``examples/example_clog_gam.py``. -In captured fixed-scale nlm/optim cases the smooth reaches its linear null +**Optimizer endpoints.** In captured fixed-scale nlm/optim cases the smooth reaches its linear null space. Large raw smoothing parameters are not compared across endpoints; fitted effects, covariance, criterion, and the limiting EDF retain their original tolerances. Other accepted cases compare smoothing parameters @@ -218,7 +222,7 @@ Remaining restrictions have distinct causes: retain the documented extended-family restrictions. These do not imply that every upstream composition or dataset is rejected. -The port retains source arithmetic and formulas, including interval +**Likelihood reporting.** The port retains source arithmetic and formulas, including interval derivative expressions and the unusual ``aic`` hook, which is independent of fitted location. Consequently reported source-compatible AIC and derived log likelihood are not substitutes for an independently normalized logistic diff --git a/docs/statistical_reference/families/cnorm.rst b/docs/statistical_reference/families/cnorm.rst index a8c7addf..022897c2 100644 --- a/docs/statistical_reference/families/cnorm.rst +++ b/docs/statistical_reference/families/cnorm.rst @@ -163,7 +163,7 @@ Parameterization and interpretation ``("cnorm", {"theta": 1})`` also resolve the family. It is a regression family; the response's second column is a censor bound, not a class label. -The reference scope covers fixed or estimated response SD, fixed smoothing +**Fitting support.** The reference scope covers fixed or estimated response SD, fixed smoothing or ML/REML smoothing selection, including joint objective gradients and Hessians. Identity, log and square-root links have family-kernel references; fixed-SD, fixed-smoothing fits also cover positive precision weights and @@ -172,14 +172,14 @@ no-intercept and parametric-only fits, conditional rank-deficient fits, BFGS/optim/nlm endpoints, and fixed-SD EFS. These targeted checks do not establish cross-platform CI acceptance. -For conditional fits with exactly aliased columns, the retained coefficient +**Aliased designs.** For conditional fits with exactly aliased columns, the retained coefficient can differ across numerical factorizations. Their parity checks compare estimable coefficient effects and covariance kernels, including predictions that preserve the training alias relation. Raw covariance coordinates and predictions outside that relation are not uniquely identified; no parity claim is made for such nonestimable newdata. -A vector response represents exact observations. A two-column response, +**Censoring input.** A vector response represents exact observations. A two-column response, provided as ``cbind(value, bound)`` in a formula or an explicit ``(n, 2)`` array, encodes each observation as follows: @@ -209,19 +209,21 @@ For a negative supplied value, mgcv 1.9-4 actually retains that value as the initial *log standard deviation*, despite the manual's negative-SD wording. ``getTheta()`` returns working log SD and ``getTheta(trans=True)`` returns SD. -The source uses observation weights as precision: each row's SD is +**Precision weights.** The source uses observation weights as precision: each row's SD is ``exp(theta_working) / sqrt(weight)``. They are not frequency weights. Zero weights are rejected during fitting: upstream mixed-censor interval observations can produce undefined derivatives and an error, even though some uncensored zero-weight fits converge. They are not automatically -omitted rows. Positive ``min_sp`` is also unsupported, and estimated SD with +omitted rows. + +**Selection limits.** Positive ``min_sp`` is also unsupported, and estimated SD with the ``efs`` optimizer is guarded. Estimated SD with nonunit external dispersion is also guarded: a captured upstream failed outer fit returns coefficients from a different parameter state. Fixed-SD fits accept positive external dispersion. Rank-deficient outer uncertainty retains the shared extended-family guard. The executable example uses unit weights. -The implementation preserves two mgcv 1.9-4 AIC quirks: its exact-observation +**Likelihood reporting.** The implementation preserves two mgcv 1.9-4 AIC quirks: its exact-observation branch omits the log-SD Jacobian after standardizing, and its later ``bound <= 0`` branch also replaces contributions from nonpositive exact or finite interval bounds. Consequently source-compatible AIC and derived diff --git a/docs/statistical_reference/families/cpois.rst b/docs/statistical_reference/families/cpois.rst index e2595427..39f77f25 100644 --- a/docs/statistical_reference/families/cpois.rst +++ b/docs/statistical_reference/families/cpois.rst @@ -165,7 +165,7 @@ unequal pair denotes the discrete event ``min(value,bound) < Y <= max(value,boun For example, ``[2, 4]`` includes counts three and four. Predictions return the underlying mean, with standard errors for that mean. -The source likelihood, deviance, saturated likelihood and derivative hooks +**Weights and numerical evaluation.** The source likelihood, deviance, saturated likelihood and derivative hooks ignore observation weights. They are not frequency-weighted Poisson hooks; nonunit-weight reference fits retain this source convention. Density and tail probabilities follow the scalar R Mathlib ``dpois``/``ppois`` branches, including @@ -173,7 +173,7 @@ extreme-tail and degenerate-mean cases. Location derivatives through fourth order, the discrete saturated-likelihood correction, residuals and null calculations use those source probabilities. -Actual-mgcv fixtures cover exact/mixed responses, all three links, fixed +**Fitting support.** Actual-mgcv fixtures cover exact/mixed responses, all three links, fixed smoothing, ML/REML selection, positive external dispersion and observation weights, coefficients, covariance, EDF, likelihood criteria, residuals and predictions/SE. The alternative ``bfgs``, ``optim``, ``nlm`` and ``efs`` routes have direct diff --git a/docs/statistical_reference/families/lognormal_lss.rst b/docs/statistical_reference/families/lognormal_lss.rst index 8a36367e..4b1f6098 100644 --- a/docs/statistical_reference/families/lognormal_lss.rst +++ b/docs/statistical_reference/families/lognormal_lss.rst @@ -15,7 +15,9 @@ Natural columns are ``loc, scale`` for log(Y); identity/log predictors are used. Distribution reference: `gamlss.dist::LOGNO `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force. +* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported. +* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable. +* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations. A lognormal model assumes Gaussian variation after taking logs of the response. This is a response distribution, rather than merely diff --git a/docs/statistical_reference/families/scat.rst b/docs/statistical_reference/families/scat.rst index eb3ce662..a4d5ae85 100644 --- a/docs/statistical_reference/families/scat.rst +++ b/docs/statistical_reference/families/scat.rst @@ -162,7 +162,7 @@ Parameterization and interpretation single-predictor ``mgcv::scat`` family. Import it from ``nampy.gam.families`` or use ``family="scat"`` in ``GAM``. -``theta`` contains the degrees of freedom and scale, in that order. Two +**Ancillary parameters.** ``theta`` contains the degrees of freedom and scale, in that order. Two positive values fix both parameters. Any negative entry requests estimation of both parameters, using their absolute values as constructor initial values. ``None`` or a zero entry selects the upstream default working parameters. @@ -176,7 +176,7 @@ these constructor values with working parameters degrees of freedom is at or below ``min_df``, the constructor warns and resets ``min_df`` to ``0.9 * abs(theta[0])``, following upstream. -The location predictor supports ``identity``, ``log`` and ``inverse`` links. +**Links and variance.** The location predictor supports ``identity``, ``log`` and ``inverse`` links. With degrees of freedom ``nu`` and scale ``sigma``, the conditional variance is ``sigma**2 * nu / (nu - 2)`` when ``nu > 2``. The scale in ``theta`` is a distribution parameter, distinct from the optional GAM dispersion argument. @@ -184,11 +184,14 @@ distribution parameter, distinct from the optional GAM dispersion argument. The implementation follows mgcv 1.9-4 ``R/efam.r::scat``, including its observed and Fisher derivatives. See the `upstream scat documentation `_. -Fixed smoothing and ``ML``/``REML`` selection support fixed or estimated + +**Smoothing selection.** Fixed smoothing and ``ML``/``REML`` selection support fixed or estimated ancillary parameters. With ``optimize_smoothing=False``, an explicitly selected ``ML`` or ``REML`` criterion still governs ancillary estimation; ``smoothing_method="fixed"`` uses REML. ``LAML`` is a REML alias. ``GCV.Cp``, ``P-ML`` and ``P-REML`` use the -upstream extended-family REML route. Unsupported criteria such as NCV +upstream extended-family REML route. + +**Fit restrictions.** Unsupported criteria such as NCV raise an explicit error, including with fixed smoothing parameters. Joint estimation with the ``efs`` optimizer is unsupported and raises an explicit error. ``ML`` with zero observation weights is also explicitly guarded: @@ -199,14 +202,14 @@ estimated ancillary parameters. The fixed-penalty offset parameterization has not been ported for joint fitting and smoothing-uncertainty corrections; zero ``min_sp`` retains the ordinary supported path. -Rank-deficient designs that drop coefficients are rejected when fitting +**Rank and covariance.** Rank-deficient designs that drop coefficients are rejected when fitting requires outer-parameter uncertainty corrections. The upstream correction attempts Cholesky factorization of the full singular coefficient Hessian; rounding can change whether that correction is included, affecting AIC and unconditional covariance across platforms. Conditional fitting with both ancillary parameters and smoothing fixed remains available. -The default external dispersion is one. A positive ``GAM(scale=...)`` +**External dispersion.** The default external dispersion is one. A positive ``GAM(scale=...)`` override follows the upstream criterion and covariance scaling. For fixed ancillary parameters and fixed smoothing, ``scale=2`` doubles the conditional coefficient covariance without changing coefficients or distribution @@ -214,7 +217,7 @@ parameters. When smoothing or ancillary parameters are estimated, the external dispersion can change their optimum; it is not merely a multiplier on the reported standard errors. -Outer ``bfgs``, ``optim`` and ``nlm`` routes have endpoint references for +**Alternative optimizers.** Outer ``bfgs``, ``optim`` and ``nlm`` routes have endpoint references for identity-link, positive-weight models with one cubic smooth and fixed or estimated ancillary parameters. ``optim`` comparisons use matching ``control={"epsilon": 1e-10, "optim": {"factr": 10}}`` to resolve a flat @@ -222,7 +225,7 @@ ancillary-parameter optimum. BFGS retains its path-dependent approximate Hessian; the final derivative-free ``nlm`` and ``optim`` fits do not supply a smoothing-parameter uncertainty correction. -Conditional and unconditional coefficient covariance, effective degrees of +**Inference and residuals.** Conditional and unconditional coefficient covariance, effective degrees of freedom, prediction standard errors, likelihood, AIC and BIC are available. Unconditional corrections require an outer-parameter Hessian: they are absent when both ancillary parameters and all smoothing parameters are diff --git a/docs/statistical_reference/families/shash.rst b/docs/statistical_reference/families/shash.rst index d55eb75d..b40fb56d 100644 --- a/docs/statistical_reference/families/shash.rst +++ b/docs/statistical_reference/families/shash.rst @@ -179,21 +179,21 @@ positive ``b``. ``GAMLSS.predict`` returns ``(mu, sigma, epsilon, delta)``; CDF/log-CDF and inverse-transform simulation hooks are present. Source GAM response prediction returns ``(mu, log_sigma, epsilon, log_delta)``. -The fitting likelihood includes the source ridge +**Fitting criterion.** The fitting likelihood includes the source ridge ``-phi_pen * log(delta)**2`` (``phiPen`` is an accepted alias). Public normalized density scoring omits that estimation ridge. All analytic derivatives through fourth order are supplied. Fixed SP, Newton-selected REML and EFS references cover initialization, covariance, criterion/EDF, AIC/logLik, predictions/SE, residuals and summary tables. -The EFS parity captures provide the same explicit initial smoothing parameters +**EFS initialization.** The EFS parity captures provide the same explicit initial smoothing parameters to both implementations. Source ``initial.spg`` uses the initially reparameterized design with the original penalty coordinates: an arbitrary eigenvector sign can change its starting parameters and the finite EFS endpoint. Static source sign-transport checks record this dependence and verify common-start prediction, covariance, penalty and EDF invariants. -Nonzero offsets are rejected. The source fitting likelihood's bin lookup +**Prediction and residual limits.** Nonzero offsets are rejected. The source fitting likelihood's bin lookup excludes a lower ``-Inf`` endpoint: an exactly zero standardized residual therefore produces positive-infinite source likelihood. The normalized density and residual expression stay finite there. Residual centering retains the diff --git a/docs/statistical_reference/families/twlss.rst b/docs/statistical_reference/families/twlss.rst index 0f899163..5b01a9c8 100644 --- a/docs/statistical_reference/families/twlss.rst +++ b/docs/statistical_reference/families/twlss.rst @@ -171,22 +171,25 @@ identity. Source response values are ``(mu, theta, rho)``; source logistic power map confines ``p`` to the supplied bounds. ``predict_point`` returns mean ``mu``. -Source ``available.derivs=0`` supplies the analytic likelihood gradient and +**Smoothing selection.** Source ``available.derivs=0`` supplies the analytic likelihood gradient and Hessian; third/fourth likelihood arrays and a numerical outer-derivative fallback are unavailable. Smoothing selection automatically uses EFS, including when another optimizer was requested. Fixed-SP and selected-EFS fits have direct references for covariance, criterion/EDF, AIC/logLik, -predictions/SE, all three residual types and summary tables. The source null +predictions/SE, all three residual types and summary tables. + +**Null deviance.** The source null fit retains its independent bounds ``a=1.001, b=1.999``; null postprocessing uses each observation's fitted dispersion. Prior weights enter deviance residuals and null deviance, although the fitting likelihood ignores them. -The source formula-list setup rejects an external fixed-SP vector when a +**Fixed smoothing in formula lists.** The source formula-list setup rejects an external fixed-SP vector when a parametric-only middle predictor precedes another smooth. Equivalent source captures fix the parameters inside their ``s(..., sp=...)`` terms. All three predictor offsets, zero/positive responses, custom power bounds and both source initialization branches have kernel references. -Selected-EFS parity uses the same explicit initial smoothing parameters in + +**EFS initialization.** Selected-EFS parity uses the same explicit initial smoothing parameters in both implementations. As for ``shash``, source ``initial.spg`` depends on arbitrary initial penalty eigenvector signs; its uncontrolled finite EFS endpoint need not agree across platforms. Common-start references compare diff --git a/docs/statistical_reference/families/weibull_lss.rst b/docs/statistical_reference/families/weibull_lss.rst index eba09006..da6a7b3c 100644 --- a/docs/statistical_reference/families/weibull_lss.rst +++ b/docs/statistical_reference/families/weibull_lss.rst @@ -15,7 +15,9 @@ Natural columns are ``scale, shape``, both log-linked. The WEI mapping is mu=sca Distribution reference: `gamlss.dist::WEI `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force. +* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported. +* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable. +* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations. The Weibull law models a positive response through scale lambda and shape k. Its survival and hazard functions explain the role of diff --git a/docs/statistical_reference/families/zaga_lss.rst b/docs/statistical_reference/families/zaga_lss.rst index f8fa562d..79581386 100644 --- a/docs/statistical_reference/families/zaga_lss.rst +++ b/docs/statistical_reference/families/zaga_lss.rst @@ -15,7 +15,9 @@ Natural columns are ``mu, sigma, pi0`` with log/log/logit links. Mu is the posit Distribution reference: `gamlss.dist::ZAGA `_. Fitting uses NAMpy's joint penalized engine, not gamlss RS backfitting. -Fixed smoothing and automatic general-family REML with outer_newton, bfgs and efs are validated. Method labels retain mgcv general-family coercion to REML; this is not separate ML/GCV/UBRE/NCV support. The optim route is unavailable because the extension has no family-defined null deviance for its objective scaling; magic and nlm.fd are also unsupported. Native deviance residuals and null deviance are unavailable; shared distribution quantile residuals are available. Censoring, truncation and alternate links are unsupported. Existing transformed-coefficient/observation and general-NCV guards remain in force. +* **Fit.** Use fixed smoothing or automatic general-family REML with ``outer_newton``, ``bfgs`` or ``efs``. Method labels follow mgcv's coercion to REML. The optim route is unavailable because it requires null-deviance scaling. ``magic`` and ``nlm.fd`` are also unsupported. +* **Diagnostics.** Use shared distribution quantile residuals. Native deviance residuals and null deviance are unavailable. +* **Scope.** The fitting route excludes censoring, truncation, alternate links, and guarded transformed-coefficient, transformed-observation and general NCV configurations. Zero-adjusted Gamma regression separates exact zeros from positive continuous outcomes. The Gamma component cannot generate zeros, so diff --git a/docs/statistical_reference/families/zip.rst b/docs/statistical_reference/families/zip.rst index aeaf3292..836dd0d4 100644 --- a/docs/statistical_reference/families/zip.rst +++ b/docs/statistical_reference/families/zip.rst @@ -166,7 +166,7 @@ Parameterization and interpretation mgcv's single-predictor ``ziP`` family. Public names ``"ziP"`` and ``"zip"`` resolve to the same family. Only the identity link is supported. -The fitted latent value ``gamma`` is the logarithm of a Poisson intensity +**Predictor and response scales.** The fitted latent value ``gamma`` is the logarithm of a Poisson intensity ``lambda = exp(gamma)``. The probability of a positive count is ``p = 1 - exp(-exp(theta[0] + (b + exp(theta[1])) * gamma))``. Conditional on presence, counts have a zero-truncated Poisson distribution. @@ -175,7 +175,7 @@ Conditional on presence, counts have a zero-truncated Poisson distribution. fitted values remain on the latent log-intensity scale. Response standard errors describe the expected count, not an interval for a new observation. -A supplied ``theta`` pair fixes both working parameters, even when entries +**Ancillary parameters.** A supplied ``theta`` pair fixes both working parameters, even when entries are zero or negative. Omitting ``theta`` estimates both, starting from ``[0, 0]``. ``getTheta()`` returns the working intercept and log slope; ``getTheta(trans=True)`` returns the intercept and ``b + exp(theta[1])``. @@ -183,17 +183,19 @@ are zero or negative. Omitting ``theta`` estimates both, starting from following mgcv. Larger ``b`` enforces stronger dependence between intensity and the probability of presence. -The response must contain nonnegative integer counts; binary data containing +**Counts and diagnostics.** The response must contain nonnegative integer counts; binary data containing both zero and one are rejected. The public model is a count regressor. Deviance, working, and response residuals are supported. Pearson and quantile residuals are explicitly unavailable. Reported deviance includes the family-specific saturated-likelihood correction; adjusted R-squared is not reported for this family. -The reference scope covers fixed and estimated ancillary parameters, fixed +**Fitting support.** The reference scope covers fixed and estimated ancillary parameters, fixed smoothing, ML/REML (including the LAML alias), offsets, multiple smooths, no-intercept and parametric-only formulas, and unit observation weights. -Positive external dispersion overrides are covered, including scale two. Nonunit or zero +Positive external dispersion overrides are covered, including scale two. + +**Weights and rank.** Nonunit or zero prior weights are explicitly guarded: mgcv's ``ziP`` deviance ignores weights while its derivatives and AIC use them, so the ordinary weighted-GLM contract does not apply. Positive ``min_sp`` and joint estimation with ``efs`` are diff --git a/docs/statistical_reference/inference.rst b/docs/statistical_reference/inference.rst index 2532aeb3..2b08de73 100644 --- a/docs/statistical_reference/inference.rst +++ b/docs/statistical_reference/inference.rst @@ -41,20 +41,31 @@ including variation of coefficients as estimated log smoothing parameters change. The supported correction is a local approximation, not exact integration over every smoothing value. -``vcov(freq=False, unconditional=False)`` returns Bayesian penalized covariance -conditional on the selected smoothing parameters. ``freq=True`` requests the -frequentist sampling covariance of the penalized estimate, where supported. -These matrices answer different questions even when based on the same fit. -``unconditional=True`` requests a smoothing-adjusted Bayesian matrix. It is not -an observation-noise adjustment, and does not change the fitted coefficients. +Covariance requests +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Operation + - Result + * - ``vcov()`` + - Bayesian penalized covariance conditional on the fitted smoothing parameters. + * - ``vcov(freq=True)`` + - Frequentist sampling covariance of the penalized estimate, where supported. + * - ``vcov(unconditional=True)`` + - Bayesian covariance adjusted for smoothing-parameter uncertainty where available. The estimate and observation variance use their original fit. + * - ``sp_vcov()`` + - Covariance of the free log smoothing parameters, or ``None`` when fitted curvature is unavailable. ``vcov(unconditional=True)`` falls back to conditional Bayesian covariance when the corrected matrix is absent. Prediction emits ``UserWarning`` ("Smoothness uncertainty corrected covariance not available") and falls back to conditional Bayesian covariance when the -correction is absent; do not infer that a requested adjustment was available -merely because fitting succeeded. ``sp_vcov()`` returns covariance of free log -smoothing parameters, or ``None`` when fitted curvature is unavailable. Family, -criterion and derivative support determine availability; see :doc:`/api/gam_advanced`. +correction is absent. Family, criterion and derivative support determine +availability. See :doc:`/api/gam_advanced`. + +Pointwise and joint uncertainty +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Prediction SE is obtained from the coefficient covariance and the prediction Jacobian. A prediction plus/minus 1.96 SE is an approximate pointwise interval; diff --git a/docs/statistical_reference/links/cauchit.rst b/docs/statistical_reference/links/cauchit.rst index 1f4a41c5..2fc0c5ea 100644 --- a/docs/statistical_reference/links/cauchit.rst +++ b/docs/statistical_reference/links/cauchit.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/cloglog.rst b/docs/statistical_reference/links/cloglog.rst index af8837cf..d96dd759 100644 --- a/docs/statistical_reference/links/cloglog.rst +++ b/docs/statistical_reference/links/cloglog.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/identity.rst b/docs/statistical_reference/links/identity.rst index 363a6357..99007252 100644 --- a/docs/statistical_reference/links/identity.rst +++ b/docs/statistical_reference/links/identity.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/index.rst b/docs/statistical_reference/links/index.rst index fe793785..8f5e9d64 100644 --- a/docs/statistical_reference/links/index.rst +++ b/docs/statistical_reference/links/index.rst @@ -39,14 +39,32 @@ Signature Parameters ~~~~~~~~~~ -``family`` — Type: str | mapping[str, object] | BaseFamily | None - Default: ``required (None selects Gaussian identity)``. A name uses that family's default link. A mapping selects name and supported options such as link. An existing family is independently cloned. Unsupported names/options or links raise errors according to the chosen factory; custom R closures are not accepted. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``family`` + - str | mapping[str, object] | BaseFamily | None + - ``required (None selects Gaussian identity)`` + - A name uses that family's default link. A mapping selects name and supported options such as link. An existing family is independently cloned. Unsupported names/options or links raise errors according to the chosen factory; custom R closures are not accepted. Outputs ~~~~~~~ -``return value`` — Type: BaseFamily subclass instance, scalar object - Unfitted, independent response-family state. It supplies link, inverse_link, mu_eta and forward-link derivatives where applicable; it does not contain fitted regression predictions. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``return value`` + - BaseFamily subclass instance, scalar object + - Unfitted, independent response-family state. It supplies link, inverse_link, mu_eta and forward-link derivatives where applicable; it does not contain fitted regression predictions. Default links ------------- diff --git a/docs/statistical_reference/links/inverse.rst b/docs/statistical_reference/links/inverse.rst index 8fe85a2a..11efafeb 100644 --- a/docs/statistical_reference/links/inverse.rst +++ b/docs/statistical_reference/links/inverse.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/inverse_squared.rst b/docs/statistical_reference/links/inverse_squared.rst index 0baa9960..747e1b50 100644 --- a/docs/statistical_reference/links/inverse_squared.rst +++ b/docs/statistical_reference/links/inverse_squared.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/log.rst b/docs/statistical_reference/links/log.rst index 21c3cb4d..ada986ed 100644 --- a/docs/statistical_reference/links/log.rst +++ b/docs/statistical_reference/links/log.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/logit.rst b/docs/statistical_reference/links/logit.rst index d2b829f5..25a47899 100644 --- a/docs/statistical_reference/links/logit.rst +++ b/docs/statistical_reference/links/logit.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/power.rst b/docs/statistical_reference/links/power.rst index 5ac776c6..e69f592d 100644 --- a/docs/statistical_reference/links/power.rst +++ b/docs/statistical_reference/links/power.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/probit.rst b/docs/statistical_reference/links/probit.rst index 1809d8cd..d3934111 100644 --- a/docs/statistical_reference/links/probit.rst +++ b/docs/statistical_reference/links/probit.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/links/sqrt.rst b/docs/statistical_reference/links/sqrt.rst index 9ae40ff8..2d8b73f7 100644 --- a/docs/statistical_reference/links/sqrt.rst +++ b/docs/statistical_reference/links/sqrt.rst @@ -40,26 +40,45 @@ Evaluation signatures and inputs family.d3link(mu) family.d4link(mu) -``mu`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. - -``eta`` — Type: array-like of floats, shape ``S`` (scalar ``()`` permitted) - Default: ``required``. Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Default + - Meaning + * - ``mu`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Response means/probabilities in the displayed link domain. Convert input to a numeric array; the forward link does not generally repair invalid domains. + * - ``eta`` + - array-like of floats, shape ``S`` (scalar ``()`` permitted) + - ``required`` + - Additive predictors in the inverse-link domain. ``inverse_link`` and ``mu_eta`` consume eta, not response means. Outputs ------- -``family.link(mu)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Forward predictor values. An existing float64 input can be returned without copying for identity. - -``family.inverse_link(eta)`` — Type: floating NumPy array/scalar-shaped numerical result, shape ``S`` - Response mean/probability after the numerical safeguards described above; no response noise is added. - -``family.mu_eta(eta)`` — Type: floating numerical result, shape ``S`` - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. - -``family.d2link(mu), d3link(mu), d4link(mu)`` — Type: floating numerical results, shape ``S`` - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Field + - Type + - Meaning + * - ``family.link(mu)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Forward predictor values. An existing float64 input can be returned without copying for identity. + * - ``family.inverse_link(eta)`` + - floating NumPy array/scalar-shaped numerical result, shape ``S`` + - Response mean/probability after the numerical safeguards described above; no response noise is added. + * - ``family.mu_eta(eta)`` + - floating numerical result, shape ``S`` + - Derivative of the inverse link, d mu / d eta. It can be negative for decreasing links. + * - ``family.d2link(mu), d3link(mu), d4link(mu)`` + - floating numerical results, shape ``S`` + - Second, third and fourth derivatives of the forward link with respect to mu, used by fitting derivatives. These are not derivatives of predictions with respect to a source feature. Ordinary Python lists are accepted through NumPy conversion. Scalar inputs retain shape ``()``; concrete scalar container types can differ between link operations. These elementwise methods preserve broadcasting shape and do not check model convergence. diff --git a/docs/statistical_reference/penalties.rst b/docs/statistical_reference/penalties.rst index 6931c35f..2910c93f 100644 --- a/docs/statistical_reference/penalties.rst +++ b/docs/statistical_reference/penalties.rst @@ -15,41 +15,56 @@ of ``z``: smoothing_method="reml", ).fit(data=df) -Each entry accepts ``penalties``, optional ``rank`` (one integer per matrix), -``sp`` (nonnegative for fixed, negative for estimated), and ``L``. Omitting -``sp`` marks its parameters for estimation; smoothing optimization must be -enabled to estimate them. Matrices are not rescaled. A factor term uses its -expanded contrast columns; a matrix-valued term uses its expanded columns. -Several penalties may act on the same term. ``L`` maps log underlying smoothing -parameters onto log penalty multipliers. It may be rectangular and contain -finite signed or fractional entries: with positive underlying parameters, -the full multipliers are ``np.exp(L @ np.log(sp))``. Fixed parameters are -removed from optimization and contribute through the fixed log-SP offset. -Zero rows specify a constant multiplier of one. Fixed zeros use mgcv's -effective-zero construction. See ``examples/example_parametric_penalty_map.py`` -for a fit with two underlying parameters and three penalties. +Penalty entries +--------------- + +.. list-table:: + :header-rows: 1 + + * - Operation + - Result + * - ``penalties`` + - One or more matrices in the fitted term's column order. Factor terms use expanded contrast columns and matrix-valued terms use their expanded columns. NAMpy uses the matrices at the supplied scale. + * - ``rank`` + - Optional rank, one integer per matrix. + * - ``sp`` + - Nonnegative values fix parameters. Negative values or an omitted ``sp`` request estimation when smoothing optimization is enabled. + * - ``L`` + - Optional map from log smoothing parameters to log penalty multipliers. The matrix may be rectangular with finite signed or fractional entries. + Parametric smoothing parameters precede smooth parameters, in formula-term -order. As in mgcv, unmatched labels are ignored and the intercept is not a -parametric-penalty target. Multi-formula ``para_pen`` is rejected, including -general-family formula lists with one predictor. +order. As in mgcv, unmatched labels are ignored. The interface supports +single-formula fits and excludes the intercept as a penalty target. + +Log-scale maps and selection +---------------------------- + +For positive underlying parameters, the full multipliers are +``np.exp(L @ np.log(sp))``. Fixed parameters contribute through the fixed +log-SP offset. A zero row gives a multiplier of one. Fixed zeros use mgcv's +effective-zero construction. See ``examples/example_parametric_penalty_map.py`` +for two underlying parameters mapped to three penalties. When combining nonidentity parametric maps with smooth penalties, setup follows mgcv's combined ``L`` row/column ordering exactly. In mgcv 1.9-4 this ordering -differs from simply prepending a parametric block to the smooth map; fixed and -selected fits follow the captured upstream setup state. Automatic EFS selection -with nonidentity maps is guarded: upstream's EFS branch omits ``L`` and its -offset, causing rectangular-map failures or inconsistent square-map states. -Newton and supported alternative outer optimizers use the mapped analytic -derivatives. Unused free map columns are rejected rather than estimated. -More generally, automatic initialization rejects rank-deficient free maps, -matching source initialization; explicit initial smoothing parameters may -bypass that initialization. Positive ``min_sp`` with nonidentity maps requires -a separate full-penalty ``H`` implementation and remains guarded. Mapped -penalties are unavailable for transformed-coefficient fits. -``gam_vcomp(rescale=False)`` reports underlying parameter names separately -from full-penalty standard deviations and uses the accepted REML variance for -Gaussian fits. Rescaling parametric variance components remains guarded where -the required scale metadata is unavailable. +interleaves setup coordinates differently from a simple parametric block followed +by a smooth block. Fixed and selected fits follow the captured upstream state. + +* **Optimizers.** Newton and supported alternative outer optimizers use mapped + analytic derivatives. Automatic EFS is guarded because its upstream branch + omits ``L`` and its offset. +* **Initialization.** Free map columns must be used. Automatic initialization + requires a full-rank free map. Explicit initial values can bypass that step. +* **Bounds and transforms.** Nonidentity maps with positive ``min_sp`` require + a separate full-penalty ``H`` implementation. Transformed-coefficient fits + also exclude mapped penalties. + +Variance components +------------------- + +``gam_vcomp(rescale=False)`` separates underlying parameter names from full-penalty +standard deviations and uses the accepted Gaussian REML variance. Rescaling +requires the corresponding parametric scale metadata. For ordinary partially pooled group intercepts, ``GAM.gam_vcomp()`` reports component standard deviations on the additive predictor scale; random-slope @@ -61,27 +76,33 @@ smoothing parameters returns ``None``. The :doc:`method reference :doc:`group-smooth tutorial ` to connect these components to partial pooling. -``constraints={1: C}`` replaces the first smooth's default centering with -``C @ beta_raw = 0``. A unique smooth label may replace the one-based index. -Fitting supports ``cr``, ``cc``, ``ps``, ``cp`` and ``bs`` without ``by``, -point constraints, or linked IDs. ``C`` acts on the uncentered basis, must be -finite with independent rows, and must leave at least one coefficient. -A matrix with zero rows requests no local constraint; global model -identifiability conditions still apply. Columns with cancelling nonzero row -sums are rejected because upstream's localized absorption cannot represent them. -Other bases/compositions remain guarded rather than accepting a constraint in -a different raw parameterization. -Explicit ``cs`` constraints are guarded: mgcv assigns unequal shrinkage to -numerically arbitrary null eigenvectors, which changes fitted predictions -across LAPACK implementations. Use ``cr`` with ``select=True`` for a portable -penalized null space. Raw ``smooth_con`` inspection of ``cs`` remains available -with invariant penalty and constraint checks. +Explicit smooth constraints +--------------------------- + +``constraints={1: C}`` replaces the first smooth's centering with +``C @ beta_raw = 0``. A unique smooth label can stand in for the one-based index. + +* **Supported fits.** Use ``cr``, ``cc``, ``ps``, ``cp`` or ``bs`` without ``by``, + point constraints or linked IDs. +* **Constraint matrix.** ``C`` acts on the uncentered basis. Use finite, + independent rows and leave at least one coefficient. A zero-row matrix + removes the local constraint while retaining global identifiability rules. + Columns with cancelling nonzero row sums are outside upstream's localized + absorption contract. +* **Shrinkage cubic splines.** Raw ``smooth_con`` inspection supports invariant + checks for ``cs``. Its unequal penalties on arbitrary null eigenvectors make + explicit constrained fits sensitive to LAPACK orientation. Use ``cr`` with + ``select=True`` for a portable penalized null space. + +Multiple B-spline penalties +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Derivative-penalized B-splines (``bs='bs'``) also support multiple derivative penalties through ``m``. The same constraint transform applies to every penalty, and ``select=True`` adds a null-space penalty after constraint absorption when a null space remains. See ``examples/example_bs_constraints.py`` for a runnable fit with an explicit coefficient-sum constraint. + For an empty constraint matrix combined with multiple B-spline penalties and ``select=True``, default GCV performance iteration can stop at different endpoints in NAMpy and mgcv. Fixed-SP reconstruction agrees; the targeted @@ -89,7 +110,8 @@ automatic-selection comparison uses the same tighter ``mgcv_tol=1e-12`` in both implementations. This is an optimizer stopping limitation, not a constraint-operator difference. -Inspect the raw basis before specifying ``C``: +Inspect the raw basis +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python diff --git a/docs/statistical_reference/quantile_calibration.rst b/docs/statistical_reference/quantile_calibration.rst index 647bae42..f9342092 100644 --- a/docs/statistical_reference/quantile_calibration.rst +++ b/docs/statistical_reference/quantile_calibration.rst @@ -13,14 +13,14 @@ scalar loss scale by comparing posterior and shrinkage-sandwich variances over the training design. It reuses the existing statistical compiler, constraints and spline penalties. Ordinary ``QuantileGAM`` fitting behavior is unchanged. -``bandwidth`` is a supplied positive ELF bandwidth in response units (upstream -``co``), or ``None`` for the Gaussian-residual SHASH estimate. For fixed -penalties, the coefficient solver uses exact score/Hessian calculations and -certifies the final Newton score step; ``max_iter`` limits score evaluations -per loss scale. Automatic smoothing selects REML penalties at every scalar -loss scale using the extended-family PIRLS engine and exact outer derivatives. -There is no alternate-solver retry or change to the native fitting engine's -stopping rules. +* **Bandwidth.** Supply a positive ``bandwidth`` in response units (upstream + ``co``), or use ``None`` for the Gaussian-residual SHASH estimate. +* **Fixed penalties.** The coefficient solver uses exact score and Hessian + calculations and certifies the final Newton score step. ``max_iter`` limits + score evaluations per loss scale. +* **Automatic smoothing.** The extended-family PIRLS engine selects REML + penalties at each loss scale using exact outer derivatives and its native + stopping rules. Fitting makes one attempt with the selected solver. Covariance construction uses qgam's prescribed diagonal-scaled spectral inverse and relative eigenvalue cutoff of ``1e-6``. This source-specific rank rule is diff --git a/docs/statistical_reference/smooths/ad.rst b/docs/statistical_reference/smooths/ad.rst index 85d1c7cc..87cc5c4d 100644 --- a/docs/statistical_reference/smooths/ad.rst +++ b/docs/statistical_reference/smooths/ad.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/bs.rst b/docs/statistical_reference/smooths/bs.rst index 0b7a27ba..99a6ec79 100644 --- a/docs/statistical_reference/smooths/bs.rst +++ b/docs/statistical_reference/smooths/bs.rst @@ -115,7 +115,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cc.rst b/docs/statistical_reference/smooths/cc.rst index 6a847cc1..169e40d8 100644 --- a/docs/statistical_reference/smooths/cc.rst +++ b/docs/statistical_reference/smooths/cc.rst @@ -129,7 +129,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cp.rst b/docs/statistical_reference/smooths/cp.rst index 07d40823..4d09467b 100644 --- a/docs/statistical_reference/smooths/cp.rst +++ b/docs/statistical_reference/smooths/cp.rst @@ -130,7 +130,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cpop.rst b/docs/statistical_reference/smooths/cpop.rst index d11112a3..e03d7d94 100644 --- a/docs/statistical_reference/smooths/cpop.rst +++ b/docs/statistical_reference/smooths/cpop.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cr.rst b/docs/statistical_reference/smooths/cr.rst index e193c315..d9d7f1c0 100644 --- a/docs/statistical_reference/smooths/cr.rst +++ b/docs/statistical_reference/smooths/cr.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cs.rst b/docs/statistical_reference/smooths/cs.rst index 284c0fb6..39ed9118 100644 --- a/docs/statistical_reference/smooths/cs.rst +++ b/docs/statistical_reference/smooths/cs.rst @@ -129,7 +129,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cv.rst b/docs/statistical_reference/smooths/cv.rst index 08bfb110..4c27adb5 100644 --- a/docs/statistical_reference/smooths/cv.rst +++ b/docs/statistical_reference/smooths/cv.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cvby.rst b/docs/statistical_reference/smooths/cvby.rst index 00c2c705..46d58536 100644 --- a/docs/statistical_reference/smooths/cvby.rst +++ b/docs/statistical_reference/smooths/cvby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cx.rst b/docs/statistical_reference/smooths/cx.rst index 41cd1e2c..d53c85bd 100644 --- a/docs/statistical_reference/smooths/cx.rst +++ b/docs/statistical_reference/smooths/cx.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/cxby.rst b/docs/statistical_reference/smooths/cxby.rst index 867c5b45..3d58fa73 100644 --- a/docs/statistical_reference/smooths/cxby.rst +++ b/docs/statistical_reference/smooths/cxby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/dpo.rst b/docs/statistical_reference/smooths/dpo.rst index 040cc0cf..2f05511c 100644 --- a/docs/statistical_reference/smooths/dpo.rst +++ b/docs/statistical_reference/smooths/dpo.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/ds.rst b/docs/statistical_reference/smooths/ds.rst index 4a333ba3..c5d7fbf0 100644 --- a/docs/statistical_reference/smooths/ds.rst +++ b/docs/statistical_reference/smooths/ds.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/fs.rst b/docs/statistical_reference/smooths/fs.rst index ff47a2f9..51467b5c 100644 --- a/docs/statistical_reference/smooths/fs.rst +++ b/docs/statistical_reference/smooths/fs.rst @@ -112,7 +112,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/gp.rst b/docs/statistical_reference/smooths/gp.rst index 2eb0ba20..577cf420 100644 --- a/docs/statistical_reference/smooths/gp.rst +++ b/docs/statistical_reference/smooths/gp.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/ipo.rst b/docs/statistical_reference/smooths/ipo.rst index 54dfd961..47c8654e 100644 --- a/docs/statistical_reference/smooths/ipo.rst +++ b/docs/statistical_reference/smooths/ipo.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/lipl.rst b/docs/statistical_reference/smooths/lipl.rst index 410a5913..b130d74b 100644 --- a/docs/statistical_reference/smooths/lipl.rst +++ b/docs/statistical_reference/smooths/lipl.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/lmpi.rst b/docs/statistical_reference/smooths/lmpi.rst index fe8ee869..1caeaeaa 100644 --- a/docs/statistical_reference/smooths/lmpi.rst +++ b/docs/statistical_reference/smooths/lmpi.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mdcv.rst b/docs/statistical_reference/smooths/mdcv.rst index 9e5a033f..2a14be20 100644 --- a/docs/statistical_reference/smooths/mdcv.rst +++ b/docs/statistical_reference/smooths/mdcv.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mdcvby.rst b/docs/statistical_reference/smooths/mdcvby.rst index 6186f8b9..8d06ba4f 100644 --- a/docs/statistical_reference/smooths/mdcvby.rst +++ b/docs/statistical_reference/smooths/mdcvby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mdcx.rst b/docs/statistical_reference/smooths/mdcx.rst index 6ee4e81e..1a5b1f34 100644 --- a/docs/statistical_reference/smooths/mdcx.rst +++ b/docs/statistical_reference/smooths/mdcx.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mdcxby.rst b/docs/statistical_reference/smooths/mdcxby.rst index 54003168..e5606233 100644 --- a/docs/statistical_reference/smooths/mdcxby.rst +++ b/docs/statistical_reference/smooths/mdcxby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/micv.rst b/docs/statistical_reference/smooths/micv.rst index 3e30ecb2..461d0d55 100644 --- a/docs/statistical_reference/smooths/micv.rst +++ b/docs/statistical_reference/smooths/micv.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/micvby.rst b/docs/statistical_reference/smooths/micvby.rst index 1a3caea2..6975fea3 100644 --- a/docs/statistical_reference/smooths/micvby.rst +++ b/docs/statistical_reference/smooths/micvby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/micx.rst b/docs/statistical_reference/smooths/micx.rst index 58d5981c..98fcceff 100644 --- a/docs/statistical_reference/smooths/micx.rst +++ b/docs/statistical_reference/smooths/micx.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/micxby.rst b/docs/statistical_reference/smooths/micxby.rst index 36b58426..0d9a19cc 100644 --- a/docs/statistical_reference/smooths/micxby.rst +++ b/docs/statistical_reference/smooths/micxby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mifo.rst b/docs/statistical_reference/smooths/mifo.rst index 3e461582..59d26333 100644 --- a/docs/statistical_reference/smooths/mifo.rst +++ b/docs/statistical_reference/smooths/mifo.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/miso.rst b/docs/statistical_reference/smooths/miso.rst index 9daa479c..de5b4855 100644 --- a/docs/statistical_reference/smooths/miso.rst +++ b/docs/statistical_reference/smooths/miso.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mpd.rst b/docs/statistical_reference/smooths/mpd.rst index 874dc47b..82747301 100644 --- a/docs/statistical_reference/smooths/mpd.rst +++ b/docs/statistical_reference/smooths/mpd.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mpdby.rst b/docs/statistical_reference/smooths/mpdby.rst index b552c269..538d00fb 100644 --- a/docs/statistical_reference/smooths/mpdby.rst +++ b/docs/statistical_reference/smooths/mpdby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mpi.rst b/docs/statistical_reference/smooths/mpi.rst index 937b489c..f3473950 100644 --- a/docs/statistical_reference/smooths/mpi.rst +++ b/docs/statistical_reference/smooths/mpi.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mpiby.rst b/docs/statistical_reference/smooths/mpiby.rst index d4cfb023..7b27a5e5 100644 --- a/docs/statistical_reference/smooths/mpiby.rst +++ b/docs/statistical_reference/smooths/mpiby.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/mrf.rst b/docs/statistical_reference/smooths/mrf.rst index 94c7b1ce..15d9a139 100644 --- a/docs/statistical_reference/smooths/mrf.rst +++ b/docs/statistical_reference/smooths/mrf.rst @@ -111,7 +111,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/po.rst b/docs/statistical_reference/smooths/po.rst index fdb5999a..6a4d4f8a 100644 --- a/docs/statistical_reference/smooths/po.rst +++ b/docs/statistical_reference/smooths/po.rst @@ -117,7 +117,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/ps.rst b/docs/statistical_reference/smooths/ps.rst index dbbba1dc..44d561ee 100644 --- a/docs/statistical_reference/smooths/ps.rst +++ b/docs/statistical_reference/smooths/ps.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/re.rst b/docs/statistical_reference/smooths/re.rst index c6a5ac3e..dd3f3f57 100644 --- a/docs/statistical_reference/smooths/re.rst +++ b/docs/statistical_reference/smooths/re.rst @@ -112,7 +112,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/sc.rst b/docs/statistical_reference/smooths/sc.rst index f7028991..390defab 100644 --- a/docs/statistical_reference/smooths/sc.rst +++ b/docs/statistical_reference/smooths/sc.rst @@ -120,7 +120,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/scad.rst b/docs/statistical_reference/smooths/scad.rst index 23b07830..e4a33464 100644 --- a/docs/statistical_reference/smooths/scad.rst +++ b/docs/statistical_reference/smooths/scad.rst @@ -120,7 +120,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/sf.rst b/docs/statistical_reference/smooths/sf.rst index e40e5e20..bf24996a 100644 --- a/docs/statistical_reference/smooths/sf.rst +++ b/docs/statistical_reference/smooths/sf.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/so.rst b/docs/statistical_reference/smooths/so.rst index 7f1b8bab..27658a97 100644 --- a/docs/statistical_reference/smooths/so.rst +++ b/docs/statistical_reference/smooths/so.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/sos.rst b/docs/statistical_reference/smooths/sos.rst index bc6a7bf4..67ddfc3b 100644 --- a/docs/statistical_reference/smooths/sos.rst +++ b/docs/statistical_reference/smooths/sos.rst @@ -115,7 +115,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/sw.rst b/docs/statistical_reference/smooths/sw.rst index df5a81b6..d243fb63 100644 --- a/docs/statistical_reference/smooths/sw.rst +++ b/docs/statistical_reference/smooths/sw.rst @@ -119,7 +119,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/sz.rst b/docs/statistical_reference/smooths/sz.rst index 505fd433..b567155d 100644 --- a/docs/statistical_reference/smooths/sz.rst +++ b/docs/statistical_reference/smooths/sz.rst @@ -112,7 +112,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/t2.rst b/docs/statistical_reference/smooths/t2.rst index a4358213..97ec8f01 100644 --- a/docs/statistical_reference/smooths/t2.rst +++ b/docs/statistical_reference/smooths/t2.rst @@ -126,7 +126,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. Before identifiability constraints, the tensor has the product of the marginal basis dimensions, not a single k columns. Marginal/term constraints and retained t2 blocks determine the final coefficient count. diff --git a/docs/statistical_reference/smooths/te.rst b/docs/statistical_reference/smooths/te.rst index b420f5b0..46dc17b0 100644 --- a/docs/statistical_reference/smooths/te.rst +++ b/docs/statistical_reference/smooths/te.rst @@ -122,7 +122,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. Before identifiability constraints, the tensor has the product of the marginal basis dimensions, not a single k columns. Marginal/term constraints and retained t2 blocks determine the final coefficient count. diff --git a/docs/statistical_reference/smooths/tecvcv.rst b/docs/statistical_reference/smooths/tecvcv.rst index c34580b5..fddd93f1 100644 --- a/docs/statistical_reference/smooths/tecvcv.rst +++ b/docs/statistical_reference/smooths/tecvcv.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tecxcv.rst b/docs/statistical_reference/smooths/tecxcv.rst index 841532c6..cd38f53b 100644 --- a/docs/statistical_reference/smooths/tecxcv.rst +++ b/docs/statistical_reference/smooths/tecxcv.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tecxcx.rst b/docs/statistical_reference/smooths/tecxcx.rst index 98fb07c8..c64b0f7d 100644 --- a/docs/statistical_reference/smooths/tecxcx.rst +++ b/docs/statistical_reference/smooths/tecxcx.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tedecv.rst b/docs/statistical_reference/smooths/tedecv.rst index 3f247a82..0cbe6cee 100644 --- a/docs/statistical_reference/smooths/tedecv.rst +++ b/docs/statistical_reference/smooths/tedecv.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tedecx.rst b/docs/statistical_reference/smooths/tedecx.rst index dc349c07..e541a43c 100644 --- a/docs/statistical_reference/smooths/tedecx.rst +++ b/docs/statistical_reference/smooths/tedecx.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tedmd.rst b/docs/statistical_reference/smooths/tedmd.rst index a1450baf..a1c9c44b 100644 --- a/docs/statistical_reference/smooths/tedmd.rst +++ b/docs/statistical_reference/smooths/tedmd.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tedmi.rst b/docs/statistical_reference/smooths/tedmi.rst index 50902704..1316bf10 100644 --- a/docs/statistical_reference/smooths/tedmi.rst +++ b/docs/statistical_reference/smooths/tedmi.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/temicv.rst b/docs/statistical_reference/smooths/temicv.rst index 8d5d0e8a..37da8041 100644 --- a/docs/statistical_reference/smooths/temicv.rst +++ b/docs/statistical_reference/smooths/temicv.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/temicx.rst b/docs/statistical_reference/smooths/temicx.rst index ca0dec72..2c4bb213 100644 --- a/docs/statistical_reference/smooths/temicx.rst +++ b/docs/statistical_reference/smooths/temicx.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tescv.rst b/docs/statistical_reference/smooths/tescv.rst index a209a156..8c2f2c88 100644 --- a/docs/statistical_reference/smooths/tescv.rst +++ b/docs/statistical_reference/smooths/tescv.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tescx.rst b/docs/statistical_reference/smooths/tescx.rst index bbcccb55..6cb6a901 100644 --- a/docs/statistical_reference/smooths/tescx.rst +++ b/docs/statistical_reference/smooths/tescx.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tesmd1.rst b/docs/statistical_reference/smooths/tesmd1.rst index c3f3e725..fd5c28b1 100644 --- a/docs/statistical_reference/smooths/tesmd1.rst +++ b/docs/statistical_reference/smooths/tesmd1.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tesmd2.rst b/docs/statistical_reference/smooths/tesmd2.rst index c8c4504a..1e61b746 100644 --- a/docs/statistical_reference/smooths/tesmd2.rst +++ b/docs/statistical_reference/smooths/tesmd2.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tesmi1.rst b/docs/statistical_reference/smooths/tesmi1.rst index cf1f9c7a..5a024116 100644 --- a/docs/statistical_reference/smooths/tesmi1.rst +++ b/docs/statistical_reference/smooths/tesmi1.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tesmi2.rst b/docs/statistical_reference/smooths/tesmi2.rst index a044ee8e..e93c92cc 100644 --- a/docs/statistical_reference/smooths/tesmi2.rst +++ b/docs/statistical_reference/smooths/tesmi2.rst @@ -116,7 +116,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/ti.rst b/docs/statistical_reference/smooths/ti.rst index a9260a01..80f227ea 100644 --- a/docs/statistical_reference/smooths/ti.rst +++ b/docs/statistical_reference/smooths/ti.rst @@ -127,7 +127,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. Before identifiability constraints, the tensor has the product of the marginal basis dimensions, not a single k columns. Marginal/term constraints and retained t2 blocks determine the final coefficient count. diff --git a/docs/statistical_reference/smooths/tismd.rst b/docs/statistical_reference/smooths/tismd.rst index 60e9922f..ea97f4d3 100644 --- a/docs/statistical_reference/smooths/tismd.rst +++ b/docs/statistical_reference/smooths/tismd.rst @@ -118,7 +118,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tismi.rst b/docs/statistical_reference/smooths/tismi.rst index 866b3ee8..1c1957ae 100644 --- a/docs/statistical_reference/smooths/tismi.rst +++ b/docs/statistical_reference/smooths/tismi.rst @@ -118,7 +118,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/tp.rst b/docs/statistical_reference/smooths/tp.rst index 769f5709..eb5d96b0 100644 --- a/docs/statistical_reference/smooths/tp.rst +++ b/docs/statistical_reference/smooths/tp.rst @@ -118,7 +118,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/docs/statistical_reference/smooths/ts.rst b/docs/statistical_reference/smooths/ts.rst index 2fb15a27..7c254999 100644 --- a/docs/statistical_reference/smooths/ts.rst +++ b/docs/statistical_reference/smooths/ts.rst @@ -131,7 +131,20 @@ Capabilities Outputs ------- -The formula adds a term to the fitted model's additive predictor. Its coefficient block has p_term columns after constraints; this dimension differs from EDF. ``predict(type='terms')`` returns a floating array with n rows and one column per retained term for a scalar predictor. ``lpmatrix`` returns the full floating model design, shape (n, p), including the other terms. The scalar Gaussian examples below produce response predictions of shape (n,). Runtime matrix and penalty contracts are documented separately. +.. list-table:: + :header-rows: 1 + :class: api-reference-table + + * - Operation + - Result + * - Formula term + - Adds a term to the link predictor. Its coefficient block has ``p_term`` columns after constraints. EDF is a separate fit statistic. + * - ``predict(type='terms')`` + - Floating array with ``n`` rows and one column per retained term for a scalar predictor. + * - ``lpmatrix`` + - Full floating model design of shape ``(n, p)``, including the other terms. + +The scalar Gaussian examples produce response predictions of shape ``(n,)``. diff --git a/tests/docs/test_reference_manual.py b/tests/docs/test_reference_manual.py index d7075fb8..b65625e0 100644 --- a/tests/docs/test_reference_manual.py +++ b/tests/docs/test_reference_manual.py @@ -124,6 +124,27 @@ def test_argument_rows_keep_type_and_default_on_their_own_line(): assert "default: " not in rendered +def test_dense_reference_topics_render_as_tables_and_subsections(): + manual = load_manual() + topics = [] + for page in manual.build_manual(): + _topics(page, topics) + survival = next(page for page in topics if page.path.name == "SurvivalGAM.rst") + rendered = manual.render_page(survival, 2, "Statistical estimators") + operations = rendered.split(r"\Rdsection{Predictions and supported operations}", 1)[1] + assert r"\begin{longtable}" in operations + assert r"\textbf{Operation} & \textbf{Result}" in operations + assert r"\Rdsubsection{Diagnostics and evaluation}" in operations + assert r"\Rdsubsection{Effects and uncertainty}" in operations + assert r"\Rdext{https://nampy.readthedocs.io/en/latest/howto/survival.html}{survival}" in operations + for name in ("CoxGAM.rst", "NeuralEnsemble.rst", "penalties.rst", "gam_smooths.rst"): + topic = next(page for page in topics if page.path.name == name) + assert r"\begin{longtable}" in manual.render_page(topic, 2) + optimizer = next(page for page in topics if page.path.name == "optimizer_endpoint_diagnostics.rst") + rendered = manual.render_page(optimizer, 2) + assert r"\Rdarg{" in rendered.split(r"\Rdsection{Outputs}", 1)[1] + + def test_bare_doc_path_becomes_a_phrase_link(): manual = load_manual() manual.DOC_PAGES["statistical_reference/methods/vcov"] = ( @@ -146,6 +167,8 @@ def test_manual_opens_with_a_short_contents(): assert "margin=2.8cm" in tex assert r"\setcounter{tocdepth}{1}" in tex assert r"\hrule height 0.35pt" not in tex + assert "breaklines=true" in tex + assert "breaksymbolleft={},breaksymbolright={}" in tex body = tex.split(r"\begin{document}", 1)[1] assert r"\Rdmeta{Author}" in body assert "Ananyapam De" in body diff --git a/tests/docs/test_reference_precision.py b/tests/docs/test_reference_precision.py index 63ac7bfd..2886dfd7 100644 --- a/tests/docs/test_reference_precision.py +++ b/tests/docs/test_reference_precision.py @@ -176,7 +176,7 @@ def test_extension_family_leads_with_supported_parameterization(name, reference) assert "automatic general-family REML" in text elif name == "beinf_lss": assert "coupled category log ratios" in text - assert "all five natural errors" in text + assert "five natural-parameter standard errors" in text assert "variance hook" in text else: assert "coercion to REML" in text