[Octave-bug-tracker] [bug #52685] redundant sentence in meansq docstring

[Dan Sebald]

Follow-up Comment #18, bug #52685 (project octave):

The main delay here was adding some clarity to the documentation for ols.m and
gls.m.  After letting this sit for a bit, I pulled back some changes I thought
were too bulky.  I aimed for adding a bit more context about least squares so
that the cov(vec(e)) = kron(S,I) didn't seem so obscure and bewildering.  That
expression is still there, but I moved it to a third paragraph that describes
the error residuals assumption.  That third paragraph is what's different
between ols and gls.  So, the structure of the documentation for these two
entries is, in short,

1) The least-square formula construct with complete description of the matrix
dimensions.

2) A description of the X and Y matrices, i.e., the input variables.

3) A description of the underlying E matrix, i.e., the implied error
variables.  It's difficult to be descriptive here without first doing detailed
definitions, but I think I've conveyed the ideas.

That seems to make this digestable in reasonable hunks of text.  The thing I
like most is that I managed to use upper-case S in ols.m case to express
matrix and lower-case s in gls.m to signify scalar (in the help-based version,
anyway).  Basically the difference is that gls() requires an input description
of the correlation relationship.  That's something hard to validate for one's
data no less construct the large matrix without being meticulous...and if one
has a large data set, t*p-by-t*p matrix can be rather large.  I suspect that
gls.m doesn't see much use, evidenced by the error that is in the routine. 
ols.m is quite usable though.  I think there might be an approach halfway
between these two called "feasible" GLS.  Also, it might be nice if there were
an alternative version that just accepted S, i.e., gls(X,Y,S), rather than
have to construct the Kronecher product O.

I'm tempted to change the section 25.4 Linear Least Squares description.  It
says, "assuming zero-mean Gaussian noise", but Gaussian noise error-variables
is not a requirement.  If the noise is Gaussian then the estimation is the
maximum-likelihood, I think.  Generally speaking, though, the requirement is
only that the second-order moment (i.e., variance) behaves reasonably nice. 
Maybe instead it should be "assuming zero-mean noise with reasonably
well-behaved variance".

As for the format in LaTeX versus help-based version, eh, I really don't want
to pursue that any further right now.  I don't think the discussion list will
produce much response, and it could be an heap of work in a project where
people contribute things sort of hodge-podge.  That is, we could make rules,
but few would probably know they exist.  This isn't a major concern at the
moment given a release is approaching.

There is one of these items, though, that I sort of wonder about.  The @code{}
format produces apostrophes around the code, e.g., 'y = x*b'.  The problem
there is the apostrophy possibly being mistook as a transpose operator to the
unobservant reader.

Well, take a look through the changes, and maybe we'll do one more pass for
minor corrections.  It might be easiest to just glance at the diff hunks then
read the help in both Octave and the octave.pdf file.  None of these routines'
documentation is very long.

(file #42743)
    _______________________________________________________

Additional Item Attachment:

File name: octave-stats_documentation-djs2017dec27.patch Size:28 KB


    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?52685>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/