Title:	Thinking Grid Statistics
Version:	0.1.0
Depends:	R (≥ 3.5.0)
Description:	Provides comprehensive tools for conducting research using the Thinking Grid framework, a psychological measurement approach for understanding the stream of thought. Includes functions for generating Qualtrics surveys with the thinking grid, processing survey responses, calculating quadrant depths, and creating various visualization types including heatmaps, animations, and statistical plots. See Irving, Z. C., Murray, S., Kuvar, V., Urena, M., and Mills, C. (2025) "Consciousness, Just in Time: Fluctuations in the Stream of Consciousness during Tasks and Rest" (manuscript under review, draft available from zci7c@virginia.edu).
URL:	https://a-kulkarn.github.io/qualtrics-thinkgrid/
BugReports:	https://github.com/a-kulkarn/qualtrics-thinkgrid/issues
Imports:	colorspace, cowplot, ggplot2, gifski, grid, gridExtra, methods, reticulate (≥ 1.45), scales, stats, utils
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Suggests:	png, testthat (≥ 3.0.0), vdiffr, lme4, knitr, rmarkdown, sjPlot
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-03-06 06:27:38 UTC; f004584
Author:	Avinash Kulkarni [aut, cre, cph], Vishal Kuvar [aut], Zac Irving [ctb, fnd]
Maintainer:	Avinash Kulkarni <avi.kulkarni.2.71@gmail.com>
Repository:	CRAN
Date/Publication:	2026-03-12 19:20:02 UTC

ThinkingGrid: Thinking Grid Statistics

Description

Provides comprehensive tools for conducting research using the Thinking Grid framework, a psychological measurement approach for understanding deliberate and automatic cognitive constraints. Includes functions for generating 'Qualtrics' surveys, processing survey responses, calculating quadrant depths, and creating various visualization types including heatmaps, animations, and statistical plots.

Author(s)

Maintainer: Avinash Kulkarni avi.kulkarni.2.71@gmail.com [copyright holder]

Authors:

• Vishal Kuvar kuvar001@umn.edu (ORCID)

Other contributors:

• Zac Irving zci7c@virginia.edu [contributor, funder]

See Also

Useful links:

• https://a-kulkarn.github.io/qualtrics-thinkgrid/

• Report bugs at https://github.com/a-kulkarn/qualtrics-thinkgrid/issues

Adds taxicab metric calculation columns to a dataframe.

Description

Adds taxicab metric calculation columns to a dataframe.

Usage

add_depths(data, dc = "Deliberate.Constraints", ac = "Automatic.Constraints")

Arguments

Details

The function calculates the quadrant depths based on the deliberate and automatic constraints provided in the data file. The quadrant depths are calculated using the taxicab norm. Only one depth will be populated per observation, depending on the quadrant the observation falls into. The remaining three depths will be set to 0.

Value

data frame containing the quadrant depths. Columns include "sticky", "hybrid", "free", "directed", "total_depth", and "quadrant". The value of quadrant is 1-4, corresponding to top-left, top-right, bottom-left, bottom-right.

Examples

# Calculate quadrant depths from survey data
data_file <- system.file("extdata", "sample_data.csv", package = "ThinkingGrid")
if (file.exists(data_file)) {
  data_file <- read.csv(data_file)
  depth_results <- add_depths(data_file, dc = "dc", ac = "ac")
}

Create custom color scale with enhanced visibility for small values

Description

Create custom color scale with enhanced visibility for small values

Usage

create_custom_colorer(
  palette = "RdYlBu",
  zero_color = "#FFFFFF",
  n_colors = 11,
  gradient_scaling = "enhanced",
  enhanced_threshold_pct = 50,
  enhanced_expansion_factor = 1.5
)

Arguments

Details

The enhanced scaling works by compressing small values in the scaled space, which gives them more colors in the final gradient. For example, if your data ranges from 0-20 percent and you use enhanced_threshold_pct = 50 with enhanced_expansion_factor = 2.0, then values 0-10 percent will get twice as much color distinction compared to linear scaling.

Value

A colorer function that can be passed to plot_tg() or create_tg_animation()

Examples

# Create dummy data for testing
dummy_data <- data.frame(
  Deliberate.Constraints = sample(1:6, 100, replace = TRUE),
  Automatic.Constraints = sample(1:6, 100, replace = TRUE)
)

# Basic usage with linear scaling
colorer <- create_custom_colorer(gradient_scaling = "linear")

# Enhanced scaling for better small value distinction
colorer_enhanced <- create_custom_colorer(
  gradient_scaling = "enhanced",
  enhanced_threshold_pct = 30,
  enhanced_expansion_factor = 2.0
)

Creates an example list of four plots for use in 2x2 plot tests.

Description

Creates four ggplot objects.

Usage

create_test_2x2_plots()

Value

A list of four ggplot objects for testing purposes.

Examples

# This is a list of four plots generated by some regression. Their exact nature is not
# important aside from the fact that they are ggplot objects.
plots <- ThinkingGrid::create_test_2x2_plots()

Create Animated Thinking Grid Visualizations

Description

Generate animated GIF showing Thinking Grid plots across different conditions or time points.

Usage

create_tg_animation(
  survey_results,
  dc_column = "Deliberate.Constraints",
  ac_column = "Automatic.Constraints",
  condition_column = NULL,
  type = "depth",
  proportion_type = "overall",
  colorer = NULL,
  palette = "RdYlBu",
  zero_color = "#FFFFFF",
  gradient_scaling = "linear",
  enhanced_threshold_pct = 50,
  enhanced_expansion_factor = 1.5,
  x_label = "Directedness",
  y_label = "Stickiness",
  max_legend = NULL,
  min_legend = NULL,
  plot_title = NULL,
  legend_title = NULL,
  plot_subtitle = NULL,
  filename = "tg_animation.gif",
  duration = 1,
  width = 800,
  height = 800,
  sorted_conditions = NULL,
  subset_condition = NULL
)

Arguments

Details

The function creates one frame per unique value in condition_column. All frames use the same legend scale (calculated from all conditions) to ensure comparability across frames. Requires the 'gifski' package for GIF creation. Will prompt to install if missing.

Value

Invisibly returns list of ggplot objects (one per frame). The GIF file is saved to disk.

Examples

## Create sample data with time points for animation
set.seed(123)  ## For reproducible examples
survey_data <- data.frame(
  Deliberate.Constraints = sample(1:6, 300, replace = TRUE),
  Automatic.Constraints = sample(1:6, 300, replace = TRUE),
  time_point = rep(1:3, each = 100),
  week = rep(1:3, each = 100),
  completed_training = sample(c(TRUE, FALSE), 300, replace = TRUE)
)


## Basic animation across time points (creates temporary GIF file)
temp_gif1 <- tempfile(fileext = ".gif")
create_tg_animation(survey_data, 
                    condition_column = "time_point",
                    filename = temp_gif1)
## Clean up temporary file
if (file.exists(temp_gif1)) file.remove(temp_gif1)

## Enhanced scaling for small differences
temp_gif2 <- tempfile(fileext = ".gif")
create_tg_animation(survey_data,
                    condition_column = "week",
                    gradient_scaling = "enhanced",
                    enhanced_threshold_pct = 40,
                    enhanced_expansion_factor = 2.0,
                    subset_condition = "completed_training == TRUE",
                    filename = temp_gif2)
## Clean up temporary file
if (file.exists(temp_gif2)) file.remove(temp_gif2)

Default theme for subplots in a ThinkingGrid 2x2 quadrant plot.

Description

The default theme settings for the subplots of a 2x2 quadrant plot. In order to display correctly, the important properties of the theme are:

1. The background are set to transparant elements.

2. The main plot titles and legends are removed. (Axis labels are kept.)

3. The aspect ratio is set to 1.00.

4. Margins are adjusted to set the plot within the background squares.

Usage

default_inner_theme(inner_margin = 20)

Arguments

Value

A theme object with the settings for the subplots of a 2x2 quadrant plot.

Examples

plots <- ThinkingGrid::create_test_2x2_plots()
p1 <- plots[[1]]
p2 <- plots[[2]]
p3 <- plots[[3]]
p4 <- plots[[4]]

# Here we can customize the theme.
itheme <- default_inner_theme(inner_margin = 10)

# This is the usual syntax.
thinkgrid_quadrant_plot(p1, p2, p3, p4, inner_theme = itheme)

Creates a Qualtrics importable survey file from a CSV file of questions.

Description

Creates a Qualtrics importable survey file from a CSV file of questions.

Usage

generate_survey(
  survey_setup_file,
  output_file_name = "output_survey",
  question_text = TRUE
)

Arguments

Value

None

Examples

## Not run: 
# Generate survey from sample setup file (requires Python)
setup_file <- system.file("extdata", "sample_setup_file.csv", package = "ThinkingGrid")
if (file.exists(setup_file)) {
  generate_survey(setup_file, "_temp_output_")
  # Clean up
  file.remove("_temp_output_-0.qsf")
}

## End(Not run)

Create Thinking Grid Visualizations

Description

Generate various types of Thinking Grid plots from survey data containing deliberate and automatic constraint responses.

Usage

plot_tg(
  survey_results,
  proportion_type = "overall",
  type = "depth",
  colorer = NULL,
  palette = "RdYlBu",
  zero_color = "#FFFFFF",
  gradient_scaling = "linear",
  enhanced_threshold_pct = 50,
  enhanced_expansion_factor = 1.5,
  x_label = "Directedness",
  y_label = "Stickiness",
  dc_column = "Deliberate.Constraints",
  ac_column = "Automatic.Constraints",
  condition_column = NULL,
  comparison_type = "separate",
  max_legend = NULL,
  min_legend = NULL,
  plot_title = NULL,
  legend_title = NULL,
  plot_subtitle = NULL,
  subset_condition = NULL
)

Arguments

Details

The function expects constraint responses on a 1-6 scale where deliberate constraints (x-axis) range from 1 = low directedness to 6 = high directedness, and automatic constraints (y-axis) range from 1 = low stickiness to 6 = high stickiness.

For enhanced scaling, the algorithm compresses small values in the color space to give them more visual distinction. This is useful when most responses are in lower ranges.

Value

A list containing: plot (ggplot object or list of ggplot objects for 3+ conditions) and prop_data (calculated proportion data).

Examples

## Create sample data for testing
set.seed(123)  ## For reproducible examples
survey_data <- data.frame(
  Deliberate.Constraints = sample(1:6, 100, replace = TRUE),
  Automatic.Constraints = sample(1:6, 100, replace = TRUE),
  treatment_group = sample(c("A", "B"), 100, replace = TRUE),
  age = sample(20:60, 100, replace = TRUE),
  experience = sample(1:5, 100, replace = TRUE)
)

## Basic overall plot
result1 <- plot_tg(survey_data)

## Cell-level heatmap with enhanced scaling for small values
result2 <- plot_tg(survey_data, 
                   type = "cells", 
                   gradient_scaling = "enhanced",
                   enhanced_threshold_pct = 30,
                   enhanced_expansion_factor = 2.0)

## Compare conditions side by side
result3 <- plot_tg(survey_data, 
                   proportion_type = "condition",
                   condition_column = "treatment_group",
                   comparison_type = "separate")

## Subset data before analysis
result4 <- plot_tg(survey_data, 
                   subset_condition = "age > 25 & experience >= 2",
                   type = "quadrants")

Parses Qualtrics survey output into a dataframe.

Description

Parses Qualtrics survey output into a dataframe.

Usage

read_qualtrics_data(data_file, setup_file)

Arguments

Value

data frame containing the Qualtrics data. Columns include "uid", "Probe.Identifier", "Deliberate.Constraints", "Automatic.Constraints"

uid: Unique identifier for each participant. This correspons to the row number in the Qualtrics output file.

Probe.Identifier: Identifier for the probe. This is the same as the "id" column in the setup_file.

Deliberate.Constraints: The deliberate constraints provided by the participant. (X-axis on the thinking grid)

Automatic.Constraints: The automatic constraints provided by the participant. (Y-axis on the thinking grid)

Examples

## Not run: 
# Read Qualtrics survey data (requires Python)
setup_file <- system.file("extdata", "sample_setup_file.csv", package = "ThinkingGrid")
data_file <- system.file("extdata", "sample_qualtrics_output.csv", package = "ThinkingGrid")
if (file.exists(setup_file) && file.exists(data_file)) {
  survey_data <- read_qualtrics_data(data_file, setup_file)
}

## End(Not run)

Creates the background for ThinkingGrid plots.

Description

Creates the background for ThinkingGrid plots.

Usage

thinkgrid_quadrant_background(
  arrowwidth = 1,
  xlab = "Executive Control",
  ylab = "Salience"
)

Arguments

Value

A plot containing the 6x6 grid background image for the 2x2 thinkgrid plots which also contains the xy-axis arrows and labels.

Creates a 2x2 plot grid overlayed on top of a ThinkingGrid background.

Description

Creates a 2x2 quadrant plot with four ggplot objects.

Usage

thinkgrid_quadrant_plot(
  p_sticky,
  p_salience,
  p_free,
  p_directed,
  inner_theme = NULL,
  arrowwidth = 1,
  xlab = "Executive Control",
  ylab = "Salience"
)

Arguments

Value

A ggplot object (created via cowplot) which consists of the thinking grid background and the inlayed 2x2 subplots (or images) corresponding to the respective quadrant.

Examples

# This is a list of four plots generated by some regression. Their exact nature is not
# important aside from the fact that they are ggplot objects.
plots <- ThinkingGrid::create_test_2x2_plots()
p1 <- plots[[1]]
p2 <- plots[[2]]
p3 <- plots[[3]]
p4 <- plots[[4]]

# This is the usual syntax.
thinkgrid_quadrant_plot(p1, p2, p3, p4)


# However, it is possible to use images as the subplots. IDEALLY, one uses an image
# type without backgrounds such as a PNG.
img_path <- system.file("extdata", "rabbiduck.png", package = "ThinkingGrid")
rabbi <- png::readPNG(img_path)
rabbigrob <- grid::rasterGrob(rabbi)  # Note you must raster the image!

# Create sample plots for demonstration
plots <- ThinkingGrid::create_test_2x2_plots()
thinkgrid_quadrant_plot(p1, p2, p3, rabbigrob)