*! version 1.10.1 05Dec2022

Title

gtools -- Manage gtools package installation.

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

gtools is a suite of commands that use hashes for a speedup
over traditional stata commands. Syntax is largely analogous to each
command's Stata counterparts. The following are available as part of
gtools (also see the examples below):

[R] gcollapse and [R] gcontract as collapse and contract replacements.

[R] gquantiles as pctile, xtile, and _pctile replacements. [R] fasterxtile is also provided as an alias

[R] gegen as a egen alternative.

[R] gisid as an isid replacement.

[R] gduplicates as a duplicates replacement.

[R] glevelsof as a levelsof replacement.

[R] gtoplevelsof (gtop): Frequency count of top levels of a varlist.

[R] gunique and [R] gdistinct: Count unique levels of a set of variables.

[R] gstats: Wrapper for several statistical functions and transformations.

[R] hashsort: (Experimental) Hash-based sorting.

Syntax

gtools
[, options]

Options
upgrade Install latest version from Github.

install_latest Alias for upgrade.

licenses Prints the open source projects used in gtools

verbose With licenses, prints the licenses of the open source projects used in gtools

examples Print examples of how to use various gtools functions.

showcase Alias for examples.

test[(tests)] Run unit tests, optionally specifying which tests to run.

branch(str) Github branch to use (defualt is master).

Description

gtools is a Stata package that provides a fast implementation of
common commands like collapse, egen, xtile, isid, levelsof, contract,
distinct, and so on using C plugins for a massive speed improvement.

This program helps the user manage their gtools installation. While
unnecessary in Linux or OSX, when trying to compile the plugin on Windows
it became apparent that I would need to include a DLL with the package
(in particular the DLL for the hash library). While I try to do this
automatically, I ran into enough problems while developing the plugin that I
felt compelled to include this program.

Options

upgrade Upgrades gtools to the latest github version.

install_latest Alias for upgrade.

license Prints the open source projects used in . With
verbose it also prints the licenses.

examples (alias showcase) prints examples of how to use
various gtools functions.

test[(tests)] Run unit tests, optionally specifying which tests
to run. Tests available are: dependencies, basic_checks, bench_test,
comparisons, switches, bench_full. A good set of "small" tests which
take 10-20 minutes are dependencies basic_checks bench_test.
By default, however, the first 5 tests are run, which take 1-3h. The
bulk of that time is from comparisons, which compares the results
from gtools to that of various native counterparts under several
different conditions. bench_full is not run by default because this
benchmarks gtools against stata using modestly-sized data (millions).
Some stata commands are very slow under some of the benchmarks, meaning
this can take well over a day.

branch(str) Github branch to use (defualt is master).

Examples

sysuse auto, clear

gstats {sum|tab} varlist [if] [in] [weight], [by(varlist) options]

gstats sum price [pw = gear_ratio / 4]

gstats tab price mpg, by(foreign) matasave

gquantiles [newvarname =] exp [if] [in] [weight], {_pctile|xtile|pctile} [options]

gquantiles 2 * price, _pctile nq(10)

gquantiles p10 = 2 * price, pctile nq(10)

gquantiles x10 = 2 * price, xtile nq(10) by(rep78)

fasterxtile xx = log(price) [w = weight], cutpoints(p10) by(foreign)

gstats winsor varlist [if] [in] [weight], [by(varlist) cuts(# #) options]

gstats winsor price gear_ratio mpg, cuts(5 95) s(_w1)

gstats winsor price gear_ratio mpg, cuts(5 95) by(foreign) s(_w2)

hashsort varlist, [options]

hashsort -make

hashsort foreign -rep78, benchmark verbose mlast

gegen target = stat(source) [if] [in] [weight], by(varlist) [options]

gegen tag = tag(foreign)

gegen group = tag(-price make)

gegen p2_5 = pctile(price) [w = weight], by(foreign) p(2.5)

gisid varlist [if] [in], [options]

gisid make, missok

gisid price in 1 / 2

gduplicates varlist [if] [in], [options gtools(gtools_options)]

gduplicates report foreign

gduplicates report rep78 if foreign, gtools(bench(3))

glevelsof varlist [if] [in], [options]

glevelsof rep78, local(levels) sep(" | ")

glevelsof foreign mpg if price < 4000, loc(lvl) sep(" | ") colsep(", ")

glevelsof foreign mpg in 10 / 70, gen(uniq_) nolocal

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

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

gtoplevelsof foreign rep78

gtop foreign rep78 [w = weight], ntop(5) missrow groupmiss pctfmt(%6.4g) colmax(3)

gcollapse (stat) out = src [(stat) out = src ...] [if] [if] [weight], by(varlist) [options]

gen h1 = headroom

gen h2 = headroom

pretty# #sourcelabel#)

gcollapse (mean) mean = price (median) p50 = gear_ratio, by(make) merge v

disp "`:var label mean', `:var label p50'"

gcollapse (iqr) irq? = h? (nunique) turn (p97.5) mpg, by(foreign rep78) bench(2) wild

gcontract varlist [if] [if] [fweight], [options]

gcontract foreign [fw = turn], freq(f) percent(p)

greshape subcommand list, i(i) j(j) [options]

gen j = _n

greshape wide f p, i(foreign) j(j)

greshape long f p, i(foreign) j(j)

greshape spread f p, j(j)

greshape gather f? p?, j(j) value(fp)

Author

Mauricio Caceres Bravo

mauricio.caceres.bravo@gmail.com

mcaceresb.github.io

Website

gtools is maintained at github.com/mcaceresb/stata-gtools

Acknowledgment

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.