Linregress

https://docs.rs/linregress/latest/
Admin
Linregress provides an easy-to-use implementation of ordinary least squares linear regression with...
Tokens:32,039
Snippets:86
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Linear Regression Example

Source: https://docs.rs/linregress/latest/src/linregress/lib

Demonstrates how to perform linear regression using the linregress crate. It shows how to build a regression model from data using a formula and then extract statistical results like parameters, p-values, and standard errors.

```rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};

# use linregress::Error;
# fn main() -> Result<(), Error> {
let y = vec![1., 2. ,3. , 4., 5.];
let x1 = vec![5., 4., 3., 2., 1.];
let x2 = vec![729.53, 439.0367, 42.054, 1., 0.];
let x3 = vec![258.589, 616.297, 215.061, 498.361, 0.];
let data = vec![("Y", y), ("X1", x1), ("X2", x2), ("X3", x3)];
let data = RegressionDataBuilder::new().build_from(data)?;
let formula = "Y ~ X1 + X2 + X3";
let model = FormulaRegressionBuilder::new()
    .data(&data)
    .formula(formula)
    .fit()?;
let parameters: Vec<_> = model.iter_parameter_pairs().collect();
let pvalues: Vec<_> = model.iter_p_value_pairs().collect();
let standard_errors: Vec<_> = model.iter_se_pairs().collect();
assert_eq!(
    parameters,
    vec![
        ("X1", -1.0000000000000004),
        ("X2", 1.5508427875232655e-15),
        ("X3", -1.4502288259166107e-15),
    ]
);
assert_eq!(
    standard_errors,
    vec![
        ("X1", 9.22799842631787e-13),
        ("X2", 4.184801029355531e-15),
        ("X3", 2.5552590991720465e-15),
    ]
);
assert_eq!(
    pvalues,
    vec![
        ("X1", 5.874726257570879e-13),
        ("X2", 0.7740647742008093),
        ("X3", 0.6713674042015161),
    ]
);
# Ok(())
# }
```

--------------------------------

### FormulaRegressionBuilder Usage Example

Source: https://docs.rs/linregress/latest/linregress/struct

Demonstrates how to use FormulaRegressionBuilder to create and fit a linear regression model with specified data and formula.

```Rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder, assert_almost_eq};

let y = vec![1., 2. ,3., 4.];
let x = vec![4., 3., 2., 1.];
let data = vec![("Y", y), ("X", x)];
let data = RegressionDataBuilder::new().build_from(data)?;
let model = FormulaRegressionBuilder::new().data(&data).formula("Y ~ X").fit()?;
// Alternatively
let model = FormulaRegressionBuilder::new().data(&data).data_columns("Y", ["X"]).fit()?;
let params = model.parameters();
assert_almost_eq!(params[0], 4.999999999999998);
assert_almost_eq!(params[1], -0.9999999999999989);
assert_eq!(model.regressor_names()[0], "X");
```

--------------------------------

### FormulaRegressionBuilder Usage Example

Source: https://docs.rs/linregress/latest/src/linregress/lib

Demonstrates how to use the FormulaRegressionBuilder to create and fit a linear regression model. It shows setting data and formula, fitting the model, and asserting the parameters and regressor names.

```rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder, assert_almost_eq};

# use linregress::Error;
# fn main() -> Result<(), Error> {
let y = vec![1., 2. ,3., 4.];
let x = vec![4., 3., 2., 1.];
let data = vec![("Y", y), ("X", x)];
let data = RegressionDataBuilder::new().build_from(data)?;
let model = FormulaRegressionBuilder::new().data(&data).formula("Y ~ X").fit()?;
// Alternatively
let model = FormulaRegressionBuilder::new().data(&data).data_columns("Y", ["X"]).fit()?;
let params = model.parameters();
assert_almost_eq!(params[0], 4.999999999999998);
assert_almost_eq!(params[1], -0.9999999999999989);
assert_eq!(model.regressor_names()[0], "X");
# Ok(())
# }
```

--------------------------------

### Linear Regression Example

Source: https://docs.rs/linregress/latest/linregress

Demonstrates how to perform ordinary least squared linear regression using the linregress crate. It shows data preparation, model fitting with an R-style formula, and extracting regression parameters, p-values, and standard errors.

```Rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};

let y = vec![1., 2. ,3. , 4., 5.];
let x1 = vec![5., 4., 3., 2., 1.];
let x2 = vec![729.53, 439.0367, 42.054, 1., 0.];
let x3 = vec![258.589, 616.297, 215.061, 498.361, 0.];
let data = vec![("Y", y), ("X1", x1), ("X2", x2), ("X3", x3)];
let data = RegressionDataBuilder::new().build_from(data)?;
let formula = "Y ~ X1 + X2 + X3";
let model = FormulaRegressionBuilder::new()
    .data(&data)
    .formula(formula)
    .fit()?;
let parameters: Vec<_> = model.iter_parameter_pairs().collect();
let pvalues: Vec<_> = model.iter_p_value_pairs().collect();
let standard_errors: Vec<_> = model.iter_se_pairs().collect();
assert_eq!(
    parameters,
    vec![
        ("X1", -1.0000000000000004),
        ("X2", 1.5508427875232655e-15),
        ("X3", -1.4502288259166107e-15),
    ]
);
assert_eq!(
    standard_errors,
    vec![
        ("X1", 9.22799842631787e-13),
        ("X2", 4.184801029355531e-15),
        ("X3", 2.5552590991720465e-15),
    ]
);
assert_eq!(
    pvalues,
    vec![
        ("X1", 5.874726257570879e-13),
        ("X2", 0.7740647742008093),
        ("X3", 0.6713674042015161),
    ]
);

```

--------------------------------

### Linear Regression Example

Source: https://docs.rs/linregress/latest/index

Demonstrates how to perform ordinary least squared linear regression using the linregress crate. It shows data preparation, model fitting with an R-style formula, and extracting regression parameters, p-values, and standard errors.

```Rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};

let y = vec![1., 2. ,3. , 4., 5.];
let x1 = vec![5., 4., 3., 2., 1.];
let x2 = vec![729.53, 439.0367, 42.054, 1., 0.];
let x3 = vec![258.589, 616.297, 215.061, 498.361, 0.];
let data = vec![("Y", y), ("X1", x1), ("X2", x2), ("X3", x3)];
let data = RegressionDataBuilder::new().build_from(data)?;
let formula = "Y ~ X1 + X2 + X3";
let model = FormulaRegressionBuilder::new()
    .data(&data)
    .formula(formula)
    .fit()?;
let parameters: Vec<_> = model.iter_parameter_pairs().collect();
let pvalues: Vec<_> = model.iter_p_value_pairs().collect();
let standard_errors: Vec<_> = model.iter_se_pairs().collect();
assert_eq!(
    parameters,
    vec![
        ("X1", -1.0000000000000004),
        ("X2", 1.5508427875232655e-15),
        ("X3", -1.4502288259166107e-15),
    ]
);
assert_eq!(
    standard_errors,
    vec![
        ("X1", 9.22799842631787e-13),
        ("X2", 4.184801029355531e-15),
        ("X3", 2.5552590991720465e-15),
    ]
);
assert_eq!(
    pvalues,
    vec![
        ("X1", 5.874726257570879e-13),
        ("X2", 0.7740647742008093),
        ("X3", 0.6713674042015161),
    ]
);

```

--------------------------------

### Linear Regression Example

Source: https://docs.rs/linregress/latest/linregress/index

Demonstrates how to perform ordinary least squared linear regression using the linregress crate. It shows data preparation, model fitting with an R-style formula, and extracting regression parameters, p-values, and standard errors.

```Rust
use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};

let y = vec![1., 2. ,3. , 4., 5.];
let x1 = vec![5., 4., 3., 2., 1.];
let x2 = vec![729.53, 439.0367, 42.054, 1., 0.];
let x3 = vec![258.589, 616.297, 215.061, 498.361, 0.];
let data = vec![("Y", y), ("X1", x1), ("X2", x2), ("X3", x3)];
let data = RegressionDataBuilder::new().build_from(data)?;
let formula = "Y ~ X1 + X2 + X3";
let model = FormulaRegressionBuilder::new()
    .data(&data)
    .formula(formula)
    .fit()?;
let parameters: Vec<_> = model.iter_parameter_pairs().collect();
let pvalues: Vec<_> = model.iter_p_value_pairs().collect();
let standard_errors: Vec<_> = model.iter_se_pairs().collect();
assert_eq!(
    parameters,
    vec![
        ("X1", -1.0000000000000004),
        ("X2", 1.5508427875232655e-15),
        ("X3", -1.4502288259166107e-15),
    ]
);
assert_eq!(
    standard_errors,
    vec![
        ("X1", 9.22799842631787e-13),
        ("X2", 4.184801029355531e-15),
        ("X3", 2.5552590991720465e-15),
    ]
);
assert_eq!(
    pvalues,
    vec![
        ("X1", 5.874726257570879e-13),
        ("X2", 0.7740647742008093),
        ("X3", 0.6713674042015161),
    ]
);

```

--------------------------------

### Get Sum of Products (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

Calculates the sum of products between rows of a matrix and elements of a vector. The result is a column matrix.

```Rust
fn get_sum_of_products(matrix: &DMatrix<f64>, vector: &[f64]) -> DMatrix<f64> {
    DMatrix::from_iterator(
        matrix.nrows(),
        1,
        matrix
            .row_iter()
            .map(|row| row.iter().zip(vector.iter()).map(|(x, y)| x * y).sum()),
    )
}
```

--------------------------------

### Get Low-Level Regression Data (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

A helper function to prepare data for low-level regression. It validates input dimensions, creates a `DMatrix` from a row-major slice, and separates inputs and outputs.

```Rust
fn get_low_level_regression(
    data_row_major: &[f64],
    num_rows: usize,
    num_columns: usize,
) -> Result<InternalLowLevelRegressionResult, Error> {
    ensure!(
        !data_row_major.is_empty() && num_rows * num_columns == data_row_major.len(),
        Error::InconsistentVectors
    );
    let data = DMatrix::from_row_slice(num_rows, num_columns, data_row_major);
    let inputs = data.view((0, 0), (num_rows, 1));
    let inputs: Vec<f64> = inputs.iter().copied().collect();
    let outputs: DMatrix<f64> = data.view((0, 1), (num_rows, num_columns - 1)).into_owned();
    fit_ols_pinv(inputs, outputs)
}
```

--------------------------------

### Rustdoc Keyboard Shortcuts

Source: https://docs.rs/linregress/latest/help

Provides a list of keyboard shortcuts for navigating and interacting with Rustdoc documentation. These shortcuts enhance efficiency when browsing API references and searching for specific items.

```APIDOC
`?`
    Show this help dialog 

`S` / `/` 
    Focus the search field 

`↑`
    Move up in search results 

`↓`
    Move down in search results 

`←` / `→` 
    Switch result tab (when results focused) 

`⏎`
    Go to active search result 

`+`
    Expand all sections 

`-`
    Collapse all sections 

`_`
    Collapse all sections, including impl blocks
```

--------------------------------

### Rust Linear Regression Parameter-Regressor Pairs

Source: https://docs.rs/linregress/latest/src/linregress/lib

Iterates over pairs of regressor names and their associated slope values, excluding the intercept. Includes usage example.

```rust
/// Iterates over pairs of regressor columns and their associated slope values
///
/// # Note
///
/// This does not include the value for the intercept.
///
/// # Usage
///
/// ```
/// # use linregress::Error;
/// # fn main() -> Result<(), Error> {
/// use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};
///
/// let y = vec![1.,2. ,3. , 4.];
/// let x1 = vec![4., 3., 2., 1.];
/// let x2 = vec![1., 2., 3., 4.];
/// let data = vec![("Y", y), ("X1", x1), ("X2", x2)];
/// let data = RegressionDataBuilder::new().build_from(data)?;
/// let model = FormulaRegressionBuilder::new().data(&data).formula("Y ~ X1 + X2").fit()?;
/// let pairs: Vec<(&str, f64)> = model.iter_parameter_pairs().collect();
/// assert_eq!(pairs[0], ("X1", -0.03703703703703709));
/// assert_eq!(pairs[1], ("X2", 0.9629629629629626));
/// # Ok(())
/// # }
/// ```
#[inline]
pub fn iter_parameter_pairs(&self) -> impl Iterator<Item = (&str, f64)> + '_ {
    self.regressor_names
        .iter()
        .zip(self.model.parameters().iter().skip(1))
        .map(|(r, &v)| (r.as_str(), v))
}
```

--------------------------------

### Rust Linear Regression Standard Error Pairs

Source: https://docs.rs/linregress/latest/src/linregress/lib

Iterates over pairs of regressor names and their associated standard errors, excluding the intercept. Includes usage example.

```rust
/// Iterates over pairs of regressor columns and their associated standard errors
///
/// # Note
///
/// This does not include the value for the intercept.
///
/// # Usage
///
/// ```
/// # use linregress::Error;
/// # fn main() -> Result<(), Error> {
/// use linregress::{FormulaRegressionBuilder, RegressionDataBuilder};
///
/// let y = vec![1.,2. ,3. , 4.];
/// let x1 = vec![4., 3., 2., 1.];
/// let x2 = vec![1., 2., 3., 4.];
/// let data = vec![("Y", y), ("X1", x1), ("X2", x2)];
/// let data = RegressionDataBuilder::new().build_from(data)?;
/// let model = FormulaRegressionBuilder::new().data(&data).formula("Y ~ X1 + X2").fit()?;
/// let pairs: Vec<(&str, f64)> = model.iter_parameter_pairs().collect();
/// assert_eq!(pairs[0], ("X1", -0.03703703703703709));
/// assert_eq!(pairs[1], ("X2", 0.9629629629629626));
/// # Ok(())
/// # }
/// ```
#[inline]
pub fn iter_se_pairs(&self) -> impl Iterator<Item = (&str, f64)> + '_ {
    self.regressor_names
        .iter()
        .zip(self.model.se().iter().skip(1))
        .map(|(r, &v)| (r.as_str(), v))
}
```

--------------------------------

### Rust Linear Regression Prediction

Source: https://docs.rs/linregress/latest/src/linregress/lib

Evaluates the model on new input data to return predicted values. Handles potential non-real values in input data. Includes usage example.

```rust
/// Evaluates the model on given new input data and returns the predicted values.
///
/// The new data is expected to have the same columns as the original data.
/// See [`RegressionDataBuilder.build`] for details on the type of the `new_data` parameter.
///
/// ## Note
///
/// This function does *no* special handling of non real values (NaN or infinity or negative infinity).
/// Such a value in `new_data` will result in a corresponding meaningless prediction.
///
/// ## Example
///
/// ```
/// # use linregress::{RegressionDataBuilder, FormulaRegressionBuilder, assert_slices_almost_eq};
/// # use linregress::Error;
/// # fn main() -> Result<(), Error> {
/// let y = vec![1., 2., 3., 4., 5.];
/// let x1 = vec![5., 4., 3., 2., 1.];
/// let x2 = vec![729.53, 439.0367, 42.054, 1., 0.];
/// let x3 = vec![258.589, 616.297, 215.061, 498.361, 0.];
/// let data = vec![("Y", y), ("X1", x1), ("X2", x2), ("X3", x3)];
///
```

--------------------------------

### Supported Platforms

Source: https://docs.rs/linregress/latest/settings

Lists the platforms for which the linregress crate has been compiled and tested.

```Rust
i686-pc-windows-msvc
i686-unknown-linux-gnu
x86_64-apple-darwin
x86_64-pc-windows-msvc
x86_64-unknown-linux-gnu
```

--------------------------------

### Get Standard Errors from Covariance Parameters (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

Calculates the standard errors from a matrix of covariance parameters. It assumes the input matrix is square and extracts the square root of the diagonal elements.

```Rust
fn get_se_from_cov_params(matrix: &DMatrix<f64>) -> Vec<f64> {
    matrix
        .row_iter()
        .enumerate()
        .map(|(n, row)| row.get(n).expect("BUG: Matrix is not square").sqrt())
        .collect()
}
```

--------------------------------

### RegressionDataBuilder::new

Source: https://docs.rs/linregress/latest/src/linregress/lib

Creates a new RegressionDataBuilder with default settings.

```rust
pub fn new() -> Self {
    Self::default()
}
```

--------------------------------

### linregress Crate Information

Source: https://docs.rs/linregress/latest/settings

Provides details about the linregress Rust crate, including its version, license, dependencies, and documentation coverage.

```Rust
crate: linregress-0.5.4
license: MIT
dependencies:
  - nalgebra ^0.33.0
  - tiny-bench ^0.3.0
documentation_coverage: 98.28%
```

--------------------------------

### linregress Crate Structure and Items

Source: https://docs.rs/linregress/latest/linregress/all

Overview of the linregress crate's structure, including its dependencies, supported platforms, and a categorized list of its items such as structs, enums, macros, and functions.

```Rust
Structs:
  FormulaRegressionBuilder
  InconsistentSlopes
  LowLevelRegressionModel
  RegressionData
  RegressionDataBuilder
  RegressionModel

Enums:
  Error
  InvalidValueHandling

Macros:
  assert_almost_eq
  assert_slices_almost_eq

Functions:
  fit_low_level_regression_model
  fit_low_level_regression_model_without_statistics
```

--------------------------------

### Rustdoc Settings

Source: https://docs.rs/linregress/latest/settings

Configurable settings for the Rustdoc documentation generator, affecting appearance and user interface behavior.

```Rust
# Rustdoc settings
Theme:
  preferred_light_theme: light | dark | ayu
  preferred_dark_theme: light | dark | ayu

Features:
  auto_hide_item_contents_for_large_items: boolean
  auto_hide_methods_documentation: boolean
  auto_hide_trait_implementation_documentation: boolean
  direct_go_to_item_in_search: boolean
  show_line_numbers_on_code_examples: boolean
  hide_persistent_navigation_bar: boolean
  hide_table_of_contents: boolean
  hide_module_navigation: boolean
  disable_keyboard_shortcuts: boolean
  use_sans_serif_fonts: boolean
  word_wrap_source_code: boolean
```

--------------------------------

### Get Data Columns from Formula or Columns (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

Retrieves the dependent variable (regressand) and independent variables (regressors) either from a formula string or directly provided column names. It enforces that either a formula or columns must be provided, but not both, and validates the input.

```rust
fn get_data_columns(&self) -> Result<(Cow<'_, str>, Vec<Cow<'_, str>>), Error> {
    match (self.formula.as_ref(), self.columns.as_ref()) {
        (Some(..), Some(..)) => Err(Error::BothFormulaAndDataColumnsGiven),
        (Some(formula), None) => Self::parse_formula(formula),
        (None, Some((regressand, regressors))) => {
            ensure!(!regressors.is_empty(), Error::InvalidDataColumns);
            Ok((regressand.clone(), regressors.clone()))
        }
        (None, None) => Err(Error::NoFormula),
    }
}
```

--------------------------------

### Rustdoc Search Tricks

Source: https://docs.rs/linregress/latest/help

Explains advanced search features in Rustdoc, allowing users to filter searches by item kind, type signature, exact name, and item paths for more precise results.

```APIDOC
Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given item kind.
Accepted kinds are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.
Search functions by type signature (e.g., `vec -> usize` or `-> vec` or `String, enum:Cow -> bool`)
You can look for items with an exact name by putting double quotes around your request: `"string"`
Look for functions that accept or return slices and arrays by writing square brackets (e.g., `-> [u8]` or `[] -> Option`)
Look for items inside another one by searching for a path: `vec::Vec`
```

--------------------------------

### FormulaRegressionBuilder API Documentation

Source: https://docs.rs/linregress/latest/src/linregress/lib

Provides API documentation for the FormulaRegressionBuilder struct, including its methods for creating, configuring, and fitting linear regression models.

```APIDOC
pub struct FormulaRegressionBuilder<'a>
  data: Option<&'a RegressionData<'a>>
  formula: Option<Cow<'a, str>>
  columns: Option<(Cow<'a, str>, Vec<Cow<'a, str>>)>

impl<'a> FormulaRegressionBuilder<'a>
  pub fn new() -> Self
    Create as new FormulaRegressionBuilder with no data or formula set.

  pub fn data(mut self, data: &'a RegressionData<'a>) -> Self
    Set the data to be used for the regression.
    The data has to be given as a reference to a [`RegressionData`] struct.
    See [`RegressionDataBuilder`] for details.

  pub fn formula<T: Into<Cow<'a, str>>>(mut self, formula: T) -> Self
    Set the formula to use for the regression.
    The expected format is `<regressand> ~ <regressor 1> + <regressor 2>`.
    E.g. for a regressand named Y and three regressors named A, B and C
    the correct format would be `Y ~ A + B + C`.
    Note that there is currently no special support for categorical variables.
    So if you have a categorical variable with more than two distinct values
    or values that are not `0` and `1` you will need to perform "dummy coding" yourself.
    Alternatively you can use [`data_columns`][Self::data_columns].

  pub fn data_columns<I, S1, S2>(mut self, regressand: S1, regressors: I) -> Self
    Set the columns to be used as regressand and regressors for the regression.
    Note that there is currently no special support for categorical variables.
    So if you have a categorical variable with more than two distinct values
    or values that are not `0` and `1` you will need to perform "dummy coding" yourself.
    Alternatively you can use [`formula`][Self::formula].

  pub fn fit(self) -> Result<RegressionModel, Error>
    Fits the model and returns a [`RegressionModel`] if successful.
    You need to set the data with [`data`] and a formula with [`formula`]
    before you can use it.

  pub fn fit_without_statistics(self) -> Result<RegressionModel, Error>
    Like [`fit`] but does not perfom any statistics on the resulting model.
```

--------------------------------

### Prepare Regression Matrices and Regressor Names (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

Internal helper function to prepare the input vector and output matrix for regression analysis, along with regressor names. It handles data extraction, column validation, and matrix construction, including adding an intercept column.

```rust
fn get_matrices_and_regressor_names(self) -> Result<FittingData, Error> {
    let (input, outputs) = self.get_data_columns()?;
    let data = &self.data.ok_or(Error::NoData)?.data;
    let input_vector: Vec<f64> = data
        .get(&input)
        .cloned()
        .ok_or_else(|| Error::ColumnNotInData(input.into()))?;
    let mut output_matrix = Vec::new();
    // Add column of all ones as the first column of the matrix
    output_matrix.resize(input_vector.len(), 1.);
    // Add each input as a new column of the matrix
    for output in &outputs {
        let output_vec = data
            .get(output.as_ref())
            .ok_or_else(|| Error::ColumnNotInData(output.to_string()))?;
        ensure!(
            output_vec.len() == input_vector.len(),
            Error::RegressorRegressandDimensionMismatch(output.to_string())
        );
        output_matrix.extend_from_slice(output_vec);
    }
    let output_matrix = DMatrix::from_vec(input_vector.len(), outputs.len() + 1, output_matrix);
    let outputs: Vec<_> = outputs.iter().map(|x| x.to_string()).collect();
    Ok(FittingData(input_vector, output_matrix, outputs))
}
```

--------------------------------

### Low-Level Regression Fitting

Source: https://docs.rs/linregress/latest/linregress/index

Provides functions to fit a regression model directly using input data matrices. Includes an option to skip statistical calculations for performance.

```Rust
fit_low_level_regression_model
fit_low_level_regression_model_without_statistics
```

--------------------------------

### Low-Level Regression Fitting

Source: https://docs.rs/linregress/latest/linregress

Provides functions to fit a regression model directly using input data matrices. Includes an option to skip statistical calculations for performance.

```Rust
fit_low_level_regression_model
fit_low_level_regression_model_without_statistics
```

--------------------------------

### FormulaRegressionBuilder Methods

Source: https://docs.rs/linregress/latest/linregress/struct

Details the methods available for the FormulaRegressionBuilder struct, including initialization, setting data, formulas, and fitting the model.

```APIDOC
pub struct FormulaRegressionBuilder<'a> { /* private fields */ }

// Methods
pub fn new() -> Self
  Create as new FormulaRegressionBuilder with no data or formula set.

pub fn data(self, data: &'a RegressionData<'a>) -> Self
  Set the data to be used for the regression.
  The data has to be given as a reference to a `RegressionData` struct. See `RegressionDataBuilder` for details.

pub fn formula<T: Into<Cow<'a, str>>>(self, formula: T) -> Self
  Set the formula to use for the regression.
  The expected format is `<regressand> ~ <regressor 1> + <regressor 2>`.
  E.g. for a regressand named Y and three regressors named A, B and C the correct format would be `Y ~ A + B + C`.
  Note that there is currently no special support for categorical variables. So if you have a categorical variable with more than two distinct values or values that are not `0` and `1` you will need to perform “dummy coding” yourself.
  Alternatively you can use `data_columns`.

pub fn data_columns<I, S1, S2>(self, regressand: S1, regressors: I) -> Self
  where I: IntoIterator<Item = S2>, S1: Into<Cow<'a, str>>, S2: Into<Cow<'a, str>>,
  Set the columns to be used as regressand and regressors for the regression.
  Note that there is currently no special support for categorical variables. So if you have a categorical variable with more than two distinct values or values that are not `0` and `1` you will need to perform “dummy coding” yourself.
  Alternatively you can use `formula`.

pub fn fit(self) -> Result<RegressionModel, Error>
  Fits the model and returns a `RegressionModel` if successful. You need to set the data with `data` and a formula with `formula` before you can use it.

pub fn fit_without_statistics(self) -> Result<Vec<f64>, Error>
  Like `fit` but does not perfom any statistics on the resulting model. Returns a `Vec` containing the model parameters (in the order `intercept, column 1, column 2, …`) if successfull.
  This is usefull if you do not care about the statistics or the model and data you want to fit result in too few residual degrees of freedom to perform statistics.
```

--------------------------------

### Low-Level Regression Fitting

Source: https://docs.rs/linregress/latest/index

Provides functions to fit a regression model directly using input data matrices. Includes an option to skip statistical calculations for performance.

```Rust
fit_low_level_regression_model
fit_low_level_regression_model_without_statistics
```

--------------------------------

### Create Regression Model from Matrices

Source: https://docs.rs/linregress/latest/src/linregress/lib

Constructs a regression model from input data matrices and regressor names. It performs an Ordinary Least Squares (OLS) fit using the pseudo-inverse method and validates that the number of regressor names matches the number of slopes in the fitted model.

```rust
fn try_from_matrices_and_regressor_names<I: IntoIterator<Item = String>>(
    inputs: Vec<f64>,
    outputs: DMatrix<f64>,
    output_names: I,
) -> Result<Self, Error> {
    let low_level_result = fit_ols_pinv(inputs, outputs)?;
    let model = LowLevelRegressionModel::from_low_level_regression(low_level_result)?;
    let regressor_names: Vec<String> = output_names.into_iter().collect();
    let num_slopes = model.parameters.len() - 1;
    ensure!(
        regressor_names.len() == num_slopes,
        Error::InconsistentSlopes(InconsistentSlopes::new(regressor_names.len(), num_slopes))
    );
    Ok(Self {
        regressor_names,
        model,
    })
}
```

--------------------------------

### Fit OLS using Pseudo Inverse (Rust)

Source: https://docs.rs/linregress/latest/src/linregress/lib

Performs ordinary least squares (OLS) linear regression using the pseudo-inverse method. It includes checks for empty inputs and outputs, computes the singular-value decomposition, and calculates parameters.

```Rust
fn fit_ols_pinv(
    inputs: Vec<f64>,
    outputs: DMatrix<f64>,
) -> Result<InternalLowLevelRegressionResult, Error> {
    ensure!(
        !inputs.is_empty(),
        Error::ModelFittingError(
            "Fitting the model failed because the input vector is empty".into()
        )
    );
    ensure!(
        outputs.nrows() >= 1 && outputs.ncols() >= 1,
        Error::ModelFittingError(
            "Fitting the model failed because the output matrix is empty".into()
        )
    );
    let singular_values = outputs
        .to_owned()
        .try_svd(false, false, std::f64::EPSILON, 0)
        .ok_or_else(|| {
            Error::ModelFittingError(
                "Computing the singular-value decomposition of the output matrix failed".into(),
            )
        })?;
        .singular_values;
    let pinv = outputs.clone().pseudo_inverse(0.).map_err(|_| {
        Error::ModelFittingError("Taking the pinv of the output matrix failed".into())
    });
    let pinv = pinv?;
    let normalized_cov_params = &pinv * &pinv.transpose();
    let params = get_sum_of_products(&pinv, &inputs);
    ensure!(
        params.len() >= 2,
        Error::ModelFittingError("Invalid parameter matrix".into())
    );
    Ok(InternalLowLevelRegressionResult {
        inputs,
        outputs,
        params,
        singular_values,
        normalized_cov_params,
    })
}
```

--------------------------------

### Rust Linear Regression Model Parameters

Source: https://docs.rs/linregress/latest/src/linregress/lib

Provides access to the model's intercept and slopes (betas) as a slice of f64.

```rust
/// The model's intercept and slopes (also known as betas)
#[inline]
pub fn parameters(&self) -> &[f64] {
    self.model.parameters()
}
```

--------------------------------

### Linear Regression Model Fitting and Statistics

Source: https://docs.rs/linregress/latest/src/linregress/lib

This code snippet demonstrates the internal logic for fitting a linear regression model and calculating various statistical properties. It computes parameters, standard errors, residuals, R-squared, adjusted R-squared, and p-values based on the input data and low-level results. It also includes error handling for insufficient degrees of freedom.

```rust
        let parameters = low_level_result.params;
        let singular_values = low_level_result.singular_values;
        let normalized_cov_params = low_level_result.normalized_cov_params;
        let diag = DMatrix::from_diagonal(&singular_values);
        let rank = &diag.rank(0.0);
        let input_vec = low_level_result.inputs.to_vec();
        let input_matrix = DMatrix::from_vec(low_level_result.inputs.len(), 1, input_vec);
        let residuals = &input_matrix - (low_level_result.outputs * parameters.to_owned());
        let ssr = residuals.dot(&residuals);
        let n = low_level_result.inputs.len();
        let df_resid = n - rank;
        ensure!(
            df_resid >= 1,
            Error::ModelFittingError(
                "There are not enough residual degrees of freedom to perform statistics on this model".into()));
        let scale = residuals.dot(&residuals) / df_resid as f64;
        let cov_params = normalized_cov_params * scale;
        let se = get_se_from_cov_params(&cov_params);
        let mean = input_matrix.mean();
        let mut centered_input_matrix = input_matrix;
        subtract_value_from_matrix(&mut centered_input_matrix, mean);
        let centered_tss = centered_input_matrix.dot(&centered_input_matrix);
        let rsquared = 1. - (ssr / centered_tss);
        let rsquared_adj = 1. - ((n - 1) as f64 / df_resid as f64 * (1. - rsquared));
        let tvalues = parameters
            .iter()
            .zip(se.iter())
            .map(|(&x, &y)| x / y.max(std::f64::EPSILON));
        let pvalues: Vec<f64> = tvalues
            .map(|x| students_t_cdf(x.abs().neg(), df_resid as i64).map(|i| i * 2.))
            .collect::<Option<_>>()
            .ok_or_else(|| {
                Error::ModelFittingError(
                    "Failed to calculate p-values: students_t_cdf failed due to invalid parameters"
                        .into(),
                )
            })?;
        // Convert these from internal Matrix types to user facing types
        let parameters: Vec<f64> = parameters.iter().copied().collect();
        let residuals: Vec<f64> = residuals.iter().copied().collect();
        Ok(Self {
            parameters,
            se,
            ssr,
            rsquared,
            rsquared_adj,
            pvalues,
            residuals,
            scale,
        })
```

--------------------------------

### FormulaRegressionBuilder Cloning

Source: https://docs.rs/linregress/latest/linregress/struct

Provides methods for cloning FormulaRegressionBuilder instances, including a direct clone and clone_from.

```rust
fn clone(&self) -> FormulaRegressionBuilder<'a>
// Returns a duplicate of the value.
```

```rust
fn clone_from(&mut self, source: &Self)
// Performs copy-assignment from `source`.
```

--------------------------------

### ULPs-based Floating-Point Comparison

Source: https://docs.rs/linregress/latest/src/linregress/lib

Implements a function `ulps_eq` for comparing floating-point numbers based on Units of Least Precision (ULPs) and an epsilon value. This provides a more robust comparison for floating-point values.

```rust
fn ulps_eq(a: f64, b: f64, epsilon: f64, max_ulps: u32) -> bool {
    if (a - b).abs() <= epsilon {
        return true;
    }
    if a.signum() != b.signum() {
        return false;
    }
    let a: u64 = a.to_bits();
    let b: u64 = b.to_bits();
    a.abs_diff(b) <= max_ulps as u64
}
```

--------------------------------

### Linear Regression Calculation Step

Source: https://docs.rs/linregress/latest/src/linregress/stats

This snippet details a step in a linear regression calculation, involving updates to variables 'd' and 'c' with checks for minimum floating-point values to prevent division by zero. It concludes by checking for convergence based on a small difference from 1.0.

```Rust
        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2));
        d = 1.0 + aa * d;

        if d.abs() < fpmin {
            d = fpmin;
        }

        c = 1.0 + aa / c;

        if c.abs() < fpmin {
            c = fpmin;
        }

        d = 1.0 / d;
        let del = d * c;
        h *= del;

        if (del - 1.0).abs() <= eps {
            return if symm_transform {
                Some(1.0 - bt * h / a)
            } else {
                Some(bt * h / a)
            };
        }
    }

    if symm_transform {
        Some(1.0 - bt * h / a)
    } else {
        Some(bt * h / a)
    }
}
```

--------------------------------

### Linear Regression Model Accessors

Source: https://docs.rs/linregress/latest/src/linregress/lib

Provides accessor methods to retrieve various statistics and parameters from a fitted linear regression model. These include the model's coefficients (parameters), standard errors, sum of squared residuals, R-squared, adjusted R-squared, p-values, residuals, and the scale factor for the covariance matrix.

```rust
    /// The two-tailed p-values for the t-statistics of the parameters
    #[inline]
    pub fn p_values(&self) -> &[f64] {
        &self.pvalues
    }

    /// The residuals of the model
    #[inline]
    pub fn residuals(&self) -> &[f64] {
        &self.residuals
    }

    /// The model's intercept and slopes (also known as betas)
    #[inline]
    pub fn parameters(&self) -> &[f64] {
        &self.parameters
    }

    /// The standard errors of the parameter estimates
    #[inline]
    pub fn se(&self) -> &[f64] {
        &self.se
    }

    /// Sum of squared residuals
    #[inline]
    pub fn ssr(&self) -> f64 {
        self.ssr
    }

    /// R-squared of the model
    #[inline]
    pub fn rsquared(&self) -> f64 {
        self.rsquared
    }

    /// Adjusted R-squared of the model
    #[inline]
    pub fn rsquared_adj(&self) -> f64 {
        self.rsquared_adj
    }

    /// A scale factor for the covariance matrix
    ///
    /// Note that the square root of `scale` is often
    /// called the standard error of the regression.
    #[inline]
    pub fn scale(&self) -> f64 {
        self.scale
    }
```

--------------------------------

### Assertion Macros for Floating-Point Comparisons

Source: https://docs.rs/linregress/latest/src/linregress/lib

Provides macros for asserting approximate equality between floating-point numbers and slices of floating-point numbers. These are useful for testing in the presence of floating-point inaccuracies.

```rust
macro_rules! assert_almost_eq {
    ($a:expr, $b:expr) => {
        $crate::assert_almost_eq!($a, $b, 1.0E-14);
    };
    ($a:expr, $b:expr, $prec:expr) => {
        if !$crate::almost_equal($a, $b, $prec) {
            panic!("assert_almost_eq failed:\n{:?} vs\n{:?}", $a, $b);
        }
    };
}

macro_rules! assert_slices_almost_eq {
    ($a:expr, $b:expr) => {
        $crate::assert_slices_almost_eq!($a, $b, 1.0E-14);
    };
    ($a:expr, $b:expr, $prec:expr) => {
        if !$crate::slices_almost_equal($a, $b, $prec) {
            panic!("assert_slices_almost_eq failed:\n{:?} vs\n{:?}", $a, $b);
        }
    };
}
```

--------------------------------

### Rust Linear Regression Residuals

Source: https://docs.rs/linregress/latest/src/linregress/lib

Provides access to the model's residuals as a slice of f64.

```rust
/// The residuals of the model
#[inline]
pub fn residuals(&self) -> &[f64] {
    self.model.residuals()
}
```

--------------------------------

### Rust Constants for Statistical Calculations

Source: https://docs.rs/linregress/latest/src/linregress/stats

Defines various mathematical constants used in statistical calculations, including natural logarithm of pi, ln(2 * sqrt(e / pi)), auxiliary variables for gamma function, polynomial coefficients for gamma_ln approximation, and the standard epsilon for f64 precision.

```rust
// ln(pi)
const LN_PI: f64 = 1.144_729_885_849_400_2;
// ln(2 * sqrt(e / pi))
const LN_2_SQRT_E_OVER_PI: f64 = 0.620_782_237_635_245_2;
// Auxiliary variable when evaluating the `gamma_ln` function
const GAMMA_R: f64 = 10.900511;

// Polynomial coefficients for approximating the `gamma_ln` function
const GAMMA_DK: [f64; 11] = [
    2.485_740_891_387_535_5e-5,
    1.051_423_785_817_219_7,
    -3.456_870_972_220_162_5,
    4.512_277_094_668_948,
    -2.982_852_253_235_766_4,
    1.056_397_115_771_267,
    -1.954_287_731_916_458_7e-1,
    1.709_705_434_044_412e-2,
    -5.719_261_174_043_057e-4,
    4.633_994_733_599_057e-6,
    -2.719_949_084_886_077_2e-9,
];

// Standard epsilon, maximum relative precision of IEEE 754 double-precision
// floating point numbers (64 bit) e.g. `2^-53`
const F64_PREC: f64 = 1.1102230246251565e-16;
```

--------------------------------

### Generic Type Implementations (Any, Borrow, BorrowMut)

Source: https://docs.rs/linregress/latest/linregress/struct

Demonstrates blanket implementations for generic types, specifically for Any, Borrow, and BorrowMut traits.

```rust
impl<T> Any for T
where T: 'static + ?Sized
fn type_id(&self) -> TypeId
```

```rust
impl<T> Borrow<T> for T
where T: ?Sized
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized
fn borrow_mut(&mut self) -> &mut T
```
Tokens:
Raw