Skip to contents

Read a directory of CI images and extract the base-subtracted signal

Source: R/ci_io.R
read_signal_matrix.Rd

Convenience wrapper composing read_cis() and extract_signal(). Returns a pixels x participants signal matrix in one call. Use this when you don't need to intervene between reading and extracting (e.g. masking pixels, swapping the base).

Note that the signal matrix (this function's output) and the noise matrix (read_noise_matrix()) are different objects: the signal matrix is pixels x participants, one column per producer's CI; the noise matrix is pixels x pool_size, the basis noise patterns from stimulus generation.

Usage

read_signal_matrix(
  dir,
  base_image_path,
  pattern = "\\.(png|jpe?g)$",
  acknowledge_scaling = FALSE
)

Arguments

dir

Directory of CI images (as for read_cis()).

base_image_path

Path to the base face image used at stimulus-generation time.

pattern

Regex for file selection (see read_cis()).

acknowledge_scaling

Set to TRUE to silence the once-per-session warning. See read_cis().

Value

A numeric pixels x participants matrix, base-subtracted.

Reading the result

Pixels x participants numeric matrix, base-subtracted. Carries an img_dims attribute. Column names are the filename without the extension. Tagged with attr(., "source") = "rendered" because PNG-derived signals are scaled, not raw.

Common mistakes

  • Pointing base_image_path at the wrong file (e.g. a generated CI PNG instead of the base face used at stimulus-generation time). The dimension check catches a wholly wrong image but not a wrong-base-of-the-right-size.

  • Treating the result as raw mask. See note below.

Raw vs. rendered CIs

PNG pixel values are necessarily what was rendered to disk: base + scaling(mask). Subtracting the base in extract_signal() therefore yields scaling(mask), not the raw mask. Variance-based reliability metrics (rel_icc(), Euclidean half of rel_dissimilarity(), pixel_t_test(), rel_cluster_test()) are sensitive to the scaling transform; only correlation-based metrics (rel_split_half(), rel_loo()) survive a single uniform linear scaling unmodified, and even those break under per-CI "matched"-style scaling. The standard 2IFC infoVal path (rcicr::computeInfoVal2IFC()) extracts the raw $ci internally from the rcicr CI-list and is not affected; hand-rolled infoVal implementations (Brief-RC, custom code) are, and should be fed the raw mask. Prefer ci_from_responses_2ifc() / ci_from_responses_briefrc() when raw responses are available; both return the raw mask.

See also

read_cis(), extract_signal(), read_noise_matrix()

Examples

if (FALSE) { # \dontrun{
signal <- read_signal_matrix(
  dir             = "data/cis_condition_A/",
  base_image_path = "data/base.jpg"
)
} # }