Reverse-Correlation Image-Classification Toolbox • rcicr

rcicr implements reverse correlation image classification, a technique from psychophysics for visualizing internal mental representations (for example, of faces). It generates noise-based stimuli for two-image-forced-choice (2IFC) perceptual tasks, and computes “classification images” from participants’ responses that reveal what visual features drove their choices.

Installation

Install from GitHub:

install.packages('remotes')

# The most recent release -- start here
remotes::install_github('rdotsch/rcicr@*release')

# A specific release, by tag -- to reproduce an analysis run under that version
remotes::install_github('rdotsch/rcicr@v1.3.0')

# The development version at the tip of main -- unreleased, may change under you
remotes::install_github('rdotsch/rcicr')

Every release is tagged, and the tags are listed on the releases page. Record the version you ran in your analysis script, and install it by tag when you come back to that analysis: a classification image is only reproducible against the version that computed it, and any release that changes numeric output says so in NEWS.md under “Reproducibility impact”.

If you saved per-participant classification images before 1.3.0, check them. generateCI(participants = ..., save_individual_cis = TRUE) wrote an image under another participant’s filename at each position where appearance order and sorted order differed (for text identifiers that means lexical order, which includes the ordinary case of p1 ... p10 in collection order). The images were correct; only the names were wrong, and correcting them is a rename rather than a re-run. The individual-CI filename advisory is the full version: how to tell whether you are affected, what it did to an analysis, and the recovery. A shorter form is in NEWS.md under “Reproducibility impact”, and which version you had if you need to work out what a stored analysis actually ran. batchGenerateCI(), batchGenerateCI2IFC() and generateCI2IFC() were never affected.

install.packages('rcicr') does not currently work. The package was archived on CRAN on 2021-06-08 because email to the maintainer had become undeliverable — an old university address that stopped working. The code was never the problem, and the maintainer address has since been updated. Returning to CRAN is being worked on; until then, GitHub is the only source. The last CRAN release was 0.3.4.1, which is several years behind.

Quick example

A minimal 2IFC workflow: generate stimuli from a base face, then turn collected responses into a classification image.

library(rcicr)

# 1. Generate stimuli: writes an original + inverted noise-blended PNG per
#    trial to stimulus_path, plus an .Rdata file that later analysis needs.
generateStimuli2IFC(
  base_face_files = list(face = "path/to/base_face.jpg"),
  n_trials        = 770,
  img_size        = 512,
  stimulus_path   = "./stimuli",
  seed            = 1
)

# 2. After running the task and collecting responses (1 = original chosen,
#    -1 = inverted chosen), compute the classification image:
generateCI(
  stimuli    = 1:770,               # stimulus numbers, in presentation order
  responses  = my_responses,        # 1 / -1 vector, same order as `stimuli`
  baseimage  = "face",              # key used in base_face_files above
  rdata      = "./stimuli/rcic_seed_1_time_....Rdata",
  targetpath = "./cis"              # where to write the CI PNG
)

Every function that writes files takes its destination explicitly: stimulus_path, targetpath and zmaptargetpath have no defaults, so nothing is ever written to a directory you did not name. Pass save_as_png = FALSE to compute a classification image without writing anything.

Documentation

Everything below is also on the web at https://rdotsch.github.io/rcicr/ — the function reference, both vignettes and the changelog — if you would rather read it before installing.

Two vignettes ship with the package:

vignette("getting-started", package = "rcicr")  # shortest working example
vignette("reverse-correlation-walkthrough", package = "rcicr")  # the full method

The walkthrough covers designing a study, generating stimuli, computing classification images for several participants, choosing a scaling method, and telling signal from noise. Its code runs when the package is built, so it cannot drift out of date.

For example datasets and analysis scripts, see rcicr_examples. There is also an older Medium post covering similar ground; the vignette above supersedes it and is the version kept current with the code.

How it works

The package is two halves that run at different times — often months apart — and share no state except one file on disk.

base face image(s) ─┐
                    ├─> generateStimuli2IFC() ─> stimulus PNGs + <label>_seed_<n>_time_<ts>.Rdata
     random noise ──┘                                        │
                                                             │  (run your experiment)
                             participant responses ──────────┤
                                                             ▼
                                       generateCI() / generateCI2IFC() ──> classification image
                                                             │
                                        ┌────────────────────┼────────────────────┐
                                        ▼                    ▼                    ▼
                                  autoscale()      computeInfoVal2IFC()      plotZmap()

1. Stimulus generation. generateNoisePattern() builds the noise basis — a stack of sinusoid (or Gabor) patches at several orientations, phases and spatial scales. This is built once and reused for every trial. generateNoiseImage() then combines one random contrast weight per patch into a single noise image, and generateStimuli2IFC() runs that loop over trials, writing two PNGs per trial per base face: the noise blended with the base image, and its inverted counterpart.

2. Analysis. generateCI() loads the stimulus file, looks up the parameters of the stimuli a participant actually saw, weights each by their response (1 = original chosen, -1 = inverted chosen), and averages them into one image — the classification image. From there, autoscale() makes a batch of CIs visually comparable, computeInfoVal2IFC() scores one against a simulated null distribution, and plotZmap() shows which regions carry reliable signal.

The .Rdata file is the only link between the two halves. Nothing about your stimuli is recoverable without it — not from the PNGs, not from the seed alone. Back it up with your response data, and keep it alongside anything you publish: recomputing a classification image years later needs this file and nothing else.

Compare numbers, not figures, across machines. Classification images, scaling, informational value and z-scores are ordinary R arithmetic and do not depend on your operating system — the test suite pins them to fixed values and they hold on Linux and on macOS ARM64 alike. The one exception is the PNG written by plotZmap(), the only function here that draws through a graphics device: devices differ between platforms in colour management and in whether they write an alpha channel, so the same z-map yields visibly identical figures whose files are not byte-identical. A z-map image that differs pixel-for-pixel on a colleague’s machine is not a different result. Every other PNG the package writes comes straight from the pixel array via png::writePNG() and is unaffected. See ?plotZmap.

Where the code lives

Apart from generateCI() itself, every function named in the table below is internal — not exported, and not callable from your own scripts. They are split by concern rather than by which exported function happens to call them. (The walkthrough above names only the exported functions it needed; for the full public API, see the function reference on the documentation site or help(package = "rcicr").)

The usual reason to look is generateCI(), whose body reads as one call per step — validate, load, select, compute, present, return — with the steps themselves in these files:

file	what is in it
`R/generateCI.R`	`generateCI()` itself, plus the presentation helpers `hasMask()`, `applyMask()`, `applyScaling()`, `combine()`, `saveToImage()`
`R/rdata.R`	reading and guarding `.Rdata` files: `loadStimulusParams()`, `captureArgs()`, `rdataWriterNote()`
`R/ci-inputs.R`	turning the caller’s arguments into a parameter matrix: `coerceTrialVectors()`, `selectBaseImage()`, `aggregateResponses()`, `selectStimulusParams()`
`R/ci-compute.R`	`computeParticipantCIs()` — one CI per participant, plus their average
`R/zmap-compute.R`	`computeZmapQuick()` and `computeZmapTTest()`
`R/parallel.R`	the `foreach` backend: `default_ncores()`, `startBackend()`, `progressOption()`, `stopClusterSafely()`

The mask helpers live in R/generateCI.R rather than a file of their own because plotZmap() shares them — masking a z-map and masking a CI are the same operation.

Anatomy of the `.Rdata` file

generateStimuli2IFC() writes one file named <label>_seed_<seed>_time_<timestamp>.Rdata. load() it and you get these objects (sizes shown for a 3-trial, 32px, nscales = 2 example):

Object	What it is
`p`	The noise basis. A list of `patches` (an `img_size × img_size × 12·nscales` array of sinusoid/Gabor layers), `patchIdx` (which parameter drives each pixel of each layer), `noise_type`, and `generator_version`. This is the expensive part and the reason the file exists.
`stimuli_params`	Named list, one entry per base image, each an `n_trials × nparams` matrix of contrast weights in `[-1, 1]`. Row i is the noise of stimulus i — this is what `generateCI()` looks up and weights by responses.
`base_faces`	Named list of the base images as greyscale matrices, after contrast maximization. The actual pixels, not paths, so the file is self-contained.
`base_face_files`	The paths they were read from, for reference.
`img_size`, `n_trials`, `nscales`, `sigma`, `noise_type`	The generation parameters. `generateReferenceDistribution2IFC()` re-reads these to rebuild the same noise basis when simulating a null distribution, so they must describe the stimuli exactly.
`seed`	The RNG seed. Regenerating with the same seed and parameters reproduces the identical stimulus set.
`use_same_parameters`	Whether every base image shared one parameter set (`TRUE`) or each got its own.
`label`, `stimulus_path`	What the files were called and where they were written.
`generator_version`	The rcicr version that wrote the file — see the caveat below.

computeInfoVal2IFC() and generateReferenceDistribution2IFC() add two more fields to the same file the first time you compute an informational value:

Object	What it is
`reference_norms`	The simulated null distribution — the norms of `iter` classification images built from random responses. Cached here because simulating it is expensive.
`reference_norms_seed`	The `response_seed` those norms were drawn with (`NULL` for the default stream). Added in 1.2.0.

Two things worth knowing before you write code against this file:

The contract is append-only. Fields get added across versions and are never renamed or repurposed, so newer rcicr reads older files. The converse does not hold: nscales and sigma were only added in 1.1.0, and noise_type earlier still, so functions warn rather than guess when reading a file that predates them.
generator_version is unreliable on older files. It was a hardcoded '0.4.0' string until 1.2.0, so any file written between 0.4.0 and 1.1.0 claims to be 0.4.0 whatever wrote it. p$generator_version has always held the real value. Compare versions with numeric_version() semantics, never as text.

Development

On a fresh Ubuntu machine with no compiler or R package library yet, tools/dev-setup.sh builds one — see CONTRIBUTING.md → “Getting set up” for details.

devtools::load_all()   # load the package for interactive development
devtools::test()       # run the test suite
devtools::check()      # full CRAN-style check

Contributing

Contributions, thoughts, and criticisms are very welcome — please open an issue.

License

GPL-2

rcicr