%\iffalse
% file: linearregression.dtx
% author: Battista Benciolini
% contact: benciolinibattista at gmail dot com
%
% process this file with pdflatex to obtain:
%
% - linearregression.pfd (full documentation, three pass needed)
% - mainlinearregression.tex (interactive main-program document)
% - linearregression.sty (package)
% - sampledata.txt (as the name says)
%
% The author would strongly appreciate to receive
% any comment, criticism and just usage report
%
%\fi
%\iffalse
%<*ins>
\begingroup
\input docstrip.tex
\keepsilent
\preamble
------------------------------------------------------------------------
[2024-12-14]
This file is part of the (expanded) distribution of linearregression
The author of linearregression is Battista Benciolini
<benciolinibattista at gmail dot com >
------------------------------------------------------------------------
The author would strongly appreciate to receive
any comment, criticism and just usage report
------------------------------------------------------------------------
This program may be used, distributed and modified under
the conditions of the LaTeX Project Public License.
(see: http://www.latex-project.org/lppl.txt)
------------------------------------------------------------------------
\endpreamble
\askforoverwritefalse
\generate{\file{linearregression.sty}{\from{linearregression.dtx}{package}}}
\generate{\file{mainlinearregression.tex}{\from{linearregression.dtx}{main}}}
\nopreamble\nopostamble
\generate{\file{sampledata.txt}{\from{linearregression.dtx}{data}}}
\endgroup
%</ins>
%\fi
%\iffalse
%<*driver>
\documentclass[a4paper,10pt]{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[lite,nobysame,non-compressed-cites]{amsrefs}
\usepackage{amsmath,amssymb,amsfonts}
\usepackage{multicol}
\usepackage{linearregression}
\usepackage{graphics}
\DeclareRobustCommand*{\Ars}{\textsf{%
\lower -.48ex\hbox{\rotatebox{-20}{A}}\kern -.3em{rs}}%
\discretionary{-}{}{\kern -.05em}\TeX\discretionary{-}{}{%
\kern -.17em}\lower -.357ex\hbox{nica}}% excerpt from some GUIT sty file
\NewDocumentCommand\vect{m}{\underline{#1}} % vector
\NewDocumentCommand\barycenter{m}{\overline{#1}} % barycenter
\NewDocumentCommand\point{}{\vect{y}} % point
\NewDocumentCommand\coeff{}{\vect{x}} % direction
\NewDocumentCommand\dx{}{\vect\delta} % direction variation
\NewDocumentCommand\vv{}{\vect{v}} % barycentric coordinates
\NewDocumentCommand\trasp{}{^{\mathsf{T}}} % traspose
\NewDocumentCommand\Renne{}{\mathbb{R}^n} % vector space
\NewDocumentCommand\dor{}{f} % distance from origin
\NewDocumentCommand\ipoint{}{i} % index for points
\NewDocumentCommand\pointsum{}{\sum_{\ipoint=1}^m} % sum over points
\NewDocumentCommand\reff{m}{(\ref{#1})} % ref in ( )
\NewDocumentCommand\matr{m}{{#1}} % matrix
\NewDocumentCommand\mC{}{\matr{C}} % matrix C
\NewDocumentCommand\mc{}{k} % elements of matrix C
\NewDocumentCommand\mL{}{\matr{\Lambda}} % matrix lambda
\NewDocumentCommand\mX{}{\matr{X}} % matrix X
\NewDocumentCommand\spm{}{\phantom{-}} % space for the sign
\NewDocumentCommand\ctext{}{caption} % caption (a variable !)
\NewDocumentCommand\matrixtwotwo{mmmm}{ % | 2 x 2
\begin{pmatrix} #1 & #2 \\ #3 & #4 \end{pmatrix}} % | matrix
\DeclareMathOperator\tr{tr} % trace
\DeclareMathOperator\sgn{sgn} % signum
\title{Linear regression with \LaTeX}
\author{Battista Benciolini}
\NewDocumentCommand\titleauthorfootnote{}{\begingroup% Not an elegant solution
\let\thefootnote\relax % but it is ok at the moment
\footnote{Linear regression with LaTeX - available in CTAN}%
\footnote{Battista Benciolini - contact: benciolinibattista at gmail dot com}%
\endgroup\setcounter{footnote}{0}}%
\parindent=0pt
\begin{document}
\hypersetup{hidelinks}
\maketitle
\titleauthorfootnote
\tableofcontents
\vfill
\DocInput{linearregression.dtx}
\end{document}
%</driver>
%\fi
%
% \section{Introduction: first description of the problem\label{intro}}
% I start with a quote from \Ars\ (April 2021, number 31, page 73):
% \begin{quotation}
% The physicist Mario Rossi is investigating a phenomenon,
% presumably linear, and he performs measurements in his laboratory
% to verify his hypothesis; he measures the quantity $x$ which generates
% the phenomenon and he measures also one of the characteristics
% $y$ showed by the phenomenon under the effect of the stimulation $x$.
% \\ ... \par
% Subsequently Mario graphs the data of the table to judge if the points
% reasonably follow a linear trend or not; in this regard he computes the
% parameters of the regression line and he draws this line on the graph
% in order to judge the quality of the obtained results.
% \\ ... \par
% Being a \LaTeX\ user, he thinks to kill two birds with one stone:
% using \LaTeX\ to draw the graph with the experimental data consisting
% in the $x$, $y$ points and, at the same time, to compute the
% parameter $a$ e $b$ of the regression line $y = ax+b$,
% and finally to draw also this line on the same graph.
% \end{quotation}
% A summary description of the problem is therefore the following.
% A set of data pairs is available and each pair is represented as a point
% in the plane. A straight line is searched that optimally approximates
% the points. The first step is therefore the choice of an optimality criterion.
% This choice is the topic of the next section. \par
% From the text we also know that the possible deviation of $y$
% with respect to the model is quite larger than the uncertainty of $x$.
% \par
% After reading the description of the problem
% of Mario Rossi I tried to produce a solution.
% In this work I will use $y_1$ and $y_2$
% instead of $x$ and $y$ for the two measured quantities that
% will become the first and second coordinate, or abscissa and ordinate,
% in the Cartesian plane.
% \par
% The problem can be treated as a mere problem of approximation or
% alternatively as an estimation problem in the frame of a
% probabilistic description of the uncertainty. The two treatments are
% conceptually different. The probabilistic treatment produces some more
% results, but the estimation of the parameters is the same.
% On the other hand the treatment as an approximation problem is in some sense
% more immediate and requires a less extended theoretical background.
% For this reason it will be preferred here.
% I consider the original problem and also a variation
% of it based on the assumption that the two variables are known with
% the same uncertainty. The two considered situations will prove
% to be quite different.
%
% \section{Geometric definition of three optimality criteria}
% \begin{figure}
% \setlength\unitlength{4cm}
% \begin{picture}(1, 0.7)(0.,0.)
% \multiput(0.,0.)(1.1,0){3}{\line(1,0){1}}
% \multiput(0.,0.)(1.1,0){3}{\line(0,1){1}}
% \multiput(1,1)(1.1,0){3}{\line(-1,0){1}}
% \multiput(1,1)(1.1,0){3}{\line(0,-1){1}}
% \thicklines
% \multiput(0.08,0.06)(1.1,0){3}{\line(4,3){0.88}}
% \multiput(0.26,0.09)(1.1,0){3}{\circle{0.03}}
% \multiput(0.45,0.65)(1.1,0){3}{\circle{0.03}}
% \multiput(0.92,0.44)(1.1,0){3}{\circle{0.03}}
% \put(0.26,0.09){\line(0,1){0.1050}}
% \put(0.45,0.65){\line(0,-1){0.3125}}
% \put(0.92,0.44){\line(0,1){0.2500}}
% \put(1.36,0.09){\line(-1,0){0.14}}
% \put(1.55,0.65){\line( 1,0){0.4167}}
% \put(2.02,0.44){\line(-1,0){0.3333}}
% \put(2.46,0.09){\line(-3,4){0.05}}
% \put(2.65,0.65){\line(3,-4){0.15}}
% \put(3.12,0.44){\line(-3,4){0.12}}
% \end{picture}
% \caption{The three kinds of segments
% used in the definition of the objective function}
% \label{fig:criteria}
% \end{figure}
% For each point given in the plane we can consider the corresponding point
% with the same abscissa and belonging to the line.
% Remember that the line is exactly what has to be determined.
% The distance between the given point and the just defined point on the line
% is a reasonable measure of the discrepancy between the empirical data and the
% corresponding theoretical model.
% The distances we are speaking about are the lengths of the segments shown
% in the leftmost scheme of figure (\ref{fig:criteria}).
% To obtain a global discrepancy measure that considers all the points
% at once we perform the sum of the squares of the lengths
% of the mentioned segments. It is now clear that the two coordinates
% of the points are treated quite differently and play a different role in
% the definition of the optimality criterion. This choice is reasonable when
% the measuring errors only (or mainly) affect the second coordinate.
% The optimal line is the line that minimize the just defined
% global discrepancy. The procedure for the determination of the optimal line
% is named linear regression.
% In this work it is named \textit{classical linear regression}.
% We can easily exchange the role of the two quantities, i.e.\ we can
% imagine that the first quantity is affected by errors.
% The problem is not conceptually different. The segments plotted in the
% central picture
% of figure (\ref{fig:criteria}) represent the discrepancy between
% the empirical data and the model.
% This other procedure is named \textit{classical linear regression
% with inverted role of the coordinates}.\par
% The situation is really different if the two coordinates have to be treated
% symmetrically.
% In this case the discrepancy between
% the empirical data and the model must be defined in a purely geometrical way.
% Just the line and the points enter in the definition without any special role
% for any predefined direction. With these requirements it is quite natural
% to use the distance of each point from the line.
% Remember that the distance of a point
% from a line is intended along the shortest path, i.e.\ measured in the
% direction orthogonal to the line itself. The rightmost scheme of
% figure (\ref{fig:criteria}) shows the segments that are considered.
% The global measure of discrepancy is again obtained as the sum
% of the squares of the lengts of the mentioned orthogonal segments.
% The procedure that obtain the optimal line that
% minimize the just defined global discrepancy is named
% \textit{symmetrical linear regression}.\par
% Some arguments of the present section will be repeated in section
% \ref{package} from the algebraic and computational point of view.
%
% \section{Information on the realised solution, including limitations}
% The code that implements the solution is recorded in two files, that are
% a package (sty) file and a main interactive document.
% The file |linearregression.sty| provides several commands
% that can be used in any document. The file |mainlinearregression.tex|
% provides a simple interactive user interface.
% The package described in the sections \ref{manual} and
% \ref{package} (user manual and implementation) provides the
% functions that execute the various needed operations, i.e.\
% data input, computations, printing the numerical results and
% generating a graphic representation of data and results.
% Some auxiliary functions complete the package.
% The design of the output (tables and plots) includes some arbitrary choices.
% The style of the graphic output is quite minimalist
% (e.g.:\ no colors, no variations of line styles).\par
%
% \section{Some comments about the programming of the package}
% Large part of the code is written using the |expl3| language.
% I have tried to be compliant with the various recommendations and
% prescriptions for a correct use of the language,
% but I probably only partly succeeded.\par
% Different more elegant and more coherent solutions probably exist
% both for the general structure of the package and for some specific part
% of the code, but this is what I have been able to do.
% Some perhaps problematic aspects are mentioned here after.\par
% Several used variables are global and they are accessed by various functions.
% This makes the various parts of the package
% quite connected to each other and creates strong dependencies. \par
% The layered programming style is only partially applied.
% The partition between document command and lower level functions is present,
% but part of the low level code is directly in the document commands.
% Variants are not used.
%
% \section{A ready to use simple user interface\label{main}}
% The main file asks the user for the name of a
% file containing the data and generates a one page output.
%\iffalse
%<*main>
%\fi
% \begin{macrocode}
\documentclass[a4paper]{article}
\usepackage{lmodern}
\usepackage{linearregression}
\begin{document}
\pagestyle{empty}
\lraskfilename
\lrcomputation
\lrplotparameters{0.16}{11.0}
\lrplot{11.0}{+}{+}{-}{-}
\lrprint
\end{document}
% \end{macrocode}
%\iffalse
%</main>
%\fi
% The plot just includes the points and the line obtained with the classical
% linear regression. Lines 8 and 9 of the code must be modified if a different
% result is desired. See the next section for details.
%
% \section{A user manual for the package\label{manual}}
% The various analysis of a data set and the representation of the data
% and of the results is obtained with a sequence of several commands.
% The main operations are:
% (i) selection of the data file, (ii) data imput and computation,
% (iii) printing of a table,
% (iv) printing of a picture (that can be repeated with different parameters).
% It is generally convenient to put the table and the picture(s)
% in a proper floating environment.
% The commands for the four mentioned operations are described here after.
% The first needed operation is to set the name of the data file.
% This is done with the command \DescribeMacro{\lrfilename}
% \cs{lrfilename}\marg{file} that has a mandatory argument.
% The argument is the name of the data file. As an alternative the
% command \DescribeMacro{\lraskfilename} \cs{lraskfilename} can be used.
% It asks the user to type the name of the data file in the terminal.
% \par
% The macro \DescribeMacro{\lrcomputation}
% \cs{lrcomputation} reads the data
% and performs all the computations.
% The results of the computations remain available in internal
% variables and are then used by the macro that print them
% or generates a plot.
%\par
% The macro \DescribeMacro{\lrprint}
% \cs{lrprint} generates a table with all the estimated
% parameters and some information about the data.
% The computed numbers are printed with four decimal digit maximum by default,
% but this number can be set to any desired value with the command
% \DescribeMacro{\lrnumdigit} \cs{lrnumdigit}\marg{number}.
% The mandatory argument is the desired maximum number of digits.
% \par
% The macro \DescribeMacro{\lrplot}
% \cs{lrplot}\marg{imagewidth}\marg{key1}\marg{key2}\marg{key3}\marg{key4}
% really generates the plot. The first argument is the
% width of the plot in centimetrs, while the height is computed according
% to the distribution of the points or it is recorded with the command
% \cs{lrplotparameters} (see below).
% The other four arguments are referred
% to the data points, to the lines determined with classical regression,
% with classical regression with inverted role of the coordinates and
% with symmetric regression.
% The four items, i.e.\ the set of points and the three lines, are drawn
% or not according to the corresponding string found in |key|$i$.
% Each item is not plotted if the string is the character |-|, it is plotted
% in any other case. Furthermore the lines are accompanied by a label made
% by the corresponding |key|, unless it is just a |+| or a |-|.
% \par
% The command \DescribeMacro{\lrplotparameters}
% \cs{lrplotparameters}\marg{diameter}\marg{imageheight}
% is used to record some more parameters that are related to the generation
% of the plot.
% The first argument \marg{diameter} is the diameter in centimeters of the discs
% that represent the points. It must be a real positive number.
% The default value is 0.2.
% The second argument \marg{imageheight} is the height of the plot
% in centimeters.
% It must be a real number with a special meaning of any non positive value.
% If the number is positive it is really used as the height and the variables are
% independently scaled to fill the width and the height of the plot.
% If the value is not positive or if the command is not used the
% two variables are scaled with the same factor and the height is computed
% accordingly. This can generate reasonable results only if the ranges
% of the two variables are not too much different.
% All the arguments are mandatory.
% \par
% The use of \cs{lrnumdigit} and \cs{lrplotparameters} is a convenient solution
% to introduce some flexibility in the output and to completely preserve
% compatibility with the previous version of the package.
% Some more elegant solution could be realized with the use of optional
% arguments and perhaps of key-value pairs, but the implemented solution
% is preferred because it is extremely simple.
% \par
% Few words are necessary about the format of the data file.
% Each record of the file hold the two values related to a point.
% The two values must be separated by any number (one is needed as a minimum) of
% space and comma characters. No character different from space
% can be accepted before the first value and after the second value.
%
% \section{An example\label{example}}
% The data reported here after will be available in |sampledata.txt|
% and will be used in the examples presented in this section .
%\iffalse
%<*data>
%\fi
% \begin{multicols}{4}
% \begin{macrocode}
-0.546 0.107
1.093 -0.510
1.440 1.995
1.414 0.991
0.735 1.585
-1.848 -0.235
-0.203 -0.292
1.517 0.779
0.559 -1.341
-0.462 -0.437
-0.785 -0.661
-0.558 0.397
0.181 -2.616
0.619 1.859
-0.223 -1.915
0.629 -0.534
-1.989 -2.300
-0.241 1.098
-0.931 -1.613
-1.070 0.592
2.341 0.413
1.993 -0.111
-2.357 -0.312
-1.975 0.140
% \end{macrocode}
% \end{multicols}
%\iffalse
%</data>
%\fi
%
% The analysis of the sample data and the generation of a numeric table
% is operated by a code similar to the following
% (see table \ref{tab:sampledata}). \\
% |\lrfilename{sampledata.txt}| \\ |\lrcomputation| \\
% |\lrnumdigit{5}| \\ |\begin{table}| \\
% | \lrprint| \\
% | \caption{Analysis of ... }| \\ |\label{tab:sampledata}\end{table}|
% \par
% The generation of some different graphical representation of the data and of
% the results is operated by a code similar to the following
% (see figures \ref{fig:sampledataB} ).\\
% \RenewDocumentCommand\ctext{}{LEFT The three lines are obtained with the three
% optimality criteria. (AA) classical linear regression; (BB) classical linear
% regression with inverted role of the coordinates; (S) symmetric linear
% regression. RIGHT Data points and line estimated with
% symmetric linear regression.}
% |\begin{figure}|\\|\lrplot{10.}{-}{AA}{BB}{S}| \\
% |\lrplot{10.}{+}{-}{-}{+}|
% \\ |\caption{|\ctext|}|\\ | \label{fig:sampledataB} \end{figure}|
%
% \lrfilename{sampledata.txt} \lrcomputation \lrnumdigit{5}
% \begin{table} \lrprint \caption{Analysis of the sample data}
% \label{tab:sampledata} \end{table}
% \begin{figure} \lrplot{6.}{-}{AA}{BB}{S} \hfill \lrplot{6.}{+}{-}{-}{+}
% \caption{\ctext} \label{fig:sampledataB} \end{figure}
% The same data are used to show the effect of the command
% \cs{lrplotparameters}.
% \begin{figure}
% \lrplotparameters{0.12}{5.} \lrplot{4.}{+}{-}{-}{+} \hfill
% \lrplotparameters{0.10}{3.} \lrplot{4.}{+}{-}{-}{+} \hfill
% \lrplotparameters{0.11}{-1.} \lrplot{4.}{+}{-}{-}{+}
% \caption{Three different version of a plot to demonstrate the use of
% the command \cs{lrplotparameters}} \label{fig:sampledataC} \end{figure}
% The commands:\\ |...| \\
% |\lrplotparameters{0.12}{5.} \lrplot{4.}{+}{-}{-}{+} \hfill | \\
% |\lrplotparameters{0.10}{3.} \lrplot{4.}{+}{-}{-}{+} \hfill | \\
% |\lrplotparameters{0.11}{-1.} \lrplot{4.}{+}{-}{-}{+} | \\ |...| \\
% generate the figure (\ref{fig:sampledataC}).
%
% \section{A package for linear regression
% and the theory behind it\label{package}}
%\iffalse
%<*package>
%\fi
%
% \subsection{Math preliminaries and notation \label{prelim}}
% The coordinates of a set of $m$ points on the plane are available.
% A straight line is searched that optimally approximates the points.\par
% The coordinates of a generic point are $y_1$ and $y_2$
% and they are collected in the vector $\point$.
% Any given point is identified with the index $\ipoint$.
% Explicit indices $(\dots)_1$ or $(\dots)_2$ always refer to the first
% or second coordinate of a point or to the first or second component
% of a vector in the plane.
% Symbolic index $(\dots)\ipoint$ always refers to the different points. Few
% formulas require both indices $(\dots)_{1\ipoint}$, $(\dots)_{2\ipoint}$.\par
% With more then two points a criterion of best approximation
% is needed to select the optimal line that describes the data. \par
% Lower case symbols are used for scalars. Lower case underlined
% symbols are used for vectors in the plane. Upper case symbols
% are used for matrices.
% \par
% It is possible that certain data generate an ambiguity or a singularity
% in the computation.
% The following mathematical treatment of the problem
% do not mention these situations and the code does not deal with them.
%
% \subsection{Package declaration, required package and definition of variables}
% The various macro will be provided in a package file
% that is introduced as usual. Most of the macros require
% the \LaTeX3 syntax.
% \begin{macrocode}
\ProvidesPackage{linearregression}[2024-12-14]
\RequirePackage{pict2e}
\ExplSyntaxOn
% \end{macrocode}
% The variables used in the package are defined hereafter.
% \begin{macrocode}
\ior_new:N \g_BBLR_file_ior
\tl_new:N \g_BBLR_file_name_tl
\int_new:N \g_BBLR_number_of_points_int
\fp_new:N \g_BBLR_abscissa_fp
\fp_new:N \g_BBLR_ordinate_fp
\fp_new:N \g_BBLR_mean_abscissa_fp
\fp_new:N \g_BBLR_mean_ordinate_fp
\fp_new:N \g_BBLR_abscissa_SecOrdMoment_fp
\fp_new:N \g_BBLR_ordinate_SecOrdMoment_fp
\fp_new:N \g_BBLR_mixed_SecOrdMoment_fp
\fp_new:N \g_BBLR_slope_A_fp
\fp_new:N \g_BBLR_slope_B_fp
\fp_new:N \g_BBLR_slope_S_fp
\fp_new:N \g_BBLR_intercept_A_fp
\fp_new:N \g_BBLR_intercept_B_fp
\fp_new:N \g_BBLR_intercept_S_fp
\fp_new:N \g_BBLR_cos_fp
\fp_new:N \g_BBLR_sin_fp
\fp_new:N \g_BBLR_sig_sin_fp
\fp_new:N \g_BBLR_eig_diff_fp
\fp_new:N \g_BBLR_diag_diff_fp
\tl_new:N \g_BBLR_file_line_tl
\fp_new:N \g_BBLR_min_abscissa_fp
\fp_new:N \g_BBLR_min_ordinate_fp
\fp_new:N \g_BBLR_max_abscissa_fp
\fp_new:N \g_BBLR_max_ordinate_fp
\fp_new:N \g_BBLR_min_draw_abscissa_fp
\fp_new:N \g_BBLR_max_draw_abscissa_fp
\bool_new:N \g_BBLR_data_eof_bool
\int_new:N \g_BBLR_record_length_int
\int_new:N \g_BBLR_rec_count_int
\int_new:N \g_BBLR_first_separator_int
\int_new:N \g_BBLR_last_separator_int
\str_const:Nn \c_BBLR_space_str {~}
\str_const:Nn \c_BBLR_comma_str {,}
\str_const:Nn \c_BBLR_plus_str {+}
\str_const:Nn \c_BBLR_minus_str {-}
\bool_new:N \g_BBLR_plot_points_bool
\bool_new:N \g_BBLR_plot_lineA_bool
\bool_new:N \g_BBLR_plot_lineB_bool
\bool_new:N \g_BBLR_plot_lineS_bool
\bool_new:N \g_BBLR_two_scale_bool
\bool_gset_false:N \g_BBLR_two_scale_bool
\fp_new:N \g_BBLR_base_fp
\fp_new:N \g_BBLR_height_fp
\fp_new:N \g_BBLR_Xbase_fp
\fp_new:N \g_BBLR_Xheight_fp
\fp_new:N \g_BBLR_XXheight_fp
\fp_new:N \g_BBLR_Dabscissa_fp
\fp_new:N \g_BBLR_Dordinate_fp
\fp_new:N \g_BBLR_diameter_fp
\fp_gset:Nn \g_BBLR_diameter_fp{0.2}
\fp_new:N \g_BBLR_line_base_length_fp
\fp_new:N \g_BBLR_scale_factor_fp
\fp_new:N \g_BBLR_scale_factor_H_fp
\str_new:N \g_BBLR_point_code_str
\str_new:N \g_BBLR_labelA_str
\str_new:N \g_BBLR_labelB_str
\str_new:N \g_BBLR_labelS_str
\int_new:N \g_BBLR_num_dec_dig_int
\int_gset:Nn \g_BBLR_num_dec_dig_int{4}
% \end{macrocode}
%
% \subsection{Preparing data input}
% \begin{macro}{\lrfilename}
% The command \cs{lrfilename} records the file name passed as argument.
% \begin{macrocode}
\NewDocumentCommand{\lrfilename}{m}{
\tl_gset:Nn \g_BBLR_file_name_tl {#1}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\lraskfilename}
% The command \cs{lraskfilename} asks for the data file name from the terminal.
% \begin{macrocode}
\NewDocumentCommand{\lraskfilename}{}{
\ior_get_term:nN {filename ? } \g_BBLR_file_name_tl
\tl_trim_spaces:N \g_BBLR_file_name_tl
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Computation}
% \begin{macro}{\lrcomputation}
% The command \cs{lrcomputation} reads the data file and
% performs all the relevant computations to solve the
% proposed problem.
% \begin{macrocode}
\NewDocumentCommand{\lrcomputation}{}{%
% \end{macrocode}
%
% \subsubsection{Computation of first and second order moments}
% In the sequel it will results that the first and second order moments
% of the data provide everything needed to solve the problem.
% The barycenter of the data is defined as
% \begin{equation}
% \barycenter{\point}=\frac{1}{m}\pointsum \point_\ipoint.
% \label{barycenter} \end{equation}
% It is convenient to scan the data to accumulate the sum
% that appears in \reff{barycenter}.
% The coordinates of each point are read from the file
% and they are immediately used. The data are not globally recorded.
% \begin{macrocode}
\bool_gset_false:N \g_BBLR_data_eof_bool
\int_zero:N \g_BBLR_number_of_points_int
\fp_zero:N \g_BBLR_mean_abscissa_fp
\fp_zero:N \g_BBLR_mean_ordinate_fp
\ior_open:Nn \g_BBLR_file_ior \g_BBLR_file_name_tl
\bool_until_do:Nn \g_BBLR_data_eof_bool {
\ior_str_get:NN \g_BBLR_file_ior \g_BBLR_file_line_tl
\if_eof:w \g_BBLR_file_ior
\bool_gset_true:N \g_BBLR_data_eof_bool
\else:
\int_incr:N \g_BBLR_number_of_points_int
\BBLR_decode_data:
\fp_gset:Nn \g_BBLR_mean_abscissa_fp
{\g_BBLR_mean_abscissa_fp + \g_BBLR_abscissa_fp}
\fp_gset:Nn \g_BBLR_mean_ordinate_fp
{\g_BBLR_mean_ordinate_fp + \g_BBLR_ordinate_fp}
\fi:
}
% \end{macrocode}
% Loop ended. Now close the file and divide by the number of points.
% \begin{macrocode}
\ior_close:N \g_BBLR_file_ior
\fp_gset:Nn \g_BBLR_mean_abscissa_fp
{\g_BBLR_mean_abscissa_fp / \g_BBLR_number_of_points_int}
\fp_gset:Nn \g_BBLR_mean_ordinate_fp
{\g_BBLR_mean_ordinate_fp / \g_BBLR_number_of_points_int}
% \end{macrocode}
%
% The barycentric coordinates are defined for each point
% \begin{equation} \vv_\ipoint= \point_\ipoint - \barycenter{\point}
% \label{residual} \end{equation}
% and the empirical dispersion matrix is defined as:
% \begin{equation} \mC=\frac{1}{m}\pointsum \vv_\ipoint\vv_\ipoint\trasp .
% \label{matrixC} \end{equation}
% Superscript as in $()\trasp$ means transpose. The elements of $\mC$ are the
% second order central moments and they are denoted as:
% \begin{equation} \mC=\matrixtwotwo{\mc_{11}}{\mc_{12}}{\mc_{12}}{\mc_{22}}.
% \label{matrixCc} \end{equation}
% A second scan of the data is performed to compute the
% sums that appears in \reff{matrixC} and to determine the
% the extremal values of the coordinates. Record scan can be regulated
% by a record counter, because the number of points is now known.
% \begin{macrocode}
\fp_zero:N \g_BBLR_abscissa_SecOrdMoment_fp
\fp_zero:N \g_BBLR_ordinate_SecOrdMoment_fp
\fp_zero:N \g_BBLR_mixed_SecOrdMoment_fp
\fp_gset_eq:NN \g_BBLR_min_abscissa_fp \g_BBLR_mean_abscissa_fp
\fp_gset_eq:NN \g_BBLR_min_ordinate_fp \g_BBLR_mean_ordinate_fp
\fp_gset_eq:NN \g_BBLR_max_abscissa_fp \g_BBLR_mean_abscissa_fp
\fp_gset_eq:NN \g_BBLR_max_ordinate_fp \g_BBLR_mean_ordinate_fp
\ior_open:Nn \g_BBLR_file_ior \g_BBLR_file_name_tl
\int_zero:N \g_BBLR_rec_count_int
\int_do_until:nn
{\g_BBLR_rec_count_int = \g_BBLR_number_of_points_int}
{
\ior_str_get:NN \g_BBLR_file_ior \g_BBLR_file_line_tl
\int_incr:N \g_BBLR_rec_count_int
\BBLR_decode_data:
\fp_gset:Nn \g_tmpa_fp
{\g_BBLR_abscissa_fp - \g_BBLR_mean_abscissa_fp}
\fp_gset:Nn \g_tmpb_fp
{\g_BBLR_ordinate_fp - \g_BBLR_mean_ordinate_fp}
\fp_gset:Nn \g_BBLR_abscissa_SecOrdMoment_fp
{\g_BBLR_abscissa_SecOrdMoment_fp + \g_tmpa_fp * \g_tmpa_fp}
\fp_gset:Nn \g_BBLR_mixed_SecOrdMoment_fp
{\g_BBLR_mixed_SecOrdMoment_fp + \g_tmpa_fp * \g_tmpb_fp}
\fp_gset:Nn \g_BBLR_ordinate_SecOrdMoment_fp
{\g_BBLR_ordinate_SecOrdMoment_fp + \g_tmpb_fp * \g_tmpb_fp}
\fp_gset:Nn \g_BBLR_min_abscissa_fp
{min(\g_BBLR_min_abscissa_fp, \g_BBLR_abscissa_fp)}
\fp_gset:Nn \g_BBLR_min_ordinate_fp
{min(\g_BBLR_min_ordinate_fp, \g_BBLR_ordinate_fp)}
\fp_gset:Nn \g_BBLR_max_abscissa_fp
{max(\g_BBLR_max_abscissa_fp, \g_BBLR_abscissa_fp)}
\fp_gset:Nn \g_BBLR_max_ordinate_fp
{max(\g_BBLR_max_ordinate_fp, \g_BBLR_ordinate_fp)}
}
\ior_close:N \g_BBLR_file_ior
\fp_gset:Nn \g_BBLR_abscissa_SecOrdMoment_fp
{\g_BBLR_abscissa_SecOrdMoment_fp / \g_BBLR_number_of_points_int}
\fp_gset:Nn \g_BBLR_mixed_SecOrdMoment_fp
{\g_BBLR_mixed_SecOrdMoment_fp / \g_BBLR_number_of_points_int}
\fp_gset:Nn \g_BBLR_ordinate_SecOrdMoment_fp
{\g_BBLR_ordinate_SecOrdMoment_fp / \g_BBLR_number_of_points_int}
\fp_gset:Nn \g_BBLR_Dabscissa_fp
{\g_BBLR_max_abscissa_fp - \g_BBLR_min_abscissa_fp }
\fp_gset:Nn \g_BBLR_Dordinate_fp
{\g_BBLR_max_ordinate_fp - \g_BBLR_min_ordinate_fp }
% \end{macrocode}
% A single pass algorithm exists, but it is numerically less stable.
%
% \subsubsection{Classical linear regression \label{classical}}
% A line in the plane is described by the equation
% \begin{equation} y_2=ay_1+b \label{eqab} \end{equation}
% that contains the parameters $a$ and $b$.
% For each point it is possible to define a distance or a discrepancy
% of the experimental data with respect to the model.
% In the given problem the second coordinate is much more affected by
% errors than the first coordinate. It is therefore reasonable
% to define the approximation error of each point as
% \begin{equation} e_\ipoint=y_{2\ipoint}-ay_{1\ipoint}-b
% \label{e}\end{equation}
% i.e.\ the difference between the empirical value $y_{2\ipoint}$
% and its model counterpart $ay_{1\ipoint}+b$.
% This is the already mentioned classical linear regression. In fact the
% absolute value of $e_\ipoint$ expressed in (\ref{e}) is the lenght
% of the segments shown in the leftmost scheeme of figure (\ref{fig:criteria}).
% The global discrepancy between the data and the model is measured by the
% least square objective function defined by:
% \begin{equation} \psi=\pointsum e_\ipoint^2 \label{psiab} \end{equation}
% and the parameters $a$ and $b$ will be determined
% just by the minimization of the function $\psi$ defined in \reff{psiab}.
% \par
% In the present treatment of the regression problem as a pure
% approximation problem the definition of $\psi$ in \reff{psiab}
% seams quite arbitrary. It is anyway a convenient choice.
% \par
% Expression \reff{e} can be rewritten in the different form
% \begin{equation}
% e_\ipoint=v_{2\ipoint}-av_{1\ipoint}+\barycenter{y}_2-a\barycenter{y}_1-b
% \label{e2}\end{equation}
% so that the function to be minimized can be expressed
% as the sum of two quadratic functions:
% \begin{equation}
% \psi=
% \pointsum (v_{2\ipoint}-av_{1\ipoint})^2+
% m(\barycenter{y}_2-a\barycenter{y}_1-b)^2
% \label{psiab2} \end{equation}
% and the minimum can be attained considering
% the two terms one at a time.
% The second term in the right-hand side of \reff{psiab2}
% vanishes if the choice of $b$ is:
% \begin{equation} b=\barycenter{y}_2-a\barycenter{y}_1.
% \label{estb} \end{equation}
% The first term in the right-hand side of \reff{psiab2} becomes:
% \begin{equation} \psi_{(a)}=m\left(\mc_{22}-2a\mc_{12}+a^2\mc_{11}\right).
% \label{parabola} \end{equation}
% Searching the minimum of $\psi$ w.r.t.\ $a$ is therefore the search
% of the abscissa of the vertex of a parabola
% with axis parallel to the second coordinated axis.
% The result is:
% \begin{equation} a=\mc_{12}/\mc_{11}
% \label{esta} \end{equation}
% Now the slope $a$ and the intercept $b$ can be actually computed.
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_slope_A_fp
{\g_BBLR_mixed_SecOrdMoment_fp / \g_BBLR_abscissa_SecOrdMoment_fp }
\fp_gset:Nn \g_BBLR_intercept_A_fp
{\g_BBLR_mean_ordinate_fp - \g_BBLR_slope_A_fp * \g_BBLR_mean_abscissa_fp}
% \end{macrocode}
% \par
% The empirical data and the estimated values of $a$ and $b$
% can be used to compute
% the value actually attained by the residuals $e_\ipoint$ and
% by the function $\psi$. Then the index
% \begin{equation} \hat\sigma_0^2=\psi/(m-2)\end{equation}
% can be used to evaluate the general quality of the data and of the model.
% This claim is clearly quite generic. A complete understanding
% of this evaluation would require to treat the linear regression
% problem in the framework of the probabilistic estimation theory.
% The used notation is derived from that theory.\par
% If the role of the two coordinates is exchanged the result
% for $a$ becomes (still with reference to \reff{eqab})
% \begin{equation} a=\mc_{22}/\mc_{12}.\end{equation}
% The slope and the intercept can be computed accordingly.
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_slope_B_fp
{\g_BBLR_ordinate_SecOrdMoment_fp / \g_BBLR_mixed_SecOrdMoment_fp}
\fp_gset:Nn \g_BBLR_intercept_B_fp
{\g_BBLR_mean_ordinate_fp - \g_BBLR_slope_B_fp * \g_BBLR_mean_abscissa_fp}
% \end{macrocode}
%
% \subsubsection{Symmetric linear regression \label{symmetric}}
% If both the coordinates of the experimental points are affected
% by the same uncertainty it is advisable to use a more symmetric
% optimality criterion and it is convenient to use a different model equation.
% \par
% The same line can be described by a different equation, i.e.\
% \begin{equation} x_1y_1+x_2y_2=\dor \end{equation}
% or in vector form:
% \begin{equation} \coeff\trasp\point=\dor. \label{eqvx} \end{equation}
% The parameters in \reff{eqvx}
% are the scalar $\dor$ and the elements
% of the vector $\coeff$, i.e.\ $x_1$ and $x_2$.
% The line described by \reff{eqvx} is obviously
% invariant when the three parameters are simultaneously
% scaled by a constant. The normalization condition
% \begin{equation} \coeff\trasp\coeff=1, \label{norm} \end{equation}
% supplemented by $\dor\ge 0$,
% is quite convenient because the parameters will assume
% a significant geometrical meaning:
% $\coeff$ is a unit vector orthogonal to the line and $\dor$
% is the distance of the line from the origin.
% The expression
% \begin{equation} d=\dor-\coeff\trasp\point \label{distance} \end{equation}
% is the distance of the generic point $\point$ from the line
% with a sign that is positive for points on the same side of the origin.
% \par
% The distance of each given point from the desired optimal line
% is denoted by $d_\ipoint$.
% It has a clear intrinsic geometrical meaning and it does not
% privileges one coordinate w.r.t.\ the other.
% The function to be minimized by the optimal line is
% \begin{equation}
% \phi=\frac{1}{m}\pointsum d_\ipoint^2. \label{phi1} \end{equation}
% The parameters of \reff{eqvx} are determined by the minimization
% of the function $\phi$ that can be expressed as:
% \begin{equation}
% \phi=\frac{1}{m}\pointsum (\coeff\trasp\point_{\ipoint}-\dor)^{2}
% \label{phi2} \end{equation}
% and then, after some algebraic manipulations:
% \begin{equation}
% \phi=\coeff\trasp\mC\coeff+(\dor-\coeff\trasp\barycenter{\point})^2
% \label{phi3}. \end{equation}
% The function $\phi$ is composed (as it was the function $\psi$) by the sum
% of two parts. The second term in the right-hand side of \reff{phi3}
% vanishes if the choice of $\dor$ is:
% \begin{equation} \dor=\coeff\trasp\barycenter{\point}.
% \label{estd} \end{equation}
% Both (\ref{estb}) and (\ref{estd}) means that the optimal line includes
% the mean point.
% Then it is necessary to minimize the function
% \begin{equation} \phi_{(\coeff)} = \coeff\trasp\mC\coeff
% \label{quadraticfun} \end{equation}
% with the constrain $\coeff\trasp\coeff=1$.
% It can be proved that the function $\phi_{(\coeff)}$
% is stationary if $\coeff$ is an eigenvector of \mC. \par
% The function $\phi_{(\coeff)}$ and the constrain must be combined
% using a Lagrange multiplier:
% \begin{equation}
% \Phi= \coeff\trasp\mC\coeff+\lambda(1-\coeff\trasp\coeff).
% \label{Phi} \end{equation}
% Then the stationarity points of $\Phi$ must be determined.
% Equating to zero the derivatives of $\Phi$ gives
% \begin{equation}
% \mC\coeff=\lambda\coeff
% \label{auto} \end{equation}
% i.e.\ $\coeff$ is an eigenvector of $\mC$. \par
% The same result is obtained with the following argument.
% The function $\phi_{(\coeff)}$ is stationary if its first variation
% is zero. The variation of $\coeff$ is named $\dx$ .
% It must respect the constrain, that becomes $\dx\trasp\coeff=0$.
% The first variation of $\phi_{(\coeff)}$ is $2\dx\trasp\mC\coeff$,
% and it is zero if and only if the following implication is valid:
% $\dx\trasp\coeff=0 \implies \dx\trasp\mC\coeff=0$,
% and the implication is valid if and only if the vector
% $\mC\coeff$ has the same direction of $\coeff$, i.e.\ if
% $\coeff$ is an eigenvector of $\mC$.
% \par
% The result on the optimal line
% can be described geometrically in the following way:
% (i) the optimal line includes the barycenter of the data;
% (ii) the optimal line is orthogonal to the eigenvector of
% $\mC$ corresponding to the minimum eigenvalue .\par
% The obtained result can be generalized in $\Renne$.
% A set of points in $\Renne$ must be approximated by an $(n-1)$-dimensional
% affine subspace. (Other more general situations can be considered.)
% \par
% The trace of the matrix $\mC$, denoted as $\tr(\mC)$, is a measure of the
% global dispersion of the set of points.
% The minimum eigenvalue $\lambda_{\textrm{min}}$ of $\mC$ is a measure
% of the dispersion of the set of points with
% respect to the optimal affine subspace. Therefore the index
% \begin{equation} \frac{n\lambda_{\textrm{min}}}{\tr(\mC)}
% \end{equation}
% can be used as an indicator of the relative residual
% dispersion of the data around the optimal affine subspace.
% The defined index is dimensionless and it is
% always between $0$ and $1$.
% \par
% For the actual computation of $\coeff$ it is convenient to consider
% the spectral factorization of the matrix $\mC$, i.e.\
% $\mC=\mX\mL\mX\trasp$ where $\mL$ is a diagonal matrix
% whose diagonal elements are the eigenvalues of $\mC$
% and $\mX$ is an orthonormal matrix whose columns are
% the eigenvectors of $\mC$. The spectral factorization exists
% for any symmetric matrix, but it is specially simple for
% a $2\times 2$ matrix.
% \begin{equation}
% \matrixtwotwo{\mc_{11}}{\mc_{12}}{\mc_{12}}{\mc_{22}}=
% \matrixtwotwo{c}{-s}{s}{\spm c}
% \matrixtwotwo{\lambda_1}{0}{0}{\lambda_2}
% \matrixtwotwo{\spm c}{s}{-s}{c}
% \label{spectral}\end{equation}
% The eigenvalues can be easily obtained because
% their sum is the trace of $\mC$
% \begin{equation}
% \lambda_1 + \lambda_2 = \mc_{11}+\mc_{22}
% \label{Sum}\end{equation}
% and their product
% is the determinant of the same matrix.
% Therefore after some manipulations it results:
% \begin{equation}
% \lambda_1 - \lambda_2 = \sqrt{(\mc_{11}-\mc_{22})^2+4\mc_{12}^2}
% \label{Difference}\end{equation}
% and the two eigenvalues are then immediately obtained. \par
% It is convenient to compute the difference of the two diagonal elements
% of the dispersion matrix and the difference of its eigenvalues.
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_diag_diff_fp
{\g_BBLR_abscissa_SecOrdMoment_fp - \g_BBLR_ordinate_SecOrdMoment_fp}
\fp_gset:Nn \g_BBLR_eig_diff_fp
{sqrt(\g_BBLR_diag_diff_fp * \g_BBLR_diag_diff_fp +
4 * \g_BBLR_mixed_SecOrdMoment_fp * \g_BBLR_mixed_SecOrdMoment_fp)}
% \end{macrocode}
% The computation of $c$ and $s$ is obtained from \reff{spectral}
% taking into account that $c^2+s^2=1$.
% From \reff{spectral} it results:
% \begin{equation} \mc_{11}-\mc_{22}=(\lambda_1-\lambda_2)(c^2-s^2)
% \label{Cos2A}\end{equation}
% and also
% \begin{equation} \mc_{12}=(\lambda_1-\lambda_2)cs
% \label{Sin2A}\end{equation}
% that is only used to determine the sign of $cs$.
% The expression for the parameters $c$ and $s$ are:
% \begin{equation}
% c=\sqrt{\frac{1}{2}+\frac{\mc_{11}-\mc_{22}}{2(\lambda_1-\lambda_2)}}
% \label{cos}\end{equation}
% \begin{equation}
% s=\sgn(\mc_{12})
% \sqrt{\frac{1}{2}-\frac{\mc_{11}-\mc_{22}}{2(\lambda_1-\lambda_2)}}
% \label{sin}\end{equation}
% The parameters $s$ and $c$ are the sine and cosine
% of the angle between the axis of $y_1$ and the eigenvector
% corresponding to the maximum eigenvalue. \par
% They are computed using the already defined elements.
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_cos_fp%
{sqrt((1 + \g_BBLR_diag_diff_fp / \g_BBLR_eig_diff_fp) / 2)}
\fp_gset:Nn \g_BBLR_sig_sin_fp {\fp_sign:n {\g_BBLR_mixed_SecOrdMoment_fp}}
\fp_gset:Nn \g_BBLR_sin_fp
{\g_BBLR_sig_sin_fp*sqrt((1-\g_BBLR_diag_diff_fp / \g_BBLR_eig_diff_fp) / 2)}
% \end{macrocode}
% The vector $\coeff$ is :
% \begin{equation}
% \coeff=\sgn(-s\barycenter{y}_1+c\barycenter{y}_2)
% \begin{pmatrix} -s \\ c\end{pmatrix}.
% \label{xhat}\end{equation}
%
%\par
% The parameter $a$ of model \reff{eqab} can be obtained as:
% \begin{equation}
% a=s/c
% \end{equation}
% Now the slope and the intercept of the optimal line corresponding to the
% symmetric criterion can be computed.
%
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_slope_S_fp
{\g_BBLR_sin_fp / \g_BBLR_cos_fp }
\fp_gset:Nn \g_BBLR_intercept_S_fp
{\g_BBLR_mean_ordinate_fp -
\g_BBLR_slope_S_fp * \g_BBLR_mean_abscissa_fp}
}
% \end{macrocode}
%
% The theoretical treatment of the proposed problem and the
% implementation of its numerical solution end here.
% \end{macro}
%
% \subsection{Print of table of results}
% \begin{macro}{\lrprint}
% The command \cs{lrprint} prints some info on the data
% and the results of the computations in tabular form.
% \begin{macrocode}
\NewDocumentCommand{\lrprint}{}{
\begin{center}
\begin{tabular}{| l | r |} \hline
Data~File & \g_BBLR_file_name_tl \\
\hline
Number~of~points & \int_use:N\g_BBLR_number_of_points_int \\
\hline
Mean~values~of~the~coordinates &%
$\BBLR_print_fp:N \g_BBLR_mean_abscissa_fp$ \\ &
$\BBLR_print_fp:N \g_BBLR_mean_ordinate_fp$ \\ \hline
Minimum~values~of~the~coordinates &%
$\BBLR_print_fp:N \g_BBLR_min_abscissa_fp$ \\ &
$\BBLR_print_fp:N \g_BBLR_min_ordinate_fp$ \\ \hline
Maximum~values~of~the~coordinates &%
$\BBLR_print_fp:N \g_BBLR_max_abscissa_fp$ \\ &
$\BBLR_print_fp:N \g_BBLR_max_ordinate_fp$ \\ \hline
{Second~order~moments}\phantom{xxxxxxxxx}{abscissa} &%
$\BBLR_print_fp:N \g_BBLR_abscissa_SecOrdMoment_fp$ \\
\multicolumn{1}{|r|}{mixed} & %
$\BBLR_print_fp:N \g_BBLR_mixed_SecOrdMoment_fp$ ~ \\
\multicolumn{1}{|r|}{ordinate} & %
$\BBLR_print_fp:N \g_BBLR_ordinate_SecOrdMoment_fp$ \\ \hline
Slope~and~intercept~of~optimal~line & $\BBLR_print_fp:N
\g_BBLR_slope_A_fp$ \\
(estimated~with~errors~in~ordinate)&$\BBLR_print_fp:N
\g_BBLR_intercept_A_fp$\\ \hline
Slope~and~intercept~of~optimal~line & $\BBLR_print_fp:N
\g_BBLR_slope_B_fp$ \\
(estimated~with~errors~in~abscissa)&$\BBLR_print_fp:N
\g_BBLR_intercept_B_fp$\\ \hline
Unit~vector~along~the~line & $\BBLR_print_fp:N
\g_BBLR_cos_fp$ \\
& $\BBLR_print_fp:N \g_BBLR_sin_fp$ \\
Slope~and~intercept~of~optimal~line &$\BBLR_print_fp:N
\g_BBLR_slope_S_fp$ \\
(estimated~with~symmetric~regression) &
$\BBLR_print_fp:N \g_BBLR_intercept_S_fp$\\ \hline
\end{tabular}
\end{center}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\lrnumdigit}
% The command \cs{lrnumdigit} records the maximum number of digits
% used in the table for computed numbers. The default value is $4$.
% \begin{macrocode}
\NewDocumentCommand{\lrnumdigit}{m}{
\int_gset:Nn \g_BBLR_num_dec_dig_int{#1}
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Plot of points and lines}
% \begin{macro}{\lrplot}
% The command \cs{lrplot} produce a framed plot of the data
% and of the regression line(s). The size of the plot and its actual
% content are determined by the arguments.
% \begin{macrocode}
\NewDocumentCommand{\lrplot}{mmmmm}{%
% \end{macrocode}
% The plotting area is divided into a main plotting area for
% the representation of points and line(s) and a small surrounding free space.
% The height is computed taking into account the distribution of the points,
% if it is not explicitelly given..
% \begin{macrocode}
\fp_gset:Nn \g_BBLR_base_fp {#1}
\fp_gset:Nn \g_BBLR_Xbase_fp {\g_BBLR_base_fp - 0.6}
\fp_gset:Nn \g_BBLR_scale_factor_fp{\g_BBLR_Xbase_fp /
\g_BBLR_Dabscissa_fp}
\bool_if:NTF \g_BBLR_two_scale_bool
{\fp_gset:Nn \g_BBLR_height_fp {\g_BBLR_XXheight_fp}
\fp_gset:Nn \g_BBLR_Xheight_fp {\g_BBLR_height_fp - 0.6}
\fp_gset:Nn \g_BBLR_scale_factor_H_fp{\g_BBLR_Xheight_fp /
\g_BBLR_Dordinate_fp}
}
{\fp_gset:Nn \g_BBLR_Xheight_fp {\g_BBLR_Dordinate_fp *
\g_BBLR_scale_factor_fp}
\fp_gset:Nn \g_BBLR_height_fp {\g_BBLR_Xheight_fp + 0.6}
\fp_gset:Nn \g_BBLR_scale_factor_H_fp {\g_BBLR_scale_factor_fp }
}
% \end{macrocode}
% The information about the items to be plotted is in the remaining arguments.
% \begin{macrocode}
\str_gset:Nn \g_BBLR_point_code_str {#2}
\str_gset:Nn \g_BBLR_labelA_str {#3}
\str_gset:Nn \g_BBLR_labelB_str {#4}
\str_gset:Nn \g_BBLR_labelS_str {#5}
\bool_gset:Nn \g_BBLR_plot_points_bool
{!(\str_if_eq_p:NN \g_BBLR_point_code_str \c_BBLR_minus_str)}
\bool_gset:Nn \g_BBLR_plot_lineA_bool
{!(\str_if_eq_p:NN \g_BBLR_labelA_str \c_BBLR_minus_str)}
\bool_gset:Nn \g_BBLR_plot_lineB_bool
{!(\str_if_eq_p:NN \g_BBLR_labelB_str \c_BBLR_minus_str)}
\bool_gset:Nn \g_BBLR_plot_lineS_bool
{!(\str_if_eq_p:NN \g_BBLR_labelS_str \c_BBLR_minus_str)}
% \end{macrocode}
% The unit of length is $1$ centimeter. The plotting area is framed.
% \begin{macrocode}
\setlength{\unitlength}{1.0cm}
\fp_gset:Nn \g_tmpa_fp {\g_BBLR_Xbase_fp +0.2}
\fp_gset:Nn \g_tmpb_fp {\g_BBLR_Xheight_fp +0.1}
\begin{picture}(\fp_use:N\g_BBLR_base_fp,\fp_use:N\g_BBLR_height_fp)(-0.3,-0.3)
\put(-0.1,-0.1){\line(1,0){\fp_use:N\g_tmpa_fp}}
\put(-0.1,\fp_use:N\g_tmpb_fp){\line(1,0){\fp_use:N\g_tmpa_fp}}
\fp_gset:Nn \g_tmpa_fp {\g_tmpa_fp -0.1}
\fp_gset:Nn \g_tmpb_fp {\g_tmpb_fp +0.1}
\put(-0.1,-0.1){\line(0,1){\fp_use:N\g_tmpb_fp}}
\put(\fp_use:N\g_tmpa_fp,-0.1){\line(0,1){\fp_use:N\g_tmpb_fp}}
% \end{macrocode}
% The plot of points and line(s) is obtained using auxiliary functions.
% \begin{macrocode}
\thicklines
\bool_if:nT {\g_BBLR_plot_points_bool}{\BBLR_plot_points:}
\bool_if:nT {\g_BBLR_plot_lineA_bool}{
\BBLR_draw_line:NNN \g_BBLR_slope_A_fp\g_BBLR_intercept_A_fp
\g_BBLR_labelA_str}
\bool_if:nT {\g_BBLR_plot_lineB_bool}{
\BBLR_draw_line:NNN \g_BBLR_slope_B_fp\g_BBLR_intercept_B_fp
\g_BBLR_labelB_str}
\bool_if:nT {\g_BBLR_plot_lineS_bool}{
\BBLR_draw_line:NNN \g_BBLR_slope_S_fp\g_BBLR_intercept_S_fp
\g_BBLR_labelS_str}
\end{picture}
}%
% \end{macrocode}
% \end{macro}
% \begin{macro}{\lrplotparameters}
% The command \cs{lrplotparameters} records two parameters related to
% the generation of the plot and sets a boolean variable.
% \begin{macrocode}
\NewDocumentCommand{\lrplotparameters}{mm}{
\fp_gset:Nn \g_BBLR_diameter_fp{#1}
\fp_gset:Nn \g_BBLR_XXheight_fp{#2}
\bool_gset:Nn \g_BBLR_two_scale_bool
{\fp_compare_p:nNn {\g_BBLR_XXheight_fp}>{0.}}
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Functions for internal use}
% The functions listed here after are for internal
% use and are just minimally documented. \par
% The function |\BBLR_decode_data:|
% \marginpar{\raggedleft\texttt{
% \textbackslash{}BBLR\textunderscore{}decode\textunderscore{}data:}}
% extract two numeric values from the string read from the file.
% Some clever actions are necessary because
% a so called csv file sometime do not contains the separating commas.
% \begin{macrocode}
\cs_new_protected:Nn \BBLR_decode_data: {
\tl_trim_spaces:N \g_BBLR_file_line_tl
\int_gzero:N \g_tmpa_int
\int_gzero:N \g_BBLR_first_separator_int
\int_gzero:N \g_BBLR_last_separator_int
\int_gset:Nn \g_BBLR_record_length_int {
\str_count:N \g_BBLR_file_line_tl}
\str_map_variable:NNn \g_BBLR_file_line_tl \g_tmpa_str {
\int_gincr:N \g_tmpa_int
\bool_lazy_or:nnTF
{\str_if_eq_p:NN \g_tmpa_str \c_BBLR_comma_str}
{\str_if_eq_p:NN \g_tmpa_str \c_BBLR_space_str}
{\int_gset_eq:NN \g_BBLR_last_separator_int \g_tmpa_int
\int_if_zero:nTF {\g_BBLR_first_separator_int}
{\int_gset_eq:NN \g_BBLR_first_separator_int \g_tmpa_int
}{\prg_do_nothing:}
}{\prg_do_nothing:}
}
\int_gincr:N \g_BBLR_last_separator_int
\int_gdecr:N \g_BBLR_first_separator_int
\fp_gset:Nn \g_BBLR_abscissa_fp{
\str_range:Nnn \g_BBLR_file_line_tl{1}{\g_BBLR_first_separator_int}}
\fp_gset:Nn \g_BBLR_ordinate_fp{
\str_range:Nnn \g_BBLR_file_line_tl
{\g_BBLR_last_separator_int}{\g_BBLR_record_length_int}}
}
% \end{macrocode}
% The function |\BBLR_plot_points:| \marginpar{\raggedleft\texttt{
% \textbackslash{}BBLR\textunderscore{}plot\textunderscore{}points:}}
% scans the data file to read the coordinates and
% it draws a circle for each point.
%
% \begin{macrocode}
\cs_new_protected:Nn \BBLR_plot_points: {
\ior_open:Nn \g_BBLR_file_ior \g_BBLR_file_name_tl
\int_zero:N \g_BBLR_rec_count_int
\int_do_until:nn
{\g_BBLR_rec_count_int = \g_BBLR_number_of_points_int}
{
\ior_str_get:NN \g_BBLR_file_ior \g_BBLR_file_line_tl
\int_incr:N \g_BBLR_rec_count_int
\BBLR_decode_data:
\fp_gset:Nn \g_tmpa_fp{(\g_BBLR_abscissa_fp-\g_BBLR_min_abscissa_fp)*
\g_BBLR_scale_factor_fp}
\fp_gset:Nn \g_tmpb_fp{(\g_BBLR_ordinate_fp-\g_BBLR_min_ordinate_fp)*
\g_BBLR_scale_factor_H_fp}
\put(\fp_use:N\g_tmpa_fp, \fp_use:N\g_tmpb_fp){
{\circle*{\fp_use:N\g_BBLR_diameter_fp}}}
}
\ior_close:N \g_BBLR_file_ior
}
% \end{macrocode}
% The function |\BBLR_draw_line:NNN| \marginpar{\raggedleft\texttt{
% \textbackslash{}BBLR\textunderscore{}draw\textunderscore{}line:NNN}}
% draws the line. The first two parameters given as arguments
% are the slope and the intercept. The third parameter is a label.
% \par The next code finds the intersection of the line with the plotting area.
% \begin{macrocode}
\cs_new_protected:Nn \BBLR_draw_line:NNN {
\fp_gset:Nn \fp_tmpa_fp {#1 * \g_BBLR_min_abscissa_fp + #2 }
\fp_compare:nTF{\fp_tmpa_fp > \g_BBLR_max_ordinate_fp}{
\fp_gset:Nn \g_BBLR_min_draw_abscissa_fp {(\g_BBLR_max_ordinate_fp -#2) / #1}
}{
\fp_compare:nTF{\fp_tmpa_fp < \g_BBLR_min_ordinate_fp}{
\fp_gset:Nn \g_BBLR_min_draw_abscissa_fp {(\g_BBLR_min_ordinate_fp - #2) / #1}
}{
\fp_gset:Nn \g_BBLR_min_draw_abscissa_fp { \g_BBLR_min_abscissa_fp }
}}
\fp_gset:Nn \fp_tmpa_fp {#1 * \g_BBLR_max_abscissa_fp + #2 }
\fp_compare:nTF{\fp_tmpa_fp > \g_BBLR_max_ordinate_fp}{
\fp_gset:Nn \g_BBLR_max_draw_abscissa_fp {(\g_BBLR_max_ordinate_fp -#2) / #1}
}{
\fp_compare:nTF{\fp_tmpa_fp < \g_BBLR_min_ordinate_fp}{
\fp_gset:Nn \g_BBLR_max_draw_abscissa_fp { (\g_BBLR_min_ordinate_fp - #2) / #1}
}{
\fp_gset:Nn \g_BBLR_max_draw_abscissa_fp { \g_BBLR_max_abscissa_fp }
}}
% \end{macrocode}
% Some parameters (coordinates of starting point, base-length, scaled slope)
% are computed and the line is drawn.
% \begin{macrocode}
\fp_gset:Nn \fp_tmpa_fp {(\g_BBLR_min_draw_abscissa_fp -
\g_BBLR_min_abscissa_fp)* \g_BBLR_scale_factor_fp}
\fp_gset:Nn \fp_tmpb_fp {(#1 * \g_BBLR_min_draw_abscissa_fp + #2 -
\g_BBLR_min_ordinate_fp)* \g_BBLR_scale_factor_H_fp}
\fp_gset:Nn \fp_BBLR_line_base_length_fp{(\g_BBLR_max_draw_abscissa_fp -
\g_BBLR_min_draw_abscissa_fp) * \g_BBLR_scale_factor_fp}
\fp_gset:Nn \fp_scaled_slope_fp
{(#1 * \g_BBLR_scale_factor_H_fp / \g_BBLR_scale_factor_fp)}
\put(\fp_use:N\fp_tmpa_fp, \fp_use:N\fp_tmpb_fp){
\line(1.,\fp_use:N\fp_scaled_slope_fp){\fp_use:N\fp_BBLR_line_base_length_fp}}
% \end{macrocode}
%The third parameter is used as a label, if it is not a |+|.
% \begin{macrocode}
\bool_if:nF {\str_if_eq_p:NN #3 \c_BBLR_plus_str}{
\fp_gset:Nn \fp_tmpa_fp
{0.08 * \g_BBLR_min_draw_abscissa_fp + 0.92 * \g_BBLR_max_draw_abscissa_fp}
\fp_gset:Nn \fp_tmpb_fp {#1 * \fp_tmpa_fp + #2 }
\fp_gset:Nn \fp_tmpa_fp
{(\fp_tmpa_fp-\g_BBLR_min_abscissa_fp)*\g_BBLR_scale_factor_fp
+ 0.3 * #1 /sqrt(1.+#1*#1)}
\fp_gset:Nn \fp_tmpb_fp
{(\fp_tmpb_fp-\g_BBLR_min_ordinate_fp)* \g_BBLR_scale_factor_fp
- 0.3 /sqrt(1.+#1*#1)}
\put(\fp_use:N\fp_tmpa_fp, \fp_use:N\fp_tmpb_fp){#3}
}
}
% \end{macrocode}
% The function |\BBLR_print_fp:N | \marginpar{\raggedleft\texttt{
% \textbackslash{}BBLR\textunderscore{}print\textunderscore{}fp:N }}
% is used to print floating point numbers with a limited number
% of decimal digit.
%
% \begin{macrocode}
\cs_new_protected:Nn \BBLR_print_fp:N {%
{\fp_eval:n{trunc(#1 ,\g_BBLR_num_dec_dig_int)}}
}
% \end{macrocode}
%
% \begin{macrocode}
\ExplSyntaxOff
% \end{macrocode}
%
%
%\iffalse
%</package>
%\fi
%
% \section{Versions}
% 2024-06-10: first post on CTAN.\par
% 2024-11-23: small changes in the text,
% different format of numbers in the table.\par
% 2024-12-14: more flexibe output, some changes in the text.
%
% \section{Acknowledgments}
% The colleagues Paolo Zatelli, Alfonso Vitti and Giulia Graldi
% read some preliminary version
% of this text and suggested several improvements.
% Claudio Beccari usefully commented about the first version
% when I was preparing the second version. \par
%
% \section{Citations and references}
% \subsection*{Mathematics}
% The books by Lang \cite{Lang} and by Strang \cite{Strang} give
% all the background on linear algebra.\par
% The texts by Sansò \cites{Sanso1, Sanso2} (in italian) treat the
% teory of probability and its application to metrology.
% The paper by Pearson \cite{Pearson} is the oldest text that
% I have found on the symmetric regression, or total regression.
% \subsection*{Programming}
% The two documents \cites{L3A, L3B} are the fountamental and official guide
% for \LaTeX3 programming. The books by Donald Knuth \cites{Knuth}
% and Leslie Lamport \cites{Lamport} are still essential references.
% The papers by Enrico Gregorio \cites{egreg1, egreg2, egreg3, egreg4, egreg5}
% explain some general and some special aspect of \LaTeX3 programming.
% \subsection*{References}
% \begin{biblist}[\normalsize]
% \bib{egreg1}{article}{
% author={Gregorio, Enrico},
% journal={ArsTeXnica},
% number={14},pages={41\ndash 47}, date={2012},
% title={\LaTeX3: un nuovo gioco per i maghi e per diventarlo},
% }
% \bib{egreg2}{article}{
% author={Gregorio, Enrico},
% journal={ArsTeXnica},
% number={22},pages={69\ndash 77}, date={2016},
% title={Liste, cicli, \LaTeX3},
% }
% \bib{egreg3}{article}{
% author={Gregorio, Enrico},
% journal={ArsTeXnica},
% number={24},pages={37\ndash 44}, date={2017},
% title={Condizionali in \LaTeX},
% }
% \bib{egreg4}{article}{
% author={Gregorio, Enrico},
% journal={ArsTeXnica},
% number={30},pages={36\ndash 45}, date={2020},
% title={Funzioni e |expl3|},
% }
% \bib{egreg5}{article}{
% author={Gregorio, Enrico},
% journal={TUGboat},
% volume={41},number={3},pages={299\ndash 307}, date={2020},
% title={Functions and |expl3|},
% }
% \bib{Knuth}{book}{
% author={Knuth, Donald},
% title={The TeXbook},
% date={1986},
% publisher={American Mathematical Society and Addison-Wesley},
% }
% \bib{Lang}{book}{
% author={Lang, Serge},
% title={Linear Algebra},
% date={1987},
% publisher={Springer-Verlag},
% place={Berlin Heidelberg},
% }
% \bib{Lamport}{book}{
% author={Lamport, Leslie},
% title={LaTeX - A document preparation system (2nd ed.\ )},
% date={1994},
% publisher={Addison-Wesley},
% note={something interesting in the fist edition, too},
% }
% \bib{L3A}{article}{
% title={The |expl3| package and LaTeX3 programming},
% author={The LaTeX project team}, date={2024},
% note={file: |expl3.pdf| available in CTAN in l3kernel},
% }
% \bib{L3B}{article}{
% title={The \LaTeX3 interface},
% author={The LaTeX project team}, date={2024},
% note={file: |interface3.pdf| available in CTAN in l3kernel}
% }
% \bib{Pearson}{article}{
% title={On lines and planes of closest fit to systems of points in space},
% author={Pearson, Karl}, date={1901},
% journal={Philosophical Magazine},
% volume={2},number={11},pages={559\ndash 572},
% }
% \bib{Sanso1}{book}{
% author={Sansò, Fernando},
% title={Elementi di teoria della probabilità},
% date={1996},
% publisher={Città-Studi},
% place={Milano},
% note={see: http://www.geolab.polimi.it/text-books/},
% }
% \bib{Sanso2}{book}{
% author={Sansò, Fernando},
% title={La teoria della stima},
% date={1996},
% publisher={Città-Studi},
% place={Milano},
% note={see: http://www.geolab.polimi.it/text-books/},
% }
% \bib{Strang}{book}{
% author={Strang, Gilbert},
% title={Introduction to linear algebra},
% date={2009},
% publisher={Wellesley-Cambridge press,},
% }
% \end{biblist}
%
% \par\vfill\centerline{\small ***}\vfill
% \end{document}
%
%\iffalse
% END OF FILE linearregression.dtx
%\fi