r(table) : when did this thing appear, why were we not told about it, and where is it documented?

[Joro Kolev]

Good morning,

Recently I (by chance) discovered that e-class commands such as -regress-, -probit-, etc., have started to leave behind useful stuff in r(table). In other words, e-class commands are now setting r-class results.

This was not so at least up until and including Stata 11. I just checked on Stata 11 version I have, and -regress- is not leaving behind an r(table).

Outrage and confusion arise in me. I will try phrase those as questions:

1. When was r(table) introduced, and why was I not included in the memo saying that it is introduced?

2. Where is r(table) documented? I read in [U] 13.6 that "You can find out what is stored where by looking in the Stored results section for the particular command in the Reference manual. If you know the class of a command—and it is easy enough to guess—you can also see what is stored by typing return list, ereturn list, or sreturn list:"
And NO and NO. The entry of -regress- does not say anywhere that it leaves r(table) behind. And no, I cannot guess, because when I know that a command is e-class, I search in -ereturn list-, because this is where e-class commands are supposed to save stuff.

In short, this r(table) seems to me like an undocumented major paradigm shift in Stata, that nobody bothered to announce.

[Joro Kolev]

In fact searching through [R], the first time r(table) appears is in -contrasts-, second time in -margins- , third time in -pwcompare- and this is all.

But if I understand correctly the paradigm shift, -r(table) now is part of every estimation command, no?

[Sven-Kristjan Bormann]

r(table) is created by ereturn display. See the documentation about ereturn for more information. This subcommand of ereturn is used to display the coefficient table mostly after estimation commands. Therefore, this subcommand is not an e-class command because it displays only previously posted information. You can find this command usually as one of the last commands in an estimation command.

[Rich Goldstein]

r(table) was introduced in version 12; see

help whatsnew11to12

and has been discussed here on Statalist various times over the years

[Richard Williams]

r(table) shows up several times in the pdf documentation and help files, albeit nowhere near as often as it could, e.g. the help for margins tells you about r(table) but the help for regress does not. I don't know why, but as far as I can tell most or all estimation commands return r(table).

Also I don't think ereturn display has anything to do with whether r(table) exists. I think it is just there.

[William Lisowski]

Joro Kolev -

I suspect a search of my old posts here will find me making the same complaint.

There is no formal statement about the creation of r(table) following estimation commands in the Version 16 documentation I have searched all the Version 16 PDFs and do not find a reference that a new user of Stata estimation commands is likely to stumble across, although it is mentioned implicitly in the reference for for certain estimations commands that notably do not include regress. Additionally, the only expository references to _b and _se are in tutorial information in the Stata User's Guide PDF.

I find the emphasis on the e-class results in the estimation command reference documentation, underneath the heading "Stored results", with no mention of these other stored results results to be not only incomplete but misleading.

The documentation would benefit with (a) a simple exposition of the non-e-class stored results as part of the output of help estimation and [U] 20 Estimation and postestimation commands and then (b) a link to that exposition underneath every "Stored results" heading.

Pace post #3, it is not necessary to run ereturn display for r(table) to be created.

. clear all

. return list

. sysuse auto
(1978 Automobile Data)

. quietly regress mpg weight

. return list

scalars:
              r(level) =  95

matrices:
              r(table) :  9 x 2

. matrix list r(table)

r(table)[9,2]
            weight       _cons
     b  -.00600869   39.440284
    se   .00051788   1.6140031
     t   -11.60251   24.436312
pvalue   3.798e-18   1.385e-36
    ll  -.00704106   36.222827
    ul  -.00497632    42.65774
    df          72          72
  crit   1.9934636   1.9934636
 eform           0           0

. matrix dir

. display _b[weight]
-.00600869

. display _se[weight]
.00051788

.

[Sebastian Kripfganz]

ereturn display internally calls _coef_table which returns r(table).

[Sven-Kristjan Bormann]

As far as I know and understand "ereturn display" without a call to "ereturn display" the r(table)-matrix is not created. It does not matter whether the coefficient table is actually displayed. It only matters that "ereturn display" creates this matrix based on previously posted results. If you look at the example for the "ereturn" command in the PDF-documentation that you will always see that "ereturn display" is used after "ereturn post b V" to display the results and to create the r(table)-matrix.
At least in Stata 14, this fact is not as clearly communicated as it could be.

See the following as an example in which I modify and repost an existing regression result

. clear all

. return list

. sysuse auto

.qui regress price  mpg weight foreign


. ret list

scalars:
              r(level) =  95

matrices:
              r(table) :  9 x 4


. mat b =e(b)

. mat V=e(V)

. mat list b

b[1,4]
           mpg      weight     foreign       _cons
y1   21.853604   3.4647058   3673.0604  -5853.6957

. mat list V

symmetric V[4,4]
                mpg      weight     foreign       _cons
    mpg   5508.7774
 weight     36.2912   .39784425
foreign   9089.6431     218.835   467826.27
  _cons   -229604.2  -2039.2381  -993431.72    11404044

. mat  b=b[1,1..3]

. mat V =V[1..3,1..3]

. mat list b

b[1,3]
          mpg     weight    foreign
y1  21.853604  3.4647058  3673.0604

. mat list V

symmetric V[3,3]
               mpg     weight    foreign
    mpg  5508.7774
 weight    36.2912  .39784425
foreign  9089.6431    218.835  467826.27

 eret clear

eret post b V


. ret list

scalars:
              r(level) =  95

matrices:
              r(table) :  9 x 4

. eret list

macros:
         e(properties) : "b V"

matrices:
                  e(b) :  1 x 3
                  e(V) :  3 x 3

. qui eret display

. ret list

scalars:
              r(level) =  95

macros:
           r(mcmethod) : "noadjust"

matrices:
              r(table) :  9 x 3

As you can see, the r(table)-matrix only changes after the "ereturn display" is run.
As per Sebastian Kripfganz comment, the point still stands that at least in the official documentation "ereturn display" is used to create the coefficient table and the internal command _coef_table is not mentioned.

[William Lisowski]

I write from the perspective of a user of estimation commands, which is what I understood from post #1 Joro's perspective to be, rather than from the perspective of an author of estimation commands, which is what I now understand the perspective in posts #3 and #8 to be.

My demonstration in post #6 is that after (most) (built-in) estimation commands, the user does not need to issue a call to ereturn display to have access to r(table), which the estimation command is responsible for creating.

When I read post #3 it seemed to me to imply otherwise, but I now understand it as an elaboration on the process of creation of r(table).

Nevertheless, I think it useful for users of estimation commands new to r(table) and _b and _se to see a demonstration of their use and access, as I provided in post #6. And the points in post #1 and post #6 still stand - the documentation for these non-e-class returned results is woefully incomplete from the perspective of a user of estimation commands.

Added in edit: I have posted the comments in post #6 about obscurity of non-e-class stored results to the Stata 17 wish list topic.

[Joro Kolev]

Yes, William, exactly what you are saying. My perspective is of a user, and the problems that I see as a user are that this is 1) Not a naturally expected behaviour because estimation commands are supposed to save stuff in ereturns, not in return. 2) As far as I and you are able to determine, this unexpected behaviour is not explained anywhere in the documentation.

I write from the perspective of a user of estimation commands, which is what I understood from post #1 Joro's perspective to be, rather than from the perspective of an author of estimation commands, which is what I now understand the perspective in posts #3 and #8 to be.

My demonstration in post #6 is that after (most) (built-in) estimation commands, the user does not need to issue a call to ereturn display to have access to r(table), which the estimation command is responsible for creating.

When I read post #3 it seemed to me to imply otherwise, but I now understand it as an elaboration on the process of creation of r(table).

Nevertheless, I think it useful for users of estimation commands new to r(table) and _b and _se to see a demonstration of their use and access, as I provided in post #6. And the points in post #1 and post #6 still stand - the documentation for these non-e-class returned results is woefully incomplete from the perspective of a user of estimation commands.

Added in edit: I have posted the comments in post #6 about obscurity of non-e-class stored results to the Stata 17 wish list topic.

[Sebastian Kripfganz]

I believe the feature is deliberately undocumented because StataCorp may decide in the future to no longer return the r(table) result in the present form. A user who writes do-files (or ado-files) that rely on the current structure of r(table) shoud be aware that their code might break in future versions of Stata (even under version control).

See: help undocumented.

Edit: It is not the estimation command that returns r(table) but the "documented undocumented" rclass programm _coef_table. The results are just available because the estimation command does not clear the latest r() results.

[Clyde Schechter]

I think it would be more accurate to say that r(table) is poorly documented. It is not "undocumented" in the sense that StataCorp uses that term. It was announced in -help whatsnew11to12- when version 12 came out (under "What's new in programming") and its use is even illustrated by an example there. I can say that I became aware of it the very day I first installed version 12.

But I suspect that the -help whatsnew- files are read even less often than the Foroum FAQ's--so that may not be a very effective way of getting the word out. Surely, it should be listed in the PDF documentation as among the things returned for every command that returns it (which, I believe, is all estimation commands). This is especially true because, in my view, r(table) is probably the single most useful saved result from estimation commands. In my usual workflow, I reference it more often than most of what comes back in e().

[Joro Kolev]

I, on the other hand, Clyde, not knowing of r(table), need to commit atrocities as the ones exemplified below in my workflow. (I kind of encountered the issue of -r(table) before one or twice, got outraged, and forgot about it. I encountered it again today. Up to now -r(table) has certainly not been part of my workflow.)

. sysuse auto, clear
(1978 Automobile Data)

. regress price mpg foreign, noheader
------------------------------------------------------------------------------
       price |      Coef.   Std. Err.      t    P>|t|     [95% Conf. Interval]
-------------+----------------------------------------------------------------
         mpg |  -294.1955   55.69172    -5.28   0.000    -405.2417   -183.1494
     foreign |   1767.292    700.158     2.52   0.014     371.2169    3163.368
       _cons |   11905.42   1158.634    10.28   0.000     9595.164    14215.67
------------------------------------------------------------------------------

Atrocity 1, recovering the vector of standard errors. (Does this expression not look pretty?):

. matlist vecdiag(cholesky(diag(vecdiag(e(V)))))

             |       mpg    foreign      _cons 
-------------+---------------------------------
          r1 |  55.69172    700.158   1158.634

Atrocity 2, recovering the vector of t-statistics. Even prettier:

. matlist vecdiag(diag(e(b))*syminv(cholesky(diag(vecdiag(e(V))))))

             |       mpg    foreign      _cons 
-------------+---------------------------------
          r1 | -5.282572   2.524134   10.27539

I think it would be more accurate to say that r(table) is poorly documented. It is not "undocumented" in the sense that StataCorp uses that term. It was announced in -help whatsnew11to12- when version 12 came out (under "What's new in programming") and its use is even illustrated by an example there. I can say that I became aware of it the very day I first installed version 12.

But I suspect that the -help whatsnew- files are read even less often than the Foroum FAQ's--so that may not be a very effective way of getting the word out. Surely, it should be listed in the PDF documentation as among the things returned for every command that returns it (which, I believe, is all estimation commands). This is especially true because, in my view, r(table) is probably the single most useful saved result from estimation commands. In my usual workflow, I reference it more often than most of what comes back in e().

[Clyde Schechter]

Yikes!

[Richard Williams]

I might promote r(table) to e(table) or else ereturn more of the results. Various results are displayed in the output but are not ereturned, e.g. T and p values. There is enough information store to compute them but, as Joro Kolev , it takes some effort. Once you know r(table) exists, life is easier, at least if you can figure out how to extract what you want.