Title: | Cumulative History Analysis for Bistable Perception Time Series |
---|---|
Description: | Estimates cumulative history for time-series for continuously viewed bistable perceptual rivalry displays. Computes cumulative history via a homogeneous first order differential process. I.e., it assumes exponential growth/decay of the history as a function time and perceptually dominant state, Pastukhov & Braun (2011) <doi:10.1167/11.10.12>. Supports Gamma, log normal, and normal distribution families. Provides a method to compute history directly and example of using the computation on a custom Stan code. |
Authors: | Alexander Pastukhov [aut, cre] |
Maintainer: | Alexander Pastukhov <[email protected]> |
License: | GPL (>= 3) |
Version: | 1.1.1 |
Built: | 2024-12-25 04:44:20 UTC |
Source: | https://github.com/alexander-pastukhov/bistablehistory |
Estimates cumulative history for time-series for continuously viewed bistable perceptual rivalry displays. Computes cumulative history via a homogeneous first order differential process. I.e., it assumes exponential growth/decay of the history as a function time and perceptually dominant state, Pastukhov & Braun (2011) doi:10.1167/11.10.12. Supports Gamma, log normal, and normal distribution families. Provides a method to compute history directly and example of using the computation on a custom Stan code.
Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.21.2. https://mc-stan.org
vignette("cumulative-history", package = "bistablehistory")
vignette("usage-examples", package = "bistablehistory")
vignette("writing-stan-code", package = "bistablehistory")
For detail refer to: Andrew Gelman, Ben Goodrich, Jonah Gabry, and Aki Vehtari (2018). R-squared for Bayesian regression models. The American Statistician doi:10.1080/00031305.2018.1549100 and https://avehtari.github.io/bayes_R2/bayes_R2.html
## S3 method for class 'cumhist' bayes_R2(object, summary = TRUE, probs = c(0.055, 0.945), ...)
## S3 method for class 'cumhist' bayes_R2(object, summary = TRUE, probs = c(0.055, 0.945), ...)
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
... |
Unused. |
vector of values or a data.frame with summary
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") bayes_R2(br_fit)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") bayes_R2(br_fit)
Dataset on binocular rivalry for eight participants.
br
br
A data frame with 3769 rows and 6 variables:
Participant ID.
Display, all rows contain "BR"
Run / block index.
Time relative to the run onset in seconds
Factor with levels "Left"
, "Right"
(clear states), and "Mixed"
.
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
Dataset on binocular rivalry with variable but equal contrast for six participants.
br_contrast
br_contrast
A data frame with 4616 rows and 6 variables:
Participant ID.
Run / block index.
Contrast on scale from 0 to 1.
Time relative to the run onset in seconds
Factor with levels "Left"
, "Right"
(clear states), and "Mixed"
.
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
A single subject / multiple runs dataset for binocular rivalry.
br_single_subject
br_single_subject
A data frame with 76 rows and 6 variables:
Participant ID, all rows contain "ap"
Display, all rows contain "BR"
Run / block index
Time relative to the run onset in seconds
Index of a perceptually dominant state, 1, 2 - clear perceptual state, 3 mixed / transition phase
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
A single subject / single run dataset for binocular rivalry.
br_singleblock
br_singleblock
A data frame with 76 rows and 6 variables:
Participant ID, all rows contain "ap"
Display, all rows contain "BR"
Run / block index, all rows contain 1
Time relative to the run onset in seconds
Index of a perceptually dominant state, 1, 2 - clear perceptual state, 3 mixed / transition phase
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
Extracts models population-level coefficients history-specific terms and fixed-effect terms for every modeled distribution parameter.
## S3 method for class 'cumhist' coef(object, summary = TRUE, probs = c(0.055, 0.945), ...)
## S3 method for class 'cumhist' coef(object, summary = TRUE, probs = c(0.055, 0.945), ...)
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
... |
Unused. |
data.frame with values or summary
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration", fixed_effects = "Time") coef(br_fit)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration", fixed_effects = "Time") coef(br_fit)
Computes cumulative history for each state in the time-series.
compute_history( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL, tau = 1, mixed_state = 0.5, history_init = 0 )
compute_history( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL, tau = 1, mixed_state = 0.5, history_init = 0 )
data |
A table with time-series. |
state |
String, the name of the column that specifies perceptual state. The column type should be a factor with two or three levels (the third level is assumed to correspond to a transition/mixed phase) or should be convertible to a two level factor (as it would be impossible to infer the identity of transition/ mixed phase). |
duration |
String, name of the column with duration of individual
perceptual dominance phases. Optional, you can specify |
onset |
String, name of the column with onsets of the perceptual
dominance states. Optional, used to compute duration of the dominance
phases, if these are not provided explicitly via |
random_effect |
String, name of the column that identifies random effect, e.g. individual participants, stimuli for a single participant, etc. If omitted, no random effect is assumed. If specified and there is more than one level (participant, stimulus, etc.), it is used in a hierarchical model. |
session |
String, name of the column that identifies unique
experimental session for which a mean dominance phase duration will
be computed (see |
run |
String, name of the column that identifies unique runs/blocks. If omitted, the data is assumed to belong to a single time series. Code assumes that run IDs are different within an experimental session but can be the same between the session. E.g. session A, runs 1, 2, 3.. and session B, runs 1, 2, 3 but not session A, runs 1, 2, 1. |
tau |
Time constant of exponential growth/decay
normalized to the mean duration of clear percepts within each |
mixed_state |
Specifies an activation level during
transition/mixed phases (state #3, see |
history_init |
Initial value for cumulative history computation. Either a numeric scalar in 0..1 range or a vector of two numbers in 0..1 range. In the latter case, two histories will start at different levels. |
A matrix nrow(data)
× 2 with computed history values
df <- compute_history(br_singleblock, state = "State", duration = "Duration", tau = 1, mixed_state = 0.5, history_init = 0)
df <- compute_history(br_singleblock, state = "State", duration = "Duration", tau = 1, mixed_state = 0.5, history_init = 0)
cumhist
.Cumulative history model fitted to time-series data.
See methods(class = "cumhist")
for an overview of available methods.
family
A string
with distribution family.
data
A list
with preprocessed data.
stanfit
a stanfit
object.
Computes history for a fitted model, uses only mean values
for each history parameter. Uses values for each random cluster,
if "random"
or "1|random"
parametrisation was used.
extract_history(object)
extract_history(object)
object |
An object of class cumhist |
A matrix of cumulative history values for each state
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") extract_history(br_fit)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") extract_history(br_fit)
Extracts a history parameter as a matrix with
samplesN
rows and randomN (found in object$data$randomN
)
columns.
extract_history_parameter( object, param_name, samplesN = NULL, link_function = NULL )
extract_history_parameter( object, param_name, samplesN = NULL, link_function = NULL )
object |
A cumhist object |
param_name |
String, a name of the parameter |
samplesN |
Number of samples, if NULL is computed from rstan (but it is cheaper to do this once). |
link_function |
A link function to use (exp or inv.logit) or |
Matrix with samplesN
rows and randomN
(found in object$data$randomN
) columns
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") extract_history_parameter(br_fit, "tau", link_function = exp)
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") extract_history_parameter(br_fit, "tau", link_function = exp)
Extract a term and replicates it randomN times for each linear model. Used for population mean or variance terms.
extract_replicate_term_to_matrix(object, term)
extract_replicate_term_to_matrix(object, term)
object |
An object of class cumhist |
term |
String, term name |
Matrix
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") bH_mu <- extract_replicate_term_to_matrix(br_fit, "bH_mu")
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") bH_mu <- extract_replicate_term_to_matrix(br_fit, "bH_mu")
Extracts a 3D array for a term with sample, linear-model, random/fixed-effect order and returns a matrix with samples as rows and columns in order 1) all random/fixed effects for lm1, 2) all random/fixed effects for lm2, etc.
extract_term_to_matrix(object, term)
extract_term_to_matrix(object, term)
object |
An object of class cumhist |
term |
String, term name |
Matrix
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") a <- extract_term_to_matrix(br_fit, "a")
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") a <- extract_term_to_matrix(br_fit, "a")
Computes cumulative history based on common history
values and
normalized_tau
and mixed_state
that are defined for each
random cluster / individual.
fast_history_compute(df, normalized_tau, mixed_state, history_init)
fast_history_compute(df, normalized_tau, mixed_state, history_init)
df |
DataFrame with |
normalized_tau |
DoubleVector A normalized tau value for each random cluster / individual. Thus, its length must be
equal to the number of unique indexes in |
mixed_state |
DoubleVector A values used for the mixed state for each random cluster / individual.
Thus, its length must be equal to the number of unique indexes in |
history_init |
DoubleVector, size 2. Initial values of history for a run. |
NumericMatrix, size df.nrows()
× 2. Computed history values for each state.
df <- preprocess_data(br_singleblock, state="State", duration="Duration") fast_history_compute(df, 1, 0.5, c(0, 0))
df <- preprocess_data(br_singleblock, state="State", duration="Duration") fast_history_compute(df, 1, 0.5, c(0, 0))
Fits a generalized linear model using cumulative history and specified fixed effects.
fit_cumhist( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL, fixed_effects = NULL, tau = NULL, mixed_state = 0.5, history_init = 0, family = "gamma", history_priors = NULL, intercept_priors = NULL, history_effect_prior = NULL, fixed_effects_priors = NULL, chains = 1, cores = NULL, ... )
fit_cumhist( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL, fixed_effects = NULL, tau = NULL, mixed_state = 0.5, history_init = 0, family = "gamma", history_priors = NULL, intercept_priors = NULL, history_effect_prior = NULL, fixed_effects_priors = NULL, chains = 1, cores = NULL, ... )
data |
A table with time-series. |
state |
String, the name of the column that specifies perceptual state. The column type should be a factor with two or three levels (the third level is assumed to correspond to a transition/mixed phase) or should be convertible to a two level factor (as it would be impossible to infer the identity of transition/ mixed phase). |
duration |
String, name of the column with duration of individual
perceptual dominance phases. Optional, you can specify |
onset |
String, name of the column with onsets of the perceptual
dominance states. Optional, used to compute duration of the dominance
phases, if these are not provided explicitly via |
random_effect |
String, name of the column that identifies random effect, e.g. individual participants, stimuli for a single participant, etc. If omitted, no random effect is assumed. If specified and there is more than one level (participant, stimulus, etc.), it is used in a hierarchical model. |
session |
String, name of the column that identifies unique
experimental session for which a mean dominance phase duration will
be computed (see |
run |
String, name of the column that identifies unique runs/blocks. If omitted, the data is assumed to belong to a single time series. Code assumes that run IDs are different within an experimental session but can be the same between the session. E.g. session A, runs 1, 2, 3.. and session B, runs 1, 2, 3 but not session A, runs 1, 2, 1. |
fixed_effects |
String or vector of strings. Name of column(s) with values to be used for fitting an additional fixed effect(s). E.g., contrast in binocular rivalry, rotation speed for kinetic-depth effect, etc. |
tau |
Time constant of exponential growth/decay
normalized to the mean duration of clear percepts within each |
mixed_state |
Specifies an activation level during
transition/mixed phases (state #3, see |
history_init |
Initial value for cumulative history computation. Either a numeric scalar in 0..1 range or a vector of two numbers in 0..1 range. In the latter case, two histories will start at different levels. |
family |
String, distribution used to fit duration of perceptual dominance
phases. Options include |
history_priors |
Named list of optional priors for population-level cumulative history
parameters. Must follow the format |
intercept_priors |
A vector of optional priors for population-level intercept
parameter. Should be |
history_effect_prior |
A vector of options priors for population-level slope of history effect. The values code mean and standard deviation of the normal distribution. Defaults to mu=0, sigma=1. |
fixed_effects_priors |
A named list of optional priors for fixed effects. Must
follow the format |
chains |
Number of chains for sampling. |
cores |
Number of CPU cores to use for sampling. If omitted, All cores are used. |
... |
Additional arguments passed to rstan::sampling() function. |
An object of class cumhist
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration")
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration")
Extracts models fixed-effect terms for every modeled distribution parameter.
fixef(object, summary = TRUE, probs = c(0.055, 0.945))
fixef(object, summary = TRUE, probs = c(0.055, 0.945))
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
tibble
with values or summary, NULL
if not fixed effects were used.
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration", fixed_effects = "Time") fixef(br_fit)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration", fixed_effects = "Time") fixef(br_fit)
A short-cut for history_parameter(object, "mixed_state", ...)
.
history_mixed_state( object, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
history_mixed_state( object, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
includePopulationLevel |
Logical, for pooled random effect only. Whether to include
population mean as a separate |
A single value, if fixed value was used. A vector or a tibble, depending on the option used (single intercept, independent or random intercepts), and whether summary was requested.
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_tau(br_fit)
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_tau(br_fit)
Extract values of used or fitted history parameter
history_parameter( object, param, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
history_parameter( object, param, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
object |
An object of class cumhist |
param |
Parameter name: |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
includePopulationLevel |
Logical, for pooled random effect only. Whether to include
population mean as a separate |
A vector, if summary was not requested. Or a tibble with a summary or if a fixed value was used.
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_parameter(br_fit, "tau")
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_parameter(br_fit, "tau")
A short-cut for history_parameter(object, "tau", ...)
.
history_tau( object, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
history_tau( object, summary = TRUE, probs = c(0.055, 0.945), includePopulationLevel = TRUE )
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
includePopulationLevel |
Logical, for pooled random effect only. Whether to include
population mean as a separate |
A single value, if fixed value was used. A vector or a tibble, depending on the option used (single intercept, independent or random intercepts), and whether summary was requested.
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_tau(br_fit)
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") history_tau(br_fit)
Extracts models population-level coefficients history-specific terms for every modeled distribution parameter.
historyef(object, summary = TRUE, probs = c(0.055, 0.945))
historyef(object, summary = TRUE, probs = c(0.055, 0.945))
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to 89% credible interval. |
data.frame with values or summary
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") historyef(br_fit)
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") historyef(br_fit)
Dataset on kinetic-depth effect for eleven participants.
kde
kde
A data frame with 38698 rows and 6 variables:
Participant ID.
Display, all rows contain "KD"
Run / block index.
Time relative to the run onset in seconds
Factor with levels "Left"
, "Right"
(clear states), and "Mixed"
.
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
Multirun data for two participants, kinetic-depth effect display
kde_two_observers
kde_two_observers
A data frame with 1186 rows and 5 variables:
Participant ID
Run / block index
Factor variable for state with levels -1
and 1
coding two clear perceptual states and -2
the mixed / transition phase
Time relative to the run onset in seconds
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
Computes an efficient approximate leave-one-out cross-validation via loo library. It can be used for a model comparison via loo::loo_compare() function.
## S3 method for class 'cumhist' loo(x, ...)
## S3 method for class 'cumhist' loo(x, ...)
x |
A cumhist object |
... |
unused |
A named list, see loo::loo()
for details.
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") loo_gamma <- loo(gamma_fit)
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") loo_gamma <- loo(gamma_fit)
Dataset on Necker cube for five participants.
nc
nc
A data frame with 3464 rows and 6 variables:
Participant ID.
Display, all rows contain "NC"
Run / block index.
Time relative to the run onset in seconds
Factor with levels "Left"
, "Right"
(clear states), and "Mixed"
.
Duration of a dominance phase in seconds. Note that the duration for the last dominance phase is curtailed and, therefore, set to zero.
Computes predicted cumulative history using fitted model. This is just a wrapper
for predict(object, summary, probs, full_length, predict_history=history_type)
.
predict_history( object, history_type, summary = TRUE, probs = NULL, full_length = TRUE, ... )
predict_history( object, history_type, summary = TRUE, probs = NULL, full_length = TRUE, ... )
object |
An object of class cumhist |
history_type |
|
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to NULL (no CI). |
full_length |
Only for |
... |
Unused |
If summary=FALSE
, a numeric matrix iterationsN x clearN.
If summary=TRUE
but probs=NULL
a vector of requested cumulative history values.
If summary=TRUE
and probs
is not NULL
, a data.frame
with a column "Predicted" (mean) and a column for each specified quantile.
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") history_difference_summary <- predict_history(br_fit, "difference") # full posterior prediction samples history_difference <- predict_history(br_fit, "difference", summary = FALSE, full_length = TRUE)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") history_difference_summary <- predict_history(br_fit, "difference") # full posterior prediction samples history_difference <- predict_history(br_fit, "difference", summary = FALSE, full_length = TRUE)
Computing prediction for each sample, recomputing cumulative history and uses fitted parameter values.
predict_samples( family, fixedN, randomN, lmN, istate, duration, is_used, run_start, session_tmean, irandom, fixed, tau_ind, mixed_state_ind, history_init, a, bH, bF, sigma )
predict_samples( family, fixedN, randomN, lmN, istate, duration, is_used, run_start, session_tmean, irandom, fixed, tau_ind, mixed_state_ind, history_init, a, bH, bF, sigma )
family |
int, distribution family: gamma (1), lognormal(2), or normal (3). |
fixedN |
int, number of fixed parameters (>= 0). |
randomN |
int, number of random factors (>= 1). |
lmN |
int, number of linear models (>= 1). |
istate |
IntegerVector, zero-based perceptual state 0 or 1, 2 is mixed state. |
duration |
DoubleVector, duration of a dominance phase. |
is_used |
IntegerVector, whether dominance phase is used for prediction (1) or not (0). |
run_start |
IntegerVector, 1 whenever a new run starts. |
session_tmean |
DoubleVector, average dominance phase duration. |
irandom |
IntegerVector, zero-based index of a random effect. |
fixed |
NumericMatrix, matrix with fixed effect values. |
tau_ind |
NumericMatrix, matrix with samples of tau for each random level. |
mixed_state_ind |
NumericMatrix, matrix with samples of mixed_state for each random level. |
history_init |
DoubleVector, Initial values of history for a run |
a |
NumericMatrix, matrix with samples of a (intercept) for each random level. |
bH |
NumericMatrix, matrix with sample of bH for each linear model and random level. |
bF |
NumericMatrix, matrix with sample of bF for each linear model and fixed factor. |
sigma |
DoubleVector, samples of sigma. |
NumericMatrix with predicted durations for each sample.
Computes predicted dominance phase durations using fitted model.
## S3 method for class 'cumhist' predict( object, summary = TRUE, probs = NULL, full_length = TRUE, predict_history = NULL, ... )
## S3 method for class 'cumhist' predict( object, summary = TRUE, probs = NULL, full_length = TRUE, predict_history = NULL, ... )
object |
An object of class cumhist |
summary |
Whether summary statistics should be returned instead of
raw sample values. Defaults to |
probs |
The percentiles used to compute summary, defaults to NULL (no CI). |
full_length |
Only for |
predict_history |
Option to predict a cumulative history state (or their difference).
It is disabled by default by setting it to |
... |
Unused |
If summary=FALSE
, a numeric matrix iterationsN x clearN.
If summary=TRUE
but probs=NULL
a vector of mean predicted durations
or requested cumulative history values.
If summary=TRUE
and probs
is not NULL
, a data.frame
with a column "Predicted" (mean) and a column for each specified quantile.
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") predict(br_fit) # full posterior prediction samples predictions_samples <- predict(br_fit, summary=FALSE)
br_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration") predict(br_fit) # full posterior prediction samples predictions_samples <- predict(br_fit, summary=FALSE)
Performs sanity checks (e.g., whether data
can be used as a data.frame),
computes duration of dominance phases (if necessary), assumes a single entry for
any missing session
, run
, random_effect
.
preprocess_data( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL )
preprocess_data( data, state, duration = NULL, onset = NULL, random_effect = NULL, session = NULL, run = NULL )
data |
A table with one or many time-series. |
state |
String, the name of the column that specifies perceptual state. The column type should be a factor with two or three levels (the third level is assumed to correspond to a transition/mixed phase) or should be convertible to a two level factor (as it would be impossible to infer the identity of transition/ mixed phase). |
duration |
String, name of the column with duration of individual
perceptual dominance phases. Optional, you can specify |
onset |
String, name of the column with onsets of the perceptual
dominance states. Optional, used to compute duration of the dominance
phases, if these are not provided explicitly via |
random_effect |
String, name of the column that identifies random effect, e.g. individual participants, stimuli for a single participant, etc. If omitted, no random effect is assumed. If specified and there is more than one level (participant, stimulus, etc.), it is used in a hierarchical model. |
session |
String, name of the column that identifies unique
experimental session for which a mean dominance phase duration will
be computed (see |
run |
String, name of the column that identifies unique runs/blocks. If omitted, the data is assumed to belong to a single time series. Code assumes that run IDs are different within an experimental session but can be the same between the session. E.g. session A, runs 1, 2, 3.. and session B, runs 1, 2, 3 but not session A, runs 1, 2, 1. |
A tibble with columns
state
duration
random
irandom
- integer, index of random
values,
session
run
session_tmean
- numeric, mean duration of clear percepts for every combination of random
and session
.
is_used
- integer, whether computed history value needs to be used for linear model fitting.
run_start
- integer, 1 for the first row of the run time-series.
df <- preprocess_data(br_singleblock, state="State", duration="Duration")
df <- preprocess_data(br_singleblock, state="State", duration="Duration")
Prints out cumhist object
## S3 method for class 'cumhist' print(x, ...)
## S3 method for class 'cumhist' print(x, ...)
x |
A cumhist object |
... |
Unused |
Nothing, console output only.
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration", fixed_effects="Time") br_fit
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration", fixed_effects="Time") br_fit
Summary for a cumhist object
## S3 method for class 'cumhist' summary(object, ...)
## S3 method for class 'cumhist' summary(object, ...)
object |
A cumhist object |
... |
Unused |
Nothing, console output only.
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") summary(br_fit)
br_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") summary(br_fit)
Computes widely applicable information criterion via loo library. It can be used for a model comparison via loo::loo_compare() function.
## S3 method for class 'cumhist' waic(x, ...)
## S3 method for class 'cumhist' waic(x, ...)
x |
A cumhist object. |
... |
Additional arguments (unused) |
A named list, see loo::waic()
for details.
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") waic_gamma <- waic(gamma_fit) normal_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration", family="normal") waic_normal <- waic(normal_fit) loo::loo_compare(waic_gamma, waic_normal)
data(br_singleblock) gamma_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration") waic_gamma <- waic(gamma_fit) normal_fit <- fit_cumhist(br_singleblock, state="State", duration="Duration", family="normal") waic_normal <- waic(normal_fit) loo::loo_compare(waic_gamma, waic_normal)