*! version 3.0.0 06 Jan 2017

Title

combival -- combines values of a categorical variable over observation groups

Syntax

combival
[varname]
[,
options]

where varname is an existing categorical variable in the working file. This so called source variable may be type numeric or type string.

Main
group(varlist) Required. Defines the group for which the values of the source variable are to be combined.

md(str) Mode option, where str is one of n|s|m. Default is n for numeric and s for string source variables.

nchar(#) Number of characters being used from the value labels or the string values, respectively, of the source variable. Default is 5.

from(#) Position within the label string or the string value, respectively, from where nchar begins. Default is 1.

vlab(str) List of values and labels of the source variable used for the combination variables. If not specified, all levels of the source variable are used, except for missing values.

Description

combival is a low-threshold tool for data exploration before applying more sophisticated statistical procedures. It combines values of a
categorical variable over groups of observations defined by the mandatory option gr(), thus showing in each observation the range of a characteristic
within the group.

Optionally, a numeric and/or a string combination variable is generated, indicating all or selected levels
of the source variable within the group.

Tested with a dataset of about 35 million observations, combival is proven to work properly with very large data sets. A feature that measures the runtime of the program is included.

The actual version 3.0.0 is adapted to work with Stata 14, and is tested to work with previous versions from Stata 11.2

Options

Main

group(varlist) Variable(s) discriminating the groups for which all or selected levels of the source variable will be combined - quite analoguous to the
"by varlist: " specification of the byable commands in Stata

md(str) Mode option, where str is one of n|s|m.

md(n) generates both a numeric and a string combination variable, with unique entries of each involved level of the source variable. Available only with numeric source variables.

md(s) generates a string combination variable, with unique entries of each involved level of the source variable.

md(m) generates a string combination variable, with multiple entries of each involved level of the source variable.

Defaults are md(n) for a numerical source variable and md(s) for a string source variable.

nchar(#) Number of characters to extract from the value labels of the numeric source variable or the values of the string source variable. The default is 5.

from(#) Position from where to start the extraction of the nchar(#) characters. The default is 1.

vlab(str) Where str is a list of values and corresponding short labels of the source variable that are to be included into the combination variables. Requirements are:

- Values and short labels are to be entered alternately, separated by a blank.

- Labels must not be framed by quotation marks.

- The values have to be existing levels of the source variable, while the short labels may be assigned newly by vlab().

If vlab() is not specified, all levels of the source variable are included, except for missing values. It is not possible to include missing values by specifying them via vlab(). They have to be recoded before executing combival if
missing values are to be included.

Remarks

Remarks are presented under the following headings:

Introduction
Details on the construction of the combination variables
Typical use cases for combival
Recommendations on the use of combival
Example 1
Example 2
Example 3

Introduction

combival is designed for exploratory and data preparation purposes. It creates variables that combine the levels of a source variable within a defined
group of observations. In the terminology of Hierarchical Linear Modeling: combival generates level n+1-variables for level n-units from a level
n-variable (see SSCC knowledge base: Stata for Researchers: Hierarchical Data).

Thus, information that is spread over several observations is compiled and displayed for each observation of the group.
combival needs a hierarchical data structure in long form, meaning that an observation in the data set is a level one unit. The level one units
have to be groupable into higher level units. This applies if there is a variable or variable list that can be
used as an identifier for the higher level units. Typical examples for such a data structure are persons in households, persons in enterprises in countries,
spells of a person, spells of a person in time spans, or panel data.

Depending on the specification of the mode option md() and on the type of the source variable, combival creates a numeric and/or a string combination variable. To ease the interpretation by humans, the values of the numeric combination
variable are labelled automatically.

Details on the construction of the combination variables

The combination variables will automatically be named combi (numeric variable) and combistr (string variable). If one of these variables already exists, the newly created variables will be named combi1 and combistr1, or,
generalized, combi#+1 and combistr#+1 if one of combi# or combistr# already exists. The labels of the new variables indicate the mode (unique or multiple), the source variable and the grouping variables. Thus you
may generate different versions of combination variables in the same session without having to care about the variable names.

Depending on the mode option md() and on the type of the source variable, combival creates a numeric and/or a string combination variable. The string combination variable may contain unique or multiple entries of the levels of the
source variable over the groups.

The numeric combination variable

The numeric combination variable combi is generated via a copy of the source variable. This copy has as many levels as the source variable without the missings, or as specified in the vlab() option. While the source variable might be
coded with negative integers or with gaps in the succession of the values, the copied variable is recoded as to have the values of the exponential function to basis 2. So if, for example, the source variable has the codes -2 -1 0 2 3 7 8, the
copy has the codes 1 2 4 8 16 32 64. Generalized, the copy will have the levels 2^n of n nonmissing levels or levels specified in the vlab() option of the source variable.

The reason for replacing the original values with the values of the 2^n function is, that combi can then simply be constructed by adding up the values of the copied source variable. Each value of combi indicates unambiguously a specific
combination of the (copied) source variable.

For example, the value 10 of combi can only be a combination of 2 and 8. There is no other way to combine the values of the 2^n function that results in 10. However, this holds only if a value of the 2^n function may be included only once.
Otherwise, more than one combination can result in a sum of 10, like 1+1+8 or 1+1+2+2+4.

This is why it is not possible to create the numeric combination variable combi with the md(m) ("multiple") option.

For usability reasons, combival labels the values of combi. For this, nchar() characters, starting with position from(), are taken from the value labels of the source variable. If from() exceeds the length of the value
labels of the source variable, the value labels of combi will be empty. If the source variable has no value labels, the labels of combi are generated from the source variable's values.

With Stata, value labels may only be applied to numeric variables up to data type 'long'. Because of this, the numeric combination variable can only be created from source variables that have up to 28 levels. If the source variable has more
levels, the mode option is automatically set to md(s), and only a string combination variable is generated.

The string combination variable

The string combination variable combistr is generated by collecting between 1 and 10 characters - depending on the nchar() and from() options - from:

- the value labels, if the source variable is a labelled numeric variable

- the values converted into a string, if the source variable is an unlabelled numeric variable

- the values, if the source variable is a string variable

As with the numeric combination variable, either all levels except the missing values, or the levels specified with the vlab() option, enter the combination variable.

Typical use cases for combival

A main application area is the exploration of spell data. combival can be used to display the parallel (isochronic) spell types of split spell data
(see: splitit.ado, also written by the authors), making it easy to identify and examine concurrencies of spell types. Also, with combival,
compiling a priority list of spell types can be supported by empirical evidence of the spell type parallelities in the data instead of applying sheer
theoretical priority considerations.

combival can also be used to display the spelltype combinations within whole life courses. For this, the data does not have to be split.

Another application area is the exploration of characteristics, such as nationalities or party preferences, within higher-level units,
such as households or enterprises.

combival is most useful for exploring categorical characteristics that have more than four or five levels and different distribution patterns
for different population groups, or with changing distribution patterns over time.

Recommendations on the use of combival

Numeric or string combination variable?

With numeric variables a wider range of descriptive and statistical operations is available. Apart from this, the numerical combination variable
is more useful for selecting certain combinations.

In contrast, the string combination variable ist more useful for selecting combinations having a certain component.

Recommendations on the (short) labels used to generate the combination variables

While the nchar() and from() options allow for influencing the characters used as short labels, this will often not be sufficient to create suitable short labels. Short labels are suitable if they are short, self-explanatory, and not contained in
each other.

There are two ways to influence the short labels beyond the nchar() and from() options: create a new label set for the source variable or use
the vlab() option. The latter will be appropriate if a) the source variable has not too many levels or
b) you want to combine only selected levels of the source variable and therefore are using the vlab() option anyway.

How to display the combination variables?

The labels of the numeric combination variable or the values of the string combination variable might be pretty long, depending on the number of levels of your source variable. Mostly it will be more practical to display the frequencies of the
combination variables using fre.ado instead of tab1 (if not installed, use ssc install fre to install this command).

It is also advisable to increase the linesize of the output.

Example 1

combine parallel spells in order to explore the activity "being a housewife/househusband" (to use with split data, see splitit.ado)

. use testdata1_combival, clear
(testdata1_combival.dta)

. combival sptype, gr(persno begin_split) nc(9) fr(5)

The above command says: combine isochronic activities (exactly concurrent activities, marked by same values in gr()-varlist) of persons. Use nine characters of the value labels of sptype (type of activity) from position 5 onwards. As md() option
is not specified, md(n) is executed: a numeric and a string combination variable is generated.

. set linesize 200

. fre combistr if strpos(combistr, "House") > 0, nowrap all width(140)
(see user written program fre.ado)

Using Stata 14 you have to replace strpos() in the above command with ustrpos().

combistr -- uComb_sptype over persno begin_split

-+

| Freq. Percent Valid Cum.

-+

Valid Full-Time+Housewif | 12 5.04 5.04 5.04
Housewif | 17 7.14 7.14 12.18
Housewif+Minijob | 39 16.39 16.39 28.57
Maternity+Housewif | 18 7.56 7.56 36.13
Maternity+Housewif+Minijob | 6 2.52 2.52 38.66
Part-Time+Housewif | 56 23.53 23.53 62.18
Part-Time+Housewif+Minijob | 12 5.04 5.04 67.23
Part-Time+Maternity+Housewif | 3 1.26 1.26 68.49
Part-Time+Retired+Housewif | 25 10.50 10.50 78.99
Retired+Housewif | 28 11.76 11.76 90.76
Retired+Housewif+Minijob | 16 6.72 6.72 97.48
Unemploye+Housewif | 6 2.52 2.52 100.00
Total | 238 100.00 100.00

-+

Obviously, the meaning of being a housewife/househusband depends on concurrent activities. With the help of combival you can distinguish different
combinations of activities and treat them suitably.

Please note: the table shows frequencies of spell splits, not frequencies of persons.

Example 2

Explore the composition of households. As an example, the relation of the household members to the head of the household is displayed.

. use testdata2_combival, clear
(testdata2_combival.dta)

. combival reltohead, gr(hhid) md(m) nc(6)

The above command says: combine the relation to the head of the household. Show multiple occurrences of the same relation type and display the first 6 characters of the value labels of reltohead.

. set linesize 200

. fre combistr, nowrap all width(140)
(see user written program fre.ado)

combistr -- mComb_reltohead over hhid

-+

| Freq. Percent Valid Cum.

-+

Valid HHEADf+CHLD | 4 3.08 3.08 3.08
HHEADf+CHLD+CHLD | 3 2.31 2.31 5.38
HHEADf+PRTNm | 4 3.08 3.08 8.46
HHEADf+PRTNm+CHLD | 15 11.54 11.54 20.00
HHEADf+PRTNm+CHLD+CHLD | 20 15.38 15.38 35.38
HHEADf+PRTNm+CHLD+CHLD+CHLD | 20 15.38 15.38 50.77
HHEADm+CHLD | 2 1.54 1.54 52.31
HHEADm+PRTNf | 14 10.77 10.77 63.08
HHEADm+PRTNf+CHLD | 3 2.31 2.31 65.38
HHEADm+PRTNf+CHLD+CHLD | 32 24.62 24.62 90.00
HHEADm+PRTNf+CHLD+CHLD+CHLD | 10 7.69 7.69 97.69
HHEADm+PRTNm+CHLD | 3 2.31 2.31 100.00
Total | 130 100.00 100.00

-+

Due to option md(m) (multiple entries), combi is not generated, and combistr distuingishes for the number of persons having a certain relation to the head of the household (showing here as multiple occurences of "CHLD" within the
string).

Please note: the table shows frequencies of persons, not frequencies of households.

You can identify persons in single parent households simply using the condition
...if strpos(combistr, "CHLD") > 0 & strpos(combistr, "PRTN") == 0.

Using Stata 14 you have to replace strpos() in the above command with ustrpos().

Example 3

Explore the composition of households: Selected nationalities are combined.

. use testdata2_combival, clear
(testdata2_combival.dta)

. combival nat, gr(hhid) vl(1 GER 2 TUR 5 RUS)

The above command says: combine nationalities over households, but use only the levels German, Turkish, and Russian (omitted are the nationalities Romanian, Italian, Polish, Spanish). Apply the short labels GER, TUR, and RUS.

. bysort hhid: gen hh = cond(_n==1, 1, 0)
construct a marker for households

. fre combi if hh==1
(see user written program fre.ado)

combi -- uComb_nat over hhid

-+

| Freq. Percent Valid Cum.

-+

Valid 1 GER | 16 41.03 41.03 41.03
2 TUR | 6 15.38 15.38 56.41
3 GER+TUR | 8 20.51 20.51 76.92
5 GER+RUS | 9 23.08 23.08 100.00
Total | 39 100.00 100.00

-+

To show the same thing for a string variable, type:

. decode nat, generate(natstr) // create a string variable from nat
. combival natstr, gr(hhid) vl(German DE Turkish TR Russian RUS)
. fre combistr1 if hh==1

combistr1 -- uComb_natstr over hhid

-+

| Freq. Percent Valid Cum.

-+

Valid DE | 16 41.03 41.03 41.03
DE+RUS | 9 23.08 23.08 64.10
DE+TR | 8 20.51 20.51 84.62
TR | 6 15.38 15.38 100.00
Total | 39 100.00 100.00

-+

Note: the tables show frequencies of households, not of persons.

As md(m) for multiple entries was not specified, variables combi and combistr show only the occurrences of nationalities within households, but not how many persons have one of the nationalities within a household.

If a household in the test data had consisted completely of persons with omitted nationalities, 0-values had shown in the table (or missing values, for frequency tables of combistr#).

Authors

Klaudia Erhardt, SOEP, DIW Berlin
Email kerhardt@diw.de

Ralf Kuenster, NEPS, WZB Berlin
Email ralf.kuenster@wzb.eu

Edition: V.3.0.0, January 2017