Thanks to Kit Baum, an -examples- program is now
downloadable from SSC. Stata 8 is required.
-examples- should be explained by examples. If I go
. examples label
Examples
. label data "in process counts"
. label variable mpg "miles per gallon"
. label define yesno 0 no 1 yes
. label values answer yesno
. label define yesno 3 "perhaps", add
. label define yesno 3 "maybe", modify
. label define codes 1 low 2 medium 3 high .a "unsure" .b "won't tell"
. label values myvar codes
I get the examples section from the help for -label-. -examples-
has some smartness about (e.g.) abbreviations of command names,
all by courtesy of some Stata built-ins:
. examples reg
Examples: linear regression
. regress y x1 x2 x3 x4 x5
. test x1 x2
. test x3=5
. test x3=(x4+x5)/2
. predict yhat if e(sample)
. predict r, resid
. regress y x1 x2 x3 [freq=pop]
. regress y x1 x2 x3 [pweight=pop]
. regress yavg x1avg x2avg x3avg [aweight=pop]
. regress y x1 x2 x3 x4 x5 if region==1
. by region: regress y x1 x2 x3 x4 x5
. by region: regress y x1 x2 x3 x4 s5 if sex=="male"
Examples: regression with robust standard errors
. regress y x1 x2, robust
. regress y x1 x2, robust cluster(patid)
. regress y x1 x2 [pweight=pop], robust
. regress y x1 x2 [pweight=pop]
(Note, specifying pweights implies robust.)
In short, -examples- shows the examples sections from on-line help files
in the Results window. It is especially designed to show quick and
easy reminders of the syntax of a given command.
-examples- has grown out of two kinds of experiences:
1. When teaching Stata, I find that users regard syntax diagrams at the head
of help files as difficult, if not scary. I find myself saying again and again,
"You may find it best to scroll down to the examples at the end and see if one
looks like what you want to do."
2. Experienced users too may have the same need. Often I guess that I
will get an answer more quickly by looking at the examples section, but
whether in the Viewer or in the Results window the price can be scrolling
through lots of other material.
Note that -examples- is a very stupid program too. It looks for
sections starting with titles specified in SMCL containing the word
"Examples" (or alternatively "Example") within any help file corresponding
to the name given. It will not be able to show (1) material from older,
pre-SMCL help files (e.g. Stata 6 or older) or (2) examples given otherwise.
To take the second point (2) first:
If you go
. examples twoway histogram
(in an up-to-date Stata: as from 18 May you can go -help twoway
histogram-) you will get no output. This is not because there are no
examples in the help for -twoway histogram-; it is just that
they are not segregated in Examples sections.
On the first point (1), I guess that it would be fairly easy to
make -examples- smarter about older help files, but it is
hardly worth it. As said, -examples- is written for Stata 8,
so the only older help files its users would encounter would
be for occasional user-written programs.
Three developments are under consideration:
1. -examples- needs to be fixed so that it understands e.g.
. examples log()
2. Some people might want the examples to be shown in the Viewer
(perhaps through a -wexamples-, by analogy with -whelp-).
I'm agnostic about that, but interested in strong views.
3. -examples- needs to be smarter about echoing repeated
blank lines.
Ken Higbee gave valuable help on aliases as I was developing
-examples-.
Nick
[email protected]
*
* For searches and help try:
* http://www.stata.com/support/faqs/res/findit.html
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
