help for descsave (Roger Newson)

Save descriptive attributes of variables to a do-file and/or a Stata dataset

descsave [varlist] [using filename] [ ,

dofile(dofilename [, replace])

list( [varlist] [if] [in] [ , [list_options] ] )

frame( framename [ , replace change ] )

saving(datafilename [, replace orphans])

norestore fast flist(global_macro_name)

dontdo(attributes_list)

charlist(characteristic_list)
idnum(#) idstr(string)

vallabkeep(vallabkeep_option)

rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n)
gsort(gsort_list) keep(varlist)

dshead detail varlist
]

where list_options is a list of options accepted by the list command,
and characteristic_list is a list of characteristic_names and/or asterisks (*) separated by spaces,
and attributes_list is a list of items from the list

type format vallab vallabdef varlab

and vallabkeep_option is an option from the list

all | present | none

and gsort_list is a list of one or more elements of the form

[+|-]varname

as used by the gsort command.

Description

descsave is an extended version of describe,
which lists descriptive attributes for a list of variables in a dataset given by
varlist, or for all variables in the dataset if varlist is not specified.
The dataset is the current dataset in memory, unless using is used to specify a dataset in a file.
The descriptive attributes are variable names, storage types, display formats, value labels and variable labels
(as output by describe),
and also (optionally) a list of characteristics specified by the charlist() option.
descsave creates an output Stata dataset (or resultsset) with one observation per variable and data on
these descriptive attributes.
This dataset may be listed using the list() option
and/or saved to a data frame using the frame() option
and/or saved to a file using the saving() option
and/or written to the memory using the norestore or fast option,
overwriting any existing dataset.
The file specified by dofile() is a do-file, containing commands which can be run to reconstruct the
descriptive attributes of the variables, assuming that variables of the same names have been created and
are numeric or character as appropriate.
descsave can be used together with export delimited to create a definitive generic
spreadsheet version of the current dataset, together with a Stata do-file to reconstruct the descriptive
attributes of the variables after the spreadsheet has been input using import delimited.

Options

These options fall into the following 3 groups:

Option group Description

outdest_opts Output-destination options for the do-file and/or resultsset

conspec_opts Content-specifying options for the do-file and/or resultsset

other_opts Other options

Output-destination options

dofile(dofilename [, replace]) specifies an output Stata do-file, with commands
to reconstruct the variable descriptive attributes (storage types, display formats, value labels,
variable labels and selected characteristics), assuming that variables with those names already exist
and are numeric or string-valued as appropriate.
If replace is specified, then any existing file of the same name is overwritten.

list(varlist [if exp] [in range] [, list_options ] )
specifies a list of variables in the output dataset,
which will be listed to the Stata log by descsave.
The user may optionally also specify if or in clauses to list subsets of variables,
or change the display style using a list of list_options allowed as options by the list command.
If the rename() option is specified (see below),
then any variable names specified by the list() option must be the new names.
If the list() option is absent, then nothing is listed.

frame( name, [ replace change ] ) specifies an output data frame,
with one observation per directory entry,
and data on the attributes of the directory entry.
If replace is specified, then any existing data frame of the same name is overwritten.
If change is specified,
then the current data frame will be changed to the output data frame
after the execution of descsave.
The frame() option may not specify the current data frame.
To do this, use one of the options norestore or fast.

saving(datafilename [, replace orphans]) specifies an output file containing a Stata dataset,
with one observation per variable, and data on the descriptive attributes of the variable.
If replace is specified, then any existing file of the same name is overwritten.
If orphans is specified,
then the dataset is saved with all value labels specified by the vallabkeep() option,
which defaults to all value labels in the input dataset.

norestore specifies that the output dataset will be written to the memory,
overwriting any pre-existing dataset.
This option is automatically set if fast is specified.
Otherwise, if norestore is not specified, then the pre-existing dataset is restored
in the memory after the execution of descsave.

fast is a stronger version of norestore, intended for use by programmers.
It specifies that the pre-existing dataset in the memory will not be restored,
even if the user presses Break during the execution of descsave.
If norestore is specified and fast is absent,
then descsave will go to extra work so that
it can restore the original data if the user presses Break.

Note that the user must specify at least one of the 6 options
dofile(), list(), frame(), saving(), norestore and fast.

flist(global_macro_name) specifies the name of a global macro,
containing a filename list (possibly empty).
If saving() is also specified, then
descsave will append the filename specified in the
saving() option to the value of the global macro specified in flist().
This enables the user to build a list of filenames in a global macro, containing the
output of a sequence of estimation result sets saved by descsave.
These files may later be concatenated using append,
or using dsconcat if installed.

Content-specifying options

dontdo(attributes_list) specifies a list of variable attributes
that will not be set by the output do-file specified by the dofile() option.
These variable attributes are items in the list type, format, vallab, vallabdef and varlab,
specifying variable types, formats, value labels,
value label definitions, and variable labels,
respectively.
For instance, dontdo(type) specifies that the output do-file
will reset formats, value labels and variable labels,
but not storage types.
This option can be useful if the user does not want to lose precision
when running the output do-file in a different dataset.

charlist(characteristic_list) specifies a list of characteristic names and/or asterisks (*),
separated by spaces.
The characteristics specified will be reconstructed by the do-file specified by dofile() (if specified),
and be written to variables in the output dataset.
If a characteristic has length greater than the maximum length for a string variable,
which is 244 in Version 9 of Stata
(see help for data_types),
then it will be truncated to that maximum length in the output dataset and/or do-file.
(This is not expected to cause problems very often.)
descsave expands the characteristic_list by replacing each asterisk * with a list of the names
of all characteristics of all variables in the varlist, and then contracts the characteristic_list
by removing the rightmost occurrences of all duplicate characteristic names.
Therefore, charlist(*) specifies a list of all characteristics
belonging to all variables in the varlist, and charlist(omit missing *) specifies a list of the same characteristics,
with omit appearing first and missing appearing second.
In the second case, the output variable char1 will contain the omit characteristics,
and the output variable char2 will contain the missing characteristic.
(See Output dataset created by descsave below for details on output variables.)

idnum(#) specifies an ID number for the output dataset.
It is used to create a numeric variable idnum in the output dataset, with that value for all
observations.
This is useful if the output dataset is concatenated with other descsave output datasets
using append, or using dsconcat if installed.

idstr(#) specifies an ID string for the output dataset.
It is used to create a string variable idstr in the output dataset, with that value for all
observations. (An output dataset may have idnum, idstr, both or neither.)

vallabkeep(vallabkeep_option) specifies the rule for keeping value labels
contained in the input dataset.
It may be all (specifying all value labels in the input dataset),
present (specifying all value labels whose names are present in the value-label variable
containing the names of value labels belonging to variables in the input varlist),
or none (specifying no value labels).
If the vallabkeep() option is absent, then all is assumed.
Note that, if the user specifies the saving() option
and wants value labels to be present in the output disk dataset,
then the user must specify an orphans suboption for the saving() option.

rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n) specifies a list
of pairs of variable names. The first variable name of each pair specifies a variable in the output dataset,
which is renamed to the second variable name of the pair.
(See Output dataset created by descsave below for details on output variables.)

gsort(gsort_list) specifies a generalized sorting order (as recognised by gsort)
for the observations in the output dataset.
If gsort() is not specified,
then the output dataset will be sorted by the single variable order.
If rename() is specified, then gsort() must use the new names.

keep(varlist) specifies a list of variables to be kept in the output dataset.
If keep() is not specified, then the output dataset contains all the variables listed in the next section.
If rename() is specified, then keep() must use the new names.

Other options

dshead specifies that a list of headlines, describing the whole dataset,
is listed, similar to the list produced by describe, short.
This list precedes any listing of variable attributes produced by the list() option.

detail modifies the list of headlines produced by the dshead option
to contain the details added by the option of the same name for describe.
If detail is specified without dshead,
then the dshead option is automatically implied.

varlist is a programmer's option, acting as the option of the same name for describe.
It specifies that, in addition to the usual saved results,
the options r(varlist) and r(sortlist) will also be saved.

Output dataset created by descsave

The output dataset (or resultsset) created by descsave
has one observation per variable in the varlist.
If the rename() option
is not specified, then it contains the following variables:

Default name Description

idnum Numeric dataset ID

idstr String dataset ID

order Variable order

name Variable name

type Storage type

isnumeric Numeric indicator

format Display format

vallab Value label

varlab Variable label

charn Characteristic varname[characteristic_name]

The variable order contains the sequential order of the variable in the input varlist specified for descsave,
or the order of that variable in the dataset, if the user does not specify an input varlist.
The variables idnum or idstr are only present if requested in the options of the same names.
The variable isnumeric is 1 if the variable is numeric and 0 if the variable is non-numeric.
There is one charn variable for each characteristic_name in the list specified
by the charlist() option. The variable charn specifies the nth characteristic
specified in the charlist() option (truncated if necessary to the maximum length for a string variable
under the current version of Stata).
All of these variables can be renamed using the rename() option,
or used by the gsort() option to specify the sorting order.
If the keep() option is used, then the output dataset will contain only the specified subset of these variables.

Remarks

descsave can be used together with outsheet and insheet to construct a definitive
generic spreadsheet version of the data. This is useful if the user needs either to convert the data to distant past
versions of Stata not produced by saveold, or to return to the data decades into the future,
when all software has evolved beyond recognition.
The do-file specified by dofile() can be used
to reconstruct variable attributes after inputting the definitive version of the data using insheet,
assuming that the variables are still numeric or string-valued, as specified in the original Stata data.
(The user may need to use destring after using insheet, if some of the numeric variables in the
definitive generic spreadsheet are formatted in nonstandard ways.)
Alternatively, the user may create a descsave resultsset
for input to the SSC package invdesc to regenerate variable attributes.
The output do-file, or the descsave resultsset,
can also be translated manually into other software languages if the user wants to use the data
under other software platforms.

descsave can also be used with the parmest package,
together with the SSC packages fvregen and/or factext and/or polyspline.
Typically, the user uses descsave
to save to a descsave resultsset or a do-file
describing the attributes of variables representing categorical or continuous factors,
generates dummy variables for categorical factors using tabulate or xi
or reference splines for continuous factors using polyspline,
enters these dummy variables or reference splines into a regression analysis,
saves the results of the regression to a dataset using parmby or parmest,
and then reconstructs the categorical or continuous factors
from the variable label in the parmest output dataset,
using fvregen or factext.

Examples

. descsave, list(,)

. descsave, list(,) dshead

. descsave make mpg weight, list(name varlab vallab, clean noobs)

. descsave, list(, subvar noobs sepa(0) abbrev(32)) char(omit)

. descsave, do(auto.do, replace)

. descsave, saving(autodesc.dta, replace)

. descsave, list(, noobs abb(32)) do(auto.do, replace) saving(autodesc.dta, replace) rename(varlab variable_label format variable_format)

. descsave using auto2, list(,)

. descsave model mpg price using auto2, list(,) saving(auto2desc, replace)

. descsave, norestore

The following example will work in the auto data. The first part creates a generic text spreadsheet in
auto.txt, with a program to reconstruct the variable attributes in auto.do. The second part reconstructs
the auto data from auto.txt, using auto.do.

. descsave, do(auto.do, replace) sa(autodesc.dta, replace) charlist(omit *)

. outsheet using auto.txt, nolabel replace

. insheet using auto.txt, clear

. run auto.do

. describe

The following example will work in the auto data
if the packages parmest, factext and eclplot are installed.
All of these packages can be downloaded from SSC.

. tab foreign, gene(type_) nolabel

. qui descsave foreign, do(foreign.do, replace)

. parmby "regress mpg type_*, noconst robust", label norestore

. factext foreign, do(foreign.do)

. eclplot estimate min95 max95 foreign, xscal(range(-1 2)) xlab(0 1)

The following advanced example will work under Stata 8 or above in the auto data
if the dsconcat and xcollapse packages
are installed. Both packages can be downloaded from SSC.
The example creates a dataset with 1 observation for each of a list of variables
and data on their names and median values, using xcollapse and dsconcat,
and then uses merge to merge in a dataset created by descsave,
with 1 observation per variable and data on the variable names,
variable labels and display formats.

. tempfile tf0

. descsave price mpg headroom trunk weight length turn displacement gear_ratio, saving(`tf0', replace) gsort(name) keep(order name varlab format)

. global tflist ""

. local i1=0

. foreach X of var price mpg headroom trunk weight length turn displacement gear_ratio {

. local i1=`i1'+1

. tempfile tf`i1'

. xcollapse (median) med=`X', idstr("`X'") nidstr(name) saving(`tf`i1'', replace) flist(tflist)

. }

. dsconcat $tflist

. sort name

. lab var med "Median value"

. merge name using `tf0'

. sort order

. list order name varlab med

Saved results

descsave saves the following in r():

Scalars

r(N) number of observations

r(k) number of variables

r(width) width of dataset

r(changed) flag indicating data have changed since last saved

Macros

r(datalabel) dataset label)

r(varlist) variables in dataset (if varlist specified)

r(sortlist) variables by which data are sorted (if varlist specified)

r(charlist) Full list of variable characteristic names specified by charlist()

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

Also see

Manual: [D] describe, [D] destring, [D] gsort, [D] insheet, [D] label, [D] outsheet

[R] tabulate, [R] xi

[U] 12.8 Characteristics

[P] char

On-line: help for append, char, describe, destring, gsort, insheet, label, outsheet,
saveold, tabulate, xi

help for dsconcat, eclplot, factext, fvregen, invdesc, polyspline, parmby, parmest, xcollapse if installed