*! version 1.0.2 23Jan2019

Title

gdistinct -- Efficiently report number(s) of distinct observations or values

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

Syntax

This is a fast option to the user command distinct,
additionally storing the results in a matrix.
It is 4 to 26 times faster in Stata/IC and 4-12 times faster in MP

gdistinct [varlist]
[if] [in]
[, missing
abbrev(#)
joint
minimum(#)
maximum(#)
]

Description

gdistinct is a faster alternative to distinct. It displays the
number of distinct observations with respect to the variables in varlist.
By default, each variable is considered separately (excluding missing values)
so that the number of distinct observations for each variable is reported and
in this case the results are stored in a matrix.

The number of distinct observations is the same as the number of distinct
values. Optionally, variables can be considered jointly so that the number
of distinct groups defined by the values of variables in varlist is
reported.

gdistinct is part of the [R] gtools project.

Options

Options

missing specifies that missing values are to be included
in counting distinct observations.

abbrev(#) specifies that variable names are to be
displayed abbreviated to at most # characters. This option has no
effect with joint.

joint specifies that distinctness is to be determined
jointly for the variables in varlist.

minimum(#) specifies that numbers of distinct values are to be displayed only if they are
equal to or greater than a specified minimum.

maximum(#) specifies that numbers of distinct values are to be displayed only if they are
less than or equal to a specified maximum.

sort(order) sort output. order may be alpha
(alphabetical by variable name), distinct (number of distinct values),
or total (number of non-missing values, unless option missing is
specified). Optionally prepend a negative sign to sort in descending order.
Tie-breaks are resolved arbitrarily. This is ignored with option joint.

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

. sysuse auto

. gdistinct

. gdistinct, max(10)

. gdistinct make-headroom

. gdistinct make-headroom, missing abbrev(6)

. gdistinct foreign rep78, joint

. gdistinct foreign rep78, joint missing

See the
online documentation
for more examples.

Stored results

gdistinct stores the following in r():

Scalars

r(N) number of non-missing observations (last variable or joint)

r(J) number of groups (last variable or joint)

r(ndistinct) number of groups (last variable or joint)

r(minJ) largest group size (last variable or joint)

r(maxJ) smallest group size (last variable or joint)

Matrices

r(ndistinct) number of non-missing observations (one row per variable or joint)

Author

Mauricio Caceres Bravo

mauricio.caceres.bravo@gmail.com

mcaceresb.github.io

Website

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

Acknowledgment

gdistinct was written largely to mimic the functionality of the community-contributed command distinct,
written by

Gary Longton, Fred Hutchinson Cancer Research Center, USA

glongton@fhcrc.org

Nicholas J. Cox, Durham University, UK

n.j.cox@durham.ac.uk

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
gunique,
gtools;
distinct (if installed)