# Fits cumulative history for bistable perceptual rivalry displays.

Source:`R/fit_cumhist.R`

`fit_cumhist.Rd`

Fits a generalized linear model using cumulative history and specified fixed effects.

## Usage

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

## Arguments

- 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`

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

`duration`

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

`norm_tau`

parameter). Code assumes that session IDs are different within a participant but can be the same between them. If omitted, a single mean dominance duration based on the entire time series is used.- 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

`session`

. Can be 1) a single positive number (>0) that is used for all participants and runs, 2)`NULL`

(default) - a*single*value will be fitted for all participants and runs, 3)`"random"`

- an independent tau is fitted for each random cluster, 4)`"1|random"`

- a tau for a random cluster is sampled from a population distribution, i.e., pooled parameter values via a multilevel model.- mixed_state
Specifies an activation level during transition/mixed phases (state #3, see

`state`

). Either a single number (range 0..1) that will be used as a fixed level or a vector of two numbers`c(mu, kappa)`

that specifies, correspondingly, mean (range 0..1) and precision (>0) of beta proportion distribution, it should be sampled from. Defaults to a fixed value of`0.5`

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

`"gamma"`

(default),`"lognormal"`

, and`"normal"`

.- history_priors
Named list of optional priors for population-level cumulative history parameters. Must follow the format

`list("tau"=c(1, 0.15))`

with values coding mean and standard deviation of the normal distribution.- intercept_priors
A vector of optional priors for population-level intercept parameter. Should be

`c(<shape-mean>, <shape-sd>, <scale-mean>, <scale-sd>)`

format for Gamma family,`c(<mean>, <sd>)`

for normal and lognormal families. The values code mean and standard deviation of the normal distribution.- 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

`list("<name-of-variable>"=c(<mu>, <sigma>))`

, where`<mu>`

and`<sigma>`

are mean and standard deviation of a normal distribution. Defaults to mu=0, sigma=1.- 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.

## Value

An object of class cumhist

## Examples

```
# \donttest{
data(br_singleblock)
gamma_fit <- fit_cumhist(br_singleblock, state = "State", duration = "Duration")
#>
#> SAMPLING FOR MODEL 'historylm' NOW (CHAIN 1).
#> Chain 1:
#> Chain 1: Gradient evaluation took 0 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 0 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1:
#> Chain 1:
#> Chain 1: Iteration: 1 / 2000 [ 0%] (Warmup)
#> Chain 1: Iteration: 200 / 2000 [ 10%] (Warmup)
#> Chain 1: Iteration: 400 / 2000 [ 20%] (Warmup)
#> Chain 1: Iteration: 600 / 2000 [ 30%] (Warmup)
#> Chain 1: Iteration: 800 / 2000 [ 40%] (Warmup)
#> Chain 1: Iteration: 1000 / 2000 [ 50%] (Warmup)
#> Chain 1: Iteration: 1001 / 2000 [ 50%] (Sampling)
#> Chain 1: Iteration: 1200 / 2000 [ 60%] (Sampling)
#> Chain 1: Iteration: 1400 / 2000 [ 70%] (Sampling)
#> Chain 1: Iteration: 1600 / 2000 [ 80%] (Sampling)
#> Chain 1: Iteration: 1800 / 2000 [ 90%] (Sampling)
#> Chain 1: Iteration: 2000 / 2000 [100%] (Sampling)
#> Chain 1:
#> Chain 1: Elapsed Time: 6.683 seconds (Warm-up)
#> Chain 1: 7.777 seconds (Sampling)
#> Chain 1: 14.46 seconds (Total)
#> Chain 1:
# }
```