ndarray_glm/
lib.rs

1//! A rust library for performing GLM regression with data represented in
2//! [`ndarray`](file:///home/felix/Projects/ndarray-glm/target/doc/ndarray/index.html)s.
3//! The [`ndarray-linalg`](https://docs.rs/ndarray-linalg/) crate is used to allow
4//! optimization of linear algebra operations with BLAS.
5//!
6//! This crate is early alpha and may change rapidly. No guarantees can be made about
7//! the accuracy of the fits.
8//!
9//! # Feature summary:
10//!
11//! * Linear, logistic, Poisson, and binomial regression (more to come)
12//! * Generic over floating-point type
13//! * L2 (ridge) regularization
14//! * Statistical tests of fit result
15//! * Alternative and custom link functions
16//!
17//!
18//! # Setting up BLAS backend
19//!
20//! See the [backend features of
21//! `ndarray-linalg`](https://github.com/rust-ndarray/ndarray-linalg#backend-features)
22//! for a description of the available BLAS configuartions. You do not need to
23//! include `ndarray-linalg` in your crate; simply provide the feature you need to
24//! `ndarray-glm` and it will be forwarded to `ndarray-linalg`.
25//!
26//! Examples using OpenBLAS are shown here. In principle you should also be able to use
27//! Netlib or Intel MKL, although these backends are untested.
28//!
29//! ## System OpenBLAS (recommended)
30//!
31//! Ensure that the development OpenBLAS library is installed on your system. In
32//! Debian/Ubuntu, for instance, this means installing `libopenblas-dev`. Then, put the
33//! following into your crate's `Cargo.toml`:
34//! ```text
35//! ndarray = { version = "0.15", features = ["blas"]}
36//! ndarray-glm = { version = "0.0.12", features = ["openblas-system"] }
37//! ```
38//!
39//! ## Compile OpenBLAS from source
40//!
41//! This option does not require OpenBLAS to be installed on your system, but the
42//! initial compile time will be very long. Use the folling lines in your crate's
43//! `Cargo.toml`.
44//! ```text
45//! ndarray = { version = "0.15", features = ["blas"]}
46//! ndarray-glm = { version = "0.0.12", features = ["openblas-static"] }
47//! ```
48//!
49//! # Examples:
50//!
51//! Basic linear regression:
52//! ```
53//! use ndarray_glm::{array, Linear, ModelBuilder};
54//!
55//! let data_y = array![0.3, 1.3, 0.7];
56//! let data_x = array![[0.1, 0.2], [-0.4, 0.1], [0.2, 0.4]];
57//! let model = ModelBuilder::<Linear>::data(&data_y, &data_x).build().unwrap();
58//! let fit = model.fit().unwrap();
59//! // The result is a flat array with the first term as the intercept.
60//! println!("Fit result: {}", fit.result);
61//! ```
62//!
63//! Data standardization and L2 regularization:
64//! ```
65//! use ndarray_glm::{array, Linear, ModelBuilder, utility::standardize};
66//!
67//! let data_y = array![0.3, 1.3, 0.7];
68//! let data_x = array![[0.1, 0.2], [-0.4, 0.1], [0.2, 0.4]];
69//! // The design matrix can optionally be standardized, where the mean of each independent
70//! // variable is subtracted and each is then divided by the standard deviation of that variable.
71//! let data_x = standardize(data_x);
72//! let model = ModelBuilder::<Linear>::data(&data_y, &data_x).build().unwrap();
73//! // L2 (ridge) regularization can be applied with l2_reg().
74//! let fit = model.fit_options().l2_reg(1e-5).fit().unwrap();
75//! println!("Fit result: {}", fit.result);
76//! ```
77//!
78//! Logistic regression with a non-canonical link function:
79//! ```
80//! use ndarray_glm::{array, Logistic, logistic_link::Cloglog, ModelBuilder};
81//!
82//! let data_y = array![true, false, false, true, true];
83//! let data_x = array![[0.5, 0.2], [0.1, 0.3], [0.2, 0.6], [0.6, 0.3], [0.4, 0.4]];
84//! let model = ModelBuilder::<Logistic<Cloglog>>::data(&data_y, &data_x).build().unwrap();
85//! let fit = model.fit_options().l2_reg(1e-5).fit().unwrap();
86//! println!("Fit result: {}", fit.result);
87//! ```
88
89#![doc(html_root_url = "https://docs.rs/crate/ndarray-glm")]
90pub mod error;
91mod fit;
92mod glm;
93mod irls;
94pub mod link;
95mod math;
96pub mod model;
97pub mod num;
98mod regularization;
99mod response;
100pub mod utility;
101
102// Import some common names into the top-level namespace
103pub use {
104    fit::Fit,
105    model::ModelBuilder,
106    response::logistic::link as logistic_link,
107    response::{binomial::Binomial, linear::Linear, logistic::Logistic, poisson::Poisson},
108};
109
110// re-export common structs from ndarray
111pub use ndarray::{array, Array1, Array2, ArrayView1, ArrayView2};
ndarray_glm/lib.rs

ndarray_glm/
lib.rs
