@@@ much mess, mostly manpages
[mLib] / utils / linreg.3.in
CommitLineData
adec5584 1.\" -*-nroff-*-
c4ccbbf9
MW
2.\"
3.\" Manual for linear regression
4.\"
5.\" (c) 2024 Straylight/Edgeware
6.\"
7.
8.\"----- Licensing notice ---------------------------------------------------
9.\"
10.\" This file is part of the mLib utilities library.
11.\"
12.\" mLib is free software: you can redistribute it and/or modify it under
13.\" the terms of the GNU Library General Public License as published by
14.\" the Free Software Foundation; either version 2 of the License, or (at
15.\" your option) any later version.
16.\"
17.\" mLib is distributed in the hope that it will be useful, but WITHOUT
18.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20.\" License for more details.
21.\"
22.\" You should have received a copy of the GNU Library General Public
23.\" License along with mLib. If not, write to the Free Software
24.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
25.\" USA.
26.
27.\"--------------------------------------------------------------------------
28.so ../defs.man \" @@@PRE@@@
29.
30.\"--------------------------------------------------------------------------
31.TH linreg 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
adec5584
MW
32.\" @linreg_init
33.\" @linreg_update
34.\" @linreg_fit
35.\" @LINREG_INIT
36.
c4ccbbf9
MW
37.\"--------------------------------------------------------------------------
38.SH NAME
39lineag \- linear regression
40.
41.\"--------------------------------------------------------------------------
adec5584
MW
42.SH SYNOPSIS
43.nf
44.B "#include <mLib/linreg.h>"
d056fbdf 45.PP
adec5584
MW
46.B "struct linreg { ...\& };"
47.B "#define LINREG_INIT ..."
d056fbdf 48.PP
adec5584
MW
49.BI "void linreg_init(struct linreg *" lr );
50.BI "void linreg_update(struct linreg *" lr ", double " x ", double " y );
51.ta \w'void linreg_fit('u
52.BI "void linreg_fit(struct linreg *" lr ,
53.BI " double *" m_out ", double *" c_out ", double *" r_out );
54.fi
55.
c4ccbbf9 56.\"--------------------------------------------------------------------------
adec5584 57.SH DESCRIPTION
c4ccbbf9 58.
adec5584
MW
59The functions declared in the
60.B <mLib/linreg.h>
61header perform simple linear regression.
62.PP
63The state for a linear regression is held in a
64.BR "struct linreg" .
65Such a structure can be initialized statically,
66using the
67.B LINREG_INIT macro,
68or dynamically, by calling the
69.B linreg_init
70function.
71.PP
72Once a state is initialized,
73points
74.RI ( x ",\ " y )
75can be added by calling
76.BR linreg_update .
77Each call just performs a small and constant amount of computation;
78the linear regression state uses a constant amount of storage
79independent of the number of points.
80.P
81Finally, the
82.B linreg_fit
83function will return the results of the regression.
84It calculates quantities
85.I m
86and
87.I c
88such that the line
89.IR y "\ =\ " m "\ " x "\ +\ " c
90is a reasonable approximation to the data points provided,
91and a correlation coefficient
92.I r
93quantifying how good this approximation is.
94These quantities are stored in
95.BI * m_out \fR,
96.BI * c_out \fR,
97and
98.BI * r_out \fR,
99respectively;
100any (or all, but that wouldn't be useful) of these pointers may be null,
101to discard the corresponding output.
102.PP
103The linear regression state can be discarded without need for ceremony:
104it holds no external resources.
105.PP
106Any half-decent introduction to statistics will explain these concepts.
107.
c4ccbbf9
MW
108.\"--------------------------------------------------------------------------
109.SH SEE ALSO
110.
111.BR mLib (3).
112.
113.\"--------------------------------------------------------------------------
adec5584 114.SH AUTHOR
c4ccbbf9 115.
adec5584 116Mark Wooding, <mdw@distorted.org.uk>
c4ccbbf9
MW
117.
118.\"----- That's all, folks --------------------------------------------------