---
title: "Introduction to dyadicMarkov"
bibliography: references.bib
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to dyadicMarkov}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Purpose of the package

`dyadicMarkov` implements an R workflow for identifying patterns of interaction in categorical dyadic sequences using transition matrices. The package is designed for situations in which one or two categorical variables are observed repeatedly for both members of one dyad, so that the analysis accounts for both temporal dependence and dyadic dependence.

`dyadicMarkov` is based on three methodological papers on dyadic pattern analysis with the Longitudinal Actor-Partner Interdependence Model (L-APIM) and Markov chains. The univariate single-case method is described by @bollen2023. The extension to visualization and clustering of similar dyadic behaviors is described by @bollen2024. The bivariate single-case method is described by @bollen2026. The visualization and clustering methodology of @bollen2024 is methodological background; it is not currently part of the exported package API.

## Real-world use cases

The package is intended for ordered categorical observations collected from two members of a dyad. In practice, such sequences may arise from coded interaction data, daily diary studies, repeated binary responses, or intensive longitudinal designs. For example, researchers may code whether each partner shows a given behavior at each measurement occasion, whether a parent and child are in one of several interaction states, or whether two individuals report the presence or absence of a response across repeated observations.

The package does not estimate a general-purpose time-series forecasting model. Instead, it summarizes how the next state of the analyzed sequence is associated with its own previous state and with the previous state of the partner. The resulting pattern labels help describe whether the observed transitions are better characterized by actor dependence, partner dependence, actor-partner dependence, independence, or, in the bivariate workflow, by partial or complete bivariate dependence structures.

The example datasets included in the package are synthetic. They are used to make the required input structure reproducible and easy to inspect. They should be read as small stand-ins for real ordered dyadic sequences, not as substantive empirical datasets.

## Data structure

The package works with categorical dyadic sequences. In the univariate case, one categorical variable is observed over time for two members of a dyad. For each function call, the first member is the member whose next state is modeled, and the second member supplies the partner sequence. The roles can be reversed to analyze the other member.

In the bivariate case, two categorical variables are observed over time for both members of the dyad. The current implementation of the bivariate workflow supports binary variables (`states = 2`). This leads to a bivariate empirical count matrix with 16 rows and 2 columns: the 16 rows represent the four binary lagged components: the first member on the main variable, the second member on the main variable, the first member on the second variable and the second member on the second variable. The 2 columns represent the possible next states of the first member on the main variable.

The state-space scope differs between the two methods. The univariate workflow supports any integer number of categorical $states \ge 2$. The bivariate method is developed for two dichotomous variables and supports `states = 2` only; bivariate analysis with more than two states would require additional mathematical and software development.

## Estimation and identification

The package separates estimation from identification. Estimation summarizes the observed sequences as empirical transition counts and maximum-likelihood transition probabilities. Identification compares the observed transition structure with restricted transition structures corresponding to interpretable patterns of interaction.

In the univariate workflow, the relevant patterns are actor-partner, actor-only, partner-only and independence. In the bivariate workflow, the analysis first identifies the global case as trivial, univariate, partial bivariate or complete bivariate. A trivial case has no subsequent local pattern. A univariate case is followed by `univariatePattern()` on the main-variable sequences. Partial and complete cases are followed by `partialPattern()` and `completePattern()`, respectively.

The comparison statistics also differ by step. The univariate pattern-identification procedure uses the Likelihood-Ratio Test (LRT) nomenclature of the underlying method; `dyadicMarkov` evaluates these comparisons using Pearson's chi-squared statistic, $X^2 = \sum (O - E)^2 / E$. The global bivariate approach compares nested models within an LRT framework; `bivariateCase()` implements two chi-squared tests for the A1 and B1 comparisons, also evaluated using Pearson's chi-squared statistic, $X^2$. The local partial and complete bivariate procedures instead compute the G-squared deviance, $G^2 = 2 \sum O \log(O / E)$, and then calculate $AIC = G^2 + 2k$ for each candidate structure.

## Exported functions

The user-facing workflow is organized around seven exported functions:

- `countEmp()` computes empirical transition counts for the first member sequence in a univariate dyadic sequence.
- `mleEstimation()` estimates transition probabilities from empirical count matrices.
- `univariatePattern()` identifies the univariate interaction pattern.
- `countEmpBivariate()` computes empirical transition counts for the first member sequence in a bivariate dyadic sequence.
- `bivariateCase()` identifies the global dependence case for the analyzed sequence.
- `partialPattern()` selects a local pattern for a partial bivariate case.
- `completePattern()` selects a local pattern for a complete bivariate case.

## Assumptions and current scope

The workflow assumes categorical states coded as integers from 1 to `states`, equal chain lengths, ordered repeated observations, and a first-order homogeneous transition process. Inputs containing `NA` are rejected; missing observations are not deleted or imputed automatically because they break the construction of transition pairs.

Based on the sensitivity analysis reported in @bollen2026, a minimum sequence length of 90 measurement points is recommended for applying the method. Pattern-identification accuracy improves with longer sequences; for shorter sequences, particularly at 30 measurement points, the procedure often results in a trivial pattern, whereas from 90 measurement points onward the occurrence of trivial patterns diminishes significantly. This is methodological guidance rather than a hard input requirement in `dyadicMarkov`.

The bivariate method and functions support the binary-state case. With two binary variables observed for two members, the previous state is described by four binary components, producing $2^4 = 16$ previous-state combinations. Generalizing this workflow beyond `states = 2` would require additional mathematical development of the bivariate restriction structures as well as software implementation.

## Relationship to the workflow vignettes

This introduction explains the scope and structure of the package. The univariate workflow vignette shows the use of `countEmp()`, `mleEstimation()` and `univariatePattern()`. The bivariate workflow vignette shows the use of `countEmpBivariate()`, `bivariateCase()`, `partialPattern()` and `completePattern()`.

## References