Movatterモバイル変換

calmr: Canonical Associative Learning Models and their Representations

Description

Implementations of canonical associative learning models, with tools to run experiment simulations, estimate model parameters, and compare model representations. Experiments and results are represented using S4 classes and methods.

Author(s)

Maintainer: Victor Navarronavarrov@cardiff.ac.uk [copyright holder]

See Also

Useful links:

• https://github.com/victor-navarro/calmr

• https://victornavarro.org/calmr/

• Report bugs athttps://github.com/victor-navarro/calmr/issues

S4 class for calmr designs

Description

S4 class for calmr designs

Slots

design:

A list containing design information.

mapping:

A list containing the object mapping.

raw_design:

The original data.frame.

CalmrDesign methods

Description

S4 methods forCalmrDesign class.

Usage

## S4 method for signature 'CalmrDesign'show(object)## S4 method for signature 'CalmrDesign'mapping(object)## S4 method for signature 'CalmrDesign'trials(object)

Arguments

Value

show() returns NULL (invisibly).

mapping() returns a list with trial mappings.

trials() returns NULL (invisibly).

S4 class for calmr experiments.

Description

S4 class for calmr experiments.

Slots

design:

ACalmrDesign object.

groups:

A string specifying the groups in the design.

model:

A string specifying the model used.

parameters:

A list with the parameters used, per group.

timings:

A list with the timings used in the design.

experiences:

A list with the experiences for the model.

results:

A list with aggregated results.

models:

The models associated with the iteration.

.groups:

Internal. The groups associated with the iteration.

.iter:

Internal. The iteration number.

.seed:

The seed used to generate the experiment.

See Also

CalmrExperiment-methods

CalmrExperiment methods

Description

S4 methods forCalmrExperiment class.

Usage

## S4 method for signature 'CalmrExperiment'show(object)## S4 method for signature 'CalmrExperiment'design(x)## S4 method for signature 'CalmrExperiment'trials(object)## S4 method for signature 'CalmrExperiment'parameters(x)## S4 replacement method for signature 'CalmrExperiment'parameters(x) <- value## S4 method for signature 'CalmrExperiment'experiences(x)## S4 replacement method for signature 'CalmrExperiment'experiences(x) <- value## S4 method for signature 'CalmrExperiment'results(object)## S4 method for signature 'CalmrExperiment'raw_results(object)## S4 method for signature 'CalmrExperiment'parsed_results(object)## S4 method for signature 'CalmrExperiment'length(x)## S4 method for signature 'CalmrExperiment'parse(object, outputs = NULL)## S4 method for signature 'CalmrExperiment'aggregate(x, outputs = NULL)## S4 method for signature 'CalmrExperiment'plot(x, type = NULL, ...)## S4 method for signature 'CalmrExperiment'graph(x, ...)## S4 method for signature 'CalmrExperiment'timings(x)## S4 replacement method for signature 'CalmrExperiment'timings(x) <- value## S4 method for signature 'CalmrExperiment'filter(x, trial_types = NULL, phases = NULL, stimuli = NULL)

Arguments

Value

show() returns NULL (invisibly).

design() returns theCalmrDesign contained in the object.

trials() returns NULL (invisibly).

parameters() returns the list of parameterscontained in the object.

⁠parameters()<-⁠ returns the object after updating parameters.

experiences() returns a list ofdata.frame objectscontaining model training routines.

⁠experiences()<-⁠ returns the object after updating experiences.

results() returns adata.table objects with aggregated results.

raw_results() returns a list with raw model results.

parsed_results() returns a list ofdata.tableobjects with parsed results.

length() returns an integer specifying the total lengthof the experiment (groups by iterations).

parse() returns the object after parsing raw results.

aggregate() returns the object after aggregating parsed results.

plot() returns a list of 'ggplot' plot objects.

graph() returns a list of 'ggplot' plot objects.

timings() returns the list of timingscontained in the object.

⁠timings()<-⁠ returns the object after updating timings.

filter() returns the object after filteringparsed aggregated results

S4 class for calmr Fit

Description

S4 class for calmr Fit

Slots

nloglik:

Numeric. Negative log likelihood of the fit

best_pars:

Numeric. Best fitting parameters

model_pars:

Numeric. Parameters used in the model function

link_pars:

Numeric. Parameters used in the link function

data:

Numeric. Data used for fit

model_function:

Function. Model function

link_function:

Function. Link function

ll_function:

Function. Objective function(usually nloglikelihood)

optimizer_options:

List. Options used for the optimizer

extra_pars:

List. Extra parameterspassed to the fit call (...)

See Also

CalmrFit-methods

CalmrFit methods

Description

S4 methods forCalmrFit class.

Usage

## S4 method for signature 'CalmrFit'show(object)## S4 method for signature 'CalmrFit'predict(object, type = "response", ...)## S4 method for signature 'CalmrFit'NLL(object)## S4 method for signature 'CalmrFit'AIC(object, k = 2)## S4 method for signature 'CalmrFit'BIC(object)

Arguments

Details

Withtype = "response", thepredict() functionpassed model responses to the link function used to fit the model.

The AIC is defined as2*k - 2*-NLL, where k is a penaltyterm and NLL is the negative log likelihood of the model.

The BIC is defined asp*log(n) - 2*-NLL, where p is the numberof parameters in the model and n is the number of observations

Value

• show() returns NULL (invisibly).

• predict() returns a numeric vector.

• NLL() returns the negative log likelihood of the model.

• AIC() returns the Akaike Information Criterion (AIC) of the model.

• BIC() returns the Bayesian Information Criterion (BIC) of the model.

S4 class for calmr Models

Description

S4 class for calmr Models

Slots

model_name

A model name string

outputs

A character vector with model outputs

parameters

A list with the model with model parameters

default_parameters

A list with the default model parameters

.internal_states

A character vector with internal states

.is_timed

A logical indicating if the model is timed

.associations

A character vector with associations output name

.dnames_map

A list with data names mapping for outputs

.parse_map

A list with parse functions for outputs

.formula_map

A list with formula mapping for outputs

.plots_map

A list with plot functions for outputs

.last_experience

A data.frame with the last experience run

.last_raw_results

A list with the last raw results

.last_parsed_results

A list with the last parsed results

CalmrModel methods

Description

S4 methods forCalmrModel

Usage

## S4 method for signature 'CalmrModel'run(object, experience, mapping, timings, ...)## S4 method for signature 'CalmrModel'parameters(x)## S4 replacement method for signature 'CalmrModel'parameters(x) <- value## S4 method for signature 'CalmrModel'raw_results(object)## S4 method for signature 'CalmrModel'parsed_results(object)## S4 method for signature 'CalmrModel'show(object)## S4 method for signature 'CalmrModel'parse(object, outputs = object@outputs)## S4 method for signature 'CalmrModel'plot(x, type = NULL, ...)## S4 method for signature 'CalmrModel'graph(x, ...)## S4 method for signature 'ANCCR'run(object, experience, mapping, timings, ..., debug = FALSE, debug_t = -1)## S4 method for signature 'HDI2020'run(object, experience, mapping, ...)## S4 method for signature 'HD2022'run(object, experience, mapping, ...)## S4 method for signature 'MAC1975'run(object, experience, mapping, ...)## S4 method for signature 'PKH1982'run(object, experience, mapping, ...)## S4 method for signature 'RAND'run(object, experience, mapping, ...)## S4 method for signature 'RW1972'run(object, experience, mapping, ...)## S4 method for signature 'SM2007'run(  object,  experience,  mapping,  debug = FALSE,  comparator_func = .witnauer_comparator_proc,  ...)## S4 method for signature 'TD'run(object, experience, mapping, timings, ...)

Arguments

Value

run() returns theCalmrModel afterrunning the phases in the design.

parameters() returns the parametersof theCalmrModel object.

⁠parameters()<-⁠ sets the parameters of aCalmrModel object.

raw_results() returns the lastraw results of theCalmrModel object.

parsed_results() returns the lastparsed results of theCalmrModel object.

show() returns NULL (invisibly).

parse() returnsCalmrModel with parsed results.

plot() returns a list of 'ggplot' plot objects.

graph() returns a 'ggplot' object.

Note

Therun method changes some internalstates of the model (if appropriate) andpopulates the.last_raw_results slot with the results of the run.

S4 class for calmr representational similarity analysis

Description

S4 class for calmr representational similarity analysis

Slots

corr_mat:

An array containing the correlation matrix

distances:

A list of pairwise distance matrices

args:

A list of the arguments used to create the object.

test_data:

A list with permutation data,only populated after testing the object.

CalmrRSA methods

Description

S4 methods forCalmrRSA class.

Usage

## S4 method for signature 'CalmrRSA'show(object)## S4 method for signature 'CalmrRSA'test(object, n_samples = 1000, p = 0.95)## S4 method for signature 'CalmrRSA'plot(x)

Arguments

Value

• show() returns NULL (invisibly).

• test() returns theCalmrRSA object with permutation test data.

• plot() returns a list of 'ggplot' plot objects.

Create a graph with calmr data

Description

patch_graphs() patches graphs with 'patchwork'

Usage

calmr_model_graph(  x,  loops = TRUE,  limits = max(abs(x$value)) * c(-1, 1),  colour_key = FALSE,  t = max(x$trial),  options = get_graph_opts())patch_graphs(graphs, selection = names(graphs))get_graph_opts(graph_size = "small")

Arguments

Value

A 'ggplot' object

patch_graphs() returns a 'patchwork' object

A list with graph options, to be passed toggnetwork::geom_nodes().

Note

You should probably be getting graphs viathe graph method forCalmrExperiment.

Set verbosity options for calmr

Description

Whether to show verbosity messages and progress bars

Usage

calmr_verbosity(verbose)

Arguments

Value

The list of progressr handlers (invisibly).

Note

Progress bars are handled by the progressr package.This is just a convenience function.

See package 'progressr' for further details.

Run models given a set of parameters

Description

Run models given a set of parameters

Usage

compare_models(x, models = NULL, ...)

Arguments

Value

A list ofCalmrExperiment objects

Examples

# By making experiment beforehand (recommended)df <- get_design("blocking")models <- c("HD2022", "RW1972", "PKH1982")exps <- lapply(models, function(m) {  make_experiment(df,    parameters = get_parameters(df, model = m),    model = m  )})comp <- compare_models(exps)# By passing minimal arguments (not recommended; default parameters)comp <- compare_models(df, models = models)

Fit model to data

Description

Obtain MLE estimates for model, given data.

Usage

fit_model(data, model_function, optimizer_options, file = NULL, ...)

Arguments

Value

ACalmrFit object

Note

See the calmr_fits vignette for examples

See Also

get_optimizer_opts()

Examples

# Make some fake datadf <- data.frame(g = "g", p1 = "!3A>(US)")pars <- get_parameters(df, model = "RW1972")pars$alphas["US"] <- 0.9exper <- make_experiment(df, parameters = pars, model = "RW1972")res <- run_experiment(exper, outputs = "responses")responses <- results(res)$responses$value# define model functionmodel_fun <- function(p, ex) {  np <- parameters(ex)  np[[1]]$alphas[] <- p  parameters(ex) <- np  results(run_experiment(ex))$responses$value}# Get optimizer optionsoptim_opts <- get_optimizer_opts(  model_pars = names(pars$alphas),  ll = rep(.05, 2), ul = rep(.95, 2),  optimizer = "optim", family = "identity")optim_opts$initial_pars[] <- rep(.6, 2)fit_model(responses, model_fun, optim_opts,  ex = exper, method = "L-BFGS-B",  control = list(maxit = 1))

Get basic designs

Description

Get basic designs

Usage

get_design(design_name = NULL)

Arguments

Value

If design_name is not NULL, a data.frame containing the design.Otherwise, a list containing all available designs.

See Also

parse_design()

Examples

names(get_design())get_design("blocking")

Get optimizer options

Description

Get optimizer options

Usage

get_optimizer_opts(  model_pars,  initial_pars = rep(NA, length(model_pars)),  ll = rep(NA, length(model_pars)),  ul = rep(NA, length(model_pars)),  optimizer = NULL,  family = NULL)

Arguments

Value

A list with optimizer options.

Note

Whenever a family function other than the identity is used,the family-specific parameters will always be appended tothe end of the relevant lists.

See Also

fit_model()

Get model parameters

Description

Get model parameters

Usage

get_parameters(design, model)

Arguments

Value

A list with model parameters depending on model

Examples

block <- get_design("blocking")get_parameters(block, model = "SM2007")

Get timing design parameters

Description

Get timing design parameters

Usage

get_timings(design, model)

Arguments

Value

A list of timing design parameters.

Examples

block <- get_design("blocking")get_timings(block, model = "TD")

Make CalmrExperiment

Description

Makes aCalmrExperiment object containingthe arguments necessary to run an experiment.

Usage

make_experiment(  design,  model,  parameters = NULL,  timings = NULL,  iterations = 1,  miniblocks = TRUE,  seed = NULL,  .callback_fn = NULL,  ...)

Arguments

Value

ACalmrExperiment object.

Note

The miniblocks option will direct the sampling function to createequally-sized miniblocks with random trials within a phase.For example, the phase string "2A/2B" will create two miniblockswith one of each trial. The phase string "2A/4B" will create two miniblockswith one A trial, and 2 B trials. However, the phase string "2A/1B" willnot result in miniblocks, even if miniblocks here is set to TRUE.

See Also

parse_design(),

Examples

des <- data.frame(Group = "G1", P1 = "10A>(US)")ps <- get_parameters(des, model = "HD2022")make_experiment(  design = des, parameters = ps,  model = "HD2022", iterations = 2)

Model information functions

Description

An assortment of functions to return model information.

Usage

supported_models()supported_timed_models()supported_optimizers()supported_families()supported_plots(model = NULL)get_model(model)model_parameters(model = NULL)model_outputs(model = NULL)

Arguments

Value

supported_models() returns a character vector.

supported_timed_models() returns a character vector.

supported_optimizers() returns a character vector.

supported_families() returns a character vector.

supported_plots() returns a character vector or list(if model is NULL).

get_model() returns aCalmrModel model instance.

model_parameters() returns a list or alist of lists (if model is NULL).

model_outputs() returns a character vector orlist (if model is NULL).

Examples

# Outputs and plots supported by the RW1972 modelmodel_outputs("RW1972")# Getting a model instance of the PKH1982 modelpkh_inst <- get_model("PKH1982")# Getting the `run` method for the MAC1975head(methods::getMethod("run", "MAC1975"), 10)# Getting the parameters required by SM2007model_parameters("SM2007")model_parameters("RW1972")

Parse design data.frame

Description

Parse design data.frame

Usage

parse_design(df)

Arguments

Value

ACalmrDesign object.

Note

Each entry in even-numbered columns of df isa string formatted as perphase_parser().

See Also

phase_parser()

Examples

df <- data.frame(  Group = c("Group 1", "Group 2"),  P1 = c("10AB(US)", "10A(US)"))parse_design(df)

Rat responses from Patittucci et al. 2016

Description

A dataset containing rat nose pokes and leverpresses when levers were associated with different appetitive stimuli.

Usage

pati

Format

A data.frame with the following variables:

subject

subject identifier

block

the 2-session block of training (1 to 8)

lever

lever presented on the trial: L = left; R = right

us

the stimulus that followed the lever: P = pellet; S = sucrose

response

the response: lp = lever press; np = nose poke

rpert

responses per trial

...

Source

Patittucci et al. (2016). JEP:ALC

Parses a phase string

Description

Parses a phase string

Usage

phase_parser(phase_string)

Arguments

Value

A named list with:

trial_info:

A trial-named list of lists.

general_info:

General phase information.

Note

This function is meant for internal use only,but we expose it so you can test your strings.

See Also

parse_design()

Examples

# A silly (but valid) stringphase_parser("10#Rescorla>Wagner")# An invalid string that needs trial repetitions for one of trials.try(phase_parser("10#Rescorla/Wagner"))

General plotting functions

Description

plot_targeted_tbins() plots targeted time data on a trial.

plot_tbins() plots non-targeted time data on a trial.

plot_targeted_trials() plots targeted trial data.

plot_trials() plots non-targeted trial data.

plot_targeted_typed_trials() plotstargeted trial data with a type.

plot_targeted_complex_trials() plotstargeted data with a third variable.

Usage

plot_targeted_tbins(data, t = max(data$trial))plot_tbins(data, t = max(data$trial))plot_targeted_trials(data)plot_trials(data)plot_targeted_typed_trials(data)plot_targeted_complex_trials(data, col)

Arguments

Value

plot_targeted_tbins() returns 'ggplot' object.

plot_tbins() returns 'ggplot' object.

plot_targeted_trials() returns 'ggplot' object.

plot_trials() returns 'ggplot' object.

plot_targeted_typed_trials() returns 'ggplot' object.

plot_targeted_complex_trials() returns 'ggplot' object.

Note

These functions are not meant to be used by non-developers.If you want to plot data from a model or an experiment,see theplot() method.All data must be parsed or aggregated, asreturned byresults() orparsed_results().

General plotting options

Description

plot_common_scale() rescales a list ofplots to have a common scale.

get_plot_opts() returns generic plotting options.

patch_plots() patches plots usingpatchwork package.

Usage

plot_common_scale(plots)get_plot_opts(common_scale = TRUE)patch_plots(plots, selection = names(plots), plot_options = get_plot_opts())

Arguments

Value

plot_common_scale() returns a list of plots.

get_plot_opts() returns a list.

patch_plots() returns apatchwork object.

Perform representational similarity analysis

Description

Perform representational similarity analysis

Usage

rsa(x, comparisons, test = FALSE, ...)

Arguments

Value

A CalmrRSA object

Note

The object returned by this functioncan be later tested via its owntest() method.

Examples

# Comparing the associations in three modelsexp <- data.frame(  Group = c("A", "B"),  P1 = c("!2(A)>(US)/1B>(US)", "!1(A)>(US)/2B>(US)"))models <- c("HD2022", "RW1972", "PKH1982")parameters <- sapply(models, get_parameters, design = exp)exp_res <- compare_models(exp,  models = models)comparisons <- list(  "HD2022" = c("associations"),  "RW1972" = c("associations"),  "PKH1982" = c("associations"))res <- rsa(exp_res, comparisons = comparisons)test(res, n_samples = 20)

Run experiment

Description

Runs an experiment with minimal parameters.

Usage

run_experiment(x, outputs = NULL, parse = TRUE, aggregate = TRUE, ...)

Arguments

Value

ACalmrExperiment with results.

Examples

# Using a data.frame only (throws warning)df <- get_design("relative_validity")run_experiment(df, model = "RW1972")# Using custom parametersdf <- get_design("relative_validity")pars <- get_parameters(df, model = "HD2022")pars$alphas["US"] <- 0.6run_experiment(df, parameters = pars, model = "HD2022")# Using make_experiment, for more iterationsdf <- get_design("blocking")pars <- get_parameters(df, model = "SM2007")exper <- make_experiment(df,  parameters = pars, model = "SM2007",  iterations = 4)run_experiment(exper)# Only parsing the associations in the model, without aggregationrun_experiment(exper, outputs = "associations", aggregate = FALSE)

Get/set the colour/fill palette for plots

Description

Get/set the colour/fill palette for plots

Usage

set_calmr_palette(palette = NULL)

Arguments

Value

The old palette (invisibly) if palette is not NULL.Otherwise, a character vector of available palettes.

Note

Changes here do not affect the palette used in graphs.

Set reward parameters for ANCCR model

Description

Set reward parameters for ANCCR model

Usage

set_reward_parameters(parameters, rewards = c("US"))

Arguments

Value

A list of parameters

Note

The default behaviour ofget_parameters for the ANCCR model is toset every reward-related parameter to its non-zero default value.This function will set those parameters to zero for non-reward stimuli