{smcl}
{* *! version 1.5.1 24Mar2019}{...}
{viewerdialog gtools "dialog gtools"}{...}
{vieweralsosee "[R] gtools" "mansection R gtools"}{...}
{viewerjumpto "Syntax" "gtools##syntax"}{...}
{viewerjumpto "Description" "gtools##description"}{...}
{viewerjumpto "Options" "gtools##options"}{...}
{viewerjumpto "Examples" "gtools##examples"}{...}
{title:Title}
{p2colset 5 18 23 2}{...}
{p2col :{cmd:gtools} {hline 2}}Manage {opt gtools} package installation.{p_end}
{p2colreset}{...}
{pstd}
{it:Important}: Please run {stata gtools, upgrade} to update
{cmd:gtools} to the latest stable version.
{pstd}
{opt 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 {help gtools##examples:examples} below):
{p 8 17 2}
{manhelp gcollapse R:gcollapse} and {manhelp gcontract R:gcontract} as {opt collapse} and {opt contract} replacements. {p_end}
{p 8 17 2}
{manhelp gquantiles R:gquantiles} as {opt pctile}, {opt xtile}, and {opt _pctile} replacements. {manhelp fasterxtile R:fasterxtile} is also provided as an alias
{p_end}
{p 8 17 2}
{manhelp gegen R:gegen} as a {opt egen} alternative. {p_end}
{p 8 17 2}
{manhelp gisid R:gisid} as an {opt isid} replacement. {p_end}
{p 8 17 2}
{manhelp gduplicates R:gduplicates} as a {opt duplicates} replacement. {p_end}
{p 8 17 2}
{manhelp glevelsof R:glevelsof} as a {opt levelsof} replacement. {p_end}
{p 8 17 2}
{manhelp gtoplevelsof R:gtoplevelsof} ({opt gtop}): Frequency count of top levels of a {opt varlist}. {p_end}
{p 8 17 2}
{manhelp gunique R:gunique} and {manhelp gdistinct R:gdistinct}: Count unique levels of a set of variables. {p_end}
{p 8 17 2}
{manhelp gstats R:gstats}: Wrapper for several statistical functions and transformations. {p_end}
{p 8 17 2}
{manhelp hashsort R:hashsort}: (Experimental) Hash-based sorting. {p_end}
{marker syntax}{...}
{title:Syntax}
{p 8 17 2}
{cmd:gtools}
[{cmd:,} {it:{help gtools##table_options:options}}]
{synoptset 15 tabbed}{...}
{marker table_options}{...}
{synopthdr}
{synoptline}
{syntab :Options}
{synopt :{opt u:pgrade}}Install latest version from Github.
{p_end}
{synopt :{opt i:nstall_latest}}Alias for {opt upgrade}.
{p_end}
{synopt :{opt license:s}}Prints the open source projects used in gtools
{p_end}
{synopt :{opt v:erbose}}With {opt licenses}, prints the licenses of the open source projects used in gtools
{p_end}
{synopt :{opt examples}}Print examples of how to use various gtools functions.
{p_end}
{synopt :{opt showcase}}Alias for {opt examples}.
{p_end}
{synopt :{bf:test[({it:tests})]}}Run unit tests, optionally specifying which tests to run.
{p_end}
{synopt :{opth branch(str)}}Github branch to use (defualt is master).
{p_end}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
{marker description}{...}
{title:Description}
{pstd}
{opt 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.
{pstd}
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.
{marker options}{...}
{title:Options}
{phang}
{opt upgrade} Upgrades {opt gtools} to the latest github version.
{phang}
{opt install_latest} Alias for {opt upgrade}.
{phang}
{opt license} Prints the open source projects used in {cmd gtools}. With
{opt verbose} it also prints the licenses.
{phang}
{opt examples} (alias {opt showcase}) prints examples of how to use
various gtools functions.
{phang}
{bf:test[({it: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 {cmd: 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 {bf:comparisons}, which compares the results
from gtools to that of various native counterparts under several
different conditions. {bf: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.
{phang}
{opth branch(str)} Github branch to use (defualt is master).
{marker examples}{...}
{title:Examples}
{p 4 4 2}{stata sysuse auto, clear}{p_end}
{p 4 4 2}{it:gquantiles [newvarname =] exp [if] [in] [weight], {_pctile|xtile|pctile} [options]}{p_end}
{p 8 4 2}{stata gquantiles 2 * price, _pctile nq(10) }{p_end}
{p 8 4 2}{stata gquantiles p10 = 2 * price, pctile nq(10) }{p_end}
{p 8 4 2}{stata gquantiles x10 = 2 * price, xtile nq(10) by(rep78) }{p_end}
{p 8 4 2}{stata fasterxtile xx = log(price) [w = weight], cutpoints(p10) by(foreign)}{p_end}
{p 4 4 2}{it:hashsort varlist, [options] }{p_end}
{p 8 4 2}{stata hashsort -make }{p_end}
{p 8 4 2}{stata hashsort foreign -rep78, benchmark verbose mlast}{p_end}
{p 4 4 2}{it:gegen target = stat(source) [if] [in] [weight], by(varlist) [options]}{p_end}
{p 8 4 2}{stata gegen tag = tag(foreign) }{p_end}
{p 8 4 2}{stata gegen group = tag(-price make) }{p_end}
{p 8 4 2}{stata gegen p2_5 = pctile(price) [w = weight], by(foreign) p(2.5) }{p_end}
{p 4 4 2}{it:gisid varlist [if] [in], [options] }{p_end}
{p 8 4 2}{stata gisid make, missok }{p_end}
{p 8 4 2}{stata gisid price in 1 / 2 }{p_end}
{p 4 4 2}{it:gduplicates varlist [if] [in], [options gtools(gtools_options)] }{p_end}
{p 8 4 2}{stata gduplicates report foreign }{p_end}
{p 8 4 2}{stata gduplicates report rep78 if foreign, gtools(bench(3)) }{p_end}
{p 4 4 2}{it:glevelsof varlist [if] [in], [options] }{p_end}
{p 8 4 2}{stata glevelsof rep78, local(levels) sep(" | ") }{p_end}
{p 8 4 2}{stata glevelsof foreign mpg if price < 4000, loc(lvl) sep(" | ") colsep(", ") }{p_end}
{p 8 4 2}{stata glevelsof foreign mpg in 10 / 70, gen(uniq_) nolocal }{p_end}
{p 4 4 2}{it:gtop varlist [if] [in] [weight], [options] }{p_end}
{p 4 4 2}{it:gtoplevelsof varlist [if] [in] [weight], [options] }{p_end}
{p 8 4 2}{stata gtoplevelsof foreign rep78 }{p_end}
{p 8 4 2}{stata gtop foreign rep78 [w = weight], ntop(5) missrow groupmiss pctfmt(%6.4g) colmax(3) }{p_end}
{p 4 4 2}{it:gcollapse (stat) out = src [(stat) out = src ...] [if] [if] [weight], by(varlist) [options]}{p_end}
{p 8 4 2}{stata gen h1 = headroom }{p_end}
{p 8 4 2}{stata gen h2 = headroom }{p_end}
{p 8 4 2}{stata pretty# #sourcelabel#) }{p_end}
{p 8 4 2}{stata gcollapse (mean) mean = price (median) p50 = gear_ratio, by(make) merge v }{p_end}
{p 8 4 2}{stata disp "`:var label mean', `:var label p50'" }{p_end}
{p 8 4 2}{stata gcollapse (iqr) irq? = h? (nunique) turn (p97.5) mpg, by(foreign rep78) bench(2) wild }{p_end}
{p 4 4 2}{it:gcontract varlist [if] [if] [fweight], [options]}{p_end}
{p 8 4 2}{stata gcontract foreign [fw = turn], freq(f) percent(p)}{p_end}
{marker author}{...}
{title:Author}
{pstd}Mauricio Caceres Bravo{p_end}
{pstd}{browse "mailto:mauricio.caceres.bravo@gmail.com":mauricio.caceres.bravo@gmail.com }{p_end}
{pstd}{browse "https://mcaceresb.github.io":mcaceresb.github.io}{p_end}
{title:Website}
{pstd}{cmd:gtools} is maintained at {browse "https://github.com/mcaceresb/stata-gtools":github.com/mcaceresb/stata-gtools}{p_end}
{marker acknowledgment}{...}
{title:Acknowledgment}
{pstd}
This project was largely inspired by Sergio Correia's {it:ftools}:
{browse "https://github.com/sergiocorreia/ftools"}.
{p_end}
{pstd}
The OSX version of gtools was implemented with invaluable help from @fbelotti;
see {browse "https://github.com/mcaceresb/stata-gtools/issues/11"}.
{p_end}