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.13", 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.13", 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. The fit options may need adjusting as
79//! these are typically more difficult to converge:
80//! ```
81//! use ndarray_glm::{array, Logistic, logistic_link::Cloglog, ModelBuilder};
82//!
83//! let data_y = array![true, false, false, true, true];
84//! let data_x = array![[0.5, 0.2], [0.1, 0.3], [0.2, 0.6], [0.6, 0.3], [0.4, 0.4]];
85//! let model = ModelBuilder::<Logistic<Cloglog>>::data(&data_y, &data_x).build().unwrap();
86//! let fit = model.fit_options().max_iter(64).l2_reg(1e-3).fit().unwrap();
87//! println!("Fit result: {}", fit.result);
88//! ```
89
90#![doc(html_root_url = "https://docs.rs/crate/ndarray-glm")]
91pub mod error;
92mod fit;
93mod glm;
94mod irls;
95pub mod link;
96mod math;
97pub mod model;
98pub mod num;
99mod regularization;
100mod response;
101pub mod utility;
102
103// Import some common names into the top-level namespace
104pub use {
105    fit::Fit,
106    model::ModelBuilder,
107    response::logistic::link as logistic_link,
108    response::{binomial::Binomial, linear::Linear, logistic::Logistic, poisson::Poisson},
109};
110
111// re-export common structs from ndarray
112pub use ndarray::{array, Array1, Array2, ArrayView1, ArrayView2};
ndarray_glm/lib.rs

ndarray_glm/
lib.rs
