R: Remove cardinal biases

remove_cardinal_biases {circhelp}

R Documentation

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
)

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:

Create two sets of bins, splitting the stimuli vector into bins centered at cardinal and at oblique directions.
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).
Choose the best-fitting model between the one using cardinal and the one using oblique bins.
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.

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

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). 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. 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
)

[Package circhelp version 1.1 Index]