# Latent Dirichlet Allocation Time Series (LDATS)

#### Juniper L. Simonis

## Overview

This vignette outlines the code base for the LDATS package. It was constructed using LDATS version 0.2.4 on 2019-07-29.

## Installation

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

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

## Analytical Pipeline

The full LDATS analysis can be executed using the `LDA_TS` function, which is the top-level of the coding pipeline’s hierarchy of functions:

- `LDA_TS()`
  - `check_LDA_TS_inputs()`
    - `check_timename()`
    - `check_formulas()`
    - `check_nchangepoints()`
    - `check_weights()`
    - `check_control()`
    - `check_document_term_table()`
    - `check_document_covariate_table()`
    - `check_topics()`
    - `check_seeds()`
  - `LDA_set()`
    - `check_LDA_TS_inputs()`
      - `check_control()`
      - `check_document_term_table()`
      - `check_topics()`
      - `check_seeds()`
    - loop over models
      - `prep_LDA_control()`
      - `LDA()`
  - `select_LDA()`
    - applies the `measurer` and `selector` functions supplied via `LDA_controls_list()`
  - `TS_on_LDA()`
    - `check_LDA_TS_inputs()`
      - `check_LDA_models()`
      - `check_formulas()`
      - `check_nchangepoints()`
      - `check_timename()`
      - `check_control()`
      - `check_weights()`
      - `check_document_covariate_table()`
    - `expand_TS()`
    - loop over models
      - `prep_TS_data()`
      - `TS()`
        - `check_TS_inputs()`
          - `check_formulas()`
          - `check_nchangepoints()`
          - `check_control()`
          - `check_weights()`
        - `est_changepoints()`
          - `prep_saves()`
          - `prep_ptMCMC_inputs()`
          - `prep_cpts()`
            - loop over chains
              - `multinom_TS()`
          - `prep_ids()`
          - `prep_pbar()`
          - loop over iterations
            - `update_pbar()`
            - `step_chains()`
              - `propose_step()`
                - `proposed_step_mods()`
                  - loop over chains
                    - `multinom_TS()`
              - `eval_step()`
              - `take_step()`
            - `swap_chains()`
              - loop over chain neighbors
            - `update_saves()`
            - `update_cpts()`
            - `update_ids()`
        - `est_regressors()`
          - loop over unique realizations of change point locations
            - `multinom_TS()`
            - loop over chunks
              - `mirror_vcov()`
              - `rmvnorm()`
        - `summarize_TS()`
          - `diagnose_ptMCMC()`
            - `count_trips()`
          - `summarize_rhos()`
          - `measure_rho_vcov()`
          - `summarize_etas()`
          - `measure_eta_vcov()`
    - `select_TS()`
      - applies the `measurer` and `selector` functions supplied via `TS_controls_list()`
    - `package_LDA_TS()`

Each component model’s function (`LDA_set()` and `TS()`) can be run independently, as well.

## Controls Lists

To minimize the length of argument lists and facilitate simple default usage throughout the pipeline, we implement an options/controls list approach, where each of the main functions (`LDA_TS`, `LDA_set`, and `TS`) and its subfunctions have a `control` argument that takes a `list` to replace the defaults returned by its `_control` function:

- `LDA_TS_control()`
- `LDA_set_control()`
- `TS_control()`