Sat 23 Dec 2017 04:33:11 AM UTC, comment #17:
No. I made changes to the ols.m documentation, then turned to the gls.m documentation. But an example I tried--for which I aimed to follow the input matrix size rules--results in an error:
So I set this aside for a day or two. If there's a bug, I will file a separate bug report to keep bugs and fixes out of the voluminous documentation changes. However, I want to understand what the issue is first. Another question I have is why the O matrix is so big. I understand it is accounting for the correlation amongst error variables and across sample "time", i.e., heteroscedasticity, but the external literature on generalized least squares typically considers the random variables having homoscedasticity.
Seeing the gls.m description makes me understand why the original author wrote
The kron(s,I) is like the big matrix O, but of course it is degenerate in the sense it is homoscedastic and reduces to a simplified form, i.e., p-by-p.
The terminology is a bit confusing and I'm still trying to make some sense out of the gls.m routine. I suspect that gls.m might not get used much; ols.m could get used though. In summary, another changeset will be posted soon.
|
Fri 22 Dec 2017 10:51:46 PM UTC, comment #16:
@Dan: Is there a final version of the patch with update OLS documentation and M-by-N syntax?
|
Tue 19 Dec 2017 11:12:48 PM UTC, comment #15:
Regarding OLS, I think there is confusion between s and S where perhaps S = diag(s.^2), s being the standard deviation and I being the identity matrix. The kron() could be confusing things.
Let's do a simple test using the variable/case naming convention that we find in the plaintext ols.m help and make the r.v.s all Gaussian so we know what to expect by multiplying by s (std dev). I'm not interested in BETA, so let's just multiply X by 3, i.e., BETA = 3*eye(t).
OK, so BETA looks like 3*eye(t), and SIGMA does look like diag(s.^2), i.e., diag([0.5^2 1.0^2 1.5^2]).
I see now why the original programmer chose vec(E) notation--because E is actually a matrix. And it is strange in the sense that if we really considered the correlation of all residual variables, of which there are t times p, our correlation matrix (if we were to stack the residuals as [e1; e2; e3; ...] where e1 is column one, etc.) would be a tp-by-tp matrix. But I think the example I gave above is more along the lines of what is meant to be expressed here, i.e., there are p random residuals with t observed outcomes per variable. The vec(E) and kron() stuff doesn't seem correct, or at least not the clearest way of describing things. I'll make an attempt at correcting that for ols.m and gls.m.
|
Tue 19 Dec 2017 07:37:30 PM UTC, comment #14:
The "by" symbol looks good in LaTeX. In plain text, I guess I'm sort of used to seeing m x n. However, I started using m-by-n in the patch, especially in cases where there were a lot of variables involved. It's more a visual digestion sort of thing. Without the hyphens, it starts to be: x is t x k, e is p x t, y is k x p, and c is kt x pt. It looks like one big strung-together set of foreign letters.
Upper case versus lower case matrix size parameter isn't too critical for me. I'm comfortable with either so long as it is consistent in a particular function doc. In signal processing, we typically use upper case limits, especially N. But in pure math, it's often lower case limits.
I think the upper-case, lower-case variable meaning matrix vs. vector vs. function input variable question is more critical.
In the ols.m documentation, I think I'll change use of "vec(e)" to just plain "e", i.e., @var{e}. I don't know what was meant--if anything--by the vec() function. kron(s,I) I think is simply supposed to be "s I" in math speak, that is the residuals are independent with the same variance. But right, one typically would write s^2 I where s is standard deviation (of a normal r.v.).
|
Tue 19 Dec 2017 07:21:18 PM UTC, comment #13:
Or maybe we just use spaces around the 'x'. I looked at the syntax at https://en.wikipedia.org/wiki/Matrix_(mathematics) and they use "m x n" where the 'x' is actually some nice mathematical multiplication symbol, but the letter 'x' would do okay.
|
Tue 19 Dec 2017 07:18:35 PM UTC, comment #12:
That makes sense to me. One usually refers to an m-by-n matrix and not an M-by-N matrix. Although, all lower-case, "mxn" looks confusing. But so does "mXn". Checking with the documentation for zeros from Matlab, they have opted to use '-by-' between matrix dimensions so it is an m-by-n matrix.
Maybe put that up for a vote too on the Maintainer's list. I have a Perl script that I use for checking the style of the DOCSTRINGS and I could add a regexp to change all dimensions to use the '-by-' syntax.
|
Tue 19 Dec 2017 06:56:59 PM UTC, comment #11:
Oh yeah, there we go. If one does "help ols", the result is
"x is a t by k matrix"
because the comments first use @math{t} and then later
"/ (T-rank(X))"
because the comment at that point uses @var{t}. My mind is so used to not thinking of T and t as the same variable. I think that should be lower case T in both plaintext and LaTeX.
|
Tue 19 Dec 2017 06:55:17 PM UTC, comment #10:
I suppose you could say it is a mess of inconsistency. Yes, my concern is mostly about the plaintext that is created when programmers use "help function_name". In LaTex there are many more ways to get the output to appear exactly as you want and I think it is fine to use @var{} in that context if it makes sense.
I'm starting to think that in general we should use real code segments in the ifnottex branches so that @var{x}(i) is used rather than @var{x}_i which doesn't make a lot of sense and requires interpreting the '_' as making the next letter a subscript.
|
Tue 19 Dec 2017 06:34:01 PM UTC, comment #9:
Just to be certain, you're aware that @var{x} in plaintext is X, but in LaTeX it is lower case non-script x (i.e., something like normal math vector notation.). Also, sometimes the documentation splits into @tex and uses x_i whereas for @ifnottex uses @var{x}(i).
|
Tue 19 Dec 2017 06:23:45 PM UTC, comment #8:
I'll write a note...
Sorry about quartile(); it's "quantile".
By "plaintext" you are referring to "help somefunc" doc? Or are you referring to some plain text version of the manual, i.e., some counterpart to octave.pdf?
Anyway, the point you are raising is the exact conundrum I had. In the case of the octave.pdf manual, with LaTeX, it's as if we are trying to be more pure math frame of mind whereas in the plaintext we are trying to be more matrix-algebra/programming language oriented. Yet, we are trying to use the same or parallel code in the documentation for both LaTeX and plaintext to achieve both of those. I tried striking a balance of using a vector notation in LaTeX whenever it would a vector in Octave script.
You are correct that from a pure math definition we have a random variable (script) x and the particular outcomes or observations are (script) x_i. But again, we have the input to the mean() routine being a vector (or matrix), and that input is expressed in the octave.pdf manual as well. To be technically correct, the math expression the formula represents is "average", not "mean". "mean" from a math perspective incorporates the underlying discrete or continuous PDF.
Capital vs. lower case, I started out using upper case to represent matrices, but this soon became confusing when trying to mixed together in LaTeX and/or plaintext. So, I started using "@var" in places I thought were either vector or matrix (depending on the function input), content with a non-script variable as meaning (typically) vector (or a matrix if one wants to think of it that way).
I'll look the OLS/GLS up in the link you gave, then define T in the patch as well.
|
Tue 19 Dec 2017 05:44:44 PM UTC, comment #7:
@Dan: Could you write a note about the documentation philosophy on the Maintainer's List? I think some of the changes are worth discussing first.
In the plaintext version of the help, for example, using @var() always produces a CAPITAL, generally sans serif, font which can be confusing.
I think there is a distinction between saying what the code does, for example, mean of a vector is
and the mathematical definition of the mean
When defining a mathematical expression, y and x and other entries are general variables, NOT the variables of this particular function, and therefore I don't think they need the @var{} surrounding them.
In particular, once you go with @var{} you can't make the distinction between vectors (lower case Roman alphabet) and matrices (upper case Roman alphabet).
For example,
versus
I don't have a function QUARTILE() in my distribution so I can't comment on that. Maybe that is in the statistics package?
There does seem to be some confusion between in ols.m between whether SIGMA or sigma^2 is being calculated. See Wikipedia (https://en.wikipedia.org/wiki/Ordinary_least_squares). The correction in the denominator is for the statistical degrees of freedom. The input x is a TxK matrix. That means there are T rows (observations). If the matrix is square and of full column rank then there is enough information to make the most accurate determination of the parameters. If x is not square, and rank deficient, then the estimate will not be as good. Still, for calculating the variance the degrees of freedom, at the best of times, are N-1, which suggests that there should be an extra 1 or 2 in this equation someplace. In particular, I tried ols() and for a full rank set of measurements sigma is returned as Inf because (T - rank (x) == 0). This isn't right.
You could also ask on the Maintainer's list about this for someone with statistical expertise to weigh in on this.
|
Tue 19 Dec 2017 09:44:06 AM UTC, comment #6:
Yes, nice catch. I've update the patch, which is attached. Thanks.
(file #42680)
|
Tue 19 Dec 2017 02:00:12 AM UTC, comment #5:
In the new attached patch (file #42677),
line 675 is "1/(N-1)"
but line 81 is "1/N-1".
Should it be changed to "1/(N-1)"?
|
Mon 18 Dec 2017 10:55:58 PM UTC, comment #4:
Updated patch attached.
As a general guideline (but not a hard rule, as it depends on the context) my logic is that only variables that are in the function argument, e.g., myfunc(x), get the @var{x} treatment. In the Octave doc, the indexing is similar to coding style, i.e., it should be X(i). I felt it might be really confusing to any new user just getting accustom to Octave and not yet understanding that X and x are different variables to have myfunc(X) and then refer in the documentation to x(i). For LaTeX it is slightly different in that the @var{} translates to italic, sans-serif which is typically a vector representation. In that case, I tried to make the individual elements such as x(i) or x_i to be italic, serif which is typically a scalar representation. Similarly, for LaTeX the mean value with bar over the top is also italic, serif because it is a scalar. And then there are some instances such as gls.m and ols.m where the math and Octave both refer to matrices, in which case I made all the matrices upper case (some without @var{} because they are not function variables).
There is a runlength.m and a run_count.m. I wonder why an underscore is used in one case and not the other.
Something doesn't make sense regarding QUARTILE(). There is a discussion in the documentation about how probabilities P are determined. (The various methods are likely meant to change the sampling intervals because distributions can vary, e.g., thin tails, etc.) The variable N shows up in all these methods but I'm wondering where that comes from because if we are generating P how do we know what its length is?
What is the following doing in stat.txi?
It really looks out of place in the octave.pdf manual where it is located.
What is the T of the following from "help ols"?
(file #42677)
|
Mon 18 Dec 2017 06:27:16 PM UTC, comment #3:
Yes, I suppose. (I tried to not look too closely. :-)
I will create a new patch in an hour or two...
|
Mon 18 Dec 2017 05:26:53 PM UTC, comment #2:
Shouldn't the TeX and plaintext documentations be kept in sync? I notice that mean and meansq, for example, are missing
in the @ifnottex section.
|
Mon 18 Dec 2017 09:05:29 AM UTC, comment #1:
I agree it is an irrelevant clause. I'm attaching a changeset that makes the documentation for the various functions of Sec. 26.1 consistent.
(file #42671)
|
Mon 18 Dec 2017 07:07:50 AM UTC, original submission:
In the docstring of "meansq.m", there is no symbol "\bar{x}" in the TeX formula, so the next sentence "where $\bar{x}$ is ..." is not necessary.
This can be seen in the PDF document "octave.pdf" in section 26.1 Descriptive Statistics.
Possible solution:
|