*! version 1.0.2 23Jan2019

Title

gcontract -- Efficiently make dataset of frequencies and percentages using C plugins.

Important: Please run gtools, upgrade to update gtools to
the latest stable version.

Syntax

This is a fast option to Stata's contract.
It is 5-7 times faster in Stata/IC and 2.5-4 times faster in MP

gcontract
varlist
[if] [in]
[weight]
[, options]

Instead of varlist, it is possible to specify

[+|-]
varname
[[+|-]
varname ...]

This will not affect the results, but it will affect the sort order of the
final data.

freq(newvar) name of frequency variable; default is _freq

cfreq(newvar) create cumulative frequency variable

percent(newvar) create percentage variable

cpercent(newvar) create cumulative percentage variable

float generate percentage variables as type float

format(format) display format for new percentage variables; default is format(%8.2f)

zero include combinations with frequency zero (VERY SLOW)

nomiss drop observations with missing values

Options
unsorted Do not sort resulting dataset. Saves speed.

fast Mirrors the same option in collapse. Do not preserve and restore the original dataset; saves speed but leaves the data in an unusable state shall the user press Break

Gtools
compress Try to compress strL to str#.

forcestrl Skip binary variable check and force gtools to read strL variables.

verbose Print info during function execution.

bench[()] Benchmark various steps of the plugin. Optionally specify depth level.

hashmethod(str) Hash method (default, biject, or spooky). Intended for debugging.

oncollision(str) Collision handling (fallback or error). Intended for debugging.

fweights are allowed; see weight.

Description

gcontract replaces the dataset in memory with a new dataset consisting
of all combinations of varlist that exist in the data and a new variable
that contains the frequency of each combination. The user can optionally request
percentages and cumulative counts and percentages.

gcontract is part of the [R] gtools project.

Options

Options

freq(newvar) specifies a name for the frequency
variable. If not specified, _freq is used.

cfreq(newvar) specifies a name for the
cumulative frequency variable. If not specified, no cumulative frequency
variable is created.

percent(newvar) specifies a name for the percentage variable.
If not specified, no percent variable is created.

cpercent(newvar) specifies a name for the
cumulative percentage variable. If not specified, no cumulative percentage
variable is created.

float specifies that the percentage variables specified by
percent() and cpercent() will be stored as variables of type
float. This only affects the Stata storage type;
gtools does all computations internally in double precision. If
float is not specified, these variables will be generated as variables
of type double. All generated variables are compressed to the
smallest storage type possible without loss of precision; see [D] compress.

format(format) specifies a
display format for the generated percentage variables specified
by percent() and cpercent(). If format() is not specified,
these variables will have the display format %8.2f.

zero specifies that combinations with frequency zero be included.
This is VERY slow.

nomiss specifies that observations with missing values on any
variable in varlist be dropped. If nomiss is not specified, all
observations possible are used.

Extras

fast specifies that gcollapse not restore the original dataset
should the user press Break.

unsorted Do not sort resulting data set. Saves speed.

Gtools

compress Try to compress strL to str#. The Stata Plugin Interface
has only limited support for strL variables. In Stata 13 and earlier
(version 2.0) there is no support, and in Stata 14 and later (version
3.0) there is read-only support. The user can try to compress strL
variables using this option.

forcestrl Skip binary variable check and force gtools to read strL
variables (14 and above only). Gtools gives incorrect results when there is binary data in strL variables.
This option was included because on some windows systems Stata detects
binary data even when there is none. Only use this option if you are
sure you do not have binary data in your strL variables.

verbose prints some useful debugging info to the console.

benchmark and benchmarklevel(int) print how long in
seconds various parts of the program take to execute. The user can also
pass bench(int) for finer control. bench(1) is the same
as benchmark but bench(2) and bench(3) additionally print
benchmarks for internal plugin steps.

hashmethod(str) Hash method to use. default automagically
chooses the algorithm. biject tries to biject the inputs into the
natural numbers. spooky hashes the data and then uses the hash.

oncollision(str) How to handle collisions. A collision should never
happen but just in case it does gtools will try to use native commands.
The user can specify it throw an error instead by passing oncollision(error).

Examples

See the
online documentation
for examples.

Stored results

gcontract stores the following in r():

Scalars

r(N) number of non-missing observations

r(J) number of groups

r(minJ) largest group size

r(maxJ) smallest group size

Author

Mauricio Caceres Bravo

mauricio.caceres.bravo@gmail.com

mcaceresb.github.io

Website

gcontract is maintained as part of [R] gtools at github.com/mcaceresb/stata-gtools

Acknowledgment

This help file was based on StataCorp's own help file for contract.

This project was largely inspired by Sergio Correia's ftools:
https://github.com/sergiocorreia/ftools.

The OSX version of gtools was implemented with invaluable help from @fbelotti;
see https://github.com/mcaceresb/stata-gtools/issues/11.

Also see

help for
gcollapse,
gtools;
fcollapse (if installed),
ftools (if installed)