Skip to contents

Read a directory of CI images into a pixels x participants matrix

Source: R/ci_io.R
read_cis.Rd

Reads every PNG / JPEG in dir (non-recursive), converts each to grayscale via ITU-R BT.709 luminance weights (0.2126 R + 0.7152 G + 0.0722 B), and returns a numeric matrix with one column per file, sorted alphabetically by filename.

Use this when you have one CI image per producer already saved on disk and you want a numeric matrix you can pass to extract_signal() or read_signal_matrix() for the base subtraction step.

Usage

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

Arguments

dir

Directory containing the CI images.

pattern

Regular expression used to select files. Defaults to any PNG / JPG / JPEG (case-insensitive).

acknowledge_scaling

Set to TRUE to silence the once-per-session warning about Mode 1 returning rendered (scaled) pixel data. Recommended only when you generated the PNGs yourself with rcicr::generateCI2IFC(scaling = "none") (or equivalent) and the PNG truly carries unscaled noise.

Value

A numeric matrix with nrow = n_pixels and ncol = n_participants, with img_dims and source attributes.

Details

All images must share the same dimensions; mixed sizes abort. Column names are the filename without the extension.

Reading the result

The returned matrix has nrow = n_pixels and ncol = n_participants. Pixel ordering follows as.vector(img) of the underlying image matrix. The integer c(nrow, ncol) of the original image is stamped on the result as an img_dims attribute, which downstream functions read automatically. The matrix is also tagged with attr(., "source") = "rendered" so variance-based metrics know it is not a raw mask.

Common mistakes

  • Forgetting to subtract the base. The matrix returned here contains the rendered CI (base + scaled noise). Pass it through extract_signal() before any reliability metric.

  • Mixing CIs from different image sizes in one directory; this aborts with a clear error rather than silently misaligning.

  • Trusting variance-based reliability numbers without first reading the note below on raw vs. rendered CIs.

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

extract_signal(), read_signal_matrix(), ci_from_responses_2ifc(), ci_from_responses_briefrc()

Examples

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