help listfirst

Title

listfirst -- List first so many observations

Syntax

listfirst [varlist]
[if exp]
[,
first(#)
last
last(#)
list_options
]

Description

listfirst lists the first # observations, either
generally or (more usefully) those satisfying an if condition.

Optionally it will also list the last # observations,
either generally or (more usefully) those satisfying an if
condition.

# defaults to 10. Optionally it may be changed, and need
not be equal for first and last subsets.

If varlist is not specified, it defaults to all variables in the
dataset. Otherwise one or more variables may be specified.

Output may be limited by what exists in the dataset. For
example, no observations will be listed if none exist that
satisfy a specified if condition. That is not considered an error.

Remarks

Many readers will be familiar with utilities in Unix or other
operating systems allowing you to see the head (top or first lines) or
tail (bottom or end lines) of text files. Similar features have been
folded into various statistical programs. In Stata most but not quite
all the possibilities yield easily to list or edit or
browse when the concern is with a dataset.

You may have special interest in what is at either end of a
dataset. Perhaps more commonly the point is just to see a small sample
of the dataset, especially of a large dataset. Perhaps a full
list or opening edit or browse seems over the top.

Examples use the auto dataset bundled with Stata, which has 74
observations.

The simplest applications of listfirst are trivial.

listfirst by itself is equivalent to list in 1/10.

listfirst mpg by itself is equivalent to list mpg in 1/10.

listfirst mpg, first(5) is equivalent to
list mpg in 1/5.

Such examples don't take you beyond what is already easy with
list. However,

listfirst mpg, last

is equivalent to

list mpg if inrange(_n, 1, 10) | inrange(_n, 65, 74)

or more generally to

list mpg if inrange(_n, 1, 10) | inrange(_n, _N - 9, _N).

Either is harder to work out or to type.

listfirst mpg, first(5) last(5)

is similarly more
challenging to emulate with list.

The use of an if condition is where listfirst
scores.

listfirst mpg if foreign

lists the first 10 observations satisfying the condition
specified, which is more difficult otherwise without working out where
they are in the dataset, or knowing that for another reason. However, a
useful trick is

list mpg if foreign & sum(foreign) <= 10

given that foreign is a (0, 1) indicator variable.
That generalises to any
true-or-false expression. See (e.g.) Cox (2007) for more on such ideas.

listfirst mpg if foreign, last

shows the last 10 observations too.

Options

first() specifies that the first # pertinent observations be
listed. The default is 10.

last() specifies that the last # pertinent observations also
be listed.

last is a convenient alternative to last(10).

list_options are options of list. For example, you
might not care about observation numbers. If so, you can suppress
them with noobs (to be parsed as "no obs" and not otherwise).

Examples

. sysuse auto, clear

. listfirst

. listfirst mpg

. listfirst mpg, last

. listfirst mpg, first(5) last(5)

. listfirst mpg if foreign

. listfirst mpg if foreign, last

Author

Nicholas J. Cox, Durham University, UK

n.j.cox@durham.ac.uk

Acknowledgments

A command listsome was posted on Statalist on 10 April 2008
in
this post
in response to a question from Malcolm Wardlaw in
this earlier post
on the same day. But that command was never documented or made public beyond
Statalist.

Independently Robert Picard posted a listsome command on
SSC that was first announced on 18 August 2014 in
this post.

Robert's command has a strong feature of offering random
samples, which is not attempted here. This listfirst command has
two small virtues, being limited, and therefore simple; and showing
"last" observations too if that is also wanted. I happily yield the
command name to Robert.

References

Cox, N.J. 2007.
How can I identify first and last occurrences systematically in panel data?
http://www.stata.com/support/faqs/data-management/first-and-last-occurrences/

Also see

Online:
[D] list,
listsome (SSC; if installed),