Rodents Example

Installation

To obtain the most recent version of LDATS, install and load the most recent version from GitHub:

install.packages("devtools")
devtools::install_github("weecology/LDATS")
library(LDATS)

Data

For this vignette, we will be using rodent data from the control plots of the Portal Project, which come with the LDATS package (data(rodents)).

rodents contains two data tables, a document_term_table and a document_covariate_table.

The document_term_table is a matrix of species (term) counts by sampling period (document). Importantly, the document_term_table contains raw counts of individual rodent captures, not catch per unit effort. The LDA models operate on proportions and weight the information from each sampling period according to total catch (document size). Similarly, the TS models use the LDA compositional breakdown and weight the information from each period according to the total catch. We therefore give both models unadjusted data. The values in the document_term_table must be integers.

The document_covariate_table contains the covariates we would like to use for the time series models. In this case, we have a column for newmoon, which is the time step for each of our sampling periods. This column can include nonconsecutive time steps (i.e., 2, 4, 5) if sampling periods are skipped or at unequal intervals, but must be integer-conformable or a date. Although if a date, the assumption is that the timestep is 1 day, which is often not desired behavior. If there is no time column, LDATS will assume all time steps are equidistant. We also include columns sin_year and cos_year so we can account for seasonal dynamics.

data(rodents)
head(rodents$document_term_table, 10)
#>    BA DM DO DS NA. OL OT PB PE PF PH PI PL PM PP RF RM RO SF SH SO
#> 1   0 13  0  2   2  0  0  0  1  1  0  0  0  0  3  0  0  0  0  0  0
#> 2   0 20  1  3   2  0  0  0  0  4  0  0  0  0  2  0  0  0  0  0  0
#> 3   0 21  0  8   4  0  0  0  1  2  0  0  0  0  1  0  0  0  0  0  0
#> 4   0 21  3 12   4  2  3  0  1  1  0  0  0  0  0  0  0  0  0  0  0
#> 5   0 16  1  9   5  2  1  0  0  2  0  0  0  0  0  0  1  0  0  0  0
#> 6   0 17  1 13   5  1  5  0  0  3  0  0  0  0  0  0  0  0  0  0  0
#> 7   0 19  0  9   4  2  3  0  1  1  0  0  0  0  0  0  0  0  0  0  0
#> 8   0 15  0  9   2  1  2  0  1  2  0  0  0  0  0  0  0  0  0  0  0
#> 9   0 11  1 12   1  1  5  0  2  3  0  0  0  0  0  0  1  0  0  0  0
#> 10  0 14  1 15   1  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
head(rodents$document_covariate_table, 10)
#>    newmoon sin_year cos_year
#> 1        1  -0.2470  -0.9690
#> 2        2  -0.6808  -0.7325
#> 3        3  -0.9537  -0.3008
#> 4        4  -0.9813   0.1925
#> 5        5  -0.7583   0.6519
#> 6        6  -0.3537   0.9354
#> 7        7   0.1373   0.9905
#> 8        8   0.6085   0.7936
#> 9        9   0.9141   0.4054
#> 10      10   0.9951  -0.0988

Stage 1: LDA models

We use LDA_set() to run replicate LDA models (each with its own seed) with varying numbers of topics (2:5) and select_LDA() to select the best model.

We use the control argument to pass controls to the LDA function via a list. In this case, we can set quiet = TRUE to make the model run quietly.

lda_model_set <- LDA_set(document_term_table = rodents$document_term_table,
                         topics = c(2:5),
                         nseeds = 10,
                         control = list(quiet = TRUE))

If we do not pass any controls, by default, quiet = FALSE (here run with only 2:3 topics and 2 seeds, to keep output short):

lda_model_set2 <- LDA_set(document_term_table = rodents$document_term_table,
                         topics = c(2:3),
                         nseeds = 2)

LDA_set() returns a list of LDA models. We use select_LDA() to identify the best number of topics and choice of seed from our set of models. By default, we will choose models based on minimum AIC. To use different selection criteria, define the appropriate functions and specify them by passing list(measurer = [measurer function], selector = [max, min, etc]) to the control argument.

selected_lda_model <- select_LDA(lda_model_set)

We can access the results of the model:

# Number of topics:

selected_lda_model[[1]]@k
#> [1] 5

# Topic composition of communities at each time step
# Columns are topics; rows are time steps
head(selected_lda_model[[1]]@gamma)
#>             [,1]        [,2]      [,3]        [,4]        [,5]
#> [1,] 0.008303695 0.466475067 0.3431302 0.008585984 0.173505077
#> [2,] 0.005769837 0.663030049 0.2480563 0.005808044 0.077335746
#> [3,] 0.005008333 0.325407486 0.6280921 0.005095116 0.036397003
#> [4,] 0.003986846 0.183762181 0.8042557 0.004034794 0.003960483
#> [5,] 0.005016414 0.005116156 0.9210663 0.063795689 0.005005489
#> [6,] 0.004157612 0.105779863 0.8817614 0.004170617 0.004130473

LDATS includes flexible plot functionality for LDAs and time series. The top panel illustrates topic composition by species, and the bottom panel shows the proportion of the community made up of each topic over time. For all the available plot options see ?plot.LDA_VEM.

plot(selected_lda_model[[1]])

Stage 2: TS changepoint models

We use TS_on_LDA() to run LDATS changepoint models with 0:6 changepoints, and then use select_TS() to find the best-fit model of these.

Here, TS_on_LDA() predicts the gamma (the proportion of the community made of up each topic) from our LDA model(s) as a function of sin_year and cos_year in the document_covariate_table. We use document_weights() to weight the information from each time step according to the total number of rodents captured at that time step.

changepoint_models <- TS_on_LDA(LDA_models = selected_lda_model, 
                                document_covariate_table = rodents$document_covariate_table,
                                formulas = ~ sin_year + cos_year,
                                nchangepoints = c(0:1), 
                                timename = "newmoon",
                                weights = document_weights(rodents$document_term_table),
                                control = list(nit = 1000))

We can adjust options (default settings can be seen using TS_control()) for both TS functions by passing a list to the control argument. For a full list see ?TS_control. Here we illustrate adjusting the number of ptMCMC iterations - the default is 10000, but it is convenient to use fewer iterations for code development.

Also, it is important to note that by default the TS functions take the name of the time-step column from the document_covariate_table to be "time". To pass a different column name, use the timename argument in TS_on_LDA().

select_TS() will identify the best-fit changepoint model of the models from TS_on_LDA(). As with select_LDA(), we can adjust the measurer and selector functions using the control argument list.

selected_changepoint_model <- select_TS(changepoint_models)

We can access the results of the selected changepoint model:

# Number of changepoints
selected_changepoint_model$nchangepoints
#> [1] 1

# Summary of timesteps (newmoon values) for each changepoint
selected_changepoint_model$rho_summary
#>                 Mean Median Mode Lower_95% Upper_95%    SD MCMCerr   AC10
#> Changepoint_1 212.93    216  217       187       225 10.03  0.3172 0.0066
#>                    ESS
#> Changepoint_1 360.2996

# Raw estimates for timesteps for each changepoint
# Changepoints are columns
head(selected_changepoint_model$rhos)
#>      [,1]
#> [1,]  220
#> [2,]  220
#> [3,]  218
#> [4,]  215
#> [5,]  213
#> [6,]  216

LDATS will plot the results of a changepoint model:

plot(selected_changepoint_model)

Full analysis with LDA_TS

Finally, we can perform an entire LDATS analysis, including all of the above steps, using the LDA_TS() function and passing options to the LDA and TS functions as a list to the control argument. The default is for LDA_TS to weight the time series model based on the document sizes, so we do not need to tell it to do so.

lda_ts_results <- LDA_TS(data = rodents,
                         nseeds = 10, 
                         topics = 2:5,
                         formulas = ~ sin_year + cos_year,
                         nchangepoints= 0:1,
                         timename = "newmoon",
                         control = list(nit = 1000))

LDA_TS() returns a list of all the model objects, and we can access their contents as above:

names(lda_ts_results)
#> [1] "LDA models"         "Selected LDA model" "TS models"         
#> [4] "Selected TS model"

# Number of topics
lda_ts_results$`Selected LDA model`$k@k
#> [1] 5

# Number of changepoints
lda_ts_results$`Selected TS model`$nchangepoints
#> [1] 1

# Summary of changepoint locations
lda_ts_results$`Selected TS model`$rho_summary
#>                 Mean Median Mode Lower_95% Upper_95%  SD MCMCerr   AC10
#> Changepoint_1 209.26    211  215       190       225 9.7  0.3067 0.0104
#>                    ESS
#> Changepoint_1 380.3491

Finally, we can plot the LDA_TS results.