help for invdesc and sinvdesc (Roger Newson)

Change variable attributes using a describe or descsave resultsset

invdesc , dframe(dframe_name) [

lframe(lframe_name [ ,
replace labels(namelist) ] )

name(varname)
type(varname)
isnumeric(varname)
format(varname)
vallab(varname)
varlab(varname)
destopts(varname)
tostopts(varname)
charvars(varlist)

]

sinvdesc , [

lframe(lframe_name [ ,
replace labels(namelist) ] )

name(varname)
type(varname)
isnumeric(varname)
format(varname)
vallab(varname)
varlab(varname)
destopts(varname)
tostopts(varname)
charvars(varlist)

]

where dframe_name and lframe_name are data frame names.

Description

invdesc inputs a data frame
containing descriptive data in a describe or descsave output dataset
or resultsset),
and (optionally) another (or the same) data frame,
containing value labels.
It uses information in the variables in the descriptive resultsset
to change the attributes of variables in the dataset
in the current data frame in memory.
These attributes can be variable mode (string or numeric),
storage type, format,
value label, variable label,
or variable characteristics.
The descriptive resultsset can be created using describe or descsave,
or can be created manually using a spreadsheet (generic or proprietary),
and can contain extra variables and/or exclude variables usually present,
in which case the corresponding variable attributes are not modified.
sinvdesc is a version of invdesc which attempts to find the descriptives
in the current data frame.
The descsave package can be downloaded from SSC
using the ssc command.

Options for invdesc only

dframe(dframe_name) must be present.
It specifies a data frame,
containing a dataset with 1 observation for each of a list of variables,
and data on variable attributes such as mode (string or numeric),
storage type, format,
value label, variable label,
or variable characteristics.

Options for invdesc and sinvdesc

lframe(lframe_name[ ,
replace labels(namelist) ] )
specifies a data frame
containing value labels,
which will be copied from there to the current frame
for use in labelling the values of variables there.
The frame may or may not be the same frame specified by the dframe() option.
The replace suboption specifies that value labels of the same names in the current frame
will be replaced (instead of being modified).
The labels() suboption specifies a subset of the value labels in the label frame
to be copied to the current frame.
Note that a dataset in a data frame may contain value labels only,
and have no variables or observations.

name(varname), type(varname), isnumeric(varname), format(varname),
vallab(varname) and varlab(varname) specify alternative names for the variables
in the input data frame containing the attributes to be changed.
In default, these variables in the input data frame
are assumed to have the same names as the corresponding options,
and to contain the same informaton as the variables of the same names
in the output datasets (or resultssets) created by describe or descsave.

destopts(varname) and tostopts(varname)
specify the names of variables in the descriptive dataset,
containing lists of options (other than generate and replace)
for destring and tostring, respectively.
If the isnumeric() variable in the descriptive dataset
is 1 (specifying a numeric variable)
and the corresponding variable in the current dataset
specified by the name() variable in the descriptive dataset
is string,
then invdesc uses destring to convert the string variable to numeric,
using the destopts() variable (if present) to specify destring options.
If the isnumeric() variable in the descriptive dataset
is 0 (specifying a string variable)
and the corresponding variable in the current dataset
specified by the name() variable in the descriptive dataset
is numeric,
then invdesc uses tostring to convert the string variable to numeric,
using the tostopts() variable (if present) to specify tostring options.
If the destopts() or tostopts() option is absent,
then invdesc looks for a variable with the same name as the option.

charlist(varlist) specifies a list of variables
in the dframe() data frame,
assumed to contain variable characteristics
for the variables in the current data frame.
Such variables are created in descsave resultssets,
using the char() option of descsave.
The characteristics specified by these variables
are identified using the charname characteristic of each variable (if present),
or assumed to be the same as the variable names otherwise.

Variables in the descriptive input dataset specified by dframe()

The descriptive input dataset specified by dframe()
has one observation for each of a list of variables,
which may be present in the current data frame.
In default, it may contain the following variables:

Default name Description

name Variable name

type Storage type

isnumeric Numeric indicator

format Display format

vallab Value label

varlab Variable label

destopts destring options

tostopts tostring options

charvars_list Variable characteristics

The variable name contains the name of a variable, which may be present in the current data frame.
The variable isnumeric is 1 if the variable is to be numeric and 0 if the variable is to be non-numeric.
Variable mode is enforced using tostring or destring,
and it may be necessary to set the tostopts() or destopts() variable to contain force.
The variables in the charvars_list are string variables containing variable characteristics
for the variable specified in the name variable.
The name of the characteristic specified is given by the charname characteristic of the charlist_variable
(if the charname characteristic exists),
or is assumed to be the same as the name of the characteristic variable otherwise.
To use a variable of a different name for each function,
use the invdesc option of the same name.

The descriptive dataset does not need to contain all the variables listed above,
although the name() variable must be present.
Variable attributes specified by absent variables are not modified.
The descriptive dataset may also contain additional variables,
especially if it is created manually iin a spreadsheet (generic or proprietary),
instead of being output by describe or descsave.

Remarks

invdesc is designed to supersede the dofile() option of descsave,
whch can also be used to modify data attributes, using a generated do-file.
Using invdesc has the advantage that variable and value labels,
and variable characteristics,
can contain strings that cannot be surrounded by simple or compound quotes,
such as strings containing an unpaired right compound quote.
Another advantage is that invdesc can input descriptive datasets
created manually using generic or proprietary spreadsheets,
and then imported into a Stata data frame,
using import delimited or import excel.

The sinvdesc module is intended for use mostly in meta-metadatasets,
which contain descriptives for descriptive variables,
such as those in describe or descsave resultssets.
It is useful if the user creates describe or descsave resultssets
manually in a spreadsheet,
and wants to convert the spreadsheet to a Stata dataset,
complete with variable attributes.

For more about the use of invdesc and other Stata packages for handling metadatasets
(datasets containing metadata), see
Newson (2020).

Examples

The following example assumes the presence of 3 generic tab-delimited spreadsheets
in the current folder, distributed with the invdesc package.
These are
descriptive.txt containing the descriptives (with 1 row per variable per dataset),
valuelabelstxt containing value labels (with 1 row per label per value),
and xauto.txt containing a modified version of the auto dataset
(with 1 observation per car model).
The example uses invdesc and sinvdesc together with the vallabdef package,
which can be downloaded from SSC.

Create descriptive dataset in data frame desframe using sinvdesc:

. frame create desframe

. frame desframe {

. import delimited using descriptive.txt, delim(tab) varnames(1) clear stringcols(_all)

. sinvdesc

. describe, full

. list, abbr(32)

. }

Create value labels dataset in data frame labframeusing invdesc and vallabdef:

. frame create labframe

. frame labframe {

. import delimited using valuelabels.txt, delim(tab) varnames(1) clear stringc(_all)

. invdesc, dfr(desframe)

. describe, full

. list, abbr(32) sepby(labname)

. vallabdef labname value label

. label list

. }

Create extended auto dataset in current frame:

. import delimited using xauto.txt, delim(tab) varnames(1) clear stringcols(_all)

. invdesc, dfr(desframe) lfr(labframe, replace) charvars(_fv_*)

Check extended auto dataset:

. describe, full

. char list

. label dir

. label list

. tab foreign, m

. tab odd, m

Author

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

References

Newson, R. B. 2020. From datasets to metadatasets in Stata.
Presented at the 2020 London Stata Conference, 10-11 September, 2020.

Also see

Manual: [D] char, [D] describe, [D] destring, [D] tostring,
[D] import, [D] label

On-line: help for char, describe, destring, tostring,
import delimited, import excel, label

help for descsaave, vallabdef, vallabsave if installed