knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
library(LDATS) vers <- packageVersion("LDATS") today <- Sys.Date()
This vignette walks through an example of
LDATS at the command line and
was constructed using
r vers on
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)
For this vignette, we will be using rodent data from the control plots of the
Portal Project, which come with
the LDATS package (
rodents contains two data tables, a
document_term_table and a
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.
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
cos_year so we can account for seasonal dynamics.
data(rodents) head(rodents$document_term_table, 10) head(rodents$document_covariate_table, 10)
LDA_set() to run replicate LDA models (each with its own seed) with varying numbers of topics (
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
load(file.path('.', 'rodents-example-files', 'lda_model_set.Rds')) rm(lda_model_set2)
selected_lda_model <- select_LDA(lda_model_set)
We can access the results of the model:
# Number of topics: selected_lda_model[]@k # Topic composition of communities at each time step # Columns are topics; rows are time steps head(selected_lda_model[]@gamma)
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
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.
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
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
select_TS() will identify the best-fit changepoint model of the models from
TS_on_LDA(). As with
select_LDA(), we can adjust the
selector functions using the
control argument list.
load(file.path('.', 'rodents-example-files', 'changepoint_models.Rds'))
selected_changepoint_model <- select_TS(changepoint_models)
We can access the results of the selected changepoint model:
# Number of changepoints selected_changepoint_model$nchangepoints # Summary of timesteps (newmoon values) for each changepoint selected_changepoint_model$rho_summary # Raw estimates for timesteps for each changepoint # Changepoints are columns head(selected_changepoint_model$rhos)
LDATS will plot the results of a changepoint model:
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))
load(file.path('.', 'rodents-example-files', 'lda_ts_results.Rds'))
LDA_TS() returns a list of all the model objects, and we can access their contents as above:
names(lda_ts_results) # Number of topics lda_ts_results$`Selected LDA model`$k@k # Number of changepoints lda_ts_results$`Selected TS model`$nchangepoints # Summary of changepoint locations lda_ts_results$`Selected TS model`$rho_summary
Finally, we can plot the
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.