---
title: "dyadicMarkov workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{dyadicMarkov workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`dyadicMarkov` analyzes categorical dyadic sequences using transition matrices. The main steps are to compute empirical transition counts, estimate transition probabilities by maximum likelihood, and identify patterns of interaction in univariate and bivariate settings. The estimation functions summarize observed transitions as count and probability matrices. The identification functions compare restricted structures to describe the pattern retained for the sequence.

This vignette uses two synthetic examples included in the package. Each contains 90 observations and is used only to illustrate the workflow.

## Univariate dyadic workflow

The univariate example contains one categorical variable observed over time for two members of a dyad. The columns are `time`, the measurement occasion index; `FM`, the state for the first member; and `SM`, the state for the second member.

```{r univariate-data}
utils::data("dyadic_univariate_example", package = "dyadicMarkov")

head(dyadic_univariate_example)
dim(dyadic_univariate_example)
```

The first step is to compute empirical transition counts. For `states = 2`, the rows represent current dyadic states `(FM_t, SM_t)` and the columns represent the state of the first member at the next time point, `FM_{t+1}`.

```{r univariate-counts}
emp_uni <- dyadicMarkov::countEmp(
  dyadic_univariate_example$FM,
  dyadic_univariate_example$SM,
  states = 2L
)

emp_uni
```

Maximum likelihood estimation turns the empirical counts into transition probabilities. Each row is treated as a separate conditional distribution.

```{r univariate-mle}
fit_uni <- dyadicMarkov::mleEstimation(emp_uni)

round(fit_uni, 3)
rowSums(fit_uni)
```

The univariate pattern identification step compares restricted actor and partner structures at the chosen significance level.

```{r univariate-pattern}
pat_uni <- dyadicMarkov::univariatePattern(
  dyadic_univariate_example$FM,
  dyadic_univariate_example$SM,
  states = 2L,
  alpha = 0.05
)

pat_uni
```

For this synthetic example, the selected pattern is `PM (A3)`. In this pattern, the next state of the first member is described using the previous state of the second member, while the previous state of the first member is not retained in the restricted structure.

## Bivariate dyadic workflow

The bivariate example contains two categorical variables observed over time for both members of the dyad. The columns are `time`, the measurement occasion index; `FM_V1` and `SM_V1`, the first and second member states for variable 1; and `FM_V2` and `SM_V2`, the corresponding states for variable 2.

```{r bivariate-data}
utils::data("dyadic_bivariate_example", package = "dyadicMarkov")

head(dyadic_bivariate_example)
dim(dyadic_bivariate_example)
```

The bivariate count matrix summarizes transitions from the previous dyadic states of the two variables. Its columns correspond to the state of the first member on variable 1 at the next time point, `FM_V1,t+1`.

```{r bivariate-counts}
emp_bi <- dyadicMarkov::countEmpBivariate(
  chainFM_V1 = dyadic_bivariate_example$FM_V1,
  chainSM_V1 = dyadic_bivariate_example$SM_V1,
  chainFM_V2 = dyadic_bivariate_example$FM_V2,
  chainSM_V2 = dyadic_bivariate_example$SM_V2,
  states = 2L
)

emp_bi
```

The bivariate case identification step corresponds to the global approach. It determines whether the sequence is treated as trivial, univariate, partial bivariate, or complete bivariate.

```{r bivariate-case}
case_bi <- dyadicMarkov::bivariateCase(emp_bi, alpha = 0.05)

case_bi
```

This example is identified as a complete bivariate case. The local step therefore uses `completePattern()` to compare the complete bivariate candidate structures by AIC.

```{r bivariate-complete}
complete_bi <- dyadicMarkov::completePattern(emp_bi)

complete_bi
```

For this synthetic example, the selected complete bivariate pattern is `D2`.

## Practical notes

The bivariate functions currently support `states = 2`. The examples in this vignette are synthetic and are intended to show the package workflow.

The returned objects keep ordinary matrix or list behavior while adding S3 print and summary methods. Count and probability objects can still be used as matrices, and pattern and case objects can still be accessed with `$`.

```{r object-behavior}
class(emp_uni)
class(fit_uni)

class(pat_uni)
summary(pat_uni)

class(case_bi)
summary(case_bi)

class(complete_bi)
complete_bi$pattern
head(complete_bi$aic)
```