seqR: Ordinal Sequence Analysis

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Adjacency Matrix
#'
#' Create an adjacency matrix from two ordinal variables.
#'
#' @param x `NumericVector`.
#' @param y `NumericVector`.
#' @param states Optional integer. Specify the max number of states
#'          between the two vectors. The outputed matrix will be of
#'          size `states ^ 2 x states ^ 2`. Default: `max(a, b)`.
#' @param direction Optional string. Specify "up" to create an
#'          adjacency matrix from only increasing transitions, or
#'          "down" for decreasing transitions.
#'
#' @section Warning: `adj_matrix` assumes that the target
#'            variables are indexed at 0.
#'
#' @details The adjacency matrix represents paired transitions for two
#'          variables. If we consider each possible unique pair as
#'          serialized on an ordinal scale (`1, 2, .., K`) then the
#'          column numbers of the adjacency matrix denote the start
#'          position of the transition (the observed pair at
#'          observation `i`) and the row numbers denote the end
#'          position of the transition (the observed pair at
#'          observation `i + 1`). This can be visualized graphically
#'          with `plot` or as an `igraph` adjacency graph with
#'          [igraph::graph.adjacency].
#'
#' @return A `S3` matrix of class `adj_mat`. Can be plotted with the
#'         normal `plot` function.
#'
#' @examples
#' x <- c(1, 2, 2)
#' y <- c(2, 1, 2)
#' adj_matrix(x, y) # `states` will be set to 3
#'
#' @export
adj_matrix <- function(x, y, states = NULL, direction = NULL) {
    .Call('_seqR_adj_matrix', PACKAGE = 'seqR', x, y, states, direction)
}

#' Collapse a data frame
#'
#' Collapse unchanging consecutive observations for a given data frame.
#'
#' @param data A data.frame. Data to collapse
#' @param include_na Boolean. Whether to collapse consecutive NAs.
#'
#' @details If the given data frame contains multiple columns, then
#'          an observation is only collapsed if all of the columns
#'          are unchanging.
#'   
#'          Row and column names will be preserved; however, other
#'          user defined attributes will be dropped.
#'
#' @section Warning: `collapse` currently only works with REALSXP,
#'           INTSXP, STRSXP, LGLSXP objects. This covers all of the
#'           common atomic R data types, including more complex types
#'           like `Date`. Unfortunately however, this means that
#'           `collapse` will return an error if a column has a class
#'           of `raw`. Bummer.
#'
#' @return A `data.frame` of row size: `0 < N <= nrow(data)`.
#'
#' @examples
#' x <- data.frame(x = c(1, 1, 1), y = c(1, 2, 2))
#' collapse(x)
#'
#' y <- data.frame(x = c(1, 1, 1), y = c("a", "a", "b"), stringsAsFactors = FALSE)
#' collapse(y)
#'
#' @export
collapse <- function(data, include_na = FALSE) {
    .Call('_seqR_collapse', PACKAGE = 'seqR', data, include_na)
}

#' Find subsequences based on movement
#'
#' Given a sequence of numbers, as a numeric vector, find the
#' increasing or decreasing subsequences.
#'
#' @param v A numeric vector.
#' @param direction Character string of either "up" to find
#'          increasing sequences or "down" to find decreasing
#'          sequences. Default: "up".
#' @param buffer Optional parameter indicating how many repeated
#'          elements to include to the left (prior to the start) and
#'          right (following the end) of a subsequence.
#' @param lbuffer Optional parameter indicating how many repeated
#'          elements to include to the left (prior to the start) of a
#'          subsequence. Takes precedence over the option
#'          `buffer`.
#' @param rbuffer Optional parameter indicating how many repeated
#'          elements to include to the right (following the end) of a
#'          subsequence. Takes precedence over the option
#'          `buffer`.
#' @param upper_lim Optional parameter that filters out
#'           subsequences which do not reach an upper lim.
#' @param lower_lim Optional parameter that filters out
#'           subsequences which do not begin below a given lim.
#'
#' @details `findMovement` finds the subsequences within a
#'           numeric vector based on either increasing or decreasing
#'           movement. An increasing subsequence is defined as a
#'           sequence of values where `V[n] >= V[n - 1]`. The
#'           start point is strict, meaning the first point where `V[n] <
#'           V[n + 1]`. The option `lbuffer` can be specified to
#'           include an arbitrary number, `k`, of constant
#'           elements prior to `V[n]` where `V[n - k] ==
#'           V[n]`. Likewise, the end point of a subsequence is the
#'           element where `V[n] > V[n + 1]` or `V[n + 1]` is
#'           NA. `rbuffer` will also include a constant number
#'           of elements after the end point. Alternatively, the
#'           option `buffer` can be used to specify equal
#'           buffering at both the start and end of subsequences.
#'
#' @return A numeric vector of the same length as `v` where
#'          subsequences are given values 1:N and elements falling
#'          outside of subsequences are set to `NA`.
#'
#'
#' @examples
#' x <- c(4, 4, 3, 1, 0, 1, 0, 1, 2, 2, 2, 3, 3)
#' findMovement(x)
#' findMovement(x, direction = "down")
#'
#' # Let's find buffered subsequences that increase starting at 2
#' findMovement(x, buffer = 1, lower_lim = 2)
#'
#' @export
findMovement <- function(v, direction = "up", buffer = 0L, lbuffer = NULL, rbuffer = NULL, upper_lim = NULL, lower_lim = NULL) {
    .Call('_seqR_findMovement', PACKAGE = 'seqR', v, direction, buffer, lbuffer, rbuffer, upper_lim, lower_lim)
}