Concepts

There are two important concepts that we need to learn and distinguish:

1. A data frame is a standard way of storing data in R. A data frame is rectangular data. Variables are in columns, observations are in rows. Example:

head(iris)
#>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> 1          5.1         3.5          1.4         0.2  setosa
#> 2          4.9         3.0          1.4         0.2  setosa
#> 3          4.7         3.2          1.3         0.2  setosa
#> 4          4.6         3.1          1.5         0.2  setosa
#> 5          5.0         3.6          1.4         0.2  setosa
#> 6          5.4         3.9          1.7         0.4  setosa

A data frame, in an of itself, cannot represent a complex survey. This is because, just by looking at a data frame, R does not know what the sampling weights are, what the strata are, etc. Even if the variables that represent the sampling weights, etc, are part of the data frame, just by looking at the data frame, R does not know which variable represents the weights or other survey design variables.

You can get a data frame into R in many different ways. If your data is currently in a comma-separated values (CSV) file, you can use read.csv(). If it’s in a SAS file, you can use a package like haven or importsurvey. If it’s already in R format, use readRDS(), and so on.

2. A survey object is an object that describes a survey. It tells R what the sampling weights are, what the strata are, and so on. A data frame can be converted into a survey object using the survey::svydesign() function; if a survey uses replicate weights, the survey::svrepdesign() function should be used.

Generally speaking, you only need to convert a data frame to a survey object once. After it has been converted, you can save it with saveRDS() (or similar). In the future, you can load it with readRDS(). You do not need to re-convert a data frame to a survey object every time.

NAMCS

Examples in this tutorial use a survey called the National Ambulatory Medical Care Survey (NAMCS) 2019 Public Use File (PUF). NAMCS is “an annual nationally representative sample survey of visits to non-federal office-based patient care physicians, excluding anesthesiologists, radiologists, and pathologists.” Note that the unit of observation is visits, not patients – this distinction is important since a single patient can make multiple visits.

The surveytable package comes with a data frame of selected variables from NAMCS, called namcs2019sv_df (sv = selected variables; df = data frame). The survey object of this survey is called namcs2019sv.

namcs2019sv is the object that we analyze. You really only need namcs2019sv. The reason that the package has namcs2019sv_df is to illustrate how to convert the data frame to the survey object.

More concepts

When importing data from another source, such as SAS or CSV, analysts should be aware of the standard way in which variables are handled in R.

• Specifically, categorical variables should be stored as factor.
• While true / false variables could be stored as factor as well, some programming tasks are easier if they are stored as logical.
• Unknown values should be stored as missing (NA). If a variable contains “special values”, such as a negative value indicating that the age is missing, those “special values” need to be converted to NA.

Variables in namcs2019sv_df are already stored correctly. Thus,

• AGER (patient’s age group) is a factor variable;
• PAYNOCHG (which indicates whether there was no charge for the physician visit) is a logical variable; and
• AGE (patient’s age in years) is a numeric variable.

library("surveytable")

class(namcs2019sv_df$AGER)
#> [1] "factor"
class(namcs2019sv_df$PAYNOCHG)
#> [1] "logical"
class(namcs2019sv_df$AGE)
#> [1] "numeric"

Create a survey object

As seen below, tables produced by surveytable are clearer if either the variable names themselves are descriptive, or if the variables have the "label" attribute that is descriptive. In namcs2019sv_df, all variables already have the "label" attribute set. For example, while the variable name AGE itself is not very descriptive, the variable does have a more descriptive "label" attribute:

attr(namcs2019sv_df$AGE, "label")
#> [1] "Patient age in years"

Documentation for the NAMCS survey provides the names of the survey design variables. Specifically, in NAMCS,

• cluster ID’s, also known as primary sampling units (PSU’s), are given in CPSUM;
• strata are given in CSTRATM; and
• sampling weights are given in PATWT.

Thus, the namcs2019sv_df data frame can be turned into a survey object as follows:

mysurvey = survey::svydesign(ids = ~ CPSUM
  , strata = ~ CSTRATM
  , weights = ~ PATWT
  , data = namcs2019sv_df)

Tables produced by surveytable are clearer if either the name of the survey object is descriptive, or if the object has the "label" attribute that is descriptive. Let’s set this attribute for mysurvey:

attr(mysurvey, "label") = "NAMCS 2019 PUF"

The mysurvey object should now be identical to namcs2019sv. Let’s verify this:

identical(namcs2019sv, mysurvey)
#> [1] TRUE

We have just successfully created a survey object from a data frame.

List variables

The var_list() function lists the variables in the survey. To avoid unintentionally listing all the variables in a survey, which can be many, the starting characters of variable names are specified. For example, to list the variables that start with the letters age, type:

var_list("age")

The table lists

• variable name;
• class, which is the type of variable; and
• variable label, which is the long name of the variable.

Common classes are factor (categorical variable), logical (yes / no variable), and numeric.

Entire population

Estimate the total count for the entire population using the total() command:

total()

Subsets or interactions

To create a table of AGER for each value of the variable SEX, type:

tab_subset("AGER", "SEX")

In addition to giving the long name of the variable being tabulated, the title of each table reflects the value of the subsetting variable (in this case, either Female or Male).

With the tab_subset() command, in each table (that is, in each subset), the percentages add up to 100%.

The tab_cross() function is similar – it crosses or interacts two variables and generates a table using this new variable. Thus, to create a table of the interaction of AGER and SEX, type:

tab_cross("AGER", "SEX")

While the estimated counts produced by tab_subset() and tab_cross() are the same, the percentages are different.

• With the tab_subset() command, within each table (that is, within each subset), the percentages add up to 100%.
• On the other hand, with tab_cross(), the percentages across the entire population add up to 100%.

Categorical variables

Consider the relationship between AGER an SPECCAT:

tab_subset("AGER", "SPECCAT", test = TRUE)

According to these tables, there is an association between physician specialty type and patient age. For instance, for patients under 15 years, there is a statistical difference between primary care physician specialty and medical care specialty. But for older patients, such as in the 45-64 age group, there is no statistical difference between the two specialty types.

As another example, consider the relationship between MRI and SPECCAT:

tab_subset("MRI", "SPECCAT", test = TRUE)

According to these tables, there is no statistical association between MRI and physician specialty. For each of the 3 specialty types, a minority of visits have MRI’s. For the visits with MRI’s, there was no statistical difference between specialty types.

As a general rule of thumb, since there is no statistical association between MRI and physician specialty, presenting this tabulation would not be particularly interesting, especially since the subsetting decreases the sample size and therefore also decreases the estimate reliability. Instead, it would generally make more sense to just tabulate MRI without subsetting by SPECCAT.

Numeric variables

The relationship between NUMMED and AGER:

tab_subset("NUMMED", "AGER", test = TRUE)

According to these tables, there is an association between the number of medications and age category. NUMMED is statistically similar for the “Under 15 years” and “15-24 years” AGER categories. It is statistically different for all other pairs of age categories.

Finally, let’s look at the relationship between NUMMED and SPECCAT:

tab_subset("NUMMED", "SPECCAT", test = TRUE)

According to these tables, there is no association between the number of medications and physician specialty type. NUMMED is statistically similar for all pairs of physician specialties.

As a general rule of thumb, since there is no statistical association between the number of medications and physician specialty, presenting this tabulation would not be particularly interesting, especially since the subsetting decreases the sample size and therefore also decreases the estimate reliability. Instead, it would generally make more sense to just tabulate NUMMED without subsetting by SPECCAT.

Categorical variables (single variable)

To test whether any pair of SPECCAT levels is statistically similar or different, type:

tab("SPECCAT", test = TRUE)

According to this, surgical and medical care specialties are statistically similar, and are statistically different from primary care.