Crate ferrolearn_linear 

ferrolearn-linear

Linear models for the ferrolearn machine learning framework.

This crate provides implementations of the most common linear models for both regression and classification tasks:

• LinearRegression — Ordinary Least Squares via QR decomposition
• Ridge — L2-regularized regression via Cholesky decomposition
• RidgeCV — Ridge with built-in cross-validated alpha selection
• Lasso — L1-regularized regression via coordinate descent
• LassoCV — Lasso with built-in cross-validated alpha selection
• ElasticNet — Combined L1/L2 regularization via coordinate descent
• ElasticNetCV — ElasticNet with cross-validated (alpha, l1_ratio) selection
• BayesianRidge — Bayesian Ridge with automatic regularization tuning
• HuberRegressor — Robust regression via IRLS with Huber loss
• LogisticRegression — Binary and multiclass classification via L-BFGS

All models implement the ferrolearn_core::Fit and ferrolearn_core::Predict traits, and produce fitted types that implement ferrolearn_core::introspection::HasCoefficients.

Design

Each model follows the compile-time safety pattern:

• The unfitted struct (e.g., LinearRegression<F>) holds hyperparameters and implements Fit.
• Calling fit() produces a new fitted type (e.g., FittedLinearRegression<F>) that implements ferrolearn_core::Predict.
• Calling predict() on an unfitted model is a compile-time error.

Pipeline Integration

All models implement PipelineEstimator for f64, allowing them to be used as the final step in a Pipeline.

Float Generics

All models are generic over F: num_traits::Float + Send + Sync + 'static, supporting both f32 and f64.

## REQ status

Binary (R-DEFER-2) for the crate-root RE-EXPORT BOUNDARY (this file is the public-API surface, not an estimator). Mirrors sklearn/linear_model/__init__.py __all__ (:48-98) + the score mixins sklearn/base.py ClassifierMixin.score (:738-764, accuracy) / RegressorMixin.score (:805-849, R²). Design doc: .design/linear/lib.md. Per-estimator REQs live in the sibling modules’ own routed docs. Score traits (ClassifierScore/RegressorScore) are pre-existing crate-root pub traits re-exported via the meta-crate (ferrolearn::linear) — grandfathered public API (goal.md S5); honest underclaim (R-HONEST-3): no production .score() caller yet. sample_weight is supported via the Option<&Array1<F>> last param on both traits (REQ-6, #1106).

REQ	Status	Evidence
REQ-1 (re-export boundary)	SHIPPED	the pub use block re-exports every implemented linear/svm/discriminant_analysis/isotonic estimator at the crate root, mirroring sklearn linear_model.__all__ (__init__.py:48-98), broadened per goal.md scope §2. Consumers: meta-crate pub use ferrolearn_linear as linear + PyO3 shim ferrolearn-python/src/{regressors,classifiers,extras}.rs.
REQ-2 (ClassifierScore::score == mean accuracy)	SHIPPED	ClassifierScore blanket impl body mean_accuracy (correct / n) mirrors ClassifierMixin.score → accuracy_score (base.py:738-764); critic-verified vs live oracle (accuracy_score([0,1,2,1],[0,1,1,1])=0.75). Consumer: grandfathered crate/meta re-export (S5). Underclaim: no production .score() caller; single-label (Output=Array1<usize>).
REQ-3 (RegressorScore::score == in-regime R²)	SHIPPED	RegressorScore blanket impl body r2_score = 1 − ss_res/ss_tot mirrors RegressorMixin.score → metrics.r2_score (base.py:805-849); matches live oracle r2_score([3.,5.,2.,7.],[2.5,5.,2.,8.])=0.9152542372881356 (r2_in_regime_matches_oracle). Consumer: grandfathered re-export (S5).
REQ-4 (constant-y R² edge parity)	SHIPPED	FIXED #1104. r2_score now returns 0.0 (was neg_infinity()) when ss_tot==0 ∧ ss_res!=0, matching metrics.r2_score (_regression.py:891); zero-residual stays 1.0. Green: divergence_r2_constant_ytrue_nonzero_residual_returns_zero + r2_constant_ytrue_zero_residual_returns_one.
REQ-5 (log_proba behind predict_log_proba)	SHIPPED	FIXED #1105. log_proba is now the unclamped p.ln(), matching sklearn predict_log_proba = np.log(predict_proba) (discriminant_analysis.py:1059); 0.0→-inf. Consumers: logistic_regression.rs/logistic_regression_cv.rs/qda.rs predict_log_proba. Green: divergence_log_proba_zero_clamps_instead_of_neg_inf.
REQ-6 (sample_weight on score)	SHIPPED	FIXED #1106. Both score traits now take sample_weight: Option<&Array1<F>> as the LAST param, matching sklearn score(self, X, y, sample_weight=None) (base.py:738,:805). ClassifierScore::score → weighted_accuracy (Σ wᵢ·[predᵢ==yᵢ] / Σ wᵢ, the accuracy_score(..., sample_weight=w) analog); RegressorScore::score → weighted_r2_score (1 − Σwᵢ(yᵢ−predᵢ)² / Σwᵢ(yᵢ−ȳ_w)², ȳ_w = Σwᵢyᵢ/Σwᵢ, the r2_score(..., sample_weight=w) analog). None is byte-identical to mean_accuracy/r2_score. Oracle-verified (live sklearn 1.5.2): weighted_accuracy([0,1,0,0,1],[0,1,1,0,1],[1,2,3,1,1])=0.625, weighted_r2_score([1.1,1.9,3.2,3.7,5.1],[1,2,3,4,5],[1,2,3,1,1])=0.9770114942528736 in tests/divergence_lib.rs (classifier_score_weighted_matches_sklearn, regressor_score_weighted_matches_sklearn, score_none_sample_weight_equals_unweighted).
REQ-substrate (ferray)	NOT-STARTED	open prereq blocker #1107. Helpers + score traits run on ndarray::{Array1,Array2} + num_traits::Float, not ferray-core arrays (R-SUBSTRATE-1).

Re-exports

pub use ard::ARDRegression;

pub use ard::FittedARDRegression;

pub use bayesian_ridge::BayesianRidge;

pub use bayesian_ridge::FittedBayesianRidge;

pub use elastic_net::ElasticNet;

pub use elastic_net::FittedElasticNet;

pub use elastic_net_cv::ElasticNetCV;

pub use elastic_net_cv::FittedElasticNetCV;

pub use glm::FittedGLMRegressor;

pub use glm::GLMFamily;

pub use glm::GLMRegressor;

pub use glm::GammaRegressor;

pub use glm::PoissonRegressor;

pub use glm::TweedieRegressor;

pub use huber_regressor::FittedHuberRegressor;

pub use huber_regressor::HuberRegressor;

pub use isotonic::FittedIsotonicRegression;

pub use isotonic::IsotonicRegression;

pub use lars::FittedLars;

pub use lars::FittedLassoLars;

pub use lars::Lars;

pub use lars::LassoLars;

pub use lasso::FittedLasso;

pub use lasso::Lasso;

pub use lasso_cv::FittedLassoCV;

pub use lasso_cv::LassoCV;

pub use lda::FittedLDA;

pub use lda::LDA;

pub use linear_regression::FittedLinearRegression;

pub use linear_regression::LinearRegression;

pub use linear_svc::FittedLinearSVC;

pub use linear_svc::LinearSVC;

pub use linear_svc::LinearSVCLoss;

pub use linear_svr::FittedLinearSVR;

pub use linear_svr::LinearSVR;

pub use linear_svr::LinearSVRLoss;

pub use logistic_regression::FittedLogisticRegression;

pub use logistic_regression::LogisticRegression;

pub use logistic_regression_cv::FittedLogisticRegressionCV;

pub use logistic_regression_cv::LogisticRegressionCV;

pub use multi_task_elastic_net::FittedMultiTaskElasticNet;

pub use multi_task_elastic_net::MultiTaskElasticNet;

pub use multi_task_elastic_net_cv::FittedMultiTaskElasticNetCV;

pub use multi_task_elastic_net_cv::MultiTaskElasticNetCV;

pub use multi_task_lasso::FittedMultiTaskLasso;

pub use multi_task_lasso::MultiTaskLasso;

pub use multi_task_lasso_cv::FittedMultiTaskLassoCV;

pub use multi_task_lasso_cv::MultiTaskLassoCV;

pub use nu_svm::FittedNuSVC;

pub use nu_svm::FittedNuSVR;

pub use nu_svm::NuSVC;

pub use nu_svm::NuSVR;

pub use omp::FittedOMP;

pub use omp::OrthogonalMatchingPursuit;

pub use one_class_svm::FittedOneClassSVM;

pub use one_class_svm::OneClassSVM;

pub use qda::FittedQDA;

pub use qda::QDA;

pub use quantile_regressor::FittedQuantileRegressor;

pub use quantile_regressor::QuantileRegressor;

pub use ransac::FittedRANSACRegressor;

pub use ransac::MinSamples;

pub use ransac::RANSACRegressor;

pub use ransac::RansacLoss;

pub use ridge::FittedRidge;

pub use ridge::FittedRidgeMulti;

pub use ridge::Ridge;

pub use ridge_classifier::FittedRidgeClassifier;

pub use ridge_classifier::RidgeClassifier;

pub use ridge_classifier_cv::FittedRidgeClassifierCV;

pub use ridge_classifier_cv::RidgeClassifierCV;

pub use ridge_cv::FittedRidgeCV;

pub use ridge_cv::RidgeCV;

pub use sgd::FittedSGDClassifier;

pub use sgd::FittedSGDOneClassSVM;

pub use sgd::FittedSGDRegressor;

pub use sgd::SGDClassifier;

pub use sgd::SGDOneClassSVM;

pub use sgd::SGDRegressor;

pub use svm::FittedSVC;

pub use svm::FittedSVR;

pub use svm::Kernel;

pub use svm::LinearKernel;

pub use svm::PolynomialKernel;

pub use svm::RbfKernel;

pub use svm::SVC;

pub use svm::SVR;

pub use svm::SigmoidKernel;

Modules

ard

Automatic Relevance Determination (ARD) Regression.

bayesian_ridge

Bayesian Ridge Regression.

elastic_net

ElasticNet regression (combined L1 and L2 regularization).

elastic_net_cv

ElasticNet regression with built-in cross-validation for alpha and l1_ratio selection.

glm

Generalized Linear Models (GLM).

huber_regressor

Huber Regressor — robust regression via joint [coef, intercept, scale] L-BFGS optimization of the scale-aware Huber loss.

isotonic

Isotonic (monotonic) regression.

lars

Least Angle Regression (LARS) and Lasso-LARS.

lasso

Lasso regression (L1-regularized linear regression).

lasso_cv

Lasso regression with built-in cross-validation for alpha selection.

lda

Linear Discriminant Analysis (LDA).

linear_regression

Ordinary Least Squares linear regression.

linear_svc

Linear Support Vector Classifier.

linear_svr

Linear Support Vector Regressor.

logistic_regression

Logistic regression classifier.

logistic_regression_cv

Logistic Regression with built-in cross-validated C selection.

multi_task_elastic_net

Multi-task ElasticNet regression (joint multi-output L1/L2,1 mixed-norm block coordinate descent).

multi_task_elastic_net_cv

Multi-task ElasticNet regression with built-in cross-validation for (alpha, l1_ratio) selection.

multi_task_lasso

Multi-task Lasso regression (joint multi-output L21 block coordinate descent).

multi_task_lasso_cv

Multi-task Lasso regression with built-in cross-validation for alpha selection.

nu_svm

Nu-parameterized Support Vector Machines.

omp

Orthogonal Matching Pursuit (OMP).

one_class_svm

One-Class SVM for novelty detection.

qda

Quadratic Discriminant Analysis (QDA).

quantile_regressor

Quantile Regression via the exact linear program (matching scikit-learn).

ransac

RANSAC (RANdom SAmple Consensus) robust regression.

ridge

Ridge regression (L2-regularized linear regression).

ridge_classifier

Ridge Classifier.

ridge_classifier_cv

Ridge classifier with built-in cross-validation for alpha selection.

ridge_cv

Ridge regression with built-in cross-validation for alpha selection.

sgd

Stochastic Gradient Descent (SGD) linear models.

svm

Support Vector Machine with kernel trick.

Traits

ClassifierScore

Mean-accuracy score(x, y) exposed on every fitted classifier in this crate via a blanket impl over Predict<Array2<F>, Output=Array1<usize>>.

RegressorScore

R² score(x, y) exposed on every fitted regressor in this crate via a blanket impl over Predict<Array2<F>, Output=Array1<F>>.