Title: | Linear Approach to Threshold with Ergodic Rate for Reaction Times |
Version: | 0.2.0 |
Description: | Implements the Linear Approach to Threshold with Ergodic Rate (LATER) model, which predicts distributions of reaction times and summarises them with as little as two free parameters. Allows for easy visualisation and comparison of datasets, along with fitting of datasets using the LATER model. |
License: | MIT + file LICENSE |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.1 |
Imports: | dplyr, ggplot2, rlang, stats, tibble, parallel, moments |
Depends: | R (≥ 4.1) |
LazyData: | true |
Suggests: | lintr, styler, testthat (≥ 3.0.0), vdiffr, printr, withr |
Config/testthat/edition: | 3 |
URL: | https://github.com/unimelbmdap/LATERmodel, https://unimelbmdap.github.io/LATERmodel/ |
BugReports: | https://github.com/unimelbmdap/LATERmodel/issues |
Config/Needs/website: | rmarkdown |
NeedsCompilation: | no |
Packaged: | 2024-05-03 06:16:05 UTC; mquiroga |
Author: | Maria del Mar Quiroga
|
Maintainer: | Maria del Mar Quiroga <mar.quiroga@unimelb.edu.au> |
Repository: | CRAN |
Date/Publication: | 2024-05-03 13:20:02 UTC |
Digitised data corresponding to Figure 2 of Carpenter and Williams (1995)
Description
Digitised data corresponding to Figure 2 of Carpenter and Williams (1995)
Usage
carpenter_williams_1995
Format
carpenter_williams_1995
A dataframe of 20014 reaction times for participant a and 22518 reaction times for participant b
- participant
Participant "name", either "a" or "b"
- condition
Prior percentage probability of the target being in the location of the eye movement (p05, p10, p25, p50, p75, p90, or p95)
- time
Saccadic latency in ms
Source
Carpenter, R. H., & Williams, M. L. L. (1995). Neural computation of log likelihood in control of saccadic eye movements. Nature, 377(6544), 59-62.
Compares the goodness-of-fit of a set of fit outcomes.
Description
Compares the goodness-of-fit of a set of fit outcomes.
Usage
compare_fits(fits)
Arguments
fits |
A list where each item has a name that identifies the fit and a
value given by the output of |
Details
The 'evidence ratio' is calculated as per Motulsky & Christopolous (2004), p. 146.
Value
A list of fit comparison results, ordered such that the fit with the lowest AIC value is in the first row.
-
aic
contains the fit AIC values. -
preferred_rel_fit_delta_aic
is the AIC value for the fit relative to the AIC of the fit with the lowest AIC (preferred AIC - current AIC). -
preferred_rel_fit_evidence_ratio
is the evidence ratio for the fit with the lowest AIC relative to the current fit. -
preferred
is a boolean that indicates whether the fit has the lowest AIC value among the fits (is 'preferred').
Examples
data <- rbind(
data.frame(name = "test", time = 1000/rnorm(100, 3, 1)),
data.frame(name = "test_2", time = 1000/rnorm(100, 1, 1))
) |> dplyr::filter(time > 0)
data <- prepare_data(data)
fit_a <- fit_data(data = data, share_a = TRUE)
fit_b <- fit_data(data = data, share_sigma = TRUE)
comparison <- compare_fits(fits = list(a = fit_a, b = fit_b))
Fit a LATER model to a single dataset or a pair of datasets.
Description
Fit a LATER model to a single dataset or a pair of datasets.
Usage
fit_data(
data,
share_a = FALSE,
share_sigma = FALSE,
share_sigma_e = FALSE,
with_early_component = FALSE,
intercept_form = FALSE,
use_minmax = FALSE,
fit_criterion = "likelihood",
jitter_settings = list(n = 7, prop = 0.5, seed = NA, processes = 2)
)
Arguments
data |
A data frame with columns |
share_a , share_sigma , share_sigma_e |
If |
with_early_component |
If |
intercept_form |
If |
use_minmax |
If |
fit_criterion |
String indicating the criterion used to optimise the fit by seeking its minimum.
|
jitter_settings |
Settings for running the fitting multiple times with randomly-generated offsets ('jitter') applied to the starting estimates.
|
Value
A list of fitting arguments and outcomes.
-
fitted_params
is a named list of fitted parameter values. -
named_fit_params
is a data frame with rows given by the dataset names and columns given by the parameter names. -
loglike
is the overall log-likelihood of the fit. -
aic
is the "Akaike's 'An Information Criterion'" value for the model. -
optim_result
is the raw output fromstats::optim
for the best fit. -
jitter_optim_results
contains the raw output from each call tostats::optim
for the different start points.
Examples
data <- data.frame(name = "test", promptness = rnorm(100, 3, 1))
data_other <- data.frame(name = "test_2", promptness = rnorm(100, 1, 1))
fit_shared_sigma <- fit_data(
data = rbind(data, data_other), share_sigma = TRUE
)
Fit individual LATER model to each dataset in a dataframe of datasets
Description
Fit individual LATER model to each dataset in a dataframe of datasets
Usage
individual_later_fit(
df,
with_early_component = FALSE,
fit_criterion = "likelihood",
jitter_settings = list(n = 7, prop = 0.5, seed = NA, processes = 2)
)
Arguments
df |
A dataframe with columns: |
with_early_component |
If |
fit_criterion |
String indicating the criterion used to optimise the fit by seeking its minimum.
|
jitter_settings |
Settings for running the fitting multiple times with randomly-generated offsets ('jitter') applied to the starting estimates.
|
Value
A dataframe with one row for each named dataset in df
and columns
equal to the LATER model parameters returned by fit_data$named_fit_params
Examples
data <- rbind(
data.frame(name = "test", promptness = rnorm(100, 3, 1)),
data.frame(name = "test_2", promptness = rnorm(100, 1, 1))
)
fit_params <- individual_later_fit(data)
Apply two-sample KS test to all pairs of datasets contained within a dataframe
Description
Apply two-sample KS test to all pairs of datasets contained within a dataframe
Usage
ks_compare(df, correct_multiple_comparisons = TRUE)
Arguments
df |
A dataframe of datasets with columns: |
correct_multiple_comparisons |
If |
Value
A dataframe with columns name1
, name2
, D
, and p_value
Examples
data <- prepare_data(dplyr::filter(
carpenter_williams_1995,
participant == "b"
))
ks_compare(data)
Create a heatmap to visualise if there is not enough evidence to reject the null hypothesis that two datasets come from the same underlying distribution
Description
Create a heatmap to visualise if there is not enough evidence to reject the null hypothesis that two datasets come from the same underlying distribution
Usage
ks_heatmap(ks_results)
Arguments
ks_results |
A dataframe with columns |
Value
A heatmap plot with all paired comparisons
Examples
data <- prepare_data(dplyr::filter(
carpenter_williams_1995,
participant == "b"
))
ks_results <- ks_compare(data)
ks_heatmap(ks_results)
Evalulate the cumulative distribution function under the model.
Description
Evalulate the cumulative distribution function under the model.
Usage
model_cdf(q, later_mu, later_sd, early_sd = NULL)
Arguments
q |
Vector of quantiles |
later_mu |
Vector of the mean of the later component. |
later_sd |
Vector of the standard deviation of the later component. |
early_sd |
Vector of the standard deviation of the early component,
or |
Value
Vector of cumulative distribution values
Examples
model_cdf(q = 1, later_mu = 1, later_sd = 1)
model_cdf(q = 1, later_mu = 1, later_sd = 1, early_sd = 3)
Evalulate the probability density function under the model.
Description
Evalulate the probability density function under the model.
Usage
model_pdf(x, later_mu, later_sd, early_sd = NULL, log = FALSE)
Arguments
x |
Vector of quantiles |
later_mu |
Vector of the mean of the later component. |
later_sd |
Vector of the standard deviation of the later component. |
early_sd |
Vector of the standard deviation of the early component,
or |
log |
If |
Value
Vector of probabilities
Examples
model_pdf(x = 1, later_mu = 1, later_sd = 1)
model_pdf(x = 1, later_mu = 1, later_sd = 1, early_sd = 3)
Prepares data for reciprobit plot
Description
Prepares data for reciprobit plot
Usage
prepare_data(raw_data, time_unit = "ms", name_separator = "_")
Arguments
raw_data |
Vector of reaction times for a single participant, or a
dataframe containing a column called
|
time_unit |
Units of the reaction times in rt_vector, must be one of "ms", "ds", or "s". |
name_separator |
If the |
Value
A dataframe with columns: time
, color
, name
, promptness
,
and e_cdf
.
Examples
df <- prepare_data(carpenter_williams_1995)
Compute the empirical cumulative distribution function for promptness
Description
Compute the empirical cumulative distribution function for promptness
Usage
promptness_ecdf(promptness, adjust_for_times = TRUE, eval_unique = FALSE)
Arguments
promptness |
A vector of promptness values (1 / times) |
adjust_for_times |
If |
eval_unique |
If |
Value
A data frame with attributes:
-
x
is the values at which the ECDF was evaluated. -
y
is the evaluated value of the ECDF.
Examples
p <- promptness_ecdf(promptness = rnorm(100, 3, 1))
Plot reaction times and LATER model fit in reciprobit axes
Description
Plot reaction times and LATER model fit in reciprobit axes
Usage
reciprobit_plot(
plot_data,
fit_params = NULL,
time_breaks = c(0.1, 0.2, 0.3, 0.5, 1),
probit_breaks = c(0.1, 1, 5, 10, 20, 50, 80, 90, 95, 99, 99.9),
z_breaks = c(-2, -1, 0, 1, 2),
xrange = NULL,
yrange = NULL
)
Arguments
plot_data |
A dataframe with columns: |
fit_params |
A dataframe with one row for each named dataset and columns
equal to the LATER model parameters returned by |
time_breaks |
Desired tick marks on the x axis, expressed in promptness (1/s) |
probit_breaks |
Desired tick marks on the y axis in probit space |
z_breaks |
Desired tick marks on secondary y axis, in z values |
xrange |
Desired range for the x axis, in promptness (1/s) |
yrange |
Desired range for the y axis, in cumulative probability space |
Value
A reciprobit plot with the cumulative probability distribution of the reaction times
Examples
data <- rbind(
data.frame(name = "test", time = 1000/rnorm(100, 3, 1)),
data.frame(name = "test_2", time = 1000/rnorm(100, 4, 1))
) |> dplyr::filter(time > 0)
data <- prepare_data(data)
fit_params <- individual_later_fit(data)
reciprobit_plot(data, fit_params)
Digitised data corresponding to Figure 2 of Reddi, Asrress, and Carpenter, 2003.
Description
Digitised data corresponding to Figure 2 of Reddi, Asrress, and Carpenter, 2003.
Usage
reddi_asrress_carpenter_2003
Format
reddi_asrress_carpenter_2003
A dataframe of 1600 reaction times for participant J
- participant
Participant "name", equal to "J"
- condition
Different degrees of coherence of the kinematograms shown as stimuli, (64%, 32%, 16%, 8%: S, low-urgency–slow and accurate–conditions)
- time
Saccadic latency in ms
Source
Reddi, B. A., Asrress, K. N., & Carpenter, R. H. (2003). Accuracy, information, and response time in a saccadic decision task. Journal of Neurophysiology, 90(5), 3538-3546.
Simulate a dataset given model parameters.
Description
Generates samples from a set of provided LATER model parameters, with the option to iteratively replace invalid samples (reaction times <= 0).
Usage
simulate_dataset(
n,
later_mu,
later_sd,
early_sd = NULL,
seed = NA,
allow_negative_times = FALSE
)
Arguments
n |
Number of samples (trials) |
later_mu |
Mean of the later component. |
later_sd |
Standard deviation of the later component. |
early_sd |
Standard deviation of the early component,
or |
seed |
Seed for the random number generator |
allow_negative_times |
If |
Value
Vector of response times (in seconds)
Examples
simulate_dataset(n = 100, later_mu = 5, later_sd = 1)
simulate_dataset(n = 100, later_mu = 5, later_sd = 1, early_sd = 5)