help for keyby and keybygen(Roger Newson)

Key the dataset by a variable list

keyby varlist [ , noorder missing fast ]

keybygen [ varlist ] , generate(newvarname) [ replace dropconstant noorder missing fast ]

Description

keyby sorts the dataset currently in memory by the variables in a varlist,
checking that the variables in the varlist uniquely identify the observations.
This makes the variables in the varlist a primary key for the dataset in memory.
If the user does not specify otherwise,
then keyby also reorders the variables in the varlist
to the start of the variable order in the dataset,
and checks that all values of these variables are nonmissing.
keybygen sorts the dataset currently in memory by the variables in a varlist,
preserving the existing order of observations within each by-group,
and then generates a new variable,
containing the sequential order of each observation within its by-group,
to form a primary key with the existing variables in the varlist.
keyby and keybygen can be useful if the user combines multiple datasets using merge,
which may cause a dataset in memory to become unsorted.

Options for keyby and keybygen

noorder specifies that the variables in the varlist
(and the generate() variable created by keyby)
are not reordered to the beginning of the variable order of the dataset in memory.
If noorder is not specified, then the variables in the varlist
(and the generate() variable created by keyby)
are reordered to the beginning of the variable order (see order).

missing specifies that missing values in the variables in the varlist are allowed.
If missing is not specified,
then missing values in the variables in the varlist cause keyby or keybygen to fail.

fast is an option for programmers.
It specifies that keyby or keybygen will take no action
to restore the existing dataset in memory in the event of failure,
or if the user presses the Break key..
If fast is not specified, then keyby will take this action,
which uses an amount of time depending on the size of the dataset in memory.

Options for keybygen only

generate(newvarname) is required.
It specifies the name of a new variable to be generated,
containing, in each observation,
the sequential order of that observation within its by-group defined by the varlist,
or the sequential order of that observation in the dataset, if the varlist is empty.
The new variable is appended to the varlist to form the new primary key,
by which the dataset is sorted,
and which uniquely identifies observations in the dataset.
Note that keybygen, unlike keyby, works with an empty varlist.
Also, note that the new variable specified by generate()
may not have the same name as any existing variable in the varlist.

replace specifies that any existing variable with the name specified by the generate() option
will be replaced.
If replace is not specified, and an existing variable has the same name as the generate() option,
then keybygen will fail.

dropconstant specifies that the generated new key variable will be dropped
if it has a constant value of 1.
In that case, the new variable is not really necessary,
because the key variables in the input varlist identify the observations uniquely,
without a new variable.

Remarks

keyby is a "clean" version of the sort command without the stable option.
keybygen is a "clean" version of the sort command with the stable option.
Either of them can be used to make a dataset conform to the relational database model,
under which a dataset is viewed as a mathematical function,
whose domain is the set of existing primary key value combinations,
and whose range is the set of all possible value combinations for variables outside the primary key.
If all datasets conform to the relational database model,
then the user can use the addinby package,
which can also be downloaded from SSC,
to add variables from a disk dataset into the dataset in memory,
based on the values of a list of variables in the dataset in memory,
which is also the primary key of the dataset on disk.
The addinby command is a "clean" version of the merge command.

Examples

. keyby foreign make

. keyby foreign make, noorder

. keyby rep78 make, missing

. keybygen foreign, gene(modseq)

. keybygen foreign, gene(modseq) replace noorder

. keybygen, gene(obsseq)

. keybygen foreign make, gene(modseq) dropconstant

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

Also see

Manual: [D] generate, [D] sort, [D] gsort, [D] merge, [D] order, [D] drop, [U] 12.2.1 Missing values

On-line: help for generate, sort, gsort, merge, order, drop, missing

help for addinby if installed