Package {wavecov}

Type: Package
Title: Overlap-Aware Workforce Wave Comparisons
Version: 0.1.0
Description: Tools for comparing workforce metric distributions between panel waves using linked stayers, reliability assumptions, or Cauchy bounds. Its purpose is to provide a low-latency alternative to traditional hierarchical or latent-growth modeling that is better-able to scale in cloud based architectures. The mathematics is an extension of rotating panel formulae from the official statistics literature.
License: GPL-3
Encoding: UTF-8
Depends: R (≥ 3.5.0)
Imports: stats
Config/roxygen2/version: 8.1.1
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-10-21 17:40:09 UTC; G561631
Author: Jack Kostal [aut, cre]
Maintainer: Jack Kostal <jack.kostal@genmills.com>
Repository: CRAN
Date/Publication: 2026-11-03 14:30:02 UTC

Compare two workforce waves for a single metric

Description

Compute overlap-aware inference for the change in a repeated organizational metric between two workforce waves, using linked stayers, a reliability assumption, or Cauchy-based bounds.

Usage

compare_waves(
  data,
  wave_0,
  wave_1,
  id_col,
  wave_col,
  metric_col,
  method = c("auto", "linked", "reliability", "bounds"),
  reliability = NULL,
  sigma2 = NULL,
  sigma2S = NULL,
  cov_sign = c("unrestricted", "nonnegative"),
  overlap_mode = c("generic", "overlap_aware"),
  level = 0.95,
  ...
)

Arguments

data

Data frame with at least id, wave, and metric columns.

wave_0

Value in wave_col for the first wave.

wave_1

Value in wave_col for the second wave.

id_col

Column name for the employee identifier.

wave_col

Column name for the wave identifier.

metric_col

Column name for the metric.

method

Method to use: "auto", "linked", "reliability", or "bounds". In "auto" mode, wavecov prefers linked, then reliability, then bounds.

reliability

Same-person cross-wave reliability for the relevant stayer population (used only for the reliability method).

sigma2

Optional common individual-level variance. When supplied with the reliability method, overrides the pooled variance from the two waves.

sigma2S

Optional pooled individual-level stayer variance. When supplied with the reliability method, is treated as a candidate sigma2. When supplied with the bounds method and overlap_mode = "overlap_aware", is used as a common stayer variance to tighten the Cauchy bounds.

cov_sign

Covariance sign restriction for bounds: "unrestricted" or "nonnegative".

overlap_mode

Whether to use generic Cauchy bounds ("generic") or overlap-aware tightening ("overlap_aware").

level

Confidence level for intervals (point-estimate methods) or sensitivity envelopes (bounded results).

...

Reserved for future extensions.

Value

A "wavecov_result" object (linked or reliability) or a "wavecov_bounds_result" object (bounds). Use print(), tidy(), and confint() for summaries.

Batch comparisons of multiple waves and metrics

Description

Batch comparisons of multiple waves and metrics

Usage

compare_waves_batch(
  data,
  wave_pairs,
  id_col,
  wave_col,
  metric_col,
  metric_id_col = NULL,
  group_cols = NULL,
  method = c("linked", "reliability", "bounds", "auto", "ols"),
  reliability = NULL,
  sigma2 = NULL,
  sigma2S = NULL,
  level = 0.95,
  ...
)

Arguments

data

...

wave_pairs

...

id_col

...

wave_col

...

metric_col

...

metric_id_col

...

group_cols

...

method

...

reliability

...

sigma2

...

sigma2S

...

level

...

...

...

Value

...

Compare two waves using summary statistics only

Description

When individual-level data are not available, this function computes overlap-aware variance for the change in means using either a reliability assumption or Cauchy-based bounds from supplied summary statistics.

Usage

compare_waves_summary_stats(
  N0,
  N1,
  nS,
  sigma2 = NULL,
  reliability = NULL,
  V0_bar = NULL,
  V1_bar = NULL,
  method = c("reliability", "bounds"),
  cov_sign = c("unrestricted", "nonnegative"),
  overlap_mode = c("generic", "overlap_aware"),
  sigma2S = NULL,
  level = 0.95
)

Arguments

N0

Workforce size at wave 0.

N1

Workforce size at wave 1.

nS

Number of stayers (present in both waves).

sigma2

Common individual-level variance for the relevant population (used with the reliability method).

reliability

Same-person cross-wave reliability (used with the reliability method).

V0_bar

Variance of the wave-0 mean (used with the bounds method).

V1_bar

Variance of the wave-1 mean (used with the bounds method).

method

"reliability" or "bounds".

cov_sign

Covariance sign restriction for bounds: "unrestricted" or "nonnegative".

overlap_mode

Whether to use generic Cauchy bounds or overlap-aware tightening. Overlap-aware bounds additionally use nS and sigma2S when supplied.

sigma2S

Optional pooled individual-level stayer variance for overlap-aware bounds.

level

Confidence level for point-estimate intervals or sensitivity envelopes.

Value

A "wavecov_result" (reliability) or "wavecov_bounds_result" (bounds) object. Use print(), tidy(), and confint() for summaries.

wavecov bounded-result object

Description

Internal constructor and methods for Cauchy-based bounds on the variance of the change in means.

Usage

new_wavecov_bounds_result(summary, bounds, level)

Arguments

summary

Minimal summary list (typically from summarize_panel()).

bounds

List returned by variance_bounds().

level

Confidence level to use when converting SE bounds to an interval envelope via confint().

Value

An object of class "wavecov_bounds_result".

wavecov point-estimate result

Description

Internal constructor and methods for overlap-aware change estimates when a point variance estimate is available (linked or reliability methods).

Usage

new_wavecov_result(summary, var_out, method, level)

Arguments

summary

List returned by summarize_panel().

var_out

List returned by variance_linked() or variance_reliability().

method

Character string naming the method ("linked" or "reliability").

level

Confidence level for intervals.

Value

An object of class "wavecov_result".

Summarize a two-wave panel with overlap

Description

Internal helper to compute wave sizes, means, variances, and stayer covariance/variances from individual-level data.

Usage

summarize_panel(data, wave_0, wave_1, id_col, wave_col, metric_col)

Arguments

data

Data frame containing at least id, wave, and metric columns.

wave_0

Value in wave_col for the first wave.

wave_1

Value in wave_col for the second wave.

id_col

Column name for the employee identifier.

wave_col

Column name for the wave identifier.

metric_col

Column name for the metric.

Value

A list with N0, N1, nS, ybar0, ybar1, V0_ind, V1_ind, C01_ind, V0S_ind, V1S_ind.

Generic tidy method

Description

A minimal generic for tidying objects returned by wavecov functions.

Usage

tidy(x, ...)

Arguments

x

An object to tidy.

...

Unused.

Value

A data frame with a structure determined by the class of x.

Tidy output for wavecov point-estimate results

Description

Tidy output for wavecov point-estimate results

Usage

## S3 method for class 'wavecov_result'
tidy(x, ...)

Arguments

x

A "wavecov_result" object.

...

Unused.

Value

A one-row data frame with change estimates and diagnostics.

Cauchy-based bounds for the variance of the change in means

Description

Compute generic and overlap-aware Cauchy bounds on the variance of the observed change in wave means when the covariance between wave means is unknown.

Usage

variance_bounds(
  N0,
  N1,
  V0_bar,
  V1_bar,
  nS = NULL,
  V0S_ind = NULL,
  V1S_ind = NULL,
  sigma2S = NULL,
  cov_sign = c("unrestricted", "nonnegative"),
  overlap_mode = c("generic", "overlap_aware")
)

Arguments

N0

Wave 0 workforce size.

N1

Wave 1 workforce size.

V0_bar

Variance of the wave-0 mean.

V1_bar

Variance of the wave-1 mean.

nS

Number of stayers (optional, for overlap-aware bounds).

V0S_ind

Stayer individual-level variance at wave 0 (optional).

V1S_ind

Stayer individual-level variance at wave 1 (optional).

sigma2S

Pooled individual-level stayer variance (optional).

cov_sign

Covariance sign restriction: "unrestricted" or "nonnegative".

overlap_mode

Whether to use generic bounds or overlap-aware tightening.

Value

A list with covariance and variance bounds and associated metadata.

Linked stayer variance for change in means

Description

Linked stayer variance for change in means

Usage

variance_linked(N0, N1, nS, V0_ind, V1_ind, C01_ind)

Reliability-based variance for change in means

Description

Reliability-based variance for change in means

Usage

variance_reliability(
  N0,
  N1,
  nS,
  V0_ind = NULL,
  V1_ind = NULL,
  sigma2 = NULL,
  reliability
)