Package {outcomerate}

Version:	1.1.0
Title:	AAPOR Survey Outcome Rates
Description:	Standardized survey outcome rate functions, including the response rate, contact rate, cooperation rate, and refusal rate. These outcome rates allow survey researchers to measure the quality of survey data using definitions published by the American Association for Public Opinion Research (AAPOR). For details on these standards, see AAPOR (2023) https://aapor.org/wp-content/uploads/2024/03/Standards-Definitions-10th-edition.pdf.
License:	CC0
Encoding:	UTF-8
LazyData:	true
ByteCompile:	true
RoxygenNote:	7.3.3
Depends:	R (≥ 2.10)
Suggests:	dplyr, forcats, ggplot2, knitr, testthat, tidyr, covr, rmarkdown, spelling, stringr
Imports:	Rdpack (≥ 0.7), stats
RdMacros:	Rdpack
Language:	en-US
URL:	https://docs.ropensci.org/outcomerate/, https://github.com/ropensci/outcomerate
BugReports:	https://github.com/ropensci/outcomerate/issues
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-09-01 01:44:51 UTC; raf
Author:	Rafael Pilliard Hellwig [aut, cre], Carl Ganz [rev], Neal Richardson [rev]
Maintainer:	Rafael Pilliard Hellwig <rafael.taph@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-01 07:10:03 UTC

Survey Eligibility Rate

Description

Provides an estimate for the proportion of cases of unknown eligibility that are eligible, as described by (Valliant et al. 2013). The rate is typically (but not necessarily) calculated on the screener data or other sources depending on the type of survey, and approaches to calculating 'e' may therefore differ from one survey to the next.

Usage

eligibility_rate(x, weight = NULL)

Arguments

Details

The present proportional-allocation implementation follows the default used in the Excel-based AAPOR Outcome Rate Calculator (Version 5.1, April 2023), on the basis of known ineligibles being coded as "NE". It is one accepted estimator of e; researchers should use better design-specific information when available. This function returns one scalar estimate. Separate estimates can be supplied directly to outcomerate() as a named vector such as c(UH = 0.4, UR = 0.7, UO = 0.2); they cannot be inferred from the package's aggregate NE count alone. See (Amaya et al. 2025) for category-specific estimation guidance.

The eligibility rate (ELR) is defined as

• ELR = (I + P + R + NC + O) / (I + P + R + NC + O + NE)

Value

A named numeric vector of length one containing the estimated eligibility rate, named ELR.

References

The American Association for Public Opinion Research (2023). “Standard Definitions: Final Dispositions of Case Codes and Outcome Rates for Surveys.” https://aapor.org/wp-content/uploads/2024/03/Standards-Definitions-10th-edition.pdf. Amaya A, Marlar J, English N (2025). “Estimating the Eligibility Status of Cases with Unknown Eligibility.” American Association for Public Opinion Research. https://aapor.org/wp-content/uploads/2025/10/Estimating-the-Eligibility-Status-of-Cases-with-Unknown-Eligibility_FINAL.pdf.

Valliant R, Dever JA, Kreuter F (2013). Practical Tools for Designing and Weighting Survey Samples, Statistics for Social and Behavioral Sciences. Springer New York.

See Also

outcomerate

Examples

# load the outcomerate package
library(outcomerate)

# Create a vector of survey dispositions
#
# I  = Complete interview
# P  = Partial interview
# R  = Refusal and break-off
# NC = Non-contact
# O  = Other eligible non-interview (2.30, 2.90)
# UH = Unknown if household/occupied housing unit (3.10)
# UR = Unknown if sampled unit is eligible/housing unit contains an eligible
#      respondent (3.20)
# UO = Unknown, other (3.90)
# NE = Not eligible (4.0)
x <- c("I", "P", "I", "NE", "NC", "UH", "I", "R", "UR", "UO", "I", "O",
       "P", "I")

# estimate the eligibility rate
eligibility_rate(x)

# calculate a weighted rate using illustrative base weights
w <- seq(0.5, 1.8, length.out = length(x))
eligibility_rate(x, weight = w)

# alternatively, provide input as counts
freq <- c(I = 6, P = 2, NC = 3, NE = 1)
eligibility_rate(freq)

outcomerate Formula Matrix (Internal Data)

Description

The fmat object is the internal dataset used by the outcomerate package. It holds all definitions for the outcome rates. With the exception of location rates, these are taken from the AAPOR Standard Definitions (2023).

Details

The data is a 3-dimensional binary array consisting of:

• outcome: codes I, P, R, NC, O, UH, UR, UO, eUH, eUR, eUO, and NE

• rate: the shorthand name for the rate (e.g. RR1)

• side: numerator (NUM) and denominator (DEN)

Given these three dimensions, each outcome rate can be defined as a rational number (i.e. a fraction) consisting of a summation of frequencies of outcome codes (where the matrix entries are nonzero).

The input parameters given by the user are I, P, R, NC, O, UH, UR, UO, and NE. The scalar or category-specific values in e are multiplied by UH, UR, and UO internally to produce the estimated eligible counts eUH, eUR, and eUO.

The reason for this implementation is:

a) It conforms to a DRY (don't repeat yourself) philosophy by holding all definitions in one place. These definitions can be used as upstream inputs to functions/test suites requiring them.

b) It makes it easier to use intermediate steps in the formula calculations. For instance, it may be of use to a researchers to want to obtain the numerator/denominators of calculations, instead of only the output.

c) it makes it easy to compare the output

d) It is easier to maintain

References

https://aapor.org/wp-content/uploads/2024/03/Standards-Definitions-10th-edition.pdf

Examples

fmat <- outcomerate:::fmat

# Print the dimensions
dimnames(fmat)

# Say we want to know the definition of Response Rate 2, RR2. We see
# below that the numerator (NUM) column is defined by the entries with a 1,
# or (I + P). Likewise, the denominator (DEN) is defined as
# (I + P + R + NC + O + UH + UR + UO)
fmat[, "RR2", ]


# To use linear algebra, we define a zero-one numerator matrix 'N'
# and a zero-one denominator matrix 'D'. Our count of disposition codes
# is given here manually as 'x' (in the same order as N and D).
N = fmat[ , , 1]
D = fmat[ , , 2]
x <- c(I = 5, P = 2, R = 1, NC = 7, O = 3,
      UH = 4, UR = 2, UO = 8, NE = 1,
      eUH = 3, eUR = 1.5, eUO = 6)

# Return all rates
(x %*% N) / (x %*% D)


# The same thing can be achieved with the apply family of functions
numden <- apply(x * fmat, 2:3, sum)
numden[, 1] / numden[, 2]

middleearth Dataset

Description

middlearth is a toy dataset consisting of 1691 fake survey interviews conducted in J.R.R. Tolkien's fictional world of Middle Earth.

Details

Variables contained in the data:

• code: one of the outcome codes I, P, R, NC, O, UH, UO, and NE

• outcome: A human-interpretable label for the code variable

• researcher: An identifier for the researcher conducting the interview

• region: The region of the respondent (one of five)

• Q1: A hypothetical binary research question posed to respondents

• Q2: A hypothetical continuous scale question posed to respondents

• day: The day the interview took place (1 being the first day of fieldwork)

• race: The race of the respondent in middle earth (Dwarf, Elf, Hobbit, Man, or Wizard)

• svywt: The survey weight (inverse probability of selection)

AAPOR Survey Outcome Rates

Description

Provides standardized outcome rates for surveys, primarily as defined by the American Association for Public Opinion Research (AAPOR). Details can be found in the Standard Definitions manual (The American Association for Public Opinion Research 2023).

Usage

outcomerate(x, e = NULL, rate = NULL, weight = NULL, return_nd = FALSE)

Arguments

Details

Survey and public opinion research often categorizes interview attempts for a survey according to a set of outcome codes as follows:

• I = Complete interview

• P = Partial interview

• R = Refusal and break-off

• NC = Non-contact

• O = Other eligible non-interview (2.30, 2.90)

• UH = Unknown if household/occupied housing unit (3.10)

• UR = Unknown if sampled unit is eligible/housing unit contains an eligible respondent (3.20)

• UO = Unknown, other (3.90)

• NE = Not eligible (4.0)

UR is the 10th-edition aggregate symbol for 3.20, which the 9th edition included under UO. Legacy UO inputs remain supported. With a scalar e, moving a 3.20 case from UO to UR does not alter a rate. With category-specific estimates it can, so new 3.20 cases should be coded UR for standards conformance.

These high-level classes are used to calculate outcome rates that provide some measure of quality over the fieldwork. These outcome rates are defined here as follows:

The formulas below show the traditional scalar form e(UH + UR + UO). If e is supplied by category, that term is evaluated as e["UH"] * UH + e["UR"] * UR + e["UO"] * UO. Each value is the conditional probability that a case in that unknown category is ultimately eligible for the survey, following the companion guidance in (Amaya et al. 2025). Calculate e separately for each frame. One vector applies to the cases in one call; combining frames requires a scientifically justified aggregation. Other design components, modes, or phases may also require separate estimates when their mechanisms differ. Document the scientific basis for every estimate.

AAPOR Response Rate

The proportion of sampled cases that yield a complete or partial interview, depending on the selected definition.

• RR1 = I / ((I + P) + (R + NC + O) + (UH + UR + UO))

• RR2 = (I + P) / ((I + P) + (R + NC + O) + (UH + UR + UO))

• RR3 = I / ((I + P) + (R + NC + O) + e(UH + UR + UO))

• RR4 = (I + P) / ((I + P) + (R + NC + O) + e(UH + UR + UO))

• RR5 = I / ((I + P) + (R + NC + O))

• RR6 = (I + P) / ((I + P) + (R + NC + O))

RR5 and RR6 are appropriate only when no unknown cases are eligible or no cases have unknown eligibility.

AAPOR Cooperation Rates

The proportion of all interviewed cases among eligible units ever contacted. These printed formulas are AAPOR's household-level rates.

• COOP1 = I / ((I + P) + R + O)

• COOP2 = (I + P) / ((I + P) + R + O)

• COOP3 = I / ((I + P) + R)

• COOP4 = (I + P) / ((I + P) + R)

AAPOR Refusal Rates

The proportion of the sample that refuses to participate in the survey.

• REF1 = R / ((I + P) + (R + NC + O) + (UH + UR + UO))

• REF2 = R / ((I + P) + (R + NC + O) + e(UH + UR + UO))

• REF3 = R / ((I + P) + (R + NC + O))

As with RR5 and RR6, excluding unknown cases from REF3 must be justified by the study's actual eligibility situation.

AAPOR Contact Rates

The proportion of cases in which a responsible member of the housing unit is reached. These printed formulas are AAPOR's household-level rates.

• CON1 = ((I + P) + (R + O)) / ((I + P) + (R + NC + O) + (UH + UR + UO))

• CON2 = ((I + P) + (R + O)) / ((I + P) + (R + NC + O) + e(UH + UR + UO))

• CON3 = ((I + P) + (R + O)) / ((I + P) + (R + NC + O))

Location Rate

The proportion of cases that could be located for an interview.

The location rate is not defined in AAPOR's Standards, but can be found in (Valliant et al. 2013). Note: depending on how the located cases are encoded, this may or may not be the correct formula.

• LOC1 = ((I + P) + (R + O + NC)) / ((I + P) + (R + NC + O) + (UH + UR + UO))

• LOC2 = ((I + P) + (R + O + NC)) / ((I + P) + (R + NC + O) + e(UH + UR + UO))

Value

If return_nd = FALSE, a named numeric vector containing the requested outcome rates. If return_nd = TRUE, a numeric matrix with one row per requested rate and columns NUM and DEN containing its numerator and denominator. Names for weighted rates have a w suffix.

References

Amaya A, Marlar J, English N (2025). “Estimating the Eligibility Status of Cases with Unknown Eligibility.” American Association for Public Opinion Research. https://aapor.org/wp-content/uploads/2025/10/Estimating-the-Eligibility-Status-of-Cases-with-Unknown-Eligibility_FINAL.pdf.

The American Association for Public Opinion Research (2023). “Standard Definitions: Final Dispositions of Case Codes and Outcome Rates for Surveys.” https://aapor.org/wp-content/uploads/2024/03/Standards-Definitions-10th-edition.pdf.

Valliant R, Dever JA, Kreuter F (2013). Practical Tools for Designing and Weighting Survey Samples, Statistics for Social and Behavioral Sciences. Springer New York.

Examples

# load the outcomerate package
library(outcomerate)

# Create a vector of survey dispositions
#
# I  = Complete interview
# P  = Partial interview
# R  = Refusal and break-off
# NC = Non-contact
# O  = Other eligible non-interview (2.30, 2.90)
# UH = Unknown if household/occupied housing unit (3.10)
# UR = Unknown if sampled unit is eligible/housing unit contains an eligible
#      respondent (3.20)
# UO = Unknown, other (3.90)
# NE = Not eligible (4.0)
x <- c("I", "P", "I", "NC", "UH", "I", "R", "NE",
      "UR", "UO", "I", "O", "P", "I")

# calculate all rates
elr <- eligibility_rate(x)
outcomerate(x, e = elr)

# use separate eligibility estimates for each unknown category
e_by_class <- c(UH = 0.4, UR = 0.7, UO = 0.2)
outcomerate(x, e = e_by_class, rate = c("RR3", "REF2", "CON2"))

# return only one rate
outcomerate(x, rate = "COOP1")

# calculate weighted rates using illustrative base weights
w <- seq(0.5, 1.8, length.out = length(x))
outcomerate(x, e = elr, weight = w)

# alternatively, provide input as counts
freq <- c(I = 6, P = 2, NC = 3, R = 1)
outcomerate(freq, e = elr)