cosmic (version 0.5)

cosmic: Fit the Conditional Ordinal Stereotype Model (COSMIC)

Description

Fits the Conditional Ordinal Stereotype Model for Identification and Comparison (COSMIC) to ordinal outcomes observed across multiple actors within shared events (e.g., officers within incidents). The model uses a conditional likelihood to remove event-level confounding and estimate actor-specific latent propensities relative to their peers.

Usage

cosmic(
  data,
  incidentID,
  officerID,
  y,
  priorSD_lambda = 2,
  priorSD_sDiff = 1,
  iter = 2000,
  chains = 4,
  cores = 1,
  threads = 8
)

Value

An object of class "cosmic_fit" containing:

fit

The fitted CmdStanMCMC object.

model

The compiled CmdStanModel used for sampling.

data

The processed data passed to Stan, including an officer_lookup table that maps sequential idOff values back to the original officerID values supplied by the user.

Arguments

data

A data frame containing one row per actor-event observation

incidentID

A column (unquoted) identifying the event or incident

officerID

A column (unquoted) identifying the actor (e.g., officer)

y

A column (unquoted) giving the ordinal outcome. Values must be consecutive integers starting at 1 (e.g., 1, 2, 3, ...)

priorSD_lambda

Prior standard deviation for the actor-specific parameters \(\lambda\). Default is 2

priorSD_sDiff

Prior standard deviation for the differences between adjacent ordinal scale parameters

iter

Number of MCMC iterations per chain

chains

Number of Markov chains

cores

Number of chains to run in parallel. When using within-chain parallelization (e.g., via reduce_sum), this should be set so that cores * threads_per_chain does not exceed the number of available CPU cores

threads

Number of threads per chain used for within-chain parallelization

Details

The likelihood is evaluated using a dynamic programming algorithm for the Poisson-multinomial normalization term, enabling efficient computation for incidents involving multiple actors. Posterior inference is performed via Markov chain Monte Carlo using cmdstanr.

Because cmdstanr is not distributed on CRAN, users may need to install it from the Stan R-universe repository before fitting models:

install.packages("cmdstanr",
                 repos = c("https://stan-dev.r-universe.dev",
                           getOption("repos")))
cmdstanr::install_cmdstan()

The COSMIC model is an ordinal regression model that estimates actor-specific latent propensities while conditioning on the set of outcomes observed within each event. This conditioning removes all event-level factors that are shared across actors, allowing for comparisons that are invariant to environmental differences.

The normalization term in the conditional likelihood involves a sum over permutations consistent with the observed counts of outcome categories. This is computed using a dynamic programming algorithm to avoid explicit enumeration.

Parallel computation is supported both across chains and within chains. When specifying cores and threads, users should ensure that total CPU usage remains within hardware limits.

References

Ridgeway, G. (2026). A Conditional Ordinal Stereotype Model to Estimate Police Officers' Propensity to Escalate Force. Journal of the American Statistical Association, 1--12. https://www.tandfonline.com/doi/full/10.1080/01621459.2025.2597050

See Also

posterior, summary.cosmic_fit

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)

print(fit)
# }