---
title: "Usage of pglmm()"
author: "Daijiang Li"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Usage of pglmm()}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", eval = FALSE, purl = FALSE
)
```

The purpose of this vignette is _not_ to provide detailed explanation of model set up and results. For this purpose, please read the documentation of `?phyr::pglmm` and the chapter 4 of [Ives 2018](https://leanpub.com/correlateddata). The purpose of this vignette is to show some cases that are not documented in details.

# Fit a binomial model with success and failures

To fit a binomial model to a data frame with columns of success and failures (say named as `yes` and `no`, respectively), use

```{r}
pglmm(cbind(yes, no) ~ 1 + x, data = dat, family = 'binomial')
```

# Prepare random terms for complex models that cannot be set up with formula

Sometimes, users may want to prepare their own list of random terms to fit phylogenetic generalized linear mixed models in more flexible ways. For example, users may want to add an extra random term on top of those specified by the model formula. For this, we can extract the list of random terms generated by the model formula using `prep_dat_pglmm()` and then append the one we want to add. See `?phyr::prep_dat_pglmm` for details about its arguments.


# Other functions to work with models fitted with `pglmm()`

All models fitted with `pglmm()` have class of `communityPGLMM`. Here is a list of functions that can be used to these models.

- `pglmm_matrix_structure()`: produce the whole covariance matrix 
- `pglmm_plot_re()`: plot images of random term matrix, see vignettes `plot-re`          
- `pglmm_predicted_values()` or `fitted()`: extract fitted values
- `pglmm_profile_LRT()`: to test significance of random terms; only works with binomial models 
- `plot_data()`: plot data used (and optionally predicted) by fitted model
- `plot_bayes()`: plot posterior distributions of random and fixed effects
- `summary()`: summary of model fit
- `print()`: summary of model fit
- `residuals()`: residuals values
- `fixef()`: estimates of fixed effects
- `ranef()`: estimates of random terms (variance and standard deviation)