Bayesian Markov Renewal Mixed Models (BMRMMs)

Description

Provides inference results of both transition probabilities and duration times using BMRMMs.

Usage

BMRMM(
  data,
  num.cov,
  cov.labels = NULL,
  state.labels = NULL,
  random.effect = TRUE,
  fixed.effect = TRUE,
  trans.cov.index = 1:num.cov,
  duration.cov.index = 1:num.cov,
  duration.distr = NULL,
  duration.incl.prev.state = TRUE,
  simsize = 10000,
  burnin = simsize/2
)

Arguments

Details

Users have the option to ignore duration times or model duration times as a discrete or continuous variable via defining duration.distr.

duration.distr can be one of the following:

• NULL: duration times are ignored. This is the default setting.

• list('mixgamma', shape, rate): duration times are modeled as a mixture gamma variable. shape and rate must be numeric vectors of the same length. The length indicates the number of mixture components.

• list('mixDirichlet', unit): duration times are modeled as a new state with discretization unit. The duration state is then analyzed along with the original states. For example, if an duration time entry is 20 and unit is 5, then the model will add 4 consecutive new states. If an duration time entry is 23.33 and unit is 5, then the model will still add 4 consecutive new states as the blocks are calculated with the floor operation.

Value

An object of class BMRMM consisting of results.trans and results.duration if duration times are analyzed as a continuous variable.

The field results.trans is a data frame giving the inference results of transition probabilities.

The field results.duration is a data frame giving the inference results of duration times.

Author(s)

Yutong Wu, yutong.wu@utexas.edu

Examples

# In the examples, we use a shorted version of the foxp2 dataset, foxp2sm

# ignores duration times and only models transition probabilities using all three covariates
results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50)

# models duration times as a continuous variable with 3 gamma mixture components,
results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50,
                 duration.distr = list('mixgamma', shape = rep(1,3), rate = rep(1,3)))

# models duration times as a discrete state with discretization 0.025 and
results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50, 
                 duration.distr = list('mixDirichlet', unit = 0.025))

MCMC Diagnostic Plots for Transition Probabilities and Duration Times

Description

Provides the traceplots and autocorrelation plots for (i) transition probabilities and (ii) mixture gamma shape and rate parameters.

Usage

diag.BMRMM(object, cov.combs = NULL, transitions = NULL, components = NULL)

Arguments

Value

None

Examples

results <- BMRMM(foxp2sm, num.cov = 2, simsize = 80, 
                 duration.distr = list('mixgamma',shape=rep(1,3),rate=rep(1,3)))
diag.BMRMM(results)
diag.BMRMM(results, cov.combs = list(c(1,1),c(1,2)), 
           transitions = list(c(1,1)), components = c(3))

Simulated FoxP2 Data Set.

Description

A simulated data set of the original FoxP2 data set, which contains the sequences of syllables sung by male mice of different genotypes under various social contexts.

Usage

foxp2

Format

A data frame with 17391 rows and 6 variables:

Id

Mouse Id

Genotype

Genotype of the mouse, 1 = FoxP2 knocked out, 2 = wild type

Context

Social context for the mouse, 1 = U (urine sample placed in the cage), 2 = L (living female mouse placed in the cage), 3 = A (an anesthetized female placed on the lid of the cage)

Prev_State

The previous syllable, {1,2,3,4} = {d,m,s,u}

Cur_State

The current syllable, {1,2,3,4} = {d,m,s,u}

Transformed_ISI

Modified inter-syllable interval times, log(original ISI + 1)

References

Chabout, J., Sarkar, A., Patel, S. R., Radden, T., Dunson, D. B., Fisher, S. E., & Jarvis, E. D. (2016). A Foxp2 mutation implicated in human speech deficits alters sequencing of ultrasonic vocalizations in adult male mice. Frontiers in behavioral neuroscience, 10, 197.

Wu, Y., Jarvis E. D., & Sarkar, A. (2023). Bayesian semiparametric Markov renewal mixed models for vocalization syntax. Biostatistics, To appear.

Shortened Simulated FoxP2 Data Set.

Description

A shortened version of the foxp2 data set for demonstrating R examples. See details of the foxp2 data set by calling ?foxp2.

Usage

foxp2sm

Format

An object of class data.frame with 69 rows and 6 columns.

Histogram of Duration Times

Description

Plots the histogram of duration times in two ways as the users desire:

1. Histogram of all duration times superimposed the posterior mean mixture gamma distribution;

2. Histogram of a specified mixture component superimposed the gamma distribution with shape and rate parameters taken from the last MCMC iteration.

Usage

## S3 method for class 'BMRMM'
hist(
  x,
  comp = NULL,
  xlim = NULL,
  breaks = NULL,
  main = NULL,
  col = "gray",
  xlab = "Duration times",
  ylab = "Density",
  ...
)

Arguments

Value

An object of class histogram.

Examples

results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50, 
                 duration.distr = list('mixgamma',shape=rep(1,3),rate=rep(1,3)))

# plot the histogram of all duration times superimposed with 
# the posterior mixture gamma distribution
hist(results, xlim = c(0, 1), breaks = 50)

# plot the histogram for components 1 superimposed with 
# the mixture gamma distribution of the last MCMC iteration
hist(results, components = 1)

Model Selection Scores for the Number of Components for Duration Times

Description

Provides the LPML (Geisser and Eddy, 1979) and WAIC (Watanabe, 2010) scores of the Bayesian Markov renewal mixture models

Usage

model.selection.scores(object)

Arguments

Details

The two scores can be used to compare different choices of isi_num_comp, i.e., the number of the mixture gamma components. Larger values of LPML and smaller values of WAIC indicate better model fits.

Value

a list consisting of LPML and WAIC scores for gamma mixture models.

References

Geisser, S. and Eddy, W. F. (1979). A predictive approach to model selection. Journal of the American Statistical Association, 74, 153–160.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicable information criterion in singular learning theory. Journal of Machine Learning Research, 11, 3571–3594.

Examples

results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50, 
                 duration.distr = list('mixgamma',shape=rep(1,3),rate=rep(1,3)))
model.selection.scores(results)

Plot Method for Visualizing BMRMM Summary

Description

Visualization of a specified field of a BMRMMsummary object.

Usage

## S3 method for class 'BMRMMsummary'
plot(x, type, xlab = NULL, ylab = NULL, main = NULL, col = NULL, ...)

Arguments

Value

None

See Also

summary.BMRMM()

Examples

results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50, 
                 cov.labels = list(c("F", "W"), c("U", "L", "A")),
                 duration.distr = list('mixgamma',shape=rep(1,3),rate=rep(1,3)))
fit.summary <- summary(results)
plot(fit.summary, 'trans.probs.mean')
plot(fit.summary, 'dur.mix.probs')

Summary Method for Objects of Class BMRMM

Description

Summarizing an object of class BMRMM, including results for transition probabilities and duration times, if applicable.

Usage

## S3 method for class 'BMRMM'
summary(object, delta = 0.02, digits = 2, ...)

Arguments

Details

We give more explanation for the global tests and local tests results.

• Global tests (for both transition probabilities and duration times)

  Global tests are presented as a matrix, where the row denote the number of clusters and the column represents covariates. For each row i and column j, the matrix entry is the percentage of the number of the clusters within the stored MCMC samples for this covariate, i.e., an estimation for ⁠Pr(# clusters for covariate j == i)⁠. We note that the probability ⁠Pr(# clusters for covariate j > 1)⁠ would be the probability for the null hypothesis that the covariate j is significant.

• Local tests (for transition probabilities only)

  Local tests focus on a particular covariate and compare the influence among its levels when the other covariates values are fixed.
  Given a pair of levels of covariate j, say j_1 and j_2, and given the levels of other covariates, the null hypothesis is that the difference between j_1 and j_2 is not significant for transition probabilities. It is calculated as the percentage of the samples with absolute difference less than delta.

  The local tests provide two matrices of size d0 x d0 where d0 is the number of states:
  

  1. mean.diff – the mean of the absolute difference in each transition type between levels j_1 and j_2;

  2. null.test – the probability of the null hypothesis that j_1 and j_2 have the same significance for each transition type.

Value

An object of class BMRMMsummary with the following elements:

See Also

plot.BMRMMsummary for plotting the summary results.

Examples

results <- BMRMM(foxp2sm, num.cov = 2, simsize = 50, 
                 cov.labels = list(c("F", "W"), c("U", "L", "A")),
                 duration.distr = list('mixgamma',shape=rep(1,3),rate=rep(1,3)))
sm <- summary(results)
sm