@@@ man wip

[mLib] / utils / linreg.3

diff --git a/utils/linreg.3 b/utils/linreg.3
new file mode 100644 (file)
index 0000000..20f74ca
--- /dev/null
+++ b/utils/linreg.3
@@ -0,0 +1,73 @@
+.\" -*-nroff-*-
+.TH linreg 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @linreg_init
+.\" @linreg_update
+.\" @linreg_fit
+.\" @LINREG_INIT
+.
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/linreg.h>"
+
+.B "struct linreg { ...\& };"
+.B "#define LINREG_INIT ..."
+
+.BI "void linreg_init(struct linreg *" lr );
+.BI "void linreg_update(struct linreg *" lr ", double " x ", double " y );
+.ta \w'void linreg_fit('u
+.BI "void linreg_fit(struct linreg *" lr ,
+.BI "  double *" m_out ", double *" c_out ", double *" r_out );
+.fi
+.
+.SH DESCRIPTION
+The functions declared in the
+.B <mLib/linreg.h>
+header perform simple linear regression.
+.PP
+The state for a linear regression is held in a
+.BR "struct linreg" .
+Such a structure can be initialized statically,
+using the
+.B LINREG_INIT macro,
+or dynamically, by calling the
+.B linreg_init
+function.
+.PP
+Once a state is initialized,
+points
+.RI ( x ",\ " y )
+can be added by calling
+.BR linreg_update .
+Each call just performs a small and constant amount of computation;
+the linear regression state uses a constant amount of storage
+independent of the number of points.
+.P
+Finally, the
+.B linreg_fit
+function will return the results of the regression.
+It calculates quantities
+.I m
+and
+.I c
+such that the line
+.IR y "\ =\ " m "\ " x "\ +\ " c
+is a reasonable approximation to the data points provided,
+and a correlation coefficient
+.I r
+quantifying how good this approximation is.
+These quantities are stored in
+.BI * m_out \fR,
+.BI * c_out \fR,
+and
+.BI * r_out \fR,
+respectively;
+any (or all, but that wouldn't be useful) of these pointers may be null,
+to discard the corresponding output.
+.PP
+The linear regression state can be discarded without need for ceremony:
+it holds no external resources.
+.PP
+Any half-decent introduction to statistics will explain these concepts.
+.
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>