cosmic (version 0.5)

officer_summary: Summarize officers relative to their peer groups

Description

Computes posterior summary measures for each officer in a fitted COSMIC model. The returned data frame includes the size of each officer's peer group, both the original and sequential officer IDs, tail-rank probabilities within that group, posterior contrasts against the mean of peers, and counts by force category.

Usage

officer_summary(object, pct_threshold = 0.25, pct_tail = 0.05)

Value

A data frame with one row per officer. When the fitted model includes an officer_lookup table, the summary includes both idOffOrig and idOff. The returned object has class c("cosmic_officer_summary", "data.frame").

Arguments

object

A fitted object of class "cosmic_fit".

pct_threshold

Threshold used to define peer groups from posterior variances. Officer j is treated as a peer of officer i when the posterior variance of lambda_i - lambda_j is less than pct_threshold * 2 * priorSD_lambda^2. Default is 0.25.

pct_tail

Tail fraction used when computing top-tail and bottom-tail rank probabilities. Default is 0.05, tracking the probability of being in the top or bottom 5 percent.

Details

Officers are treated as peers when the posterior variance of \(\lambda_i - \lambda_j\) is smaller than pct_threshold * 2 * priorSD_lambda^2.

When the future.apply package is installed, computations are distributed using the active future plan. If progressr is also installed, progress updates are emitted while officers are processed.

Parallel workers are not configured by officer_summary() itself. Instead, the function respects the future plan that is already active. For example, users can request four background R sessions with future::plan(future::multisession, workers = 4) before calling officer_summary(). If no multi-worker plan is active, computation falls back to sequential evaluation. To see progress updates in an interactive session, call progressr::handlers("cli") before running officer_summary().

Examples

# \donttest{
d <- data.frame(
  id = c(1,1,2,2),
  idOff = c(1,2,1,2),
  y = c(1,2,1,3)
)
fit <- cosmic(d, id, idOff, y, iter = 300, chains = 1, cores = 1, threads = 1)

# use plan() and handlers() to run officer_summary() in parallel
# future::plan(future::multisession, workers = 4)
# progressr::handlers("cli")
off_summary <- officer_summary(fit)
outlier_report(off_summary)
# }