Skip to contents

Wrapper to generate, and optionally plot, an ENA model

Source: R/ena.R
ena.Rd

Convenience entry point for constructing an ENA model from a coded data frame. Handles accumulation, dimensional reduction, and optional plot generation in a single call, returning an ena.set object that contains unit positions, network weights, node positions, and plots.

Usage

ena(
  data,
  codes,
  units,
  conversation,
  metadata = NULL,
  model = c("EndPoint", "AccumulatedTrajectory", "SeparateTrajectory"),
  weight.by = "binary",
  window = c("MovingStanzaWindow", "Conversation"),
  window.size.back = 1,
  window.size.forward = 0,
  include.meta = TRUE,
  groupVar = NULL,
  groups = NULL,
  runTest = FALSE,
  points = FALSE,
  mean = FALSE,
  network = TRUE,
  networkMultiplier = 1,
  subtractionMultiplier = 1,
  unit = NULL,
  colors = NULL,
  confidence.interval = "box",
  include.plots = T,
  print.plots = F,
  ...
)

Arguments

data

data.frame containing metadata and coded columns

codes

vector, numeric or character, of column names or indices containing the codes to model

units

vector, numeric or character, of column names that together uniquely identify each unit of analysis

conversation

vector, numeric or character, of column names used to segment the data into conversations (stanza boundaries reset at each new conversation)

metadata

vector, numeric or character, of column names to carry through as unit-level metadata (default: NULL)

model

character, the ENA model to construct: EndPoint (default) produces a single adjacency vector per unit summing co-occurrences across all lines; AccumulatedTrajectory produces one adjacency vector per unit per conversation, where each successive conversation accumulates prior ones; SeparateTrajectory produces one adjacency vector per unit per conversation, each modeled independently

weight.by

how to weight co-occurrences: "binary" (default) counts each co-occurrence once per stanza window; supply a function (e.g. sum) to use raw counts

window

stanza window type: "MovingStanzaWindow" (default) or "Conversation" (all lines in a conversation form one window)

window.size.back

integer, number of lines back from each line to include in the stanza window (default: 1)

window.size.forward

integer, number of lines forward from each line to include in the stanza window (default: 0). Set to model bidirectional co-occurrence within a window.

include.meta

logical, if TRUE (default) unit metadata is attached to the resulting ENAdata object and accessible via the set; set to FALSE to omit metadata from the model output

groupVar

character, name of the column containing group labels. When supplied with two groups, the model uses a means rotation that maximises variance between group means.

groups

vector, character, of exactly the group values from groupVar to use for means rotation, plotting, and statistical tests. If omitted, the first two unique values of groupVar are used with a warning.

runTest

logical, if TRUE runs a Wilcoxon rank-sum test and a Student's t-test comparing the two groups on dimensions 1 and 2; results stored in set$tests (default: FALSE)

points

logical, TRUE will plot individual unit points (default: FALSE)

mean

logical, TRUE will plot group mean positions with confidence intervals — recommended whenever groupVar is supplied (default: FALSE)

network

logical, TRUE will plot mean networks (default: TRUE)

networkMultiplier

numeric, scaling factor applied to edge weights in non-subtracted network plots (default: 1)

subtractionMultiplier

numeric, scaling factor applied to edge weights in the subtracted network plot (default: 1)

unit

character, name of a single unit to plot in isolation; when supplied, all group plotting is skipped

colors

vector, character, of colors for groups or points. For two-group models, supply two values (group1, group2); for single-group or no-group models, supply one value. Defaults to "blue"/"red" for two groups and "black" otherwise.

confidence.interval

character, style of confidence interval shown on mean points: "box" (default), "crosshairs", or "none"

include.plots

logical, if TRUE (default) generates and attaches plot objects to the returned set; set to FALSE to skip all plotting for faster programmatic use

print.plots

logical, if TRUE renders plots in the Viewer as they are created (default: FALSE)

...

Additional parameters passed to set creation and plotting functions, including mask (an optional binary matrix of size ncol(codes) x ncol(codes) where 0 suppresses co-occurrence modeling between a pair of codes; see ena.accumulate.data)

Value

An ena.set object. See the Details section for a description of the key fields ($points, $line.weights, $plots, $tests, etc.).

Details

ena() runs three phases internally:

1. Accumulation — co-occurrence counts are computed for each unit across stanza windows defined by window, window.size.back, and window.size.forward.

2. Dimensional reduction — accumulated vectors are normed, centered, and rotated into a low-dimensional ENA space. When groupVar and two groups are supplied the rotation maximises separation between the group means (means rotation); otherwise SVD is used.

3. Plotting — plots are built and stored on the returned set in set$plots. Pass include.plots = FALSE to skip this phase entirely, which is useful for programmatic use (simulations, parameter sweeps) where plot objects are not needed.

Plot defaults: network = TRUE but points = FALSE and mean = FALSE. For a two-group comparison you almost always want mean = TRUE as well, to show group centroids and confidence intervals alongside the network.

Accessing results: the returned ena.set object contains:

$points

unit positions in the rotated ENA space (rows = units)

$line.weights

normed co-occurrence weights per unit (rows = units, cols = code pairs)

$node.positions

positions of each code node in the ENA space

$plots

named list of ENAplot objects; two-group models produce three plots keyed by group1, group2, and "group1-group2"

$tests

list of Wilcoxon and t-test results on dimensions 1 and 2, populated when runTest = TRUE

$variance

proportion of variance explained by each dimension

Examples

data(RS.data)

codes = c('Data',
          'Technical.Constraints',
          'Performance.Parameters',
          'Client.and.Consultant.Requests',
          'Design.Reasoning',
          'Collaboration')

# Minimal call: fit a model with no group comparison
rs = ena(
  data = RS.data,
  units = c("UserName", "Condition", "GroupName"),
  conversation = c("Condition", "GroupName"),
  codes = codes,
  window.size.back = 4
)

# Two-group comparison with means rotation, centroids, and statistical tests
rs = ena(
  data = RS.data,
  units = c("UserName", "Condition", "GroupName"),
  conversation = c("Condition", "GroupName"),
  codes = codes,
  window.size.back = 4,
  groupVar = "Condition",
  groups = c("FirstGame", "SecondGame"),
  mean = TRUE,
  runTest = TRUE,
  print.plots = FALSE
)

# Model fitting only, no plots (faster for programmatic use)
rs = ena(
  data = RS.data,
  units = c("UserName", "Condition", "GroupName"),
  conversation = c("Condition", "GroupName"),
  codes = codes,
  window.size.back = 4,
  include.plots = FALSE
)