| 1 | .\" -*-nroff-*- |
| 2 | .TH linreg 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library" |
| 3 | .\" @linreg_init |
| 4 | .\" @linreg_update |
| 5 | .\" @linreg_fit |
| 6 | .\" @LINREG_INIT |
| 7 | . |
| 8 | .SH SYNOPSIS |
| 9 | .nf |
| 10 | .B "#include <mLib/linreg.h>" |
| 11 | |
| 12 | .B "struct linreg { ...\& };" |
| 13 | .B "#define LINREG_INIT ..." |
| 14 | |
| 15 | .BI "void linreg_init(struct linreg *" lr ); |
| 16 | .BI "void linreg_update(struct linreg *" lr ", double " x ", double " y ); |
| 17 | .ta \w'void linreg_fit('u |
| 18 | .BI "void linreg_fit(struct linreg *" lr , |
| 19 | .BI " double *" m_out ", double *" c_out ", double *" r_out ); |
| 20 | .fi |
| 21 | . |
| 22 | .SH DESCRIPTION |
| 23 | The functions declared in the |
| 24 | .B <mLib/linreg.h> |
| 25 | header perform simple linear regression. |
| 26 | .PP |
| 27 | The state for a linear regression is held in a |
| 28 | .BR "struct linreg" . |
| 29 | Such a structure can be initialized statically, |
| 30 | using the |
| 31 | .B LINREG_INIT macro, |
| 32 | or dynamically, by calling the |
| 33 | .B linreg_init |
| 34 | function. |
| 35 | .PP |
| 36 | Once a state is initialized, |
| 37 | points |
| 38 | .RI ( x ",\ " y ) |
| 39 | can be added by calling |
| 40 | .BR linreg_update . |
| 41 | Each call just performs a small and constant amount of computation; |
| 42 | the linear regression state uses a constant amount of storage |
| 43 | independent of the number of points. |
| 44 | .P |
| 45 | Finally, the |
| 46 | .B linreg_fit |
| 47 | function will return the results of the regression. |
| 48 | It calculates quantities |
| 49 | .I m |
| 50 | and |
| 51 | .I c |
| 52 | such that the line |
| 53 | .IR y "\ =\ " m "\ " x "\ +\ " c |
| 54 | is a reasonable approximation to the data points provided, |
| 55 | and a correlation coefficient |
| 56 | .I r |
| 57 | quantifying how good this approximation is. |
| 58 | These quantities are stored in |
| 59 | .BI * m_out \fR, |
| 60 | .BI * c_out \fR, |
| 61 | and |
| 62 | .BI * r_out \fR, |
| 63 | respectively; |
| 64 | any (or all, but that wouldn't be useful) of these pointers may be null, |
| 65 | to discard the corresponding output. |
| 66 | .PP |
| 67 | The linear regression state can be discarded without need for ceremony: |
| 68 | it holds no external resources. |
| 69 | .PP |
| 70 | Any half-decent introduction to statistics will explain these concepts. |
| 71 | . |
| 72 | .SH AUTHOR |
| 73 | Mark Wooding, <mdw@distorted.org.uk> |