Package 'ratecalib'

Calibrate directly from an Excel workbook

Description

One-step convenience: read the sample data and the target table from an Excel workbook, infer the grouping variables from the targets, and solve.

Usage

calibrate_from_excel(
  path,
  outcome,
  weight,
  data_sheet = 1,
  targets_sheet = "targets",
  group_vars = NULL,
  ...
)

Arguments

path	Path to an .xlsx file.
outcome	Name of the binary outcome column.
weight	Name of the initial weight column.
data_sheet	Sheet holding the sample data (default 1).
targets_sheet	Sheet holding the target table (default "targets").
group_vars	Optional grouping-variable names; inferred from the target table when NULL.
...	Further arguments passed to calibrate_pass_rates().

Value

An object of class pass_rate_calibration.

Examples

if (requireNamespace("openxlsx", quietly = TRUE)) {
  path <- tempfile(fileext = ".xlsx")
  d <- example_rate_data(300)
  tg <- make_rate_targets(groups = list(sex = c(M = 0.72, F = 0.68)))
  openxlsx::write.xlsx(list(data = d, targets = tg), path)
  fit <- calibrate_from_excel(path, "qualified", "initial_weight",
                              data_sheet = "data", targets_sheet = "targets")
  fit$target_check
}

---

Calibrate weights to multiple pass-rate targets

Description

Adjust initial positive weights so that an overall binary outcome rate and subgroup outcome rates approach or exactly match specified targets. The optimization is performed on demographic-cell-by-outcome aggregates.

Usage

calibrate_pass_rates(
  data,
  outcome,
  weight,
  group_vars,
  targets,
  lower = 0.25,
  upper = 4,
  mode = c("soft", "exact"),
  distance = c("chi2", "raking", "logit"),
  lambda = 10000,
  new_weight = "weight_calibrated",
  verbose = FALSE
)

Arguments

data	A data frame containing one row per sampled unit.
outcome	Name of a binary 0/1 outcome column.
weight	Name of the initial positive weight column.
group_vars	Character vector naming grouping variables.
targets	A data frame with columns variable, level, and target_rate; optional column priority controls soft-mode importance.
lower, upper	Scalar lower and upper bounds on the multiplier applied to each initial cell weight.
mode	Either "soft" or "exact".
distance	Distance function of the calibration family. "chi2" (the default) is the linear/quadratic distance solved as a bounded QP via OSQP and reproduces earlier behaviour. "raking" is the entropy distance ⁠g log g - g + 1⁠, whose solution g = exp(eta) is strictly positive by construction; it is solved by a dual Newton iteration and currently supports mode = "exact" only. Raking is unbounded above, so lower and upper are not enforced for it but multipliers outside that range are reported in the diagnostics. "logit" is the bounded logit distance whose multipliers stay strictly inside ⁠(lower, upper)⁠ by construction (requires ⁠lower < 1 < upper⁠); it is also dual-Newton solved and mode = "exact" only. Use "logit" when capping extreme weights is a hard requirement.
lambda	Positive soft-constraint penalty. Larger values emphasize target matching more strongly.
new_weight	Name of the calibrated weight column added to data.
verbose	Logical; passed to OSQP.

Value

An object of class pass_rate_calibration.

Examples

d <- example_rate_data(300)
targets <- make_rate_targets(groups = list(sex = c(M = 0.72, F = 0.68)))
fit <- calibrate_pass_rates(d, "qualified", "initial_weight",
                            group_vars = "sex", targets = targets)
fit$target_check

---

One-step pass-rate weight calibration

Description

A convenience interface for everyday use. The user only supplies the data, the outcome variable, the initial weights, an overall target and per-group targets; the function builds the target table, identifies grouping variables, runs the data checks and calls calibrate_pass_rates().

Usage

calibrate_rates(
  data,
  outcome,
  weight,
  overall = NULL,
  groups = list(),
  priority = 5,
  group_priority = 1,
  lower = 0.25,
  upper = 4,
  mode = c("soft", "exact"),
  distance = c("chi2", "raking", "logit"),
  lambda = 10000,
  new_weight = "weight_calibrated",
  check = TRUE,
  verbose = FALSE
)

Arguments

data	A data frame with one row per sampled unit.
outcome	Name of the binary outcome column (1 = pass, 0 = fail).
weight	Name of the initial weight column.
overall	Optional scalar overall target rate; may be NULL.
groups	Named list. Each element name is a grouping variable and each element is a named numeric vector of target rates.
priority	Priority of the overall target. Defaults to 5.
group_priority	Priority of the group targets; a single number or a vector named by grouping variable.
lower, upper	Lower and upper bounds on the weight-adjustment multiplier.
mode	"soft" for soft constraints, "exact" for exact constraints.
distance	Calibration distance, passed to calibrate_pass_rates(). "chi2" (default), "raking" (entropy) or "logit" (bounded); the latter two are exact mode only.
lambda	Soft-constraint penalty strength.
new_weight	Name of the new calibrated weight column.
check	Whether to run the data checks before solving.
verbose	Whether to print OSQP solver information.

Value

An object of class pass_rate_calibration.

Examples

d <- example_rate_data(300)
fit <- calibrate_rates(d, "qualified", "initial_weight",
                       groups = list(sex = c(M = 0.72, F = 0.68)))
summary(fit)

---

Re-calibrate replicate weights

Description

Re-runs the calibration of a fitted pass_rate_calibration object for each set of replicate weights (e.g. bootstrap, jackknife or BRR weights produced elsewhere), holding the targets and solver settings fixed. The resulting calibrated replicate weights feed replicate_variance() for design-consistent variance estimation, mirroring the replicate-weights approach of the survey package.

Usage

calibrate_replicate_weights(
  fit,
  repweights,
  scale = 1,
  rscales = NULL,
  progress = FALSE
)

## S3 method for class 'replicate_calibration'
print(x, ...)

Arguments

fit	A fitted object of class pass_rate_calibration.
repweights	A numeric matrix or data frame of replicate weights with one row per observation (matching fit) and one column per replicate. All entries must be finite and positive.
scale, rscales	Replication variance constants, as in survey::svrepdesign(). ⁠Var = scale * sum_r rscales_r * (theta_r - theta_0)^2⁠. Set them to match your replication scheme (for example JK1: scale = (R-1)/R, rscales = 1; bootstrap: scale = 1/R). rscales defaults to a vector of ones.
progress	Logical; show a text progress bar over the replicates.
x	A replicate_calibration object (for the print method).
...	Ignored.

Value

An object of class replicate_calibration with the full-sample calibrated weights, the matrix of calibrated replicate_weights, and the scale/rscales constants.

See Also

replicate_variance()

Examples

d <- example_rate_data(300)
fit <- calibrate_rates(d, "qualified", "initial_weight",
                       groups = list(sex = c(M = 0.72, F = 0.68)))
repw <- d$initial_weight * matrix(stats::runif(nrow(d) * 5, 0.8, 1.2), ncol = 5)
rc <- calibrate_replicate_weights(fit, repw)
replicate_variance(rc, d$qualified, statistic = "mean")

---

Extract calibration diagnostics

Description

Extract calibration diagnostics

Usage

calibration_diagnostics(x, sort_targets = TRUE)

Arguments

x	A pass_rate_calibration object.
sort_targets	Whether to sort targets by absolute error, descending.

Value

A list with target, margin and weight diagnostics.

Examples

d <- example_rate_data(300)
fit <- calibrate_rates(d, "qualified", "initial_weight",
                       groups = list(sex = c(M = 0.72, F = 0.68)))
calibration_diagnostics(fit)

---

Pre-solve target feasibility checks

Description

Runs two deterministic, closed-form feasibility checks before calibration. Both rely only on the initial weight marginals that the solver preserves, so they are cheap and exact within their stated scope.

Usage

calibration_feasibility(
  data,
  outcome,
  weight,
  group_vars,
  targets,
  lower = 0.25,
  upper = 4,
  tol = 1e-08
)

## S3 method for class 'ratecalib_feasibility'
print(x, ...)

Arguments

data	A data frame with one row per sampled unit.
outcome	Name of the binary outcome column (1 = pass, 0 = fail).
weight	Name of the initial weight column.
group_vars	Character vector of grouping-variable names.
targets	Target table with columns variable, level, target_rate.
lower, upper	Lower and upper bounds on the weight-adjustment multiplier.
tol	Numeric tolerance for the consistency comparison.
x	A ratecalib_feasibility object (for the print method).
...	Further arguments (ignored by the print method).

Details

1. Overall-vs-group consistency. Marginal totals are held fixed during calibration, so if every level of a grouping variable carries an exact target, the overall rate is uniquely pinned to $\sum_\ell W_\ell r_\ell / W$. Two such "complete" variables, or one plus an explicit overall target, can disagree; that disagreement is a guaranteed conflict under mode = "exact".

2. Single-target marginal interval. With the group total fixed and per-unit multipliers bounded by ⁠[lower, upper]⁠, a group's reachable weighted rate lies in a closed interval (two-block water-filling). A target outside that interval can never be met. This is a necessary condition only: passing every single-target check does not guarantee the targets are jointly feasible, because overlapping units couple the groups.

Value

A list of class ratecalib_feasibility with elements consistency (a list with pins, consistent and detail), marginal (a data frame of per-target achievable intervals), necessary_ok (logical) and note.

Examples

d <- example_rate_data(300)
targets <- make_rate_targets(overall = 0.62,
                             groups = list(sex = c(M = 0.66, F = 0.60)))
calibration_feasibility(d, "qualified", "initial_weight", "sex", targets)

---

Pre-calibration data checks

Description

Checks variables, weights, the binary outcome, group coverage and target supportability, and reports the current weighted pass rates.

Usage

check_calibration_data(
  data,
  outcome,
  weight,
  group_vars,
  targets = NULL,
  consistency_tol = 0.01
)

## S3 method for class 'ratecalib_check'
print(x, ...)

Arguments

data	A data frame.
outcome	Name of the binary outcome column.
weight	Name of the initial weight column.
group_vars	Character vector of grouping-variable names.
targets	Optional target table.
consistency_tol	Tolerance (on the rate scale) for the overall-vs-group consistency warning. Only inconsistencies larger than this are reported, so that sub-tolerance rounding (round-number targets that do not divide the weighted marginals exactly) does not trigger noise. For a precise, exact-mode feasibility analysis call calibration_feasibility() directly.
x	A ratecalib_check object (for the print method).
...	Further arguments (ignored by the print method).

Value

A list of class ratecalib_check with ok, errors, warnings, overview, group_summary and target_support.

Examples

d <- example_rate_data(300)
check_calibration_data(d, "qualified", "initial_weight", group_vars = "sex")

---

Generate example data

Description

Creates a simulated data set with sex, residence, a 5-level education variable, a 5-level age variable, a pass indicator and initial weights.

Usage

example_rate_data(n = 5000L, seed = 2026L)

Arguments

n	Sample size.
seed	Random seed.

Value

A data frame.

Examples

d <- example_rate_data(200)
head(d)

---

Export a calibration result to an Excel workbook

Description

Writes a multi-sheet workbook: data (with the calibrated weight column), target_check, margin_check, diagnostics and settings.

Usage

export_calibration_xlsx(fit, path, overwrite = TRUE)

Arguments

fit	An object of class pass_rate_calibration.
path	Output .xlsx path.
overwrite	Whether to overwrite an existing file.

Value

path, invisibly.

Examples

if (requireNamespace("openxlsx", quietly = TRUE)) {
  d <- example_rate_data(300)
  fit <- calibrate_rates(d, "qualified", "initial_weight",
                         groups = list(sex = c(M = 0.72, F = 0.68)))
  export_calibration_xlsx(fit, tempfile(fileext = ".xlsx"))
}

---

Build a pass-rate target table

Description

Build a pass-rate target table

Usage

make_rate_targets(
  overall = NULL,
  groups = list(),
  interactions = list(),
  overall_priority = 5,
  group_priority = 1,
  interaction_priority = 1,
  means = NULL,
  totals = NULL,
  proportions = NULL
)

Arguments

overall	Optional scalar overall target rate.
groups	Named list. Each element is a named numeric vector containing target rates for one grouping variable.
interactions	Named list of cross-classification (interaction) targets. Each element name is a colon-joined set of grouping variables (e.g. "sex:residence") and each element is a named numeric vector whose names are the matching colon-joined level combinations (e.g. c("M:Urban" = 0.7)).
overall_priority	Positive priority for the overall target.
group_priority	Either one positive scalar or a named positive vector indexed by group-variable name.
interaction_priority	Either one positive scalar or a named positive vector indexed by interaction key.
means, totals	Optional data frames of mean/total targets for a numeric variable, each with columns variable, level, value_var and target (plus optional priority). When supplied, the result gains statistic, value_var and value columns; proportion rows are tagged statistic = "proportion".
proportions	Optional data frame of proportion targets for a value of a categorical variable, with columns variable, level, value_var, value and target (plus optional priority).

Value

A data frame suitable for calibrate_pass_rates().

Examples

make_rate_targets(overall = 0.70, groups = list(sex = c(M = 0.72, F = 0.68)))

---

Methods for pass_rate_calibration objects

Description

S3 methods that print, summarize and plot calibration results.

Usage

## S3 method for class 'pass_rate_calibration'
weights(object, ...)

## S3 method for class 'pass_rate_calibration'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'pass_rate_calibration'
print(x, digits = 4, ...)

## S3 method for class 'pass_rate_calibration'
summary(object, top = 10L, ...)

## S3 method for class 'summary_pass_rate_calibration'
print(x, digits = 4, ...)

## S3 method for class 'pass_rate_calibration'
plot(x, type = c("target_error", "multipliers"), top = 20L, ...)

Arguments

...	Further arguments passed to the underlying print or graphics functions.
x, object	A pass_rate_calibration object (or, for the summary printer, a summary_pass_rate_calibration object).
row.names, optional	Standard as.data.frame() arguments (ignored).
digits	Number of decimal places to display.
top	Number of largest-error targets to display.
type	Plot type: "target_error" for target errors or "multipliers" for the weight-multiplier histogram.

Value

print and plot return their input invisibly; summary returns a summary_pass_rate_calibration object; weights returns the calibrated weight vector; as.data.frame returns the data with the calibrated weight column.

Examples

d <- example_rate_data(300)
fit <- calibrate_rates(d, "qualified", "initial_weight",
                       groups = list(sex = c(M = 0.72, F = 0.68)))
print(fit)
summary(fit)
head(weights(fit))
head(as.data.frame(fit))
plot(fit, type = "target_error")

---

Read calibration sample data from an Excel workbook

Description

Read calibration sample data from an Excel workbook

Usage

read_calibration_data(path, sheet = 1)

Arguments

path	Path to an .xlsx file.
sheet	Sheet name or index (default 1).

Value

A data frame with one row per sampled unit.

Examples

if (requireNamespace("openxlsx", quietly = TRUE)) {
  path <- tempfile(fileext = ".xlsx")
  openxlsx::write.xlsx(example_rate_data(50), path)
  head(read_calibration_data(path))
}

---

Read a pass-rate target table from an Excel workbook

Description

Reads a worksheet of targets and maps its headers (English or Chinese, in any letter case) onto the canonical columns variable, level, target_rate and the optional priority.

Usage

read_targets_xlsx(path, sheet = 1)

Arguments

path	Path to an .xlsx file.
sheet	Sheet name or index (default 1).

Value

A data frame suitable for calibrate_pass_rates().

Examples

if (requireNamespace("openxlsx", quietly = TRUE)) {
  path <- tempfile(fileext = ".xlsx")
  openxlsx::write.xlsx(
    make_rate_targets(groups = list(sex = c(M = 0.72, F = 0.68))), path)
  read_targets_xlsx(path)
}

---

Replicate-weight variance of a calibrated estimate

Description

Computes the point estimate, variance and standard error of a weighted total or mean of a study variable, using calibrated replicate weights.

Usage

replicate_variance(object, x, statistic = c("total", "mean"))

Arguments

object	A replicate_calibration object from calibrate_replicate_weights().
x	Numeric study variable, one value per observation.
statistic	Either "total" (weighted sum) or "mean" (weighted mean).

Value

A list with estimate, variance and se.

Examples

d <- example_rate_data(300)
fit <- calibrate_rates(d, "qualified", "initial_weight",
                       groups = list(sex = c(M = 0.72, F = 0.68)))
repw <- d$initial_weight * matrix(stats::runif(nrow(d) * 5, 0.8, 1.2), ncol = 5)
rc <- calibrate_replicate_weights(fit, repw)
replicate_variance(rc, d$qualified, statistic = "mean")

---