| Type: | Package |
| Title: | Pattern Estimation and Identification for Dyadic Sequences Using Transition Matrices in R |
| Version: | 0.1.2 |
| Description: | Provides methods for analyzing categorical dyadic sequences using transition matrices within the Longitudinal Actor-Partner Interdependence Model and Markov-chain framework. The package supports empirical transition counts, maximum likelihood estimation of transition probabilities, and identification of univariate and bivariate patterns of interaction in dyadic sequences. |
| License: | MIT + file LICENSE |
| URL: | https://github.com/BoellenruecherM/dyadicMarkov-public, https://boellenruecherm.github.io/dyadicMarkov-public/ |
| BugReports: | https://github.com/BoellenruecherM/dyadicMarkov-public/issues |
| Encoding: | UTF-8 |
| Language: | en-US |
| Depends: | R (≥ 4.1.0) |
| Imports: | stats |
| Suggests: | testthat (≥ 3.0.0), knitr, rmarkdown, srr |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| LazyData: | true |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-08-21 05:34:19 UTC; bolle |
| Author: | Mattia Böllenrücher
 [aut, cre,
cph],
Mégane Bollenrücher
[aut],
Jean-Philippe Antonietti
[aut] |
| Maintainer: | Mattia Böllenrücher <mboellenruec@student.ethz.ch> |
| Repository: | CRAN |
| Date/Publication: | 2026-08-21 08:30:02 UTC |
dyadicMarkov: Pattern Estimation and Identification for Dyadic Sequences Using Transition Matrices in R
Description
The dyadicMarkov package provides tools for analyzing categorical dyadic sequences using transition matrices in the Longitudinal Actor-Partner Interdependence Model and Markov-chain framework. It supports empirical transition counts, maximum likelihood estimation of transition probabilities, and identification of univariate and bivariate patterns of interaction.
Statistical scope
dyadicMarkov is designed for single-case categorical dyadic sequences. The temporal structure is represented by the order of the observations. The main outputs are empirical count matrices, estimated transition probability matrices, and identified patterns of interaction.
Supported state spaces
The univariate workflow supports any integer number of categorical states
S \ge 2. The bivariate method is developed for two dichotomous variables
and therefore supports states = 2 only, producing 16-by-2 empirical
count matrices. Bivariate support beyond two states would require additional
mathematical and software development and is not implemented by this package.
Comparison statistics
The univariate pattern-identification procedure is a likelihood-ratio test
(LRT) procedure that dyadicMarkov evaluates using Pearson's chi-squared statistic. The
global bivariate approach compares nested models within an LRT framework;
bivariateCase() implements two chi-squared tests for the A1 and B1
comparisons, evaluated using Pearson's chi-squared statistic. Local partial and complete
bivariate pattern selection is separate: it computes the G-squared deviance
and then AIC = G^2 + 2k for each candidate structure.
Main terminology
A dyadic sequence records the categorical states of two interacting individuals over time. Empirical transition counts summarize transitions from previous dyadic states to subsequent states of the analyzed sequence. Transition probabilities are estimated by normalizing each row of the empirical transition count matrix. Patterns of interaction are identified by comparing unrestricted and restricted transition structures based on actor and partner effects.
Lifecycle statement
dyadicMarkov is under active development. The current version focuses on univariate and bivariate categorical dyadic sequences. The core exported functions are intended to remain stable across minor releases.
Method
The method models categorical dyadic sequences with Markov chains in the Longitudinal Actor-Partner Interdependence Model (L-APIM) framework. It uses transition matrices to represent how previous dyadic states are related to the current state of the analyzed sequence.
Algorithmic contribution
The package implements the main computational steps of the method: empirical transition counts, estimation of transition probabilities, and identification of patterns of interaction in univariate and bivariate cases.
Author(s)
Maintainer: Mattia Böllenrücher mboellenruec@student.ethz.ch (ORCID) [copyright holder]
Authors:
Mattia Böllenrücher mboellenruec@student.ethz.ch (ORCID) [copyright holder]
Mégane Bollenrücher (ORCID)
Jean-Philippe Antonietti (ORCID)
References
Bollenrücher, M., Darwiche, J., & Antonietti, J.-P. (2023). Dyadic pattern analysis using longitudinal Actor-Partner Interdependence Model with Markov chains for unique case analysis. The Quantitative Methods for Psychology, 19(3), 230–243. doi:10.20982/tqmp.19.3.p230
Bollenrücher, M., Darwiche, J., & Antonietti, J.-P. (2024). Methodology for identification, visualization, and clustering of similar behaviors in dyadic sequences analyzed through the longitudinal Actor-Partner Interdependence Model with Markov chains. The Quantitative Methods for Psychology, 20(1), 17–32. doi:10.20982/tqmp.20.1.p017
Böllenrücher, M., Darwiche, J., & Antonietti, J.-P. (in press). Bivariate dyadic patterns analysis using longitudinal actor-partner interdependence model and Markov chains for single-case. Quantitative and Computational Methods in Behavioral Sciences. doi:10.23668/psycharchives.22174
Kenny, D. A., Kashy, D. A., & Cook, W. L. (2006). Dyadic Data Analysis. Guilford Press.
Bakeman, R., & Quera, V. (2011). Sequential Analysis and Observational Methods for the Behavioral Sciences. Cambridge University Press.
See Also
Useful links:
Bivariate case identification for dyadic Markov chains
Description
Identifies the bivariate case as "trivial", "univariate",
"partial", or "complete" using two chi-squared tests
against constrained binary bivariate structures.
Usage
bivariateCase(empirical, alpha = 0.05)
Arguments
empirical |
An empirical bivariate count matrix with 16 rows and 2
columns, as returned by |
alpha |
A single number in (0, 1) giving the significance level. Default is 0.05. |
Details
The returned case corresponds to the global approach of the
binary bivariate method. The scientific method treats the global
comparisons as nested-model comparisons within a likelihood-ratio test
(LRT) framework. bivariateCase() implements the two chi-squared
tests for the A1 and B1 comparisons. dyadicMarkov evaluates these tests
using Pearson's chi-squared statistic,
X^2 = \sum_{ij} (O_{ij} - E_{ij})^2 / E_{ij},
where O and E are the empirical and theoretical transition
counts. A global comparison is treated as rejected when
p \leq \alpha. The result determines whether the sequence analyzed is
treated as trivial, univariate, partial bivariate, or complete bivariate before the
separate local AIC-based identification of the pattern of interaction.
Value
A list with class c("dyadic_case", "list") containing
components testUnivariate, testPartial, case, and
metadata fields alpha and call. It remains usable as an
ordinary list.
Examples
chainFM_V1 <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM_V1 <- c(2L, 1L, 2L, 1L, 1L, 2L)
chainFM_V2 <- c(1L, 1L, 2L, 2L, 1L, 2L)
chainSM_V2 <- c(2L, 2L, 1L, 1L, 2L, 1L)
emp <- countEmpBivariate(
chainFM_V1, chainSM_V1, chainFM_V2, chainSM_V2,
states = 2L
)
bivariateCase(emp, alpha = 0.05)
Complete bivariate pattern identification by AIC
Description
Compares the complete bivariate patterns C, D1–D4, and E1–E4 using AIC and returns the selected pattern.
Usage
completePattern(empirical)
Arguments
empirical |
An empirical bivariate count matrix with 16 rows and 2
columns, as returned by |
Details
Conditional on the complete bivariate case, the G-squared deviance is computed for each C, D1–D4, and E1–E4 candidate before calculating
AIC = G^2 + 2k,
where
G^2 = 2 \sum_{ij} O_{ij} \log(O_{ij} / E_{ij}).
The candidate with the smallest AIC is selected.
Value
A list with class c("dyadic_pattern", "list") containing
components aic (a data frame with columns pattern,
matrix, and aic), pattern (the selected pattern
label), and call. It remains usable as an ordinary list.
Examples
chainFM_V1 <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM_V1 <- c(2L, 1L, 2L, 1L, 1L, 2L)
chainFM_V2 <- c(1L, 1L, 2L, 2L, 1L, 2L)
chainSM_V2 <- c(2L, 2L, 1L, 1L, 2L, 1L)
emp <- countEmpBivariate(
chainFM_V1, chainSM_V1, chainFM_V2, chainSM_V2,
states = 2L
)
completePattern(emp)
Empirical transition counts for univariate dyadic sequences
Description
Computes empirical transition counts for the sequences of the first and second member. Rows correspond to dyadic states of the two members, and columns correspond to the state of the first member at the next time point.
Usage
countEmp(chainFM, chainSM, states)
Arguments
chainFM |
Vector of observed states for the first member (FM). |
chainSM |
Vector of observed states for the second member (SM). |
states |
A single integer >= 2 giving the number of states. |
Details
Rows correspond to current dyadic states (FM_t, SM_t).
For general states, the row index is computed as
1 + states * (FM_t - 1) + (SM_t - 1). Columns correspond to the
state of the first member at the next time point, FM_{t+1}.
Value
An integer matrix with class
c("dyadic_counts", "matrix", "array"),
with states^2 rows and states columns. It remains usable as an
ordinary matrix.
Examples
chainFM <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM <- c(2L, 1L, 2L, 1L, 1L, 2L)
countEmp(chainFM, chainSM, states = 2L)
Empirical transition counts for bivariate dyadic sequences
Description
Computes empirical transition counts for bivariate categorical dyadic
sequences with two variables. This function currently supports
states = 2 only.
Usage
countEmpBivariate(chainFM_V1, chainSM_V1, chainFM_V2, chainSM_V2, states = 2L)
Arguments
chainFM_V1, chainSM_V1 |
Vectors of observed states for variable 1 for the first and second member. |
chainFM_V2, chainSM_V2 |
Vectors of observed states for variable 2 for the first and second member. |
states |
A single integer. Currently only |
Details
The bivariate counter currently supports states = 2 only.
Rows represent the previous dyadic states of variable 1 and variable 2.
Writing K for the number of states, the row index at time t is
r_t = 1 + K^2 [K(FM_{V1,t} - 1) + (SM_{V1,t} - 1)] + K(FM_{V2,t} - 1) + (SM_{V2,t} - 1)
Columns correspond to
the state of the first member on variable 1 at the next time point,
FM_{V1,t+1}.
Value
An integer matrix with class
c("dyadic_counts", "matrix", "array") with 16 rows and 2 columns
when states = 2. It remains usable as an ordinary matrix.
Examples
chainFM_V1 <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM_V1 <- c(2L, 1L, 2L, 1L, 1L, 2L)
chainFM_V2 <- c(1L, 1L, 2L, 2L, 1L, 2L)
chainSM_V2 <- c(2L, 2L, 1L, 1L, 2L, 1L)
emp <- countEmpBivariate(
chainFM_V1, chainSM_V1, chainFM_V2, chainSM_V2,
states = 2L
)
dim(emp)
Synthetic bivariate dyadic sequence example
Description
A synthetic bivariate dyadic sequence with 90 observations, designed for package workflow examples.
Usage
dyadic_bivariate_example
Format
A data frame with 90 rows and 5 columns:
- time
Index of the measurement occasion.
- FM_V1
Integer variable 1 state for the first member, taking values 1 or 2.
- SM_V1
Integer variable 1 state for the second member, taking values 1 or 2.
- FM_V2
Integer variable 2 state for the first member, taking values 1 or 2.
- SM_V2
Integer variable 2 state for the second member, taking values 1 or 2.
Details
The bivariate workflow classifies this example as complete
using bivariateCase with alpha = 0.05. The complete
bivariate pattern selected by completePattern is D2.
Synthetic univariate dyadic sequence example
Description
A synthetic dyadic sequence with 90 observations, designed for package workflow examples.
Usage
dyadic_univariate_example
Format
A data frame with 90 rows and 3 columns:
- time
Index of the measurement occasion.
- FM
Integer state for the first member, taking values 1 or 2.
- SM
Integer state for the second member, taking values 1 or 2.
Details
The package workflow classifies this example as PM (A3)
using univariatePattern with states = 2.
Maximum likelihood estimation of transition probabilities
Description
Estimates transition probabilities by maximum likelihood from an empirical
count matrix returned by countEmp or
countEmpBivariate.
Usage
mleEstimation(empirical)
Arguments
empirical |
An empirical count matrix. |
Details
Each row of empirical is normalized independently. Rows with
zero total count are assigned a uniform probability vector, so each row of
the returned matrix sums to one.
Value
A numeric matrix with class
c("dyadic_mle", "matrix", "array")
containing estimated transition probabilities with the same dimensions as
empirical. It remains usable as an ordinary matrix.
Examples
chainFM <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM <- c(2L, 1L, 2L, 1L, 1L, 2L)
emp <- countEmp(chainFM, chainSM, states = 2L)
mleEstimation(emp)
Partial bivariate pattern identification by AIC
Description
Compares the partial bivariate patterns B1, B2, and B3 using AIC and returns the selected pattern.
Usage
partialPattern(empirical)
Arguments
empirical |
An empirical bivariate count matrix with 16 rows and 2
columns, as returned by |
Details
Conditional on the partial bivariate case, the G-squared deviance is computed for each B1, B2, and B3 candidate before calculating
AIC = G^2 + 2k,
where
G^2 = 2 \sum_{ij} O_{ij} \log(O_{ij} / E_{ij}).
The candidate with the smallest AIC is selected.
Value
A list with class c("dyadic_pattern", "list") containing
components aic (a data frame with candidate patterns and AIC
values), pattern (the selected pattern label), and call. It
remains usable as an ordinary list.
Examples
chainFM_V1 <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM_V1 <- c(2L, 1L, 2L, 1L, 1L, 2L)
chainFM_V2 <- c(1L, 1L, 2L, 2L, 1L, 2L)
chainSM_V2 <- c(2L, 2L, 1L, 1L, 2L, 1L)
emp <- countEmpBivariate(
chainFM_V1, chainSM_V1, chainFM_V2, chainSM_V2,
states = 2L
)
partialPattern(emp)
Univariate pattern identification for dyadic Markov chains
Description
Computes empirical transition counts, estimates transition probabilities by maximum likelihood, and performs likelihood-ratio tests against the actor-only and partner-only constrained models to identify the univariate pattern of interaction.
Usage
univariatePattern(chainFM, chainSM, states, alpha = 0.05)
Arguments
chainFM |
Vector of observed states for the first member (FM). |
chainSM |
Vector of observed states for the second member (SM). |
states |
A single integer >= 2 giving the number of states. |
alpha |
A single number in (0, 1) giving the significance level. Default is 0.05. |
Details
The nested full/restricted comparisons form the univariate likelihood-ratio test (LRT) procedure. dyadicMarkov evaluates each LRT comparison using Pearson's chi-squared statistic,
X^2 = \sum_{ij} (O_{ij} - E_{ij})^2 / E_{ij},
where O and E are the empirical and theoretical transition
counts. A comparison is treated as rejected when p \leq \alpha.
Pattern labels summarize which structure is retained by the tests:
IM (A0) denotes an independence pattern, APM (A1) an
actor-partner pattern, AM (A2) an actor-only pattern, and
PM (A3) a partner-only pattern.
Value
A list with class c("dyadic_pattern", "list") containing two
htest objects (TEST.AM, TEST.PM), a string
pattern, and metadata fields alpha, states, and
call. It remains usable as an ordinary list.
Examples
chainFM <- c(1L, 2L, 1L, 2L, 2L, 1L)
chainSM <- c(2L, 1L, 2L, 1L, 1L, 2L)
univariatePattern(chainFM, chainSM, states = 2L, alpha = 0.05)