quickpsy: Fits psychometric functions

In danilinares/quickpsy: Fits Psychometric Functions for Multiple Groups

Fits psychometric functions

Description

quickpsy fits, by direct maximization of the likelihood (Prins and Kingdom, 2010; Knoblauch and Maloney, 2012), psychometric functions of the form

ψ(x) = γ + (1 - γ - λ) * fun(x)

where γ is the guess rate, λ is the lapse rate and fun is a sigmoidal-shape function with asymppotes at 0 and 1.

Usage

quickpsy(
  d,
  x = x,
  k = k,
  n = NULL,
  grouping = c(),
  xmin = NULL,
  xmax = NULL,
  log = FALSE,
  fun = cum_normal_fun,
  parini = NULL,
  guess = 0,
  lapses = 0,
  prob = NULL,
  thresholds = TRUE,
  bootstrap = "parametric",
  B = 100,
  ci = 0.95,
  control = NULL,
  parinivector = NULL,
  paircomparisons = FALSE
)

Arguments

d	Data frame with a tidy form in which each column corresponds to a variable and each row is an observation.
x	Name of the explanatory variable.
k	Name of the response variable. It could be the number of trials in which a yes-type response was given or a vector of 0s (no-type response) and 1s (yes-type response) indicating the response on each trial.
n	Only necessary if k refers to the number of trials in which a yes-type response was given. It corresponds to the name of the variable indicating the total number of trials.
grouping	Name of the grouping variables. It should be specified as grouping = c("variable_name1", "variable_name2").
xmin	Minimum value of the explanatory variable for which the curves should be calculated (the default is the minimum value of the explanatory variable).
xmax	Maximum value of the explanatory variable for which the curves should be calculated (the default is the maximum value of the explanatory variable).
log	If TRUE, the logarithm in base 10 of the explanatory variable is used to fit the curves (default is FALSE).
fun	Name of the shape of the curve to fit. It could be a predefined shape (cum_normal_fun, logistic_fun, weibull_fun) or the name of a function introduced by the user. It could also be a data frame of functions we shared parameters. See the vignetter functions. (default is cum_normal_fun).
parini	Initial parameters. quickpsy calculates default initial parameters for the predefined functions by linear modelling of the probit-transformed data. Otherwise, parini could be a vector of initial parameters a list of the form list(c(par1min, par1max), c(par2min, par2max)) to constraint the lower and upper bounds of the parameters a dataframe specifiying the initial parameters for each condition with the same structure that the output par, but without the confidence intervals. a dataframe specifiying the lower (the column should be called parmin) and upper bound (the column should be called parmax) for each condition.
guess	Value indicating the guess rate (leftward asymptote) γ (default is 0). If TRUE, the guess rate is estimated as the i + 1 parameter where i corresponds to the number of parameters of fun. If, for example, fun is a predefined shape with parameters p1 and p2, then the guess rate corresponds to parameter p3.
lapses	Value indicating the lapse rate (rightward asymptote) λ (default is 0). If TRUE, the lapse rate is estimated as the i + 1 parameter where i corresponds to the number of parameters of fun plus one if the guess rate is estimated. If, for example, fun is a predefined shape with parameters p1 and p2, then the lapse rate corresponds to parameter p3. If the guess rate is also estimated, p3 will be the guess rate and p4 the lapse rate.
prob	Probability to calculate the threshold (default is guess + .5 * (1 - guess)).
thresholds	If FALSE, thresholds are not calculated (default is TRUE).
bootstrap	'parametric' performs parametric bootstrap; 'nonparametric' performs non-parametric bootstrap; 'none' does not perform bootstrap (default is 'parametric').
B	number of bootstrap samples (default is 100 ONLY).
ci	Bootstrap confidence intervals level based on percentiles (default is .95).
control	control argument of the optim function.
parinivector	A optional vector of initials parameters when the lower and the upper bounds of the parameter are specified.
paircomparisons	If TRUE bootstrap paircomparions of the parameters are performed. Default is FALSE

Value

A list containing the following components:

• x, k, n

• grouping The grouping variables.

• funname String with the name of the shape of the curve.

• psyfunguesslapses Curve including guess and lapses.

• limits Limits of the curves.

• parini Initial parameters.

• ypred Predicted probabilities at the values of the explanatory variable.

• curves Psychometric curves.

• par Fitted parameters and its confidence intervals.

• parcomnparisons Pair-wise comparisons of the parameters to assess whether two parameters are significantly different using bootstrap. Specifically, the parameter bootstrap samples for each of the two conditions are substrated and then it is considered whether zero was within the confidence interval level of the distributions of differences.

• curvesbootstrap Bootstrap psychometric curves.

• thresholds Thresholds and its confidence intervals.

• thresholdscomparisons Pair-wise comparisons of the thresholds.

• logliks Log-likelihoods of the model.

• loglikssaturated Log-likelihoods of the saturated model.

• deviance Deviance of the model and the p-value calculated by using the chi-square distribution and bootstraping.

• aic AIC of the model defined as

  - 2 * loglik + 2 *k

  where k is the number of parameters of the model.

References

Burnham, K. P., & Anderson, D. R. (2003). Model selection and multimodel inference: a practical information-theoretic approach. Springer Science & Business Media.

Knoblauch, K., & Maloney, L. T. (2012). Modeling Psychophysical Data in R. New York: Springer.

Prins, N., & Kingdom, F. A. A. (2016). Psychophysics: a practical introduction. London: Academic Press.

Examples

library(quickpsy)
fit <- quickpsy(qpdat, phase, resp,
grouping = c("participant", "cond"), bootstrap = "none")
plot(fit)
plot(fit, color = cond)
plotpar(fit)
plotthresholds(fit, geom = "point")

danilinares/quickpsy documentation built on Feb. 13, 2023, 8:44 p.m.