Skip to contents

Per-producer infoVal report (with calibration sanity checks)

Source: R/infoval_report.R
infoval_report.Rd

Runs the package's native infoVal computation for every producer and reports per-producer z-scores plus three sanity checks: a masked-vs-unmasked comparison, a group-mean z against a matched reference, and a random-responder calibration check. Works for both 2IFC and Brief-RC.

Usage

infoval_report(
  responses,
  method = NULL,
  rdata = NULL,
  stimuli = NULL,
  noise_matrix = NULL,
  base_image = "base",
  col_participant = "participant_id",
  col_stimulus = "stimulus",
  col_response = "response",
  iter = 1000L,
  face_mask = "auto",
  with_replacement = "auto",
  seed = NULL,
  progress = TRUE,
  ...
)

Arguments

responses

Data frame with one row per trial. Required columns: participant_id, stimulus, response (values in {-1, +1}). Load yours from CSV via read_responses() or utils::read.csv(); column names are configurable via the col_* arguments.

method

"2ifc" or "briefrc". If NULL, inferred from whichever of rdata / noise_matrix is supplied.

rdata

Path to an rcicr .RData file (2IFC). Either rdata or stimuli must be supplied for the 2IFC path.

stimuli

In-memory stimuli list (the $stimuli element of an rcisignal_sim object). Use in place of rdata when the file path no longer resolves (e.g. after saveRDS()/ readRDS() across R sessions).

noise_matrix

Path to a Brief-RC noise-matrix text file, or an already-loaded numeric matrix.

base_image

Name of the base image in the rdata base_face_files list. Default "base". Only consulted for 2IFC.

col_participant, col_stimulus, col_response

Column names.

iter

Reference-distribution Monte Carlo size. Default 1000L (a diagnostic-grade value). Bump to 10000 for publication numbers.

face_mask

Mask specification. One of:

  • "auto" (default): generate a Schmitz 2024 oval via make_face_mask() sized to the image dims.

  • NULL: skip the masked-vs-unmasked comparison.

  • A logical vector of length n_pixels.

  • A numeric matrix matching the image dims (coerced via > 0.5).

  • A character path to a PNG / JPEG mask image (loaded via read_face_mask()).

with_replacement

Sampling regime forwarded to infoval() for building the reference distribution at the across-trials level. "auto" (default) matches the standard Brief-RC convention (without replacement when a producer's trial count fits in the pool, with replacement otherwise). Set explicitly only if your task design departs from this convention. See infoval() for details. Ignored on the 2IFC path because there n_trials equals the pool size by construction.

seed

Optional integer; RNG state restored on exit.

progress

Show a cli progress bar.

...

Unused.

Value

An rcisignal_diag_result(). data carries the rich output:

  • random_responder_z – numeric scalar; a simulated random producer's z against the per-producer reference. Should land near 0; |z| > 2 indicates the reference is mis-calibrated.

  • infoval_unmasked – rcisignal_diag_infoval object (see infoval()).

  • infoval_masked – rcisignal_diag_infoval; NULL when no mask.

  • group_mean_z_unmasked, group_mean_z_masked – numeric scalars; the modified-z of the group-mean (across producers) CI's Frobenius norm against a reference distribution of N matched random producers averaged together (one simulated producer per real producer, at matched trial counts). Supplementary to the per-producer z distribution – treat the per-producer summary as primary (Brinkman et al., 2019). See Details above and vignette("rcisignal") §11.

  • tally – named integer vector with counts per z band.

  • mask – logical vector or NULL.

  • interpretation – character vector of human-readable bullets.

Details

Use this as the canonical per-producer infoVal entry point when you want both a summary and the calibration cross-checks. For the bare per-producer z-score vector with no calibration overlay, use infoval() directly.

The six steps:

  1. Simulate the reference distribution at every unique producer trial count present in the data.

  2. Sanity-check the reference with a simulated random responder. A random producer should land near z = 0; |z| > 2 indicates the reference is mis-calibrated.

  3. Compute per-producer z unmasked.

  4. Compute per-producer z with the supplied (or auto-generated) face mask, and report the median masked-vs-unmasked z lift.

  5. Compute the group-mean CI's z, against a reference matched to the same producer count and trial counts.

  6. Tabulate per-producer z into four bands (< -1.96, [-1.96, 0), [0, 1.96), >= 1.96) and produce interpretation bullets summarising the evidence.

Whether per-producer z values cluster above or below the conventional 1.96 threshold is paradigm- and target-dependent. Brinkman et al. (2019) report 68% (lab) and 54% (online) of 2IFC participants clearing 1.96 on perceived gender, with mean per-participant infoVal 3.9 (lab) and 2.9 (online); Schmitz et al. (2024) report Brief-RC infoVals systematically below 1.96 across all conditions in both experiments. The reportable summary is therefore context-specific: per-producer z is useful for exclusion decisions on individual cases. Neither paper computes a group-mean CI's z directly, but the mathematical extension (a group-mean CI compared against an N-producer-matched reference) is a useful aggregate when individual-level z is noisy, and infoval_report() reports it.

Note on the group-mean z (group_mean_z_unmasked / group_mean_z_masked in the return value). This is not Brinkman's per-producer infoVal applied to a group CI. It is a related-but-distinct statistic: the modified-z of the producer-averaged CI's Frobenius norm against a Monte-Carlo reference of N random producers (one per real producer, at matched trial counts) averaged together. The reference correctly accounts for the ~1/sqrt(N) shrinkage of random-producer norms under averaging, so the z is calibrated; but Brinkman et al.'s Type-I and power validation work was done at the per-producer level and does not transfer to the group statistic. Brinkman et al. recommend reporting the distribution of per-producer infoVals (median z, % above 1.96 — both available from the tally and infoval_* fields) as the primary group-level summary. Treat the group-mean z as a supplementary headline number, not a replacement. vignette("rcisignal") §11 unpacks how group_mean_z() builds its reference distribution, how it differs from per-producer infoVal, and how to read it appropriately — with a side-by-side illustration of the two nulls.

For method = "2ifc", the function calls rcicr to reconstruct per-trial noise patterns from stimuli_params and p (the .RData does not store the patterns themselves; see vignette "What data the package expects"). The reconstruction is one rcicr::generateNoiseImage() call per pool item, which is fast (seconds) but does require rcicr to be installed. The Brief-RC path needs no rcicr dependency.

References

Brinkman, L., Goffin, S., van de Schoot, R., van Haren, N. E. M., Dotsch, R., & Aarts, H. (2019). Quantifying the informational value of classification images. Behavior Research Methods, 51(5), 2059-2073.

Schmitz, M., Rougier, M., & Yzerbyt, V. (2024). Introducing the brief reverse correlation: an improved tool to assess visual representations. European Journal of Social Psychology.

See also

infoval(), make_face_mask().

Examples

if (FALSE) { # \dontrun{
sim <- simulate_2ifc_data(n_per_condition = 10, n_trials = 60, seed = 1)
infoval_report(sim$data, method = "2ifc",
               rdata = sim$rdata_path, iter = 200L)

# Same call via the session-portable in-memory stimuli list:
infoval_report(sim$data, method = "2ifc",
               stimuli = sim$stimuli, iter = 200L)
} # }