help for xcontract and freqtop(Roger Newson)

Create or extend dataset of variable combinations with frequencies and percents

xcontract varlist [weight] [if exp] [in range] [,

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

frame( framename [ , replace change ] )

saving(filename[,replace]) norestore fast
flist(global_macro_name)

freq:(newvarname) percent:(newvarname)
cfreq:(newvarname) cpercent:(newvarname)

ptype(storage_type) pformat(format) ztotal(#)

by(by_varlist)

zero nomiss

idnum(#) nidnum(newvarname)
idstr(string) nidstr(newvarname)

format(varlist_1 format_1 ... varlist_n format_n)

]

freqtop [if exp] [in range] [,

freq:(newvarname) percent:(newvarname)
cfreq:(newvarname) cpercent:(newvarname)

ptype(storage_type) pformat(format) ztotal(#)

by(by_varlist)

fast replace

]

fweights, aweights, pweights, and iweights are allowed for xcontract,
and are all treated in the same way;
see help for weights.

Description

xcontract is an extended version of contract.
It creates an output data set (or resultsset),
with 1 observation per combination of values of the variables in varlist,
and data on the frequencies and percents of those combinations of values
in the existing data set,
and, optionally, the cumulative frequencies and percents of those combinations.
If the by() option is used, then the output data set
has one observation per combination of values of the varlist variables per by-group,
and percents are calculated within each by-group.
The output data set created by xcontract
may be listed to the Stata log, or saved to a data frame, or saved to a disk file, or written to the memory
(overwriting any pre-existing data set).
freqtop inputs an existing frequency variable in the current dataset,
which is typically an output dataset made by xcontract.
It generates new variables, in the same dataset,
containing the corresponding cumulative frequencies and/or percents and/or cumulative percents,
optionally defined within user-specified by-groups.

Options for use with xcontract and freqtop

xcontract and freqtop have a large number of options, which are listed in 4 groups:

1. Options for xcontract and freqtop.

2. Output-destination options for xcontract.
(These specify where the output data set will be written.)

3. Other options for xcontract only.

4. Other options for freqtop.

Options for xcontract and freqtop

freq(newvarname) specifies a name for the output frequency
variable (for xcontract)
or the input frequency variable (for freqtop).
If not specified, the name _freq is used.

percent(newvarname) specifies a name for the percent
variable. If not specified, _percent is used.
If the by() option is used,
then the percent for each combination of values of the
varlist variables in each by-group is calculated as a percent of the by-group.

cfreq(newvarname) specifies a name for the cumulative
frequency variable. If not specified, no cumulative frequency variable is created.
If the by() option is used,
then the cumulative frequency for each combination of values of the
varlist variables in each by-group is calculated as a cumulative frequency within the by-group.

cpercent(newvarname) specifies a name for the cumulative
percent variable. If not specified, no cumulative percent variable is created.
If the by() option is used,
then the cumulative percent for each combination of values of the
varlist variables in each by-group is calculated as a cumulative percent of the by-group.

ptype(storage_type) specifies a storage type
for generating the percent variables specified by percent() and cpercent().
If type() is not specified, then these variables will be generated as variables
of type float. All generated variables are compressed to the smallest
storage type possible without loss of precision. See help for compress.

pformat(format) specifies a display format
for the percent variables specified by percent() and cpercent().
If pformat() is not specified,
then these variables will have format %8.2f,
unless the formats are changed using the format() option.

ztotal(#) specifies a numeric value (usually missing)
to which percents are evaluated if the denominator from which they are derived is zero.
For instance, ztotal(.z) evaluates such percents to the missing value .z.
The default is ztotal(.), using the standard numeric missing value.

by(by_varlist) specifies a list of by-variables. If by()
is specified, then all percents will be calculated as percents of their by-groups.
Note that, if the if expression or the weight expression contains the
reserved names _n and _N, then these will be interpreted as the observation sequence number
and the number of observations, respectively, within the whole data set, not within the by-group.

Output-destination options for xcontract.

list(varlist [if exp] [in range] [, list_options ] )
specifies a list of variables in the output
data set, which will be listed to the Stata log by xcontract.
The list() option can be used with the format() option (see below)
to produce a list of frequencies and/or percents
with user-specified numbers of decimal places or significant figures.
The user may optionally also specify if or in qualifiers to list subsets of combinations
of variable values,
or change the display style using a list of list_options allowed as options by the list command.
If by(by_varlist) is used, then the combinations are listed by the by-groups defined by
by_varlist.

frame( name, [ replace change ] ) specifies an output data frame,
to be generated to contain the output data set.
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 xcontract.
The frame() option may not specify the current data frame.
To do this, use one of the options norestore or fast.

saving(filename[,replace]) saves the output data set to a disk file.
If replace is specified, and a file of that name already exists,
then the old file is overwritten.

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

fast is a stronger version of norestore, intended for use by programmers.
It specifies that the pre-existing data set in the memory will not be restored,
even if the user presses Break during the execution of xcontract.
If norestore is specified and fast is absent,
then xcontract 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 five options list(), frame(),
saving(), norestore, and fast.
These options specify whether the output data set is listed to the Stata log,
saved to a disk file, or written to the memory (overwriting any pre-existing data set). More than
one of these options can be specified.

flist(global_macro_name) specifies the name of a global macro, containing
a filename list (possibly empty). If saving() is also specified, then
xcontract will append the name of the data set 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 output data sets.
These files may later be concatenated using append.

Other options for xcontract only

zero specifies that combinations of values of the variables in varlist
with zero frequency in the input data set will be included in the output data set.

nomiss specifies that observations with missing values for any of
the variables in varlist will be excluded from the output data set.
If not specified, all observations are included,
except if excluded by the if and in qualifiers or given zero weights.

idnum(#) specifies an ID number for the output data set.
It is used to create a numeric variable, with default name idnum, in the output data set,
with that value for all observations.
This is useful if the output data set is concatenated with other xcontract output data sets
using append.

nidnum(newvarname) specifies a name for the numeric ID variable
evaluated by {cmd:idnumrher If idnum() is present and nidnum() is absent,
then the name of the numeric ID variable is set to idnum.

idstr(string) specifies an ID string for the output data set.
It is used to create a string variable, with default name idstr in the output data set,
with that value for all observations.
This is useful if the output data set is concatenated with other xcontract output data sets
using append.

nidstr(newvarname) specifies a name for the string ID variable
evaluated by idstr(). If idstr() is present and nidstr() is absent,
then the name of the string ID variable is set to idstr.

format(varlist_1 format_1 ... varlist_n format_n)
specifies a list of pairs of variable lists and display formats.
The formats will be allocated to
the variables in the output data set specified by the corresponding varlist_i
lists.
If the format() option is absent, then the percent variables have the format %8.2f,
the frequency variables have the format %12.0g,
and the other variables have the same formats as the variables of the same names
in the input data set.

Other options for freqtop

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

replace specifies that, if there are existing variables in the current dataset,
with the same names as the output percents and/or cumulative frequencies created by freqtop,
then those existing variables will be replaced.

Examples

The following examples use the list() option to list the output data set to the Stata log.
After these examples are executed, there is no new data set either in the memory or on disk.

. xcontract foreign rep78, list(,)

. xcontract foreign rep78, zero list(,clean noobs)

. xcontract foreign rep78, f(count) p(percent) cf(ccount) cp(cpercent) zero nomiss list(*,clean noobs)

. xcontract rep78, by(foreign) fr(frequency) per(percentage) cf(cumfreq) cp(cumperc) pty(double) format(percentage cumperc %4.0f) list(rep78-cumperc,clean noobs abbrev(16))

. xcontract _all, list(*,clean noobs)

The following examples use the norestore option to create an output data set in the memory,
overwriting any pre-existing data set.

. xcontract foreign rep78, norestore

. xcontract foreign rep78, zero norestore

. xcontract foreign rep78, f(count) p(percent) cf(ccount) cp(cpercent) zero nomiss norestore

. xcontract rep78, by(foreign) fr(frequency) per(percentage) cf(cumfreq) cp(cumperc) pty(double) format(percentage cumperc %4.0f) norestore

. xcontract _all, norestore

The following examples use the saving() option to create an output data set in a disk file.

. xcontract foreign rep78, saving(myfreq1.dta)

. xcontract foreign rep78, zero saving(myfreq2.dta,replace)

. xcontract foreign rep78, f(count) p(percent) cf(ccount) cp(cpercent) zero nomiss saving(myfreq3.dta,replace)

. xcontract rep78, by(foreign) fr(frequency) per(percentage) cf(cumfreq) cp(cumperc) pty(double) format(percentage cumperc %4.0f) saving(myfreq4.dta,replace)

. xcontract _all, saving(myfreq5.dta,replace)

The following examples use the frame() option to create an output data set in a data frame.

. sysuse auto, clear

. xcontract rep78, by(foreign) frame(outframe)

. frame outframe {

. describe, full

. by foreign: list, abbr(32)

. }

. frame drop outframe

. sysuse auto, clear

. xcontract rep78, by(foreign) frame(outframe, replace change)

. describe, full

. twoway bar _percent rep78 [fweight=_freq], hori by(foreign, col(1)) yscale(reverse) ylab(1(1)5)

. frame change default

. describe, full

. frame drop outframe

The following advanced example
uses freqtop to add row and column percents
to a resultsset created by xcontract.
We start by creating the resultsset using xcontract,
with 1 observation per combination of foreign and rep78,
including combinations with no observations (because of the zero option),
and overwriting the dataset in memory (because of the fast option).
We then add a variable _colpercent,
containing percents foreach each rep78 value in by-groups defined by foreign values.
We then add a variable _rowpercent,
containing percents foreach each foreign value in by-groups defined by rep78 values.
The dataset then represents a table, with columns corresponding to foreign values,
and rows corresponding to rep78 values.
Note that the column percents sum to 100.00 percent
in the columns (but not in the rows),
and the row percents sum to 100.00 percent
in the rows (but not in the columns).

. sysuse auto, clear

. xcontract foreign rep78, zero fast

. describe, full

. by foreign: list, abbr(32)

. freqtop, percent(_colpercent) by(foreign)

. describe, full

. by foreign: list, abbr(32) sum(_percent _colpercent)

. freqtop, percent(_rowpercent) by(rep78)

. describe, full

. by foreign: list, abbr(32) sum(_percent _colpercent _rowpercent)

. bysort rep78 (foreign): list, abbr(32) sum(_percent _colpercent _rowpercent)

Acknowledgements

I would like to thank Nicholas J. Cox of Durham University, UK
for some very helpful advice about writing efficient code,
and also for writing the original version of contract, from which I re-engineered some of
the code for xcontract.
I would also like to thank Jeremy Freese of Stanford University for writing the SSC package frameappend,
from which I also re-engineered some of the code for xcontract.
I would also like to thank StataCorp for writing fillin, from which
I also re-engineered some of the code for xcontract.

Author

Roger Newson, Queen Mary University London, UK.
Email: r.newson@qmul.ac.uk

Also see

Manual: [R] contract, [R] collapse, [R] fillin, [R] compress, [R] format,
[R] expand, [R] duplicates

Online: help for contract, collapse, fillin, compress, format,
expand, duplicates

help for xcollapse if installed