# Usage examples In bistablehistory: Cumulative History Analysis for Bistable Perception Time Series

knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )  knitr::opts_chunk$set(warning = FALSE, message = FALSE)
library(bistablehistory)


## Minimal example

The main function is fit_cumhist() that takes a data frame with time-series as a first argument. In addition, you need to specify the name of the column that codes the perceptual state (state argument) and a column that holds either dominance phase duration (duration) or its onset (onset). The code below fits data using Gamma distribution (default family) for a single run of a single participant. By default, the function fits cumulative history time constant but uses default fixed mixed state value (mixed_state = 0.5), history mixing proportion (history_mix = 0.2), and initial history values (history_init = 0).

data(br_singleblock)
gamma_fit <- fit_cumhist(br_singleblock,
state="State",
duration="Duration",
refresh=0)


Alternatively, you specify onset of individual dominance phases that will be used to compute their duration.

gamma_fit <- fit_cumhist(br_singleblock,
state="State",
onset="Time")


Now you can look at the fitted value for history time constant using history_tau()

history_tau(gamma_fit)


and main effect of history for both parameters of gamma distribution

historyef(gamma_fit)


The following model is fitted for the example above, see also companion vignette for details on cumulative history computation. $$Duration[i] \sim Gamma(shape[i], rate[i]) \ log(shape[i]) = \alpha^{shape} + \beta^{shape}H \cdot H{mix}[i] \ log(rate[i]) = \alpha^{rate} + \beta^{rate}H \cdot H{mix}[i] \ H_{mix}[i] = \text{cumulative_history}(\tau,\text{history_mixture}, \text{history_init})\ \alpha^{shape}, \alpha^{rate} \sim Normal(log(3), 5) \ \beta^{shape}_H, \beta^{rate}_H \sim Normal(0, 1) \ \tau \sim Normal(log(1), 0.75)$$

## Run

By default, fit_cumhist() function assumes that the time-series represent a single run with the consequence that history states are initialized only once at the very beginning. You can use run argument to pass the name of a column that specifies individual runs. In this case, history is initialize at the beginning of every run to avoid spill-over effects.

gamma_fit <- fit_cumhist(br_single_subject,
state="State",
onset="Time",
run="Block")


## Computing and using cumulative history

If you are interested in the cumulative history itself, you can extract from the fitted object via extract_history() function

H <- extract_history(gam_fit)


Alternatively, you can skip fittiong and compute history directly using predefined values via compute_history().

df <- compute_history(br_singleblock,
state="State",
duration="Duration",
tau=1,
mixed_state=0.5,
history_init=0)


## Try the bistablehistory package in your browser

Any scripts or data that you put into this service are public.

bistablehistory documentation built on Sept. 28, 2021, 5:10 p.m.