circhelp (version 1.1)

remove_cardinal_biases: Remove cardinal biases

Description

Remove cardinal biases

Usage

remove_cardinal_biases(
  err,
  x,
  space = "180",
  bias_type = "fit",
  plots = "hide",
  poly_deg = 4,
  var_sigma = TRUE,
  var_sigma_poly_deg = 4,
  reassign_at_boundaries = TRUE,
  reassign_range = 2,
  break_points = NULL,
  init_outliers = NULL,
  debug = FALSE,
  do_plots = NULL
)

Value

If plots=='return', returns the three plots showing the biases (combined together with patchwork::wrap_plots()). Otherwise, returns a list with the following elements:

• is_outlier - 0 for outliers (defined as ±3*pred_sigma for the model with varying sigma or as ±3\*SD for the simple model)

• pred predicted error

• be_c error corrected for biases (be_c = observed error - pred)

• which_bin the numeric ID of the bin that the stimulus belong to

• bias the bias computed as described above

• bias_typ bias type (cardinal or oblique)

• pred_lin predicted error for a simple linear model for comparison

• pred_sigma predicted SD of the error distribution

• coef_sigma_int, coef_sigma_slope intercept and slope for the sigma prediction

Arguments

err

a vector of errors, deviations of response from the true stimuli

x

a vector of true stimuli in degrees (see space)

space

circular space to use (a string: 180 or 360)

bias_type

bias type to use (fit, card, obl, or custom, see details)

plots

a string hide, show, or return to hide, show, or return plots (default: hide)

poly_deg

degree of the fitted polynomials for each bin (default: 4)

var_sigma

allow standard deviation (width) of the fitted response distribution to vary as a function of distance to the nearest cardinal (default: True)

var_sigma_poly_deg

degree of the fitted polynomials for each bin for the first approximation for the response distribution to select the best fitting model (default: 4)

reassign_at_boundaries

select the bin for the observations at the boundaries between bins based on the best-fitting polynomial (default: True)

reassign_range

maximum distance to the boundary at which reassignment can occur (default: 2 degrees)

break_points

can be used to assign custom break points instead of cardinal/oblique ones with bias_type set to custom (default: NULL)

init_outliers

a vector determining which errors are initially assumed to be outliers (default: NULL)

debug

print some extra info (default: False)

do_plots

deprecated, use the parameter plots instead

Details

If the bias_type is set to fit, the function computes the cardinal biases in the following way:

1. Create two sets of bins, splitting the stimuli vector into bins centered at cardinal and at oblique directions.

2. For each set of bins, fit a nth-degree polynomial for the responses in each bin, optionally allowing the distribution of responses to vary in width as a function of distance to the nearest cardinal (regardless of whether the bins are centered at the cardinal or at the oblique, the width of the response distribution usually increases as the distance to cardinals increase).

3. Choose the best-fitting model between the one using cardinal and the one using oblique bins.

4. Compute the residuals of the best-fitting model - that's your bias-corrected error - and the biases (see below).

The bias is computed by flipping the sign of errors when the average predicted error is negative, so, that, for example, if on average the responses are shifted clockwise relative to the true values, the trial-by-trial error would count as bias when it is also shifted clockwise.

If bias_type is set to obl or card, only one set of bins is used, centred at cardinal or oblique angles, respectively.

References

• Chetverikov, A., & Jehee, J. F. M. (2023). Motion direction is represented as a bimodal probability distribution in the human visual cortex. Nature Communications, 14(7634). tools:::Rd_expr_doi("10.1038/s41467-023-43251-w")

• van Bergen, R. S., Ma, W. J., Pratte, M. S., & Jehee, J. F. M. (2015). Sensory uncertainty decoded from visual cortex predicts behavior. Nature Neuroscience, 18(12), 1728–1730. tools:::Rd_expr_doi("10.1038/nn.4150")

Examples

# Data in orientation domain from Pascucci et al. (2019, PLOS Bio),
# https://doi.org/10.5281/zenodo.2544946

ex_data <- Pascucci_et_al_2019_data[observer == 4, ]
remove_cardinal_biases(ex_data$err, ex_data$orientation, plots = "show")

# Data in motion domain from Bae & Luck (2018, Neuroimage),
# https://osf.io/2h6w9/
ex_data_bae <- Bae_Luck_2018_data[subject_Num == unique(subject_Num)[5], ]
remove_cardinal_biases(ex_data_bae$err, ex_data_bae$TargetDirection,
  space = "360", plots = "show"
)

# Using a stricter initial outlier boundary

remove_cardinal_biases(ex_data_bae$err, ex_data_bae$TargetDirection,
  space = "360", plots = "show",
  init_outliers = abs(ex_data_bae$err) > 60
)

# We can also use just one bin by setting `bias_type` to custom
# and setting the `break_points` at the ends of the range for x

remove_cardinal_biases(ex_data_bae$err, ex_data_bae$TargetDirection,
  space = "360", bias_type = "custom",
  break_points = c(-180, 180), plots = "show",
  reassign_at_boundaries = FALSE, poly_deg = 8,
  init_outliers = abs(ex_data_bae$err) > 60
)