Package 'acsmoe'

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

data	A data frame containing ACS estimate and MOE columns.
group_var	Name of the grouping column, supplied as a single string.
value_cols	Character vector of estimate column names to aggregate.
moe_cols	Character vector of MOE column names paired with value_cols.
cov_strategy	Covariance strategy: "zero", "supplied", or "constant".
cov_value	For "constant", a scalar correlation. For "supplied", a named list of full covariance matrices keyed by estimate column.
conf	Confidence level associated with input and output MOEs.

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

estimate	Numeric estimate.
moe	Numeric MOE.
conf	Confidence level associated with moe.

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

estimate1	First estimate.
moe1	MOE for estimate1.
estimate2	Second estimate.
moe2	MOE for estimate2.
cov	Covariance between the two estimates on the standard-error scale.
conf	Confidence level associated with input and output MOEs.

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

estimates	Numeric estimates.
moes	Numeric MOEs corresponding to estimates.
weights	Numeric weights for the linear combination.
cov	Optional covariance matrix on the standard-error scale. A scalar is interpreted as a common off-diagonal covariance.
conf	Confidence level associated with input and output MOEs.

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

estimate1	First estimate.
moe1	MOE for estimate1.
estimate2	Second estimate.
moe2	MOE for estimate2.
cov	Covariance between the two estimates on the standard-error scale.
conf	Confidence level associated with input and output MOEs.

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

num	Numerator estimate.
num_moe	Numerator MOE.
denom	Denominator estimate.
denom_moe	Denominator MOE.
cov	Numerator-denominator covariance on the standard-error scale.
conf	Confidence level associated with input and output MOEs.

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

num	Numerator estimate.
num_moe	Numerator MOE.
denom	Denominator estimate.
denom_moe	Denominator MOE.
cov	Numerator-denominator covariance on the standard-error scale.
conf	Confidence level associated with input and output MOEs.

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

estimate	Numeric estimate.
moe	Numeric MOE.
conf	Confidence level associated with moe.
thresholds	Named numeric vector with reliable and caveat CV thresholds. Defaults of 0.12 and 0.40 reflect commonly used applied conventions (e.g., reliable below 12% CV, unreliable above 40% CV); these are not a Census Bureau standard and should be adjusted to your domain, agency guidance, or project-specific quality standard.

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

estimates	Numeric estimates.
moes	Numeric MOEs corresponding to estimates.
cov	Optional covariance matrix on the standard-error scale.
n_sims	Number of Monte Carlo simulations.
dist	Distribution assumption: "normal" or "censored_normal". The censored variant replaces below-zero draws with zero, matching the convention used in Napierala & Denton (2017) for ACS counts.
conf	Confidence level associated with input MOEs.

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

estimates	Numeric estimates.
moes	Numeric MOEs corresponding to estimates.
fn	Function applied to each simulated row.
cov	Optional covariance matrix on the standard-error scale.
n_sims	Number of Monte Carlo simulations.
dist	Distribution assumption: "normal" or "censored_normal". The censored variant replaces below-zero draws with zero, matching the convention used in Napierala & Denton (2017) for ACS counts.
conf	Confidence level associated with input MOEs.
summary	Summary to return: "mean", "median", or "ci".
point	For summary = "ci", point estimate to report alongside the percentile interval: "mean" (default) or "median".

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

estimates	Numeric estimates to sum.
moes	Numeric MOEs corresponding to estimates.
cov	Optional covariance matrix on the standard-error scale. A scalar is interpreted as a common off-diagonal covariance.
conf	Confidence level associated with input and output MOEs.

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

estimate	Numeric estimate.
moe	Numeric margin of error.
conf_in	Confidence level associated with moe.
conf_out	Desired confidence level for the returned interval.

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

moe	Numeric margin of error.
conf	Confidence level associated with moe.

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

se	Numeric standard error.
conf	Desired confidence level.

Value

Numeric margin of error.

Examples

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

---