# Introduction to roundRobinR

    library(roundRobinR)

## Overview

The `roundRobinR` package provides tools for analyzing directed dyadic data collected with a round-robin design, in which every person in a group rates or interacts with every other person. The core analytical framework is the Social Relations Model (SRM; Kenny, Kashy, & Cook, 2006), estimated via multilevel modeling following Snijders and Kenny (1999) and Knight and Humphrey (2019).

The SRM decomposes the total variance in a directed dyadic outcome into four components:

Component | Interpretation
--- | ---
Group | How much groups differ in their mean level
Actor | How much people differ in what they give or emit
Partner | How much people differ in what they receive or elicit
Dyad | Variance in the unique relationship between each specific pair

In addition, two reciprocity parameters are estimated:

- Generalized reciprocity: Do people who give a lot also tend to receive a lot? (Actor-partner correlation)
- Dyadic reciprocity: Does person A’s unique relationship with person B predict B’s unique relationship with A? (Within-dyad relationship correlation)

## The Sample Dataset

The package includes `sampleDyadData`, a simulated dataset with 1,548 rows from a round-robin design collected at two time points.

    head(sampleDyadData)
    #>      groupId actId partId timeId contact liking actEx actAg actMale actAge
    #> 4          1     1      2      1       1      7   4.4   4.4       1     19
    #> 1300       1     1      2      2      NA      7   2.7   3.2       1     19
    #> 7          1     1      3      1       1      7   4.4   4.4       1     19
    #> 1303       1     1      3      2      NA      7   2.7   3.2       1     19
    #> 11         1     1      4      1      NA      7   4.4   4.4       1     19
    #> 1307       1     1      4      2      NA      7   2.7   3.2       1     19
    #>      partEx partAg partMale partAge groupCohesion groupEfficacy
    #> 4       4.7    1.5        0      20            NA            NA
    #> 1300    3.8    1.5        0      20            NA            NA
    #> 7       5.0    1.5        1      21            NA            NA
    #> 1303    5.6    1.3        1      21            NA            NA
    #> 11      3.5    2.0        1      20            NA            NA
    #> 1307    4.7    1.2        1      20            NA            NA
    nrow(sampleDyadData)
    #> [1] 1584
    length(unique(sampleDyadData$groupId))
    #> [1] 66

Key variables:

- `groupId`, `actId`, `partId` — group, actor, and partner identifiers
- `timeId` — time point (1 or 2)
- `liking` — directed dyadic rating of liking (the main outcome)
- `actEx`, `partEx` — actor and partner extraversion scores
- `contact` — dyad-level contact frequency
- `groupCohesion` — group-level cohesion

## Step 1: Create Dummy Variables

The SRM requires a set of dummy variables for each actor and partner position within a group. `createDummies()` generates these automatically.

    d <- createDummies(
      group.id       = "groupId",
      act.id         = "actId",
      part.id        = "partId",
      d              = sampleDyadData[sampleDyadData$timeId == 1, ],
      merge.original = TRUE
    )
    head(d[, c("groupId", "actId", "partId", "pdSRM_dyad_id",
               "a1", "a2", "a3", "a4", "p1", "p2", "p3", "p4")])
    #>   groupId actId partId pdSRM_dyad_id a1 a2 a3 a4 p1 p2 p3 p4
    #> 1       1     1      2             1  1  0  0  0  0  1  0  0
    #> 2       1     1      3             2  1  0  0  0  0  0  1  0
    #> 3       1     1      4             4  1  0  0  0  0  0  0  1
    #> 4       1     2      1             1  0  1  0  0  1  0  0  0
    #> 5       1     2      3             3  0  1  0  0  0  0  1  0
    #> 6       1     2      4             5  0  1  0  0  0  0  0  1

The key output columns are:

- `a1`–`a4`: actor dummy variables (one equals 1 per row, indicating which group position is acting)
- `p1`–`p4`: partner dummy variables (same, for the partner)
- `pdSRM_dyad_id`: undirected dyad identifier (shared by i→j and j→i)

## Step 2: Fit the Null SRM

The simplest model decomposes total variance into the four SRM components with no predictors. `srmRun()` handles dummy creation and model fitting in one step.

    null_mod <- srmRun(
      dv      = "liking",
      groupId = "groupId",
      actId   = "actId",
      partId  = "partId",
      data    = sampleDyadData[sampleDyadData$timeId == 1, ]
    )
    null_mod$srm.output
    #>                         variances.and.covariances percents.and.correlations
    #> Group                                       0.122                     9.926
    #> Actor                                       0.808                    65.596
    #> Partner                                     0.027                     2.154
    #> Dyad                                        0.275                    22.324
    #> Generalized Reciprocity                     0.002                     0.011
    #> Dyadic Reciprocity                          0.009                     0.033

Reading the output:

- `variances.and.covariances`: raw variance estimates for each component
- `percents.and.correlations`: for the four variance components, the percentage of total variance; for the two reciprocity rows, the correlation coefficients

## Step 3: Fit a Model with Predictors

Adding fixed effects tests whether actor-level, partner-level, or dyad-level predictors explain variance in the outcome.

    full_mod <- srmRun(
      dv      = "liking",
      groupId = "groupId",
      actId   = "actId",
      partId  = "partId",
      feVars  = c("actEx", "partEx", "contact"),
      data    = sampleDyadData[sampleDyadData$timeId == 1, ]
    )
    full_mod$srm.output
    #>                         variances.and.covariances percents.and.correlations
    #> Group                                       0.119                     9.790
    #> Actor                                       0.800                    66.073
    #> Partner                                     0.020                     1.667
    #> Dyad                                        0.272                    22.470
    #> Generalized Reciprocity                     0.000                    -0.002
    #> Dyadic Reciprocity                          0.005                     0.018

The fixed-effect estimates can be examined with:

    summary(full_mod$lme.output)$tTable
    #>                   Value  Std.Error  DF    t-value      p-value
    #> (Intercept)  5.20484636 0.26625736 683 19.5481783 6.346570e-68
    #> actEx        0.07387859 0.06060827 683  1.2189522 2.232832e-01
    #> partEx      -0.01342750 0.02468930 683 -0.5438589 5.867161e-01
    #> contact      0.07888947 0.01591042 683  4.9583522 8.979027e-07

## Step 4: Pseudo R-Squared

`srmPseudoRSq()` compares the null and full models to estimate the proportion of variance in each component explained by the predictors.

    srmPseudoRSq(
      null.model    = null_mod$lme.output,
      predict.model = full_mod$lme.output
    )
    #>               null    predict    pseudoR2
    #> Group   0.12228080 0.11860539 0.030057131
    #> Actor   0.80811232 0.80048626 0.009436881
    #> Partner 0.02654036 0.02019843 0.238954181
    #> Dyad    0.27502661 0.27222552 0.010184796

A positive `pseudoR2` for a given component means the fixed effects reduced that component’s variance, suggesting the predictors partly explain the group-, actor-, partner-, or relationship-level variation.

## References

Kenny, D. A., Kashy, D. A., & Cook, W. L. (2006). Dyadic Data Analysis. Guilford Press.

Knight, A. P., & Humphrey, S. E. (2019). Dyadic data analysis. In S. E. Humphrey & J. M. LeBreton (Eds.), The Handbook for Multilevel Theory, Measurement, and Analysis (pp. 423–447). American Psychological Association. https://doi.org/10.1037/0000115-019

Snijders, T. A. B., & Kenny, D. A. (1999). The social relations model for family data: A multilevel approach. Personal Relationships, 6, 471–486. https://doi.org/10.1111/j.1475-6811.1999.tb00204.x