help for gsgroup                                                 (Roger Newson)

Create a group variable and optionally an output dataset for a gsort key

gsgroup gsort_list , generate(varname) [ saving(filename [, replace]) nomissing mfirst ]

where gsort_list is a list of one or more elements of the form


as used by the gsort command.


gsgroup inputs a gsort key (a list of elements of the form used by gsort, and generates as output a new variable, indicating the sequential order of the group to which each observation belongs, and (optionally) an output dataset (or resultsset), with 1 observation per group, and data on the values of the generated variable, and the variables of the gsort key corresponding to that group. Unlike gsort, gsgroup does not change the sort order of the dataset in memory. The output dataset can be merged into other datasets, using the official Stata command merge or the SSC package addinby. gsgroup is typically used together with the SSC packages parmest and xcontract.


generate(varname) must be present. It specifies the name of an output variable to be generated. This output variable will contain, in each observation, the group to which that observation belongs, based on the values of the variables of the gsort key in that ovservation. It will have 1 integer value per combination of values for the input variables in the varlist, in ascending order of these values, starting with 1.

saving(filename [, replace]) specifies a file containing an output dataset (or resultsset), with 1 observation per group specified by the varlist, and data on the corresponding value of the new variable specified by the generate() option, and also on the values of the input variables in the gsort key corresponding to that group. The output dataset is sorted primarily by the grouping variable, and secondarily by the variables in the gsort key in order of appearance. If replace is specified, then any existing file named filename will be replaced.

nomissing specifies that observations with missing values in the variables of the input gsort key will have missing values in the generated group variable, and that these missing values will not be included in the saving() dataset (if specified). In default, groups with missing values will be included, both in the group variable and in the output dataset.

mfirst functions as the option of the same name for gsort.


.sysuse auto, clear .gsgroup -foreign rep78, gene(frgroup)

.sysuse auto, clear .gsgroup rep78 foreign, g(rfgroup) saving(rfgroup1.dta, replace)

The following advanced example requires Stata Version 11 or higher. It uses xgroup with the packages parmest, xcontract, keyby and addinby, downloadable from SSC. It defines a new binary variable odd, indicating that a car is odd-numbered in the sequence of the data. It then uses gsgroup to create a new variable fogroup, grouping the data by the binary variables foreign and odd, and an output dataset with 1 option per group. It then fits a regression model predicting fuel efficiency in miles per gallon (mpg) from car weight in US pounds (lb) to the data in each group defined by fogroup, and uses margins to estimate the expected mileage per gallon, in that group, of a car weighing 3000 lb. The estimated mileage for each group, with its confidence limits, is saved in an output dataset (or resultsset) in a temporary file, using parmest, with the idstr() and rename() options to create a numeric identifier variable, also with the name fogroup. We then concatenate the parmest resultssets into the memory using append, and then use addinby to add in the values of the key variables from the gsgroup resultsset. Finally, we use keyby to key the resultsset by the groups and by their defining variables, and describe and list the resultsset. Note that this example uses the variable characteristic fogroup[varlist], documented in Saved results, and containing a list of the variables defining the groups.


.sysuse auto, clear .gene byte odd=mod(_n,2) .lab var odd "Odd-numbered car"


.gsgroup -foreign odd, gene(fogroup) saving(fogroup1, replace) .global tflist "" .levelsof fogroup, lo(fogroups) .foreach GP of num `fogroups' { .xcontract fogroup `fogroup[varlist]' if fogroup==`GP', list(,) .regress mpg weight if fogroup==`GP' .margins, at(weight=3000) .tempfile tfcur .parmest, bmat(r(b)) vmat(r(V)) idnum(`GP') rename(idnum fogroup) saving(`"`tfcur'"', replace) flis(tflist) .} .clear .append using $tflist .addinby fogroup using fogroup1 .keyby fogroup `fogroup[varlist]' .describe .list

Saved results

gsgroup assigns to the generate() variable a variable characteristic varlist, containing a varlist of the variables appearing in the input gsort key, in order of appearance in the key.


Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk

Also see

Manual: [D] gsort, [D] save, [D] sort, [D] merge On-line: help for gsort, save, sort, merge help for addinby, keyby, parmest, xcontract if installed