-------------------------------------------------------------------------------
help for xrewide and xrelong                                     (Roger Newson)
-------------------------------------------------------------------------------

Extended versions of reshape wide and reshape long

xrewide [ stubnames ] [ , cjvalue(charname) vjvalue(varlist) cjlabel(charname) vjlabel(varlist) pjvalue(string) sjvalue(string) pjlabel(string) sjlabel(string) xmlsub lxjk(local_macro_name) lxkj(local_macro_name) reshape_wide_options ]

xrelong [ stubnames ] [ , jlabel(label_name) reshape_long_options ]

where stubnames is a list of stub names as input to reshape wide, label_name is the name of a value label, reshape_wide_options is a list of options used by reshape wide, and reshape_long_options is a list of options used by reshape long.

Description

The xrewide package contains 2 commands, xrewide and xrelong. The xrewide commmand is an extended version of reshape wide. It saves results in variable characteristics, in addition to the dataset characteristics saved by reshape. This is done using additional options for assigning the values and/or value labels of the j-variable to characteristics of the corresponding generated output variables. These characteristics can be useful for defining column headings if the reshaped output dataset is output to a table using the listtab package, which can be downloaded from SSC. The xrelong commmand is an extended version of reshape long, with the option of assigning an existing value label to the generated variable specified by the j() option. For more about the use of xrewide with listtab and other packages to produce tables, see Newson (2012).

Options for use with xrewide

cjvalue(charname) specifies thae name of a variable characteristic, to be assigned for the generated output variables, which will contain the corresponding values of the input variable specified by the j() option of reshape wide.

vjvalue(varlist) specifies a subset of the input variables to be reshaped, whose corresponding reshaped output variables will have the characteristic specified by the cjvalue() option. If vjvalue() is not specified, then it is set to the full set of input variables to be reshaped, and the characteristic specified by the cjvalue() option will be assigned to all the reshaped output variables.

cjlabel(charname) specifies thae name of a variable characteristic, to be assigned for the generated output variables, which will contain the corresponding value labels of the input variable specified by the j() option of reshape wide.

vjlabel(varlist) specifies a subset of the input variables to be reshaped, whose corresponding reshaped output variables will have the characteristic specified by the cjlabel() option. If vjlabel() is not specified, then it is set to the full set of input variables to be reshaped, and the characteristic specified by the cjlabel() option will be assigned to all the reshaped output variables.

pjvalue(string) specifies a prefix, to be added to the left of j() values when these are assigned to the variable characteristic specified by cjvalue().

sjvalue(string) specifies a suffix, to be added to the right of j() values when these are assigned to the variable characteristic specified by cjvalue().

pjlabel(string) specifies a prefix, to be added to the left of j() value labels when these are assigned to the variable characteristic specified by cjlabel().

sjlabel(string) specifies a suffix, to be added to the right of j() value labels when these are assigned to the variable characteristic specified by cjlabel().

xmlsub specifies that, in the variable characteristic specified by cjlabel(), the substrings "&", "<" and ">" will be replaced throughout with the XML entity references "&amp;", "&lt;" and "&gt;", respectively. This is useful if the variable characteristic is intended for output to a table in a document in XHTML, or in other XML-based languages.

lxjk(local_macro_name) specifies the name of a local macro, to be assigned a list of the names of the reshaped output variables created by xrewide, sorted primarily in the order of the corresponding j() values and secondarily in the order of the corresponding input variables specified by the stubnames.

lxkj(local_macro_name) specifies the name of a local macro, to be assigned a list of the names of the reshaped output variables created by xrewide, sorted primarily in the order of the corresponding input variables specified by the stubnames and secondarily in the order of the corresponding j() values.

reshape_wide_options is a list of options used by reshape wide.

Options for use with xrelong

jlabel(label_name) specifies the name of an existing value label, to be assigned to the generated variable specified by the j() option of reshape long.

reshape_long_options is a list of options used by reshape long.

Examples

Set-up:

. webuse reshape1, clear . describe . list . reshape long inc ue, i(id) j(year) . describe . char list . list, sepby(id) . lab def yr 80 "Eighty" 81 "Eighty one" 82 "Eighty two" . lab val year yr . list, sepby(id)

Simple examples:

. xrewide inc ue, i(id) j(year) cjlabel(varname2) vjlabel(inc) cjval(varseq2) vjval(ue) . char list

. xrewide, cjlab(head1) vjlab(ue) . char list

Note that, if the user does not specify the variables to be reshaped and/or the i() variable list and/or the j() variable, then xrewide tries to find them in the latest reshape estimation results, which are stored as dataset characteristics.

The following example demonstrates the use of xrewide, together with the chardef package downloadable from SSC, to assign characteristics. These characteristics will then be used by the listtab package, also downloadable from SSC, to define headings in a LaTeX tabular environment containing a table of the reshaped dataset, which can be cut and pasted into a LaTeX document. Note that characteristics assigned by chardef to the input variables to be reshaped are inherited by the reshaped output variables generated by xrewide.

. chardef id inc ue, char(varname) val("ID" "Income" "UE") . list, subvar . xrewide inc ue, i(id) j(year) cjlab(varname2) vjlab(inc) pjlab("\textit{") sjlab("}") . listtab_vars id *80 *81 *82, sub(char varname) rstyle(tabular) lo(h1) . listtab_vars id *80 *81 *82, sub(char varname2) rstyle(tabular) lo(h2) . listtab id *80 *81 *82, type rstyle(tabular) head("\begin{tabular}{rrrrrrr}" "`h2'" "`h1'") foot("\end{tabular}")

The following sequence demonstrates the use of xrelong with the varlabdef package, which can be downloaded from SSC, and can create a value label based on a list of variables, with 1 value per variable, and value labels copied from the variable labels, or from other variable attributes.

Set-up:

. sysuse auto, clear . keep foreign make mpg weight price . rename mpg cmval1 . rename weight cmval2 . rename price cmval3 . describe

Reshape from wide to long:

. varlabdef cmlab, vlist(cmval*) from(varlab) . label list cmlab . xrelong cmval, i(foreign make) j(carmeas) jlabel(cmlab) . describe . list, abbr(32) sepby(foreign make)

Reshape from long to wide:

. xrewide cmval, i(foreign make) j(carmeas) cjlab(cmeaslabel) . describe . list

Reshape from wide to long again:

. varlabdef cmlab2, vlist(cmval*) from(char cmeaslabel) . label list cmlab2 . xrelong cmval, i(foreign make) j(carmeas) jlabel(cmlab2) . describe . list, abbr(32) sepby(foreign make)

Saved results

xrewide and xrelong save the same dataset characteristics saved by reshape wide and reshape long, respectively. However, the characteristic _dta[ReS_jv] is always set by xrewide, whether or not the user specifies the values explicitly in the j() option. Also, the characteristic _dta[ReS_Xij] always contains a stub list complete with the @ signs, whether or not the user explicitly included these @ signs in the input stub names. This makes life simpler for programmers, who might want to use these characteristics.

Author

Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk

References

Newson, R. B. 2012. From resultssets to resultstables in Stata. The Stata Journal 12(2): 191-213. Download from The Stata Journal website.

Also see

Manual: [D] reshape, [P] char On-line: help for reshape, char help for listtab, chardef, varlabdef if installed