Adding info to e() and r()

First the basics

(1978 automobile data)

As you may know, whenever Stata runs calculations, it stores the information created in elements that can be easily accessed in subsequent commands.

While most standard users will not require to know how to manipulate this information, if you are trying to advances your programming skills, it will be necessary for you to learn what type of information can be contained in this elements, and how to modify them. A good place to start learning about them is by typing help return.

Overall, there are three types of elements:

r-class: These elements are produced by non-estimation commands. For example, after summarize, you can see what information is stored by the command by typing return list. They can store locals, scalars and matrices.

. summarize mpg

    Variable |        Obs        Mean    Std. dev.       Min        Max
-------------+---------------------------------------------------------
         mpg |         74     21.2973    5.785503         12         41

. return list

scalars:
                  r(N) =  74
              r(sum_w) =  74
               r(mean) =  21.2972972972973
                r(Var) =  33.47204738985561
                 r(sd) =  5.785503209735141
                r(min) =  12
                r(max) =  41
                r(sum) =  1576

. 

e-class: These elements are typically produced after estimation commands. At the minimum, it will contain information of estimated coefficients, variance covariance matrix, and the estimation command that was used. To see the information left behind, you just need to type ereturn list. They can store locals, scalars and matrices.

qui:reg price mpg
ereturn list

scalars:
                  e(N) =  74
               e(df_m) =  1
               e(df_r) =  72
                  e(F) =  20.25835256291882
                 e(r2) =  .2195828561874973
               e(rmse) =  2623.652888667587
                e(mss) =  139449473.54623
                e(rss) =  495615922.5753916
               e(r2_a) =  .2087437291901014
                 e(ll) =  -686.5395809065244
               e(ll_0) =  -695.7128688987767
               e(rank) =  2

macros:
            e(cmdline) : "regress price mpg"
              e(title) : "Linear regression"
          e(marginsok) : "XB default"
                e(vce) : "ols"
             e(depvar) : "price"
                e(cmd) : "regress"
         e(properties) : "b V"
            e(predict) : "regres_p"
              e(model) : "ols"
          e(estat_cmd) : "regress_estat"

matrices:
                  e(b) :  1 x 2
                  e(V) :  2 x 2
               e(beta) :  1 x 1

functions:
             e(sample)   

s-class: These elements are used to help with parsing. They can only store locals.

Adding elements to e() and r()

While creating and modifying this information from within your own programs is easy, some times, you may want to add additional information to your summary statistics, or your regression results. You may also want to create a set of results from scracth, but being able to store it in equation form.

Well, to do this, you can use the programs adde and addr. Both programs have the goal of adding or modifying information to e() and r(). They structures are rather simple:

program adde, eclass
    ereturn `0'
end

program addr, rclass
    syntax anything(equalok), [new copy]
    if "`new'"=="" {
        return add
        if "`copy'"!="" local 0 `anything', copy
        else            local 0 `anything'
    }
    else {
        if "`copy'"!="" local 0 `anything', copy
        else            local 0 `anything'
    }
    return `0'
end

Because examples are usally better than words, here a very small example:

First using adde:

qui:reg price mpg
adde local note "Regression MPG vs Price"
adde local data "auto.dta"
ereturn list

scalars:
                  e(N) =  74
               e(df_m) =  1
               e(df_r) =  72
                  e(F) =  20.25835256291882
                 e(r2) =  .2195828561874973
               e(rmse) =  2623.652888667587
                e(mss) =  139449473.54623
                e(rss) =  495615922.5753916
               e(r2_a) =  .2087437291901014
                 e(ll) =  -686.5395809065244
               e(ll_0) =  -695.7128688987767
               e(rank) =  2

macros:
               e(data) : "auto.dta"
               e(note) : "Regression MPG vs Price"
            e(cmdline) : "regress price mpg"
              e(title) : "Linear regression"
          e(marginsok) : "XB default"
                e(vce) : "ols"
             e(depvar) : "price"
                e(cmd) : "regress"
         e(properties) : "b V"
            e(predict) : "regres_p"
              e(model) : "ols"
          e(estat_cmd) : "regress_estat"

matrices:
                  e(b) :  1 x 2
                  e(V) :  2 x 2
               e(beta) :  1 x 1

functions:
             e(sample)   

But also with addr:

qui:sum price 
addr local note "Summary of Price"
addr scalar magic = 1
return list

scalars:
              r(magic) =  1
                r(sum) =  456229
                r(max) =  15906
                r(min) =  3291
                 r(sd) =  2949.495884768919
                r(Var) =  8699525.974268788
               r(mean) =  6165.256756756757
              r(sum_w) =  74
                  r(N) =  74

macros:
               r(note) : "Summary of Price"

Installation

To install this programs, simply create ado files with the names addr.ado and adde.ado, and save them in your personal ado folder. otherwise, just copy the versions I provide you here: adde and addr