help for insingap (Roger Newson)

Insert a single gap observation at the top of each by-group in a dataset

insingap [ byvarlist ]
[ , innerorder(varlist)

neworder(newvar [, replace])

gapindicator(newvar [, replace])

rowlabel(varname) grdecode(varlist)

msdecode_options

growlabels(string)
rstring(string_replacement_option)
fast
]

where string_replacement_option can be

order | name | type | format | varlab | char characteristic_name | label | labname

and characteristic_name is the name of a variable characteristic,
and msdecode_options is a list of any options used by msdecode,
apart from generate() and replace.

Description

insingap inputs a dataset and (optionally) a list of by-variables.
It sorts the dataset by these by-variables (if present),
and then inserts a single gap observation at the beginning of each by-group,
or at the top of the dataset if there are no by-variables.
In the gap observations, values of the non-by variables are initialized to missing.
However, the user may specify an existing string variable as a row label variable,
and set its value in the gap observations
to a value derived by decoding a subset of the by-variables,
using the msdecode module of the SSC package sdecode.
These gap observations may be useful when presenting the dataset.
For instance, the dataset may be used to produce tables,
using the SSC package listtab.
Alternatively, the dataset may be used to produce plots,
using the SSC package sencode to encode the row variable.
insingap requires the packages sdecode and ingap,
which the user can download from SSC.

Options

innerorder(varlist) specifies a list of variables,
used to sort the observations in the dataset,
or in each by-group specified by the byvarlist,
before the gap observations are inserted.
If innerorder() is not specified,
then the observations are left in the original order.

neworder(newvarname [, replace]) specifies the name of a new variable to be generated,
equal to the new sequential order of the observation within the dataset,
or within the by-group if a byvarlist is specified,
after the gap observations have been inserted.
The new variable has no missing values.
After execution of insingap, the dataset in memory is sorted primarily by the by-variables (if specified),
and secondarily by the neworder() variable (if specified).
The replace suboption specifies that any existing variable with the same name will be replaced.

gapindicator(newvarname [, replace]) specifies the name of a new variable to be generated,
equal to 1 for the newly-inserted gap observations and 0 for all other observations.
The replace suboption specifies that any existing variable with the same name will be replaced.

rowlabel(string_varname) specifies the name of an existing string variable,
used as the row labels for a table whose rows are the observations.
In the gap observations,
this string variable is set by the grdecode() option if specified,
or otherwise by the growlabels() option if specified,
or otherwise to an empty string.
The rowlabel() variable may not be a by-variable.

Note that the neworder(), gapindicator() and rowlabel() options may not specify the same variable names,
and may not specify the names of by-variables.
Also, note that the neworder() and gapindicator() variables are always non-missing.

grdecode(varlist) specifies a list of variables,
which must be a subset of the by-variables,
and which are decoded, using the msdecode module of the SSC package sdecode,
to produce values for the rowlabel() variable in the gap observations.

msdecode_options are any options used by msdecode,
other than generate() and replace.
They specify the way in which the grdecode() variables will be decoded
to produce the gap row label values in the rowlabel() variable.

growlabels(string) specifies a string value for the row label variable in the gap observations,
if these values are not set by the grdecode() option.
If the rowlabel() option is present
and the grdecode() and growlabels() options are absent,
then the rowlabel() variable is initialised to missing in the gap observations.

rstring(string_replacement_option) specifies a rule for replacing the values of
string variables (other than the by-variables and row label variable) in gap observations.
If rstring() is not set,
then these variables will be set to a missing value (an empty string) in the gap observations.
rstring() can be set to
order, name, type, format, varlab, char characteristic_name,
label, or labname.
The options order, name, type, format, varlab and char characteristic_name
imply that the value of each string variable, in the gap observations,
will be set to the order of the variable in the existing dataset,
the storage type of the variable,
the display format of the variable,
the variable label of the variable,
or the ccharacteristic of the variable with the name characteristic_name,
respectively.
The option label is a synonym for varlab.
The option labname specifies that the value of each string variable, in the gap observations,
will be set to its variable label, if that label exists,
and to its name otherwise.
(Note that numeric variables that are not by-variables, gapindicator() variables or neworder() variables
are always set to the numeric missing value . in gap observations.)
The rstring() option allows the user to add a row of column headings to a dataset of string variables,
or to add a row of column headings to each by-group of a dataset of string variables.
Note also that numeric variables may be converted to string variables using the sdecode package,
downloadable from SSC,
before using insingap and listtab.
This allows the user to use the rstring() option,
and also to format numeric variables in ways not possible using Stata formats alone,
such as adding parentheses to confidence limits.

fast is an option for programmers.
It specifies that insingap will do no work to ensure
that the original dataset is preserved in the event that insingap fails,
or if the user presses the Break key.
If fast is not specified,
and insingap fails, or the user presses the Break key,
then the original existing dataset is preserved, with no additional gap observations.

Remarks

insingap is typically used to convert a Stata dataset to a form with 1 observation per table row
(including gap rows), or 1 observation per graph axis label (including gap axis labels).
The user can then list the dataset as a TeX, LaTeX, HTML or Microsoft Word table,
using the listtab package (downloadable from SSC).
Alternatively, for immediate impact, the user can use the sencode package
(downloadable from SSC) to encode the row labels to a numeric variable,
and then plot this numeric variable against other variables using Stata graphics programs.
For instance, a user might use eclplot (downloadable from SSC)
to produce horizontal confidence interval plots, with the row labels on the vertical axis.
It is usually advisable for the user to type preserve before a sequence of commands including
insingap, and to type restore after a sequence of commands using insingap,
because insingap modifies the dataset by adding new observations.
It is usually also advisable for the user to place the whole sequence of commands in a do-file,
and to execute this do-file,
rather than to type the sequence of commands one by one at the terminal.

The listtab package is described in Newson (2012).
It inputs a list of variables in a Stata dataset,
and outputs a text table, in a file or on the screen,
containing these variables as columns and the observations as rows,
and formatted using a row style.
This row style may correspond to table rows in plain TeX, LaTeX, HTML, XML, or RTF tables,
or to rows of tab-delimited, column-delimited or ampersand-delimited generic text spreadsheets,
or to rows in other styles that may be invented in future.
The row style is defined using a row-beginning string, a row-end string,
and a between-column delimiter string.
listtab is a successor to the listtex package,
described in Newson (2006), Newson (2004) and Newson (2003).
The main change introduced in listtab is that empty delimiter strings are now allowed.
Users of Stata versions 10 and above
are advised to use listtab in preference to listtex,
although both packages are still downloadable from SSC.

Examples

The following example inputs the auto dataset,
adds a gap observation to the start of each car origin group
defined by the variable foreign,
and describes and lists the new dataset.
Note that changes to the dataset are made
between a preserve statement and a restore statement.
It is usually a good idea to do this,
if the user wants to restore the original dataset after the listing and/or plotting and/or tabulation has been done.

. sysuse auto, clear

. describe

. preserve

. insingap foreign, grdecode(foreign) suffix(" cars:") row(make) neworder(rowseq) gapind(gapstat)

. describe

. list make mpg weight rowseq gapstat, sepby(foreign)

. restore

The following example inputs the auto dataset and keeps every 8th model.
It then adds a gap observation to the start of each car origin group,
uses the SSC package sencode
to encode the row label variable make to a numeric variable make2
(numbered in order of appearance),
lists the variable labels for make2,
and plots the weights of US and non-US cars.
Note that the gap observations are labelled in bold type, using SMCL.
This is done using the prefix() and suffix() options,
which are two of the msdecode_options that insingap inherits from msdecode,
to define value labels for make2 containing SMCL.
To find more about the use of SMCL in graph text, see help for graph_text.

. sysuse auto, clear

. preserve

. keep if mod(_n,8)==0

. describe

. insingap foreign, grd(foreign) pref("{bf:") suff(" cars:}") row(make) newo(rowseq)

. describe

. list make weight rowseq, sepby(foreign)

. sencode make, many gene(make2)

. label list make2

. twoway spike weight make2, hori ylabel(1(1)11, valuelabel angle(0)) yscale(reverse) xlabel(0(500)5000)

. restore

insingap is designed as an easy-to-use front end for the more comprehensive package ingap,
which can also be downloaded from SSC.
Examples of the use of ingap, together with other packages, can be found in
Newson (2012), Newson (2006), Newson (2004) and Newson (2003).
The insingap package is expected to be preferred to ingap
for most applications.

Author

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

References

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12(2): 191-213.
Download from The Stata Journal website.

Newson, R. 2006.
Resultssets, resultsspreadsheets and resultsplots in Stata.
Presented at the 4th German Stata User Meeting, Mannheim, 31 March, 2006.

Newson, R. 2004.
From datasets to resultssets in Stata.
Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004.

Newson, R. 2003.
Confidence intervals and p-values for delivery to the end user.
The Stata Journal 3(3): 245-269.
Download from The Stata Journal website

Also see

Manual: [P] preserve, [D] encode, [D] label, [R] ssc

On-line: help for preserve, restore, encode, decode, label, ssc

help for ingap, listtab, listtex, sencode, sdecode, msdecode if installed