Assign values to a characteristic of a list of items
chardef [ evarlist ] [ , char(name) values(string_list) prefix(string) suffix(string) ]
charundef [ evarlist ] [ , charlist(characteristic_list) ]
where evarlist is a list of names which are either variable names or _dta, and characteristic_list is
namelist | *
Description
chardef is a mass-production version of the char define command. It assigns a list of values to a named characteristic of a list of items, which can be variables, or the current dataset. If the evarlist is not supplied, then chardef assigns the values to the named characteristic for all variables in the dataset currently in the memory. If the named characteristic is not supplied, then the values are assigned to the characteristic varname, used by the list command. If the list of values is shorter than the evarlist, then the list of values is extended on the right with copies of the last value. Optionally, a prefix and/or a suffix may be added to the values. The charundef module resets a list of characteristics to empty strings for a list of items.
Options for chardef
char(name) specifies the name of the variable characteristic whose values will be reset for all items in the evarlist. If the char() option is not supplied, then the values are assigned to the characteristic varname, used by the subvarname option of the list command.
values(string_list) specifies the list of values to be assigned to the characteristic specified by the char() option, for the corresponding items in the evarlist. If not specified, then it is initialized to a single empty string (""). If the list of values is shorter than the evarlist, then it is extended on the right with copies of the last value in the list, which may or may not be an empty string. Therefore, in default, the values of the named characteristic are cleared for all items in the evarlist.
prefix(string) specifies a common prefix string, to be added to the left of the values specified by the values() option, before assignment to the characteristic named by the char() option for the corresponding items in the evarlist.
suffix(string) specifies a common suffix string, to be added to the right of the values specified by the values() option, before assignment to the characteristic named by the char() option for the corresponding items in the evarlist.
Options for charundef
charlist(characteristic_list) specifies a list of names of characteristics to be undefined (by being set to the empty string ""). It may be a list of legal Stata names, or may be *, implying a list of the names of all characteristics present for any item in the evarlist. If not set, charlist() is set to the names of all characteristics present for any item in the evarlist.
Remarks
chardef and charundef are designed to save the user the work of typing multiple char define commands for multiple variables and/or for the current dataset. It is particularly useful if the user is using the listtab package, downloadable from SSC, to generate tables for TeX, HTML, XML or RTF documents. The user may want to specify one or more header rows, using the headlines() option of listtab, and generate some of these header rows using the listtab_vars module. These header rows will typically be rows of header cells, separated by the delimiter() string used by listtab. The text in the header cells may be prefixed using the prefix() option of chardef, and/or suffixed using the suffix() option of chardef, to specify alignment and/or formatting in the generated table. The whole header row may be prefixed and suffixed by the begin() and end() strings, respectively, specified as options to listtab. For more about the use of chardef with listtab and other packages to create tables, see Newson (2012).
Examples
Setup
.sysuse auto, clear .describe
The following example sets the default varname characteristic for 5 variables, and lists them using list.
.chardef make foreign weight length mpg, values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .list make foreign weight length mpg, abbr(32) subvarname
The following example sets the varname characteristic for the first variable (make), and clears the varname characteristic for all other variables (using the empty string ""), and lists all variables.
.chardef, values("Model of car" "") .list, abbr(32) subvarname
The following example clears the varname characteristic for all variables, and lists them.
.chardef .list, abbr(32) subvarname
The following example assigns the non-default header characteristic for 5 variables.
.chardef make foreign weight length mpg, char(header) values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .char list
The following 3 examples assign the header characteristic for 5 variables, and then unset it.
.chardef make foreign weight length mpg, char(header) values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .char list .charundef
.chardef make foreign weight length mpg, char(header) values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .char list .charundef, char(*)
.chardef make foreign weight length mpg, char(header) values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .char list .charundef make foreign weight length mpg, char(*)
The following advanced example demonstrates the use of chardef, with the packages sdecode, listtab and rtfutil, to create a Rich Text Format (RTF) file myrtf1.rtf, containing a table of 5 variables for odd-numbered car models. The packages sdecode, listtab and rtfutil can be downloaded from SSC.
.sysuse auto, clear .keep if mod(_n,2) .chardef make foreign weight length mpg, char(hcell) prefix("\qr{\i ") suffix("}") values("Car model" "Where from?" "How heavy?" "How long?" "How efficient?") .replace make="\qr{"+make+"}" .foreach Y of var foreign weight length mpg { . sdecode `Y', replace prefix("\qr{") suffix("}") .} .tempname buff1 .rtfopen `buff1' using "myrtf1.rtf", replace template(fnmono1) .capture noisily { . rtfrstyle make foreign weight length mpg, cwidth(2000 1000) lo(b d e) . listtab_vars make foreign weight length mpg, b(`b') d(`d') e(`e') substitute(char hcell) lo(hrow) . listtab make foreign weight length mpg, handle(`buff1') head("`hrow'") b(`b') d(`d') e(`e') .} .rtfclose `buff1'
The following example clears all characteristics of the current dataset:
.sysuse auto, clear .char list .charundef _dta .char list
Saved results
charundef saves the following results in r():
Macros r(charlist) list of names of characteristics cleared (in alphabetic order)
Author
Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk
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: [P] char
Help: [P] char sdecode, listtab, rtfutil if installed