Package {acsmoe}

acsmoe: Propagate Uncertainty for ACS Tabular Estimates

Description

acsmoe provides utilities for American Community Survey workflows that already have published estimates and margins of error. It complements tidycensus by matching the standard zero-covariance ACS MOE formulas by default while allowing users to supply covariance structures when available.

Details

The package does not download ACS data, estimate variance from microdata, or implement regionalization. Use tidycensus for data access and survey or srvyr for microdata/replicate-weight workflows.

Core references include the U.S. Census Bureau ACS handbook guidance on derived estimates, Walker and Herman's tidycensus package, and the ACS uncertainty literature by Spielman, Folch, Nagle, Arribas-Bel, and Koschinsky. See the README and vignettes for full references.

Output shape

Propagation helpers (acs_sum, acs_diff, acs_ratio, acs_prop, acs_product, acs_linear) return a data frame with columns estimate, moe, and se. moe_ci() returns estimate, lower, upper, moe. acs_simulate() returns a numeric matrix of draws. acs_simulate_fn() returns either ⁠(estimate, se)⁠ for summary = "mean"/"median", or ⁠(estimate, lower, upper)⁠ for summary = "ci". acs_cv() and acs_reliability() return atomic vectors.

Author(s)

Maintainer: Dmitry Shkolnik dmitry@dshkol.com

See Also

Useful links:

• https://dshkol.github.io/acsmoe/

• https://github.com/dshkol/acsmoe

• Report bugs at https://github.com/dshkol/acsmoe/issues

Aggregate paired ACS estimate and MOE columns by group.

Description

Aggregate paired ACS estimate and MOE columns by group.

Usage

acs_aggregate(
  data,
  group_var,
  value_cols,
  moe_cols,
  cov_strategy = c("zero", "supplied", "constant"),
  cov_value = 0,
  conf = 0.9
)

Arguments

Details

cov_strategy = "constant" interprets cov_value as a correlation, not a covariance. This differs from scalar cov arguments in core propagation functions, where a scalar means an off-diagonal covariance on the standard-error scale.

Output rows are ordered by first appearance of each group level in data, not alphabetically.

Value

A data frame with one row per group and aggregated estimate/MOE columns.

Examples

tracts <- data.frame(
  region = c("north", "north", "south", "south"),
  pop = c(1000, 1200, 900, 1100),
  pop_moe = c(120, 140, 100, 130)
)
acs_aggregate(tracts, "region", "pop", "pop_moe")
acs_aggregate(tracts, "region", "pop", "pop_moe",
              cov_strategy = "constant", cov_value = 0.25)

Calculate coefficient of variation from an ACS estimate and MOE.

Description

Calculate coefficient of variation from an ACS estimate and MOE.

Usage

acs_cv(estimate, moe, conf = 0.9)

Arguments

Value

Numeric coefficient of variation, using standard error divided by absolute estimate.

Examples

acs_cv(estimate = 1000, moe = 80)
acs_cv(estimate = c(1000, 100, 0), moe = c(80, 60, 5))

Propagate ACS uncertainty for a difference.

Description

Propagate ACS uncertainty for a difference.

Usage

acs_diff(estimate1, moe1, estimate2, moe2, cov = 0, conf = 0.9)

Arguments

Value

A data frame with estimate, moe, and se.

Examples

acs_diff(100, 10, 40, 8)
acs_diff(100, 10, 40, 8, cov = 5)

Propagate ACS uncertainty for a linear combination.

Description

Propagate ACS uncertainty for a linear combination.

Usage

acs_linear(estimates, moes, weights, cov = NULL, conf = 0.9)

Arguments

Details

A scalar cov is a covariance, not a correlation. In contrast, acs_aggregate(cov_strategy = "constant") accepts a scalar correlation because that interface derives covariances from group-specific MOEs.

Value

A one-row data frame with estimate, moe, and se.

Examples

acs_linear(c(100, 50, 25), c(10, 8, 6), weights = c(2, -1, 0.5))

Propagate ACS uncertainty for a product.

Description

Propagate ACS uncertainty for a product.

Usage

acs_product(estimate1, moe1, estimate2, moe2, cov = 0, conf = 0.9)

Arguments

Value

A data frame with estimate, moe, and se.

Examples

acs_product(10, 2, 50, 5)

Propagate ACS uncertainty for a proportion.

Description

Propagate ACS uncertainty for a proportion.

Usage

acs_prop(num, num_moe, denom, denom_moe, cov = 0, conf = 0.9)

Arguments

Details

This function follows the Census approximation used for proportions where the numerator is a subset of the denominator. It does not validate that num <= denom; behavior for non-nested ratios is formulaic rather than a claim that the inputs define a valid proportion.

Value

A data frame with estimate, moe, and se.

Examples

acs_prop(num = 10, num_moe = 2, denom = 50, denom_moe = 5)

Propagate ACS uncertainty for a ratio.

Description

Propagate ACS uncertainty for a ratio.

Usage

acs_ratio(num, num_moe, denom, denom_moe, cov = 0, conf = 0.9)

Arguments

Value

A data frame with estimate, moe, and se.

Examples

acs_ratio(num = 10, num_moe = 2, denom = 50, denom_moe = 5)

Categorize ACS estimate reliability by CV thresholds.

Description

Categorize ACS estimate reliability by CV thresholds.

Usage

acs_reliability(
  estimate,
  moe,
  conf = 0.9,
  thresholds = c(reliable = 0.12, caveat = 0.4)
)

Arguments

Value

Ordered factor with levels reliable, caveat, unreliable.

Examples

acs_reliability(estimate = 1000, moe = 80)
acs_reliability(estimate = c(1000, 200, 50), moe = c(80, 60, 50))

Simulate ACS estimates from published estimates and MOEs.

Description

Simulate ACS estimates from published estimates and MOEs.

Usage

acs_simulate(
  estimates,
  moes,
  cov = NULL,
  n_sims = 1000,
  dist = c("normal", "censored_normal"),
  conf = 0.9
)

Arguments

Value

A numeric matrix of simulated draws.

Examples

set.seed(1)
acs_simulate(c(x = 100, y = 50), c(10, 5), n_sims = 5)

Simulate a derived ACS statistic.

Description

Simulate a derived ACS statistic.

Usage

acs_simulate_fn(
  estimates,
  moes,
  fn,
  cov = NULL,
  n_sims = 1000,
  dist = c("normal", "censored_normal"),
  conf = 0.9,
  summary = c("mean", "median", "ci"),
  point = c("mean", "median")
)

Arguments

Details

For summary = "ci", the returned interval is the central conf-level percentile interval of the simulated derived values. The reported estimate is the chosen point summary of those values.

Value

A data frame summarizing the simulated derived statistic.

Examples

set.seed(1)
acs_simulate_fn(c(100, 50), c(10, 5), fn = sum, n_sims = 500)
set.seed(1)
acs_simulate_fn(c(100, 50), c(10, 5), fn = sum, n_sims = 500,
                summary = "ci", conf = 0.90)

Propagate ACS uncertainty for a sum.

Description

Propagate ACS uncertainty for a sum.

Usage

acs_sum(estimates, moes, cov = NULL, conf = 0.9)

Arguments

Details

A scalar cov is a covariance, not a correlation. In contrast, acs_aggregate(cov_strategy = "constant") accepts a scalar correlation because that interface derives covariances from group-specific MOEs.

Value

A one-row data frame with estimate, moe, and se.

Examples

acs_sum(c(100, 50, 25), c(12, 8, 6))
acs_sum(c(100, 50), c(12, 8), cov = 5)

Convert an ACS MOE to lower and upper confidence bounds.

Description

Convert an ACS MOE to lower and upper confidence bounds.

Usage

moe_ci(estimate, moe, conf_in = 0.9, conf_out = 0.95)

Arguments

Value

A data frame with estimate, lower, upper, and moe.

Examples

moe_ci(estimate = 100, moe = 10)
moe_ci(estimate = c(100, 200), moe = c(10, 25), conf_out = 0.99)

Convert an ACS margin of error to a standard error.

Description

Convert an ACS margin of error to a standard error.

Usage

moe_to_se(moe, conf = 0.9)

Arguments

Value

Numeric standard error.

Examples

moe_to_se(c(10, 25, 100))
moe_to_se(10, conf = 0.95)

Convert a standard error to an ACS-style margin of error.

Description

Convert a standard error to an ACS-style margin of error.

Usage

se_to_moe(se, conf = 0.9)

Arguments

Value

Numeric margin of error.

Examples

se_to_moe(c(6, 15, 60))
se_to_moe(6, conf = 0.95)