rgsl/fit.rs
1//
2// A rust binding for the GSL library by Guillaume Gomez (guillaume1.gomez@gmail.com)
3//
4
5/*!
6Linear Regression
7
8The functions described in this section can be used to perform least-squares fits to a straight line model, Y(c,x) = c_0 + c_1 x.
9!*/
10
11use crate::Value;
12
13/// This function computes the best-fit linear regression coefficients (c0,c1) of the model
14/// Y = c_0 + c_1 X for the dataset (x, y), two vectors of length n with strides xstride and
15/// ystride.
16///
17/// The errors on y are assumed unknown so the variance-covariance matrix for the parameters
18/// (c0, c1) is estimated from the scatter of the points around the best-fit line and returned via
19/// the parameters (cov00, cov01, cov11).
20///
21/// The sum of squares of the residuals from the best-fit line is returned in sumsq. Note: the
22/// correlation coefficient of the data can be computed using gsl_stats_correlation (see
23/// [`Correlation`](http://www.gnu.org/software/gsl/manual/html_node/Correlation.html#Correlation)),
24/// it does not depend on the fit.
25///
26/// Returns `(c0, c1, cov00, cov01, cov11, sumsq)`.
27#[doc(alias = "gsl_fit_linear")]
28pub fn linear(
29 x: &[f64],
30 xstride: usize,
31 y: &[f64],
32 ystride: usize,
33 n: usize,
34) -> Result<(f64, f64, f64, f64, f64, f64), Value> {
35 let mut c0 = 0.;
36 let mut c1 = 0.;
37 let mut cov00 = 0.;
38 let mut cov01 = 0.;
39 let mut cov11 = 0.;
40 let mut sumsq = 0.;
41 let ret = unsafe {
42 ::sys::gsl_fit_linear(
43 x.as_ptr(),
44 xstride,
45 y.as_ptr(),
46 ystride,
47 n,
48 &mut c0,
49 &mut c1,
50 &mut cov00,
51 &mut cov01,
52 &mut cov11,
53 &mut sumsq,
54 )
55 };
56 result_handler!(ret, (c0, c1, cov00, cov01, cov11, sumsq))
57}
58
59/// This function computes the best-fit linear regression coefficients (c0,c1) of the model
60/// Y = c_0 + c_1 X for the weighted dataset (x, y), two vectors of length n with strides xstride
61/// and ystride.
62///
63/// The vector w, of length n and stride wstride, specifies the weight of each datapoint.
64///
65/// The weight is the reciprocal of the variance for each datapoint in y.
66///
67/// The covariance matrix for the parameters (c0, c1) is computed using the weights and returned via
68/// the parameters (cov00, cov01, cov11).
69/// The weighted sum of squares of the residuals from the best-fit line, \chi^2, is returned in chisq.
70///
71/// Returns `(c0, c1, cov00, cov01, cov11, chisq)`.
72#[doc(alias = "gsl_fit_wlinear")]
73pub fn wlinear(
74 x: &[f64],
75 xstride: usize,
76 w: &[f64],
77 wstride: usize,
78 y: &[f64],
79 ystride: usize,
80 n: usize,
81) -> Result<(f64, f64, f64, f64, f64, f64), Value> {
82 let mut c0 = 0.;
83 let mut c1 = 0.;
84 let mut cov00 = 0.;
85 let mut cov01 = 0.;
86 let mut cov11 = 0.;
87 let mut chisq = 0.;
88 let ret = unsafe {
89 ::sys::gsl_fit_wlinear(
90 x.as_ptr(),
91 xstride,
92 w.as_ptr(),
93 wstride,
94 y.as_ptr(),
95 ystride,
96 n,
97 &mut c0,
98 &mut c1,
99 &mut cov00,
100 &mut cov01,
101 &mut cov11,
102 &mut chisq,
103 )
104 };
105 result_handler!(ret, (c0, c1, cov00, cov01, cov11, chisq))
106}
107
108/// This function uses the best-fit linear regression coefficients c0, c1 and their covariance
109/// cov00, cov01, cov11 to compute the fitted function y and its standard deviation y_err for the
110/// model Y = c_0 + c_1 X at the point x.
111///
112/// Returns `(y, y_err)`.
113#[doc(alias = "gsl_fit_linear_est")]
114pub fn linear_est(
115 x: f64,
116 c0: f64,
117 c1: f64,
118 cov00: f64,
119 cov01: f64,
120 cov11: f64,
121) -> Result<(f64, f64), Value> {
122 let mut y = 0.;
123 let mut y_err = 0.;
124 let ret =
125 unsafe { ::sys::gsl_fit_linear_est(x, c0, c1, cov00, cov01, cov11, &mut y, &mut y_err) };
126 result_handler!(ret, (y, y_err))
127}
128
129/// This function computes the best-fit linear regression coefficient c1 of the model Y = c_1 X for
130/// the datasets (x, y), two vectors of length n with strides xstride and ystride.
131/// The errors on y are assumed unknown so the variance of the parameter c1 is estimated from the
132/// scatter of the points around the best-fit line and returned via the parameter cov11.
133/// The sum of squares of the residuals from the best-fit line is returned in sumsq.
134///
135/// Returns `(c1, cov11, sumsq)`.
136#[doc(alias = "gsl_fit_mul")]
137pub fn mul(
138 x: &[f64],
139 xstride: usize,
140 y: &[f64],
141 ystride: usize,
142 n: usize,
143) -> Result<(f64, f64, f64), Value> {
144 let mut c1 = 0.;
145 let mut cov11 = 0.;
146 let mut sumsq = 0.;
147 let ret = unsafe {
148 crate::sys::gsl_fit_mul(
149 x.as_ptr(),
150 xstride,
151 y.as_ptr(),
152 ystride,
153 n,
154 &mut c1,
155 &mut cov11,
156 &mut sumsq,
157 )
158 };
159 result_handler!(ret, (c1, cov11, sumsq))
160}
161
162/// Returns `(c1, cov11, sumsq)`.
163#[doc(alias = "gsl_fit_wmul")]
164pub fn wmul(
165 x: &[f64],
166 xstride: usize,
167 w: &[f64],
168 wstride: usize,
169 y: &[f64],
170 ystride: usize,
171 n: usize,
172) -> Result<(f64, f64, f64), Value> {
173 let mut c1 = 0.;
174 let mut cov11 = 0.;
175 let mut sumsq = 0.;
176 let ret = unsafe {
177 crate::sys::gsl_fit_wmul(
178 x.as_ptr(),
179 xstride,
180 w.as_ptr(),
181 wstride,
182 y.as_ptr(),
183 ystride,
184 n,
185 &mut c1,
186 &mut cov11,
187 &mut sumsq,
188 )
189 };
190 result_handler!(ret, (c1, cov11, sumsq))
191}
192
193/// This function uses the best-fit linear regression coefficient c1 and its covariance cov11 to
194/// compute the fitted function y and its standard deviation y_err for the model Y = c_1 X at the
195/// point x.
196///
197/// Returns `(y, y_err)`.
198#[doc(alias = "gsl_fit_mul_est")]
199pub fn mul_est(x: f64, c1: f64, cov11: f64) -> Result<(f64, f64), Value> {
200 let mut y = 0.;
201 let mut y_err = 0.;
202 let ret = unsafe { crate::sys::gsl_fit_mul_est(x, c1, cov11, &mut y, &mut y_err) };
203 result_handler!(ret, (y, y_err))
204}