help findname (SJ25-4: dm0048_6)

Title

findname -- List variables matching name
patterns or other properties

Syntax

findname [varlist] [if] [in] [, options]

Control
insensitive perform case-insensitive pattern matching

local(macname) put list of variable names in local macro macname

cslocal(macname) put comma-separated list of variable names in local macro macname

not list variable names not in varlist

placeholder(symbol) specify alternative to @

Display
alpha list variable names in alphabetical order

detail display additional details

indent(#) indent output

skip(#) gap between variables; default is skip(2)

varwidth(#) display width for variable names; default is varwidth(12)

Selection by column position in dataset
columns(numlist) select variables according to column position

Selection by data types, values, and formats
type(typelist) has specified type

all(condition) has all values satisfying condition

any(condition) has any values satisfying condition

format(patternlist) has display format matching patternlist

Selection by variable and value labels
varlabel has variable label

varlabeltext(patternlist) has variable label with text matching patternlist

vallabel has value label

vallabelname(patternlist) has value label with name matching patternlist

vallabeltextdef(patternlist) has value label defined with text matching patternlist

vallabeltextuse(patternlist) has value label used with text matching patternlist

vallabelcountdef(#1 [#2]) has value label defined with designated number of labels

vallabelcountuse(#1 [#2]) has value label used with designated number of labels

Selection by characteristics
char has characteristic(s)

charname(patternlist) has characteristic(s) with name matching patternlist

chartext(patternlist) has characteristic(s) with text matching patternlist

typelist used in type(typelist) is a list of one
or more types, each of which may be numeric,
string, byte, int, long, float, or
double,
may be strL (Stata 13 up),
or may be a numlist, such as 1/8 to mean
str1 str2 ... str8 . Examples include

type(int) is of type int

type(byte int long) is of integer type

type(numeric) is a numeric variable

type(strL) is of type strL

type(1/40) is str1, str2, ..., str40

type(numeric 1/2) is numeric or str1 or str2

patternlist used in, for example, format(patternlist), is
a list of one or more patterns. A pattern is the expected name or text
with the likely addition of the characters * and ?. *
indicates 0 or more characters go here and ? indicates exactly 1
character goes here. Examples include

format(*f) format is %#.#f

format(%t*) has time or date format

format(%-*s) is a left-justified string

varl(*weight*) variable label includes word weight

varl(*weight* *Weight*) variable label includes word weight or Weight

To match a phrase, it is important to enclose the entire phrase in quotes.

varl("*some phrase*") variable label has some phrase

If instead you used varl(*some phrase*), then only variables having
labels ending in some or starting with phrase would be listed.

condition used in all() or any() is a true-or-false condition
defined by an expression in which variable names are represented by @.
For example, any(@ < 0) selects numeric variables in which any values
are negative.

Description

findname lists variable names of the dataset currently in memory
in a compact or detailed format and lets you specify subsets of
variables to be listed, either by name or by properties (for example, the
variables are numeric). In addition, findname leaves behind in
r(varlist) the names of variables selected so that you can use
them in a subsequent command.

findname, typed without arguments, lists all variable names of the
dataset currently in memory in a compact form.

If two or more options specifying properties of variables are specified,
findname identifies only those variables that satisfy all the option
specifications, that is, the intersection of all the subsets identified. The
not option provides a direct way to identify the complementary set. Two
or more calls to findname with results saved in local macros using the
local() option may be used together with macro operations to produce the
union, set difference, etc., of different subsets.

if and in when specified only affect the operation of any(),
all(), vallabeltextuse(), or vallabelcountuse().

Options

Control

insensitive specifies that the matching of any pattern in
patternlist be case-insensitive. For example,
varl(*weight*) inse is an alternative to, and more inclusive than,
varl(*weight* *Weight*).

local(macname) puts the resulting list of variable names into
local macro macname.

cslocal(macname) puts the resulting list of variable names,
separated by commas, into local macro macname. This option may
be preferred, for example, if output is to be fed to a function needing
that form of input.

These options may be specified together. However, if the
same macro name is specified to both options, cslocal() overwrites
the result of local().

not specifies that varlist or the specifications given define the set
of variables not to be listed. For instance, findname pop*, not
specifies that all variables not starting with the letters pop be
listed. The default is to list all the variables in the dataset or, if
varlist or particular properties are specified, to list the variable
names so defined.

placeholder(symbol) specifies an alternative to @ to use in the
any() or all() option. This should only be necessary for making
string comparisons involving @ as a literal character (or if your @
key is somehow unavailable).

Display

alpha specifies that the variable names be listed in alphabetical
order.

detail specifies that detailed output identical to that of
describe be produced. If detail is specified,
indent(), skip(), and varwidth() are ignored.

indent(#) specifies the amount the lines are indented.

skip(#) specifies the number of spaces between variable names; the
default is skip(2).

varwidth(#) specifies the display width of the variable names; the
default is varwidth(12).

Selection by column position in dataset

columns(numlist) selects variables according to column position.
For example, columns(1) selects the first variable in the dataset, and
columns(1/3) selects the first three variables in the dataset. Negative
numbers count from the end of the dataset, so columns(-1) selects the
last variable in the dataset, and columns(-3/-1) selects the last three
variables in the dataset. columns(0) would be ignored, as would be any
column positions that do not correspond to variables. (Note: If you specify
this option, any varlist is ignored.)

Selection by data types, values, and formats

type(typelist) selects variables of the specified typelist.
Typing findname, type(string) would list all the names of string variables in
the dataset, and typing findname pop*, type(string) would
list all the names of string variables beginning with the letters pop.

all(condition) selects variables that have all values
satisfying condition. If either if or in is specified,
attention is restricted to the observations specified.

any(condition) selects variables that have any values
satisfying condition. If either if or in is specified,
attention is restricted to the observations specified.

With either all() or any(), conditions that mismatch type are ignored.

format(patternlist) selects variables whose format
matches any of the patterns in patternlist. format(*f) would
select all variables with formats ending in f, which presumably
would be all %#.#f,
%0#.#f, and
%-#.#f formats. format(*f *fc) would
select all formats ending in f or fc.

Selection by variable and value labels

varlabel selects variables with defined variable labels.

varlabeltext(patternlist) selects variables with variable-label text
matching any of the words or phrases in patternlist.

vallabel selects variables with defined value labels.

vallabelname(patternlist) selects variables with value-label names
matching any of the words in patternlist.

vallabeltextdef(patternlist) selects variables with value-label text
defined matching any of the words or phrases in patternlist.

vallabeltextuse(patternlist) selects variables with value-label text
defined and used matching any of the words or phrases in patternlist.
For example, a value label may be defined for value 42 as "answer" and
associated with a variable. In that case, the previous option would find it
if prompted to search for such text. But if the value 42 does not in fact
occur in that variable, this option would not find it. If either if or
in is specified, attention is restricted to the observations specified.

vallabelcountdef(#1 [#2]) selects variables with the designated
number of value labels defined.

If just one number #1 is specified (for example,
vallabelcountdef(2)), then a variable must have precisely that many
labels defined. If two numbers are specified, then a variable must have
between #1 and #2 labels defined, the limits being inclusive, unless
the second argument is system missing. Thus, if vallabelcountdef(2 4)
is specified, there must be 2, 3, or 4 value labels defined. Two numbers may
be given in any order. Note that missing is allowed, so that
vallabelcountdef(5 .) would mean 5 or more value labels defined.
Note that you may specify vallabelcountdef(0) to find variables with
value label sets attached but no value labels defined.

vallabelcountuse(#1 [#2]) selects variables with the designated
number of value labels defined and used. For example, a value label may
be defined for value 42 as "answer" and associated with a variable. In
that case, the previous option would count it if prompted. But if the
value 42 does not in fact occur in that variable, this option would not
count it.

If just one number #1 is specified (for example, vallabeluse(2)),
then a variable must have precisely that many labels defined and used. If two
numbers are specified, then a variable must have between #1 and #2
labels defined and used, the limits being inclusive, unless the second
argument is system missing. Thus, if vallabelcountuse(2 4) is
specified, there must be 2, 3, or 4 value labels defined and used. Two
numbers may be given in any order. Note that missing is allowed, so that
vallabelcountuse(5 .) would mean 5 or more value labels defined and
used. If either if or in is specified, attention is restricted to
the observations specified. Note that you may specify
vallabelcountuse(0) to find variables with value label sets attached but
no value labels defined.

Selection by characteristics

char selects variables with defined characteristics.
Notes in the sense of notes are characteristics.

charname(patternlist) selects variables with characteristic names matching
any of the words in patternlist.

chartext(patternlist) selects variables with characteristic text matching
any of the words or phrases in patternlist.

Examples

Sandbox dataset

. sysuse auto, clear

All variables

. findname

First and last variables

. findname, col(1 -1)

All string variables

. findname, type(string)

. edit `r(varlist)'

All str1, str2, str3, str4 variables

. findname, type(1/4)

All numeric variables

. findname, type(numeric)

. order `r(varlist)'

. findname, type(numeric)

. summarize `r(varlist)'

All byte or int variables

. findname, type(byte int)

All float variables

. findname, type(float)

All variables that are not float

. findname, type(float) not

All date variables, that is, those with formats %t* or %-t*

. findname, format(%t* %-t*)

All variables with only integer values

. findname, all(@ == int(@))

All variables with any missing values

. findname, any(missing(@))

All variables with any extended missing values .a to .z

. findname, any(inrange(@, .a, .z))

All indicator or dummy variables with all values 0, 1, or missing

. findname, all(inlist(@, 0, 1) | missing(@))

All variables with any negative values

. findname, any(@ < 0)

All variables that are constants

. findname, all(@ == @[1])

Variables with left-justified string formats

. findname, format(%-*s)

Variables with comma formats

. findname, format(*c)

All variables with value labels attached

. findname, vallabel

All variables with the value label origin attached

. findname, vallabelname(origin)

All variables with precisely two value labels defined

. findname, vallabelcountdef(2)

Variables with characteristics defined

. findname, char

Variables with notes

. findname, charname(note*)

Find text in characteristics

. notes mpg: hidden treasure

. findname, chartext(*treasure*)

Author

Nicholas J. Cox

Durham University

Durham City, U.K.

n.j.cox@durham.ac.uk

Acknowledgments

findname owes a major debt to ds. ds and its
relatives under differing names have had a complicated history in various
official and community-contributed versions (for example, Anonymous [1992]; Cox [2000,
2001]; Weiss [2008]; and ds2, ds3, and ds5 on SSC). My
earlier work was aided by suggestions from Richard Goldstein, William Gould,
Jay Kaufman, and Fred Wolfe. More recently, Maarten Buis, Martin Weiss, Vince
Wiggins, and several members of Statalist provided helpful comments both
directly and indirectly. Stephen Okiya suggested the problem of counting
value labels on Statalist: Google Statalist 1429068. Daniel Klein's
comments around value-label options and columns() were very helpful.
Andreas Fabian Fischer posed the problem of finding variables with
attached value label sets that are empty or not used.

References

Anonymous. 1992. Short describes, finding variables, and codebooks.
Stata Technical Bulletin 8: 3-5. Reprinted in
Stata Technical Bulletin Reprints, vol. 2, pp. 11-14. College Station,
TX: Stata Press.

Cox, N. J. 2000. dm78: Describing variables in memory.
Stata Technical Bulletin 56: 2-4. Reprinted in
Stata Technical Bulletin Reprints, vol. 10, pp. 15-17. College Station,
TX: Stata Press.

-----. 2001. dm78.1: Describing variables in memory: update to
Stata 7.
Stata Technical Bulletin 60: 3. Reprinted in
Stata Technical Bulletin Reprints, vol. 10, pp. 17. College Station, TX:
Stata Press.

Weiss, M. 2008. Stata tip 66: ds--A hidden gem.
Stata Journal 8: 448-449.

Also see

Article: Stata Journal, volume 23, number 4: dm0048_5,

Stata Journal, volume 20, number 2: dm0048_4,

Stata Journal, volume 15, number 2: dm0048_3,

Stata Journal, volume 12, number 1: dm0048_2,

Stata Journal, volume 10, number 4: dm0048_1,

Stata Journal, volume 10, number 2: dm0048

Manual: [D] ds

Help: [D] compress, [D] codebook,
[D] describe, [D] format,
[D] label, [D] lookfor, [D] notes,
[D] order, [D] rename