Title:	Transmodal Analysis (TMA)
Type:	Package
Author:	Cody L Marquart [aut, cre], Muhammad Hasnat Ashiq [aut], David Williamson Shaffer [aut]
Maintainer:	Cody L Marquart <cody.marquart@wisc.edu>
Version:	0.3.0
Encoding:	UTF-8
Description:	A robust computational framework for analyzing complex multimodal data. Extends existing state-dependent models to account for diverse data streams, addressing challenges such as varying temporal scales and learner characteristics to improve the robustness and interpretability of findings. For methodological details, see Shaffer, Wang, and Ruis (2025) "Transmodal Analysis" <doi:10.18608/jla.2025.8423>.
LazyData:	TRUE
Depends:	R (≥ 3.6), data.table
License:	GPL-3
Imports:	stats, methods, rlang, jsonlite, Rcpp
Suggests:	testthat (≥ 2.1.0), rstudioapi, knitr, rmarkdown
RoxygenNote:	7.3.2
LinkingTo:	Rcpp, RcppArmadillo
NeedsCompilation:	yes
Packaged:	2025-08-19 18:41:41 UTC; clmarquart
Repository:	CRAN
Date/Publication:	2025-08-25 08:00:02 UTC

Extract Metadata or Columns from Network Matrix (S3 method)

Description

This S3 method allows convenient extraction of metadata columns from a network matrix object using the $ operator. If the requested column is metadata, it is returned from the model's meta.data; otherwise, the standard extraction is performed.

Usage

## S3 method for class 'network.matrix'
x$i

Arguments

Value

The requested column or metadata field from the network matrix.

Coded Rescushell Chat Data

Description

A dataset containing sample chat data from the Rescushell Virtual Internship

Usage

RS.data

Format

An object of class data.frame with 3824 rows and 21 columns.

Coded Rescushell multi-modal Data

Description

A dataset containing sample chat data from the Rescushell Virtual Internship with multiple modalities

Usage

RS.data.multimodal

Format

An object of class data.table (inherits from data.frame) with 6641 rows and 19 columns.

Accumulate Connections from a Multidimensional Array and Context Model

Description

This function processes a context model and a multidimensional array of window/weight parameters to compute connection counts for each unit of analysis. It applies the context model to the array, using sender, receiver, and mode columns (as defined in the array attributes), and accumulates co-occurrence or adjacency matrices for each unit. The result is a set of connection counts and row-level connection matrices, suitable for network analysis (e.g., ENA/ONA).

Usage

accumulate(
  context_model,
  codes,
  tensor = context_tensor(context_model$model$raw.input),
  time_column = NULL,
  ordered = TRUE,
  binary = FALSE
)

Arguments

Details

This function is used to perform accumulation of network connections for each unit, based on the context model and tensor parameters. It supports both ordered and unordered accumulation, and returns results suitable for further network analysis or visualization.

Value

The input 'context_model' with additional fields:

The class of the returned object is updated to reflect the type of accumulation (ordered or unordered).

accumulate_contexts

Description

accumulate_contexts

Usage

accumulate_contexts(
  x,
  codes,
  decay.function = decay(simple_window, window_size = 4),
  time.column = NULL,
  mode.column = NULL,
  mask = NULL,
  weight.by = sqrt,
  norm.by = `_sphere_norm`,
  meta.data = NULL,
  return.dena.set = FALSE,
  return.ena.set = TRUE,
  context_filter = NULL,
  summarize_ground_using = colSums,
  calculate_adj_vectors_using = ground_response_crossprod,
  ground_effect_function = function(x, y) crossprod(t(x), y),
  accumulate_unit_vectors_by = colSums
)

Arguments

Value

ENA set

fast accumulate networks

Description

fast accumulate networks

Usage

accumulate_networks(
  x,
  code_cols,
  decay_function,
  time_col = -1L,
  ordered = TRUE
)

Arguments

accumulate_threads

Description

accumulate_threads

Usage

accumulate_threads(
  data,
  units_by,
  conversation_rules,
  code_cols,
  ...,
  conversation_splits = NULL,
  as_directed = FALSE,
  window_size = 4,
  meta_data = units_by
)

Arguments

Value

TBD

Apply windowing and weighting to context data for network accumulation (C++ backend)

Description

This function implements the core logic for accumulating network connections using a multidimensional parameter array (context_tensor), efficiently applying window and weight parameters to each response line in a unit's context. It is designed for use in the TMA package to speed up accumulation calculations by leveraging C++ and Armadillo for matrix operations.

Usage

apply_tensor(
  tensor,
  dims,
  dims_sender,
  dims_receiver,
  dims_mode,
  context_matrix,
  unit_rows,
  codes,
  times,
  ordered = TRUE
)

Arguments

Value

A list with two elements: - row_connection_counts: A matrix of connection counts for each response line (rows = response lines, columns = connections). - connection_counts: A vector of accumulated connection counts for the unit (length = number of connections).

Convert Adjacency Key to Character (S3 method)

Description

This S3 method converts an adjacency key object (typically a 2-row matrix or list of pairs) into a character vector, concatenating each pair with ' & '.

Usage

## S3 method for class 'adjacency.key'
as.character(x, ...)

Arguments

Value

A character vector where each element is a concatenation of the adjacency key pair.

Convert Adjacency Key to Double (S3 method)

Description

This S3 method converts an adjacency key object to a numeric (double) vector, applying as.numeric to each element.

Usage

## S3 method for class 'adjacency.key'
as.double(x, ...)

Arguments

Value

A numeric vector representation of the adjacency key.

Matrix without metadata

Description

Matrix without metadata

Usage

## S3 method for class 'ena.matrix'
as.matrix(x, ...)

Arguments

Value

matrix

Convert Network Connections to Matrix (S3 method)

Description

This S3 method extracts the connection columns from a network connections object and returns them as a numeric matrix. It is used to facilitate matrix operations on network connection data.

Usage

## S3 method for class 'network.connections'
as.matrix(x, ...)

Arguments

Value

A numeric matrix of network connections (rows = units/contexts, columns = connections).

Re-class vector as network.connection

Description

Re-class vector as network.connection

Usage

as.network.connection(x)

Arguments

Value

re-classed vector

Extract Upper Triangular Elements

Description

This function extracts the elements from the upper triangular part of a matrix.

Usage

as.undirected.vector(x, diag = FALSE)

Arguments

Value

A vector containing the upper triangular elements of the matrix.

Convert to Unordered Factor

Description

This function is a generic method to convert an object to an unordered factor. It dispatches methods based on the class of the input object.

Usage

as.unordered(x)

Arguments

Value

An unordered factor representation of the input object.

Default Method for as.unordered

Description

This function provides the default method for handling the input x when no specific method is available.

Usage

## Default S3 method:
as.unordered(x)

Arguments

Value

The input object x, unchanged.

Unorder Connections in a Matrix

Description

This function takes a matrix and creates an unordered version of its connections, combining upper and lower triangular elements.

Usage

## S3 method for class 'ordered.ena.connections'
as.unordered(x)

Arguments

Value

A data.table with ordered connections, reclassified as "unordered.ena.connections", "ena.connections", and "ena.matrix".

Convert Ordered Row Connections to Unordered (S3 method)

Description

This S3 method takes a matrix or data frame of ordered row connections (e.g., from ONA) and produces an unordered version by summing upper and lower triangular elements for each connection.

Usage

## S3 method for class 'ordered.row.connections'
as.unordered(x)

Arguments

Value

A data.table with unordered row connections, reclassified as "unordered.row.connections", "row.connections", and "ena.matrix".

n choose 2

Description

n choose 2

Usage

choose_two(n)

Arguments

Column Sums for ENA Matrices (S3 method)

Description

This S3 method computes column sums for ENA matrix objects, with optional binarization. It is used to summarize connection counts across rows (e.g., for each unit or context).

Usage

colSums.ena.matrix(x, na.rm = FALSE, dims = 1L, binary = FALSE)

Arguments

Value

A numeric vector of column sums for the matrix.

Generate a multidimensional array for window and weight parameters

Description

This function constructs a multidimensional array representing all combinations of sender(s), receiver(s), and mode(s), with an additional axis for weight and window parameters. The resulting array can be used to efficiently look up or modify window and weight values for each unique combination in your data, which is useful for network accumulation and modeling.

Usage

context_tensor(
  df,
  sender_cols = NULL,
  receiver_cols = NULL,
  mode_column = ATTR_NAMES$CONTEXT_ID,
  default_window = 1,
  default_weight = 1
)

Arguments

Value

A multidimensional array with dimensions [sender(s), receiver(s), mode(s), weight/window], where the last axis has two levels: "weight" and "window". The array is initialized with the default weight and window values, and has named dimensions for easy indexing.

Examples

df <- data.frame(sender = c("A", "B"), receiver = c("X", "Y"), mode = c("chat", "resource"))
arr <- context_tensor(df, sender_cols = "sender", receiver_cols = "receiver", mode_column = "mode")
arr["A", "X", "chat", "weight"] # Access the weight for sender A, receiver X, mode chat

Create Contexts for Units of Analysis

Description

This function generates context data for each unit of analysis in your dataset, applying subsetting rules ("hoo rules") and optional splitting rules to organize the data for network accumulation.

Usage

contexts(x, hoo_rules, units_by = NULL, split_rules = NULL)

Arguments

Details

This function is a core part of the TMA workflow. It first applies the specified 'hoo_rules' to subset the data for each unit, then (optionally) applies 'split_rules' to further divide each context. The resulting contexts are used in subsequent accumulation and network analysis steps.

Value

A TMA model object with updated contexts for each unit, where each context is a data.table containing only the relevant rows for that unit and context. The object includes attributes for unit labels and context row indices.

Examples

data(test_mockdata, package = "tma")
mock_data <- test_mockdata[test_mockdata$chatGroup == "PAM",]
unit_cols <- c("userID", "condition")
codes <- c("A", "B", "C")
HOO_rules_model <- rules(
  modality %in% "chat" & chatGroup %in% UNIT$chatGroup & condition %in% UNIT$condition, 
  modality %in% "resource" & userID %in% UNIT$userID & condition %in% UNIT$condition
)
 
context_model <- contexts(
  x = mock_data,
  units = unit_cols,
  hoo_rules = HOO_rules_model
)
str(context_model$model$contexts)

Conversation rules

Description

Conversation rules

Usage

conversation_rules(...)

Arguments

Value

callable expressions, see 'rlang::exprs'

Internal: Decay function factory (legacy)

Description

Internal factory for creating decay functions, used in TMA v0.1.0. Not exported. Kept for backward compatibility with legacy code.

Usage

decay(what, ...)

Arguments

Value

A function that applies the specified decay kernel to its input.

Find metadata columns

Description

Find metadata columns

Usage

find_meta_cols(x)

Arguments

Value

logical vector

Apply a Subsetting Rule to TMA Contexts (Internal)

Description

Internal helper to apply a logical subsetting rule ("hoo rule") to each unit's context in a TMA model object. Updates the contexts for each unit by including only rows that match the rule.

Usage

hoo(x, ..., rule = NULL)

Arguments

Value

The input TMA model object with updated contexts for each unit, where each context contains only rows matching the rule.

Title

Description

Title

Usage

## S3 method for class 'network.connections'
names(x)

Arguments

Value

TBD

Names to Adjacency Key

Description

Convert a vector of strings, representing the names of a square matrix, to an adjacency key matrix.

Usage

namesToAdjacencyKey(vector, upper_triangle = TRUE)

Arguments

Details

Returns a matrix with 2 rows and choose(length(vector), 2) columns, where each column represents a unique pair of names from the input vector, corresponding to the upper triangle of a square matrix.

Value

A character matrix with 2 rows and choose(length(vector), 2) columns. Each column contains a pair of names representing a unique adjacency (edge) between nodes in the original square matrix.

Print Method for Network Matrix (S3 method)

Description

This S3 method prints a network matrix object, optionally including metadata. It adjusts the class and attaches adjacency key names for improved readability.

Usage

## S3 method for class 'network.matrix'
print(x, include.meta = TRUE, ...)

Arguments

Value

Invisibly returns the printed object.

Remove meta columns from a data.table or data.frame

Description

This function removes columns of class 'ena.meta.data' from the input object.

Usage

remove_meta_data(x)

Arguments

Value

A 'data.frame' with columns of class 'ena.meta.data' removed.

Capture Subsetting Rules as Expressions

Description

Allows users to supply conditions for subsetting rows from their data. The collected unevaluated expressions are intended to be used as the 'hoo_rules' parameter in the 'contexts()' function within the TMA workflow.

Usage

rules(...)

Arguments

Value

A list of unevaluated expressions representing subsetting rules.

Examples

rules(
  modality %in% "chat" & chatGroup %in% UNIT$chatGroup & condition %in% UNIT$condition, 
  modality %in% "resource" & userID %in% UNIT$userID & condition %in% UNIT$condition
)

Internal: Simple window decay (legacy)

Description

Internal helper for window decay, used in TMA v0.1.0. Not exported. Kept for backward compatibility with legacy decay function creation.

Usage

simple_window(x, args = NULL)

Arguments

Value

Numeric vector (0/1) indicating whether each value is within the window.

Sample Data

Description

A small sample dataset

Usage

test_mockdata

Format

An object of class data.table (inherits from data.frame) with 24 rows and 12 columns.

Sample Data

Description

A dataset containing threads

Usage

test_reddit

Format

An object of class data.frame with 463 rows and 19 columns.

Sample Data

Description

A dataset containing threads

Usage

test_reddit2

Format

An object of class data.frame with 776 rows and 15 columns.

Sample Data

Description

A small sample dataset

Usage

test_smalldata

Format

An object of class data.frame with 12 rows and 8 columns.

TMA for ENA

Description

TMA for ENA. rENA is used to create and visualize network models of discourse and other phenomena from coded data using Epistemic Network Analysis (ENA).

Find conversations by unit

Description

Identify and extract rows corresponding to conversations for specified units in a dataset or context model. Useful for subsetting and analyzing conversational windows in network analysis.

Usage

tma.conversations(
  x,
  units,
  units.by = NULL,
  codes = NULL,
  conversation.by = NULL,
  window = 4,
  conversation.exclude = c(),
  id_col = "QEUNIT"
)

Arguments

Details

This function groups rows by conversation (using 'conversation.by' columns), identifies which rows are associated with the specified units and codes, and returns indices for each conversation, as well as metadata about which rows to include or exclude.

Value

A list with elements:

Set Units of Analysis for a TMA Model

Description

Internal helper to initialize and label units of analysis in a TMA model object. Given a data.frame and a set of columns, this function creates a model structure with unit labels and context placeholders for each unique unit.

Usage

units(x, by)

Arguments

Value

A TMA model object with unit labels and empty context slots for each unit.

Interactive Conversation Viewer

Description

Launch an interactive HTML viewer for conversations and codes for a specified unit or set of units. Useful for exploring and validating conversation windows and code assignments in the TMA workflow.

Usage

view(
  x,
  wh,
  text_col = "text",
  units.by = x$`_function.params`$units.by,
  conversation.by = x$`_function.params`$conversation.by,
  codes = x$rotation$codes,
  window_size = x$`_function.params`$window_size,
  more_cols = NULL,
  in_browser = FALSE,
  id_col = "QEUNIT"
)

Arguments

Value

A list containing the viewer data and metadata (invisibly). The function is called for its side effect of launching the viewer.

Deprecated Alias for context_tensor

Description

Use context_tensor() instead. This alias will be removed in a future release.

Usage

windows_weights(...)

Arguments

Value

A multidimensional array with dimensions [sender(s), receiver(s), mode(s), weight/window], where the last axis has two levels: "weight" and "window". The array is initialized with the default weight and window values, and has named dimensions for easy indexing.

See Also

context_tensor