Package 'rENA'

Title: Epistemic Network Analysis
Description: ENA (Shaffer, D. W. (2017) Quantitative Ethnography. ISBN: 0578191687) is a method used to identify meaningful and quantifiable patterns in discourse or reasoning. ENA moves beyond the traditional frequency-based assessments by examining the structure of the co-occurrence, or connections in coded data. Moreover, compared to other methodological approaches, ENA has the novelty of (1) modeling whole networks of connections and (2) affording both quantitative and qualitative comparisons between different network models. Shaffer, D.W., Collier, W., & Ruis, A.R. (2016).
Authors: Cody L Marquart [aut, cre] , Zachari Swiecki [aut], Wesley Collier [aut], Brendan Eagan [aut], Roman Woodward [aut], David Williamson Shaffer [aut]
Maintainer: Cody L Marquart <[email protected]>
License: GPL-3 | file LICENSE
Version: 0.4.14
Built: 2026-10-12 23:24:56 UTC
Source: https://gitlab.com/epistemic-analytics/qe-packages/rena

Help Index

Multiply ena.matrix objects Element-wise multiplication of dimension columns in an ena.matrix by another ena.matrix or numeric matrix. If e2 is an ena.matrix, it is converted to a standard matrix before multiplication. The multiplication is applied only to the dimension columns of e1, while other columns remain unchanged.

Description

Multiply ena.matrix objects Element-wise multiplication of dimension columns in an ena.matrix by another ena.matrix or numeric matrix. If e2 is an ena.matrix, it is converted to a standard matrix before multiplication. The multiplication is applied only to the dimension columns of e1, while other columns remain unchanged.

Usage

## S3 method for class 'ena.matrix'
e1 * e2

Arguments

e1

An ena.matrix object whose dimension columns will be multiplied.
e2

An ena.matrix or numeric matrix to multiply with the dimension columns of e1.

Value

An ena.matrix object with the dimension columns of e1 multiplied by e2.

Extract from ena.matrix easily using metadata

Description

Extract from ena.matrix easily using metadata

Usage

## S3 method for class 'ena.matrix'
x$i

Arguments

x

[TBD]
i

[TBD]

Value

[TBD]

Extract metadata easily

Description

Extract metadata easily

Usage

## S3 method for class 'ena.metadata'
x$i

Arguments

x

[TBD]
i

[TBD]

Value

[TBD]

Extract points easily

Description

Extract points easily

Usage

## S3 method for class 'ena.points'
x$i

Arguments

x

[TBD]
i

[TBD]

Value

[TBD]

Extract line.weignts easily

Description

Extract line.weignts easily

Usage

## S3 method for class 'line.weights'
x$i

Arguments

x

[TBD]
i

[TBD]

Value

[TBD]

Accumulate Connection Counts for ENA

Description

This function takes a data.frame and accumulates co-occurrences of codes within specified units and conversations (horizon), preparing it for ENA. It's designed to be used with pipes ('|>')..

Usage

accumulate(
  x,
  units = rENA::units(x),
  codes = rENA::codes(x),
  horizon = rENA::horizon(x),
  ...,
  ordered = FALSE,
  binary = TRUE,
  weight_by = NULL
)

Arguments

x

A data.frame or similar object containing the data to be analyzed.
units

A character vector specifying the columns that define the units of analysis.
codes

A character vector specifying the columns that contain the codes for co-occurrence analysis.
horizon

A character vector specifying the columns that define the conversational boundaries (horizon).
...

Additional arguments passed to underlying accumulation functions.
ordered

A logical value. If TRUE, creates ordered networks (A -> B is different from B -> A). Defaults to FALSE.
binary

A logical value. If TRUE, each line's connection counts are binarized (0 or 1) before they are summed per unit (unordered networks; ordered counts are always summed raw). Defaults to TRUE. Ignored when 'weight_by' is given.
weight_by

Weight model applied to each line's connection counts before they are summed into the unit network (the same stage as 'weight.by' in 'ena.accumulate.data()'): '"binary"', '"product"' (the raw, non-binarized counts), '"sqrt"', or '"log1p"' (alias '"log"'). For unordered networks the weight is applied after each line is folded to the upper triangle; for ordered networks, to each directed cell, and '"binary"' keeps the raw directed counts. Defaults to '"binary"' when 'binary = TRUE', otherwise '"product"'. Passed to [tma::accumulate()].

Value

An ena.set object containing the accumulated connection counts and metadata.

Examples

data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon)

# square-root weighting of each line's co-occurrence counts
enaset_sqrt <- RS.data |>
  accumulate(units, codes, horizon, weight_by = "sqrt")

Add a group mean to an ENA plot

Description

This function adds a group mean to an existing ENA plot or ENA set. It supports various input types for the 'wh' parameter, including unevaluated expressions and language objects.

Usage

add_group(x, wh = NULL, ...)

Arguments

x

An 'ENAplot' object or an ENA set containing plots.
wh

Specifies the group to plot. Can be an unevaluated expression or a language object.
...

Additional parameters passed to the plotting functions.

Details

The function determines the type of the 'wh' parameter and processes it accordingly: - If 'wh' is an unevaluated expression, it is captured and evaluated in the parent frame. - If 'wh' is a language object, it is processed to extract the relevant group information.

The function updates the plot with the new group mean and stores the updated plot back in the ENA set.

Value

Invisibly returns the modified ENA set.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Add a network to an ENA plot

Description

Adds a network (set of edges) to an existing ENA plot or ENA set. The network can be specified in several ways, including as an unevaluated expression, a numeric matrix, or a language object. This function is typically used to visualize group means, differences between groups, or custom networks on an ENA plot.

Usage

add_network(
  x,
  wh = NULL,
  ...,
  with.mean = F,
  edge.multiplier = 1,
  colors = NULL
)

Arguments

x

An 'ENAplot' object or an ENA set containing plots.
wh

Specifies the network to plot. Can be:

  • An unevaluated expression (e.g., 'Condition$FirstGame - Condition$SecondGame')

  • A numeric matrix or data.frame of edge weights

  • A language object

  • NULL (defaults to the mean network)

...

Additional parameters passed to the plotting functions.
with.mean

Logical; if 'TRUE', also plots the mean for the points in the network. Default is 'FALSE'.
edge.multiplier

Numeric scalar to multiply the edge weights. Useful for scaling the network visualization. Default is 1.
colors

Optional vector of colors for the network. If not specified, colors are chosen from the plot palette.

Details

The function determines the type of the 'wh' parameter and processes it accordingly:

  • If 'wh' is an unevaluated expression, it is captured and evaluated in the parent frame. This allows for flexible specification of group means or differences.

  • If 'wh' is a numeric matrix or data.frame, its column means are plotted; a numeric vector (e.g. a subtracted network) is plotted as is.

  • If 'wh' is a language object, it is processed to extract the relevant network information.

  • If 'wh' is NULL, the mean network is plotted.

The function updates the plot with the new network and returns the modified plot object. The ENA set is not modified in-place.

Value

The modified ENAplot object with the new network added.

Examples

See 'inst/examples/example-plot-piping.R' for usage examples.

Add nodes to an ENA plot

Description

This function adds nodes to an existing ENA plot or ENA set. It can be used to customize the nodes displayed on the plot, including their size and other graphical parameters.

Usage

add_nodes(x, ..., return_plot = FALSE)

Arguments

x

An ENAplot object or an ENA set containing plots.
...

Additional arguments passed to ena.plot.points, such as nodes, size, and other graphical parameters.
return_plot

Logical; if TRUE, returns the modified ENA set. If FALSE (default), returns the modified plot invisibly.

Details

If x is an ENAplot, the function extracts the associated ENA set and plot. Otherwise, it assumes x is an ENA set and uses the last plot in the set. The nodes to be added can be specified via the nodes argument; otherwise, the default nodes from the set's rotation are used. Node size can be customized via the size argument.

The function updates the plot with the new nodes and stores the updated plot back in the ENA set.

Value

Invisibly returns the modified plot or ENA set, depending on the value of return_plot.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Add points to an ENA plot

Description

This function adds points to an existing ENA plot or ENA set. It supports various input types for the 'wh' parameter, including unevaluated expressions and language objects.

Usage

add_points(x, wh = NULL, ..., colors = NULL)

Arguments

x

An 'ENAplot' object or an ENA set containing plots.
wh

Specifies the points to plot. Can be an unevaluated expression or a language object.
...

Additional parameters passed to the plotting functions.
colors

A vector of colors for the plotted points. Default is 'NULL'.

Details

The function determines the type of the 'wh' parameter and processes it accordingly: - If 'wh' is an unevaluated expression, it is captured and evaluated in the parent frame. - If 'wh' is a language object, it is processed to extract the relevant points information.

The function updates the plot with the new points and stores the updated plot back in the ENA set.

Value

Invisibly returns the modified ENA set.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Add a trajectory to an ENA plot

Description

This function adds a trajectory to an existing ENA plot or ENA set. It supports various input types for the 'wh' parameter, including unevaluated expressions and language objects.

Usage

add_trajectory(x, wh = NULL, ..., name = "plot")

Arguments

x

An 'ENAplot' object or an ENA set containing plots.
wh

Specifies the trajectory to plot. Can be an unevaluated expression or a language object.
...

Additional parameters passed to the plotting functions.
name

A character string specifying the name of the plot. Default is "plot".

Details

The function determines the type of the 'wh' parameter and processes it accordingly: - If 'wh' is an unevaluated expression, it is captured and evaluated in the parent frame. - If 'wh' is a language object, it is processed to extract the relevant trajectory information.

The function updates the plot with the new trajectory and stores the updated plot back in the ENA set.

Value

Invisibly returns the modified ENA set.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Title

Description

Title

Usage

as_trajectory(
  x,
  by = x$`_function.params`$conversation[1],
  model = c("AccumulatedTrajectory", "SeperateTrajectory"),
  ...
)

Arguments

x

[TBD]
by

[TBD]
model

[TBD]
...

[TBD]

Value

[TBD]

Re-class vector as ena.co.occurrence

Description

Re-class vector as ena.co.occurrence

Usage

as.ena.co.occurrence(x)

Arguments

x

Vector to re-class

Value

re-classed vector

Re-class vector as ena.dimension

Description

Re-class vector as ena.dimension

Usage

as.ena.dimension(x)

Arguments

x

Vector to re-class

Value

re-classed vector

Re-class matrix as ena.matrix

Description

Re-class matrix as ena.matrix

Usage

as.ena.matrix(x, new.class = NULL)

Arguments

x

data.frame, data.table, or matrix to extend
new.class

Additional class to extend the matrix with, default: NULL

Value

Object of same st

Re-class matrix as ena.metadata

Description

Re-class matrix as ena.metadata

Usage

as.ena.metadata(x)

Arguments

x

data.frame, data.table, or matrix to extend

Value

Object of same st

ENA Connections as a matrix

Description

ENA Connections as a matrix

Usage

## S3 method for class 'ena.connections'
as.matrix(x, ...)

Arguments

x

ena.connections object
...

additional arguments to be passed to or from methods

Value

If square is FALSE (default), a matrix with all metadata columns removed, otherwise a list with square matrices

ENA line weights as matrix

Description

ENA line weights as matrix

Usage

## S3 method for class 'ena.line.weights'
as.matrix(x, ..., square = FALSE)

Arguments

x

ena.line.weights data.table to covert to matrix
...

additional arguments to be passed to or from methods
square

[TBD]

Value

matrix

Matrix without metadata

Description

Matrix without metadata

Usage

## S3 method for class 'ena.matrix'
as.matrix(x, ...)

Arguments

x

Object to convert to a matrix
...

additional arguments to be passed to or from methods

Value

matrix

ENA nodes as matrix

Description

ENA nodes as matrix

Usage

## S3 method for class 'ena.nodes'
as.matrix(x, ...)

Arguments

x

ena.nodes to convert to matrix
...

additional arguments to be passed to or from methods

Value

matrix

ENA points as matrix

Description

ENA points as matrix

Usage

## S3 method for class 'ena.points'
as.matrix(x, ...)

Arguments

x

ena.points to convert to a matrix
...

additional arguments to be passed to or from methods

Value

matrix

ENA rotations as matrix

Description

ENA rotations as matrix

Usage

## S3 method for class 'ena.rotation.matrix'
as.matrix(x, ...)

Arguments

x

ena.rotation.matrix to conver to matrix
...

additional arguments to be passed to or from methods

Value

matrix

ENA row connections as matrix

Description

ENA row connections as matrix

Usage

## S3 method for class 'row.connections'
as.matrix(x, ...)

Arguments

x

ena.row.connections to conver to a matrix
...

additional arguments to be passed to or from methods

Value

matrix

Convert a vector to 'qe.code' class

Description

This function converts a vector to the 'qe.code' class. If the vector is a factor, it is first converted to a character vector.

Usage

as.qe.code(x)

Arguments

x

A vector. The vector to be converted to 'qe.code' class.

Value

The modified vector with the 'qe.code' class.

Examples

vec <- factor(c("A", "B", "C"))
vec <- as.qe.code(vec)
class(vec) # Should show 'qe.code' along with other classes

Convert an object to 'qe.data' class

Description

This function converts an object to the 'qe.data' class. If the object is not a data.frame or matrix, it is first converted to a data.table.

Usage

as.qe.data(x)

Arguments

x

An object. The object to be converted to 'qe.data' class.

Value

The modified object with the 'qe.data' class.

Examples

library(data.table)

dt <- data.table(
  ID = 1:5,
  Name = c("Alice", "Bob", "Charlie", "David", "Eve"),
  Age = c(25, 30, 35, 40, 45),
  Score = c(85, 90, 95, 80, 75)
)
dt <- as.qe.data(dt);
class(dt) # Should show 'qe.data' along with other classes

Convert a vector to 'qe.horizon' class

Description

This function converts a vector to the 'qe.horizon' class. If the vector is a factor, it is first converted to a character vector.

Usage

as.qe.horizon(x)

Arguments

x

A vector. The vector to be converted to 'qe.horizon' class.

Value

The modified vector with the 'qe.horizon' class.

Examples

vec <- factor(c("A", "B", "C"))
vec <- as.qe.horizon(vec)
class(vec) # Should show 'qe.horizon' along with other classes

Convert a vector to 'qe.metadata' class

Description

This function converts a vector to the 'qe.metadata' class. If the vector is a factor, it is first converted to a character vector.

Usage

as.qe.metadata(x)

Arguments

x

A vector. The vector to be converted to 'qe.metadata' class.

Value

The modified vector with the 'qe.metadata' class.

Examples

vec <- factor(c("A", "B", "C"))
vec <- as.qe.metadata(vec)
class(vec) # Should show 'qe.metadata' along with other classes

Convert a vector to 'qe.unit' class

Description

This function converts a vector to the 'qe.unit' class. If the vector is a factor, it is first converted to a character vector.

Usage

as.qe.unit(x)

Arguments

x

A vector. The vector to be converted to 'qe.unit' class.

Value

The modified vector with the 'qe.unit' class.

Examples

vec <- factor(c("A", "B", "C"))
vec <- as.qe.unit(vec)
class(vec) # Should show 'qe.unit' along with other classes

Center ENA Data

Description

This function centers the line weights of an 'ena.set' by subtracting the mean of each connection from all units. This is a standard step in preparing data for rotation.

Usage

center(x, add.meta = TRUE, exclude_zero_networks = FALSE)

Arguments

x

An 'ena.set' object (typically after 'sphere_norm()') or a numeric matrix.
add.meta

A logical value. If 'TRUE' (the default), metadata is preserved. Ignored if 'x' is a matrix.
exclude_zero_networks

A logical value. If 'TRUE', units whose line weights are all zero are excluded when computing the column means used for centering. The mean is computed from non-zero units only, but all units (including zero-network ones) are shifted by that mean. This prevents empty networks from pulling the centroid toward zero. Defaults to 'FALSE' (standard behaviour: all units contribute to the mean). Use 'TRUE' for ordered/directed ENA sets produced by 'accumulate(ordered = TRUE)'.

Value

If 'x' is an 'ena.set', it returns the modified 'ena.set' with the centered data stored in 'x$model$points.for.projection'. If 'x' is a matrix, it returns a centered matrix.

Examples

data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  sphere_norm() |>
  center()

Updates the axis ranges of an ENA plot based on the plotted data.

Description

This function adjusts the x and y axis ranges of the ENA plot to ensure that all plotted points, networks, and means are visible.

Usage

check_range(x)

Arguments

x

An ENA plot object containing the plotted data and axis configurations.

Value

The updated ENA plot object with adjusted axis ranges.

Clears specified plots from an ENA set.

Description

This function removes the plots specified by their indices from the 'plots' field of the ENA set.

Usage

clear(x, wh = seq(x$plots))

Arguments

x

An ENA set object containing the plots.
wh

A numeric vector specifying the indices of the plots to clear. Default is all plots.

Value

Invisibly returns the modified ENA set object with the specified plots removed.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Reclassify specified columns as codes or list codes columns in a data.table

Description

This function reclassifies specified columns of a data.table to the 'qe.code' format if column names are provided. If no column names are provided, it returns the names of columns that are already classified as 'qe.code'.

Usage

codes(x, ...)

Arguments

x

A data.table. The data.table containing the columns to be reclassified or checked.
...

Additional arguments specifying the names of the columns to be reclassified.

Value

The modified data.table with specified columns reclassified as 'qe.code', or a character vector of column names already classified as 'qe.unit'.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
# Reclassify columns 'a' and 'b' as 'qe.code'
dt <- codes(dt, "a", "b")
# List columns classified as 'qe.code'
code_columns <- codes(dt)

Compute Between-Group Scatter Matrix

Description

This function calculates the between-group scatter matrix (SB) for a given numeric matrix and grouping variable.

Usage

compute_SB(A, g)

Arguments

A

A numeric matrix of dimensions m x n, where rows represent observations and columns represent features.
g

A grouping variable of length m, either a factor or a character vector, indicating group membership for each observation.

Details

The function computes the total mean of the matrix A and the mean for each group defined by g. It then calculates the between-group scatter matrix by summing the outer product of the mean differences, weighted by the group sizes.

Value

A numeric matrix representing the between-group scatter matrix (SB).

Examples

# Example usage:
A <- matrix(rnorm(20), nrow = 5, ncol = 4)
g <- factor(c("A", "B", "A", "B", "A"))
SB <- rENA:::compute_SB(A, g)

Connection counts as square matrix

Description

Connection counts as square matrix

Usage

connection.matrix(x)

Arguments

x

ena.set or ena.connections (i.e. set$connection.counts)

Value

matrix

Apply metadata and code transformations to a data.table

Description

This function applies metadata and code transformations to a data.table if provided. It checks if the metadata and codes are supplied as vectors of column names.

Usage

define(
  x,
  metadata_cols = find_meta_cols(x),
  codes_cols = find_binary_cols(x),
  horizon_cols = NULL,
  units_cols = NULL
)

Arguments

x

A data.table. The data.table to be transformed.
metadata_cols

A vector of column names or NULL. A vector specifying the columns for metadata transformations.
codes_cols

A vector of column names or NULL. A vector specifying the columns for code transformations.
horizon_cols

A vector of column names or NULL. A vector specifying the columns for horizon transformations.
units_cols

A vector of column names or NULL. A vector specifying the columns for unit transformations.

Value

The modified data.table after applying the metadata and code transformations.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
dt <- define(dt, metadata = c("a"), codes = c("b"))

Directed ENA node positions

Description

Least-squares node positions for directed ENA.

Usage

directed_node_positions(line_weights, points, numDims)

Arguments

line_weights

Numeric matrix (units x connections)
points

Numeric matrix of rotated points (units x dims)
numDims

Number of dimensions

Value

List with nodes, centroids, weights, points

Directed node positions with ground+response combined

Description

Directed node positions with paired ground+response rows combined.

Usage

directed_node_positions_with_ground_response_added(
  line_weights,
  points,
  numDims
)

Arguments

line_weights

Numeric matrix (units x connections)
points

Numeric matrix of rotated points (units x dims)
numDims

Number of dimensions

Value

List with nodes, centroids, weights, points

Wrapper to generate, and optionally plot, an ENA model

Description

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)

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

Value

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

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
)

Calculate ENA correlations

Description

Pearson correlation with confidence interval between ENA points and centroids.

Usage

ena_correlation(points, centroids, conf_level = 0.95)

Arguments

points

Numeric matrix (units x dims)
centroids

Numeric matrix (units x dims)
conf_level

Confidence level (default 0.95)

Value

Numeric matrix with columns: r, lower CI, upper CI

Two-group comparison statistics for ENA points

Description

Per-dimension parametric (Welch t-test, Cohen's d) and non-parametric (Wilcoxon rank-sum, rank-biserial r) statistics comparing two groups.

Usage

ena_group_stats(g1, g2)

Arguments

g1

Numeric matrix of group 1 points (units x dims)
g2

Numeric matrix of group 2 points (units x dims)

Value

List with: n1, n2, t, df, pvalue_t, cohens_d, means, sds, U, pvalue_u, effect_r, medians — each a vector/matrix of length dims

Confidence intervals around group mean positions

Description

Per-dimension t-based confidence intervals around the column means of a numeric matrix of ENA points.

Usage

ena_mean_ci(points, conf_level = 0.95)

Arguments

points

Numeric matrix (units x dims)
conf_level

Confidence level (default 0.95)

Value

Numeric matrix (dims x 3): mean, lower CI, upper CI

Outlier (Tukey-fence) intervals for group positions

Description

Per-dimension Tukey-fence intervals: Q1 - k*IQR to Q3 + k*IQR.

Usage

ena_outlier_ci(points, iqr_factor = 1.5)

Arguments

points

Numeric matrix (units x dims)
iqr_factor

IQR multiplier (default 1.5)

Value

Numeric matrix (dims x 2): lower fence, upper fence

Correlation between distances in two ENA spaces

Description

Calculates the Pearson correlation between the pairwise Euclidean distances of points in two ENA spaces (A and B). For smaller datasets, it computes the exact correlation. For larger datasets, it estimates the correlation using a sampled subset of pairs.

Usage

ena_space_dist_corr(A, B, max_sample_size = 1e+05)

Arguments

A

A matrix or data frame representing the first ENA space (rows as points).
B

A matrix or data frame representing the second ENA space (must have the same number of rows as A).
max_sample_size

Numeric. The maximum number of pairwise distances to compute. If the total possible pairs exceeds this value, sampling is used. Default is 100,000.

Value

A numeric value representing the Pearson correlation.

Accumulate data from a data frame into a set of adjacency (co-occurrence) vectors

Description

This function initializes an ENAdata object, processing conversations from coded data to generate adjacency (co-occurrence) vectors

Usage

ena.accumulate.data(
  units = NULL,
  conversation = NULL,
  codes = NULL,
  metadata = NULL,
  model = c("EndPoint", "AccumulatedTrajectory", "SeparateTrajectory"),
  weight.by = "binary",
  window = c("MovingStanzaWindow", "Conversation"),
  window.size.back = 1,
  window.size.forward = 0,
  mask = NULL,
  include.meta = T,
  as.list = T,
  ...
)

Arguments

units

A data frame where the columns are the properties by which units will be identified
conversation

A data frame where the columns are the properties by which conversations will be identified
codes

A data frame where the columns are the codes used to create adjacency (co-occurrence) vectors
metadata

(optional) A data frame with additional columns of metadata to be associated with each unit in the data
model

A character, choices: EndPoint (or E), AccumulatedTrajectory (or A), or SeparateTrajectory (or S); default: EndPoint. Determines the ENA model to be constructed
weight.by

(optional) A function to apply to values after accumulation
window

A character, choices are Conversation (or C), MovingStanzaWindow (MSW, MS); default MovingStanzaWindow. Determines how stanzas are constructed, which defines how co-occurrences are modeled
window.size.back

A positive integer, Inf, or character (INF or Infinite), default: 1. Determines, for each line in the data frame, the number of previous lines in a conversation to include in the stanza window, which defines how co-occurrences are modeled
window.size.forward

(optional) A positive integer, Inf, or character (INF or Infinite), default: 0. Determines, for each line in the data frame, the number of subsequent lines in a conversation to include in the stanza window, which defines how co-occurrences are modeled
mask

(optional) A binary matrix of size ncol(codes) x ncol(codes). 0s in the mask matrix row i column j indicates that co-occurrence will not be modeled between code i and code j
include.meta

Locigal indicating if unit metadata should be attached to the resulting ENAdata object, default is TRUE
as.list

R6 objects will be deprecated, but if this is TRUE, the original R6 object will be returned, otherwise a list with class 'ena.set'
...

additional parameters addressed in inner function

Details

ENAData objects are created using this function. This accumulation receives separate data frames for units, codes, conversation, and optionally, metadata. It iterates through the data to create an adjacency (co-occurrence) vector corresponding to each unit - or in a trajectory model multiple adjacency (co-occurrence) vectors for each unit.

In the default MovingStanzaWindow model, co-occurrences between codes are calculated for each line k in the data between line k and the window.size.back-1 previous lines and window.size.forward-1 subsequent lines in the same conversation as line k.

In the Conversation model, co-occurrences between codes are calculated across all lines in each conversation. Adjacency (co-occurrence) vectors are constructed for each unit u by summing the co-occurrences for the lines that correspond to u.

Options for how the data is accumulated are endpoint, which produces one adjacency (co-occurrence) vector for each until summing the co-occurrences for all lines, and two trajectory models: AccumulatedTrajectory and SeparateTrajectory. Trajectory models produce an adjacency (co-occurrence) model for each conversation for each unit. In a SeparateTrajectory model, each conversation is modeled as a separate network. In an AccumulatedTrajectory model, the adjacency (co-occurrence) vector for the current conversation includes the co-occurrences from all previous conversations in the data.

Value

ENAdata object with data [adjacency (co-occurrence) vectors] accumulated from the provided data frames.

See Also

ENAdata, ena.make.set

Compute Cross-Covariance Decay Curves and Noise Floor

Description

Evaluates window-matched cross-covariance matrices and noise-floor corrected Frobenius norms across multiple conversation subsets over a range of lag steps.

Usage

ena.ccd(
  x,
  codeNames = NULL,
  conversation_cols = NULL,
  max_window = 20,
  min_overlap = 10
)

Arguments

x

A data.frame, data.table, or an ENAdata/ena.set accumulation object.
codeNames

A character vector of column names corresponding to ENA codes.
conversation_cols

A character vector of column names defining discrete conversations.
max_window

An integer specifying the maximum lag to evaluate. Default is 20.
min_overlap

An integer specifying the minimum effective row overlap required per conversation at lag ll. Default is 10.

Value

An S3 object of class ena.ccd containing:

window_size

The estimated optimal window size (integer).

peak_lag

The lag corresponding to the peak cross-covariance norm.

curves

A data.frame of pooled cross-covariance metrics by lag.

codeNames

The evaluated code names.

conversation_cols

The conversation column names.

Examples

data(RS.data)
codeNames <- c("Data", "Technical.Constraints", "Performance.Parameters",
               "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration")
ccd_res <- ena.ccd(RS.data, codeNames = codeNames,
                   conversation_cols = c("Condition", "GroupName"))
print(ccd_res)
plot(ccd_res)

Calculate ENA Moving Window Size via Cross-Covariance Decay (CCD)

Description

Calculates the recommended moving window size for Epistemic Network Analysis (ENA) by estimating the half-life decay lag of the noise-corrected Frobenius norm across pooled conversation cross-covariance matrices.

Usage

ena.ccd.window(
  x,
  codeNames = NULL,
  conversation_cols = NULL,
  max_window = 20,
  min_overlap = 10
)

Arguments

x

A data.frame, data.table, or an ENAdata/ena.set accumulation object.
codeNames

A character vector of column names representing binary codes (optional if x is an ENA object).
conversation_cols

A character vector of column names defining discrete conversations (optional if x is an ENA object).
max_window

A numeric value indicating the maximum lag window size to evaluate. Default is 20.
min_overlap

A numeric value specifying the minimum required overlapping rows (N−lagN - lag) per conversation subset. Default is 10.

Details

The function computes pooled cross-covariance curves over lags 0:max_window. It normalizes the noise-corrected Frobenius norm relative to its peak value and identifies the first lag step strictly after the peak where the normalized norm falls below 0.5 (half-life threshold).

Value

An integer scalar representing the estimated half-life lag window size.

References

Shaffer, D. W. & Cai, Z. (2026). Discourse Coherence Length: Noise-Corrected Covariance Estimation of Window-Size in Epistemic Network Analysis. International Conference on Quantitative Ethnography (ICQE26).

Examples

data(RS.data)
codeNames <- c("Data", "Technical.Constraints", "Performance.Parameters",
               "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration")
w <- ena.ccd.window(RS.data, codeNames = codeNames,
                    conversation_cols = c("Condition", "GroupName"))
print(w)

Find conversations by unit

Description

Find rows of conversations by unit

Usage

ena.conversations(
  set,
  units,
  units.by = NULL,
  codes = NULL,
  conversation.by = NULL,
  window = 4,
  conversation.exclude = c()
)

Arguments

set

[TBD]
units

[TBD]
units.by

[TBD]
codes

[TBD]
conversation.by

[TBD]
window

[TBD]
conversation.exclude

[TBD]

Details

[TBD]

Value

list containing row indices representing conversations

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("Condition","UserName")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre",
                        "CONFIDENCE.Post","C.Change")],
  codes = RS.data[,codeNames],
  model = "EndPoint",
  window.size.back = 4
);
set = ena.make.set(
  enadata = accum,
  rotation.by = ena.rotate.by.mean,
  rotation.params = list(accum$meta.data$Condition=="FirstGame",
                         accum$meta.data$Condition=="SecondGame")
);
ena.conversations(set = RS.data,
  units = c("FirstGame.steven z"), units.by=c("Condition","UserName"),
  conversation.by = c("Condition","GroupName"),
  codes=codeNames, window = 4
)

Calculate the correlations

Description

Calculate both Spearman and Pearson correlations for the provided ENAset

Usage

ena.correlations(enaset, dims = c(1:2))

Arguments

enaset

ENAset to run correlations on
dims

The dimensions to calculate the correlations for. Default: c(1,2)

Value

Matrix of 2 columns, one for each correlation method, with the corresponding correlations per dimension as the rows.

Export a self-contained interactive ENA plot as HTML

Description

Writes a single .html file containing the qeviz bundle and embedded model data. No R, no Python, and no server are required to open the file — share it with collaborators, attach it to a paper submission, or archive it as supplementary material.

Usage

ena.export.html(
  set,
  file,
  group_col = NULL,
  ...,
  width = 700L,
  height = 600L,
  selfcontained = TRUE
)

Arguments

set

An ena.make.set result.
file

Output file path, e.g. "ena_plot.html".
group_col

Character. Grouping column in set$points.
...

Additional arguments passed to ena.plot.interactive (e.g. group, compare, label_nodes).
width, height

Plot dimensions in pixels. Default 700 × 600.
selfcontained

Logical. Inline the qeviz bundle in the HTML file. Default TRUE. Set to FALSE to reference the bundle via a relative path (smaller file, not portable).

Value

The resolved absolute path of the written file (invisibly).

Examples

## Not run: 
set <- ena.make.set(enadata = accum)
ena.export.html(set, "model.html", group_col = "Condition")

## End(Not run)

Calculate the Peak Ground Diversity Window

Description

This function acts as a wrapper to identify the sliding window size that yields the highest (peak) ground diversity/entropy for a given dataset.

Usage

ena.gd.window(data, codeNames, conversation_cols, max_window = 20)

Arguments

data

A data.frame or data.table containing the conversation data.
codeNames

A character vector of column names representing the binary codes.
conversation_cols

A character vector of column names that define unique conversations.
max_window

An integer specifying the maximum window size to evaluate. Default is 20.

Value

An integer representing the window size that maximizes ground entropy.

Examples

## Not run: 
peak_w <- ena.gd.window(data = my_data,
                        codeNames = c("CodeA", "CodeB"),
                        conversation_cols = "ConversationID",
                        max_window = 15)

## End(Not run)

Calculate Ground Diversity (Entropy) Curves and Peaks

Description

Evaluates the diversity of "ground types" (combinations of active codes) across a series of sliding window sizes. It returns both the curves and the peak window values.

Usage

ena.ground.diversity(data, codeNames, conversation_cols, max_window = 20)

Arguments

data

A data.frame or data.table containing the conversation data.
codeNames

A character vector of column names representing the binary codes.
conversation_cols

A character vector of column names that define unique conversations.
max_window

An integer specifying the maximum window size to evaluate. Default is 20.

Value

A list containing three elements:

curves

A data.table containing aggregated entropy curves across windows.

peaks

A data.table highlighting the window size(s) where entropy peaked.

conversation_curves

A data.table showing calculated entropy per individual conversation per window.

Examples

## Not run: 
gd_results <- ena.ground.diversity(data = my_data,
                                   codeNames = c("CodeA", "CodeB"),
                                   conversation_cols = "ConversationID")

## End(Not run)

Compute summary statistic for groupings of units using given method (typically, mean)

Description

Computes summary statistics for groupings (given as vector) of units in ena data using given method (typically, mean); computes summary statistic for point locations and edge weights for each grouping

Usage

ena.group(
  enaset = NULL,
  by = NULL,
  method = mean,
  names = as.vector(unique(by))
)

Arguments

enaset

An ENAset or a vector of values to group.
by

A vector of values the same length as units. Uses rotated points for group positions and normed data to get the group edge weights
method

A function that is used on grouped points. Default: mean(). If 'enaset' is an ENAset, enaset$points.rotated will be groups using 'mean' regardless of 'method' provided
names

A vector of names to use for the results. Default: unique(by)

Value

A list containing names, points, and edge weights for each of the unique groups formed by the function

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum
)

means = ena.group(set, "Condition")

Generate ENA Set

Description

Generates an ENA model by constructing a dimensional reduction of adjacency (co-occurrence) vectors in an ENA data object

Usage

ena.make.set(
  enadata,
  dimensions = 2,
  norm.by = fun_sphere_norm,
  rotation.by = ena.svd,
  rotation.params = NULL,
  rotation.set = NULL,
  endpoints.only = TRUE,
  center.align.to.origin = TRUE,
  node.position.method = lws.positions.sq,
  as.list = TRUE,
  ...
)

Arguments

enadata

ENAdata that will be used to generate an ENA model
dimensions

The number of dimensions to include in the dimensional reduction
norm.by

A function to be used to normalize adjacency (co-occurrence) vectors before computing the dimensional reduction, default: sphere_norm_c()
rotation.by

A function to be used to compute the dimensional reduction, default: ena.svd()
rotation.params

(optional) A character vector containing additional parameters for the function in rotation.by, if needed
rotation.set

A previously-constructed ENARotationSet object to use for the dimensional reduction
endpoints.only

A logical variable which determines whether to only show endpoints for trajectory models
center.align.to.origin

A logical variable when TRUE (default) determines aligns both point center and centroid center to the origin
node.position.method

A function to be used to determine node positions based on the dimensional reduction, default: lws.position.es()
as.list

R6 objects will be deprecated, but if this is TRUE, the original R6 object will be returned, otherwise a list with class 'ena.set'
...

additional parameters addressed in inner function

Details

This function generates an ENAset object from an ENAdata object. Takes the adjacency (co-occurrence) vectors from enadata, computes a dimensional reduction (projection), and calculates node positions in the projected ENA space. Returns location of the units in the projected space, as well as locations for node positions, and normalized adjacency (co-occurrence) vectors to construct network graphs

Value

ENAset class object that can be further processed for analysis or plotting

See Also

ena.accumulate.data, ENAset

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum
)

set.means.rotated = ena.make.set(
  enadata = accum,
  rotation.by = ena.rotate.by.mean,
  rotation.params = list(
      accum$meta.data$Condition=="FirstGame",
      accum$meta.data$Condition=="SecondGame"
  )
)

Generate a plot of an ENAset

Description

Generates an a plot from a given ENA set object

Usage

ena.plot(
  enaset,
  title = "ENA Plot",
  dimension.labels = c("", ""),
  font.size = 10,
  font.color = "#000000",
  font.family = c("Arial", "Courier New", "Times New Roman"),
  scale.to = "network",
  backend = getOption("rENA.plot.backend", "plotly"),
  ...
)

Arguments

enaset

The ENAset that will be used to generate a plot
title

A character used for the title of the plot, default: ENA Plot
dimension.labels

A character vector containing labels for the axes, default: c(X, Y)
font.size

An integer determining the font size for graph labels, default: 10
font.color

A character determining the color of label font, default: black
font.family

A character determining the font type, choices: Arial, Courier New, Times New Roman, default: Arial
scale.to

"network" (default), "points", or a list with x and y ranges. Network and points both scale to the c(-max, max) of the corresponding data.frame
backend

"plotly" (default) or "qeviz". Default: getOption("rENA.plot.backend", "plotly"). With "qeviz" the plot is drawn by the qeviz package (>= 0.5.0) and $plot is a qeviz htmlwidget; scale.to must be "network", "points" or a number.
...

additional parameters addressed in inner function

Details

This function defines the axes and other features of a plot for displaying an ENAset; generates an ENAplot object that can used to plot points, network graphs, and other information from an ENAset

Value

ENAplot used for plotting an ENAset

See Also

ena.make.set, ena.plot.points

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum
)

plot = ena.plot(set)

group1.points = set$points.rotated[set$enadata$units$Condition == "FirstGame",]
plot = ena.plot.points(plot, points = group1.points);
print(plot);

Plot of ENA set groups

Description

Plot a point based on a summary statistic computed from a given method (typically, mean) for a set of points in a projected ENA space

Usage

ena.plot.group(
  enaplot,
  points = NULL,
  method = "mean",
  labels = NULL,
  colors = default.colors[1],
  shape = c("square", "triangle-up", "diamond", "circle"),
  confidence.interval = c("none", "crosshairs", "box"),
  outlier.interval = c("none", "crosshairs", "box"),
  label.offset = "bottom right",
  label.font.size = NULL,
  label.font.color = NULL,
  label.font.family = NULL,
  show.legend = T,
  legend.name = NULL,
  ...
)

Arguments

enaplot

ENAplot object to use for plotting
points

A matrix or data.frame where columns contain coordinates of points in a projected ENA space
method

A function for computing a summary statistic for each column of points
labels

A character which will be the label for the group's point
colors

A character, determines color of the group's point, default: enaplot$color
shape

A character, determines shape of the group's point, choices: square, triangle, diamond, circle, default: square
confidence.interval

A character that determines how the confidence interval is displayed, choices: none, box, crosshair, default: none
outlier.interval

A character that determines how outlier interval is displayed, choices: none, box, crosshair, default: none
label.offset

character: top left (default), top center, top right, middle left, middle center, middle right, bottom left, bottom center, bottom right
label.font.size

An integer which determines the font size for label, default: enaplot$font.size
label.font.color

A character which determines the color of label, default: enaplot$font.color
label.font.family

A character which determines font type, choices: Arial, Courier New, Times New Roman, default: enaplot$font.family
show.legend

Logical indicating whether to show the point labels in the in legend
legend.name

Character indicating the name to show above the plot legend
...

Additional parameters

Details

Plots a point based on a summary statistic for a group (typically, mean)

Value

The ENAplot provided to the function, with its plot updated to include the new group point.

See Also

ena.plot, ena.plot.points

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum,
  rotation.by = ena.rotate.by.mean,
  rotation.params = list(
      accum$meta.data$Condition=="FirstGame",
      accum$meta.data$Condition=="SecondGame"
  )
)

plot = ena.plot(set)

unitNames = set$enadata$units

### Plot Condition 1 Group Mean
plot = ena.plot.group(plot, as.matrix(set$points$Condition$FirstGame), labels = "FirstGame",
    colors = "red", confidence.interval = "box")

### plot Condition 2 Group Mean
plot = ena.plot.group(plot, as.matrix(set$points$Condition$SecondGame), labels = "SecondGame",
    colors  = "blue", confidence.interval = "box")

print(plot);

Interactive ENA plot using qeviz

Description

Renders an interactive ENA plot inside RStudio, R Markdown / Quarto, and Shiny using the qeviz visualization library. This is a shortcut for a qeviz::qe_plot() chain; use qeviz directly for full control.

Usage

ena.plot.interactive(
  set,
  group_col = NULL,
  group = NULL,
  unit = NULL,
  compare = NULL,
  also = NULL,
  dim_cols = c("SVD1", "SVD2"),
  label_nodes = "on",
  label_means = "on",
  label_points = "off",
  confidence = TRUE,
  outlier = FALSE,
  scale_points = TRUE,
  conf_level = 0.95,
  iqr_factor = 1.5,
  width = NULL,
  height = NULL
)

Arguments

set

An ena.make.set result.
group_col

Character. Name of the grouping column in set$points (e.g. "Condition"). Controls point colours and group mean networks.
group

Character. Which group's mean network to display. Defaults to the first group.
unit

Character. A specific unit ID to display its individual network instead of a group mean.
compare

Character. Second group or unit for a subtraction view (group minus compare).
also

Character. Second group for an overlay view (both networks drawn simultaneously).
dim_cols

Character vector of two dimension names to plot. Default c("SVD1", "SVD2").
label_nodes

"on" | "off" | "auto" | "click". Visibility of code-node labels. Default "on".
label_means

Visibility of group-mean labels. Default "on".
label_points

Visibility of unit-point labels. Default "off".
confidence

Logical. Draw the confidence interval box around each shown group mean. Default TRUE.
outlier

Logical. Also draw the outlier interval (Q1 - 1.5 IQR to Q3 + 1.5 IQR). Default FALSE.
scale_points

Logical. Rescale unit points to match the node coordinate space. Default TRUE.
conf_level

Numeric. Confidence level for CI boxes. Default 0.95.
iqr_factor

Deprecated; the outlier interval always uses 1.5 IQR.
width, height

Widget size in pixels or CSS units. NULL uses the qeviz defaults (100% x 440).

Value

An htmlwidget object that renders in RStudio Viewer, R Markdown, Quarto, and Shiny.

Examples

## Not run: 
data(RS.data)
codeNames <- c("Data", "Technical.Constraints", "Performance.Parameters",
               "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration")
accum <- ena.accumulate.data(
  units        = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("Condition", "GroupName")],
  codes        = RS.data[, codeNames],
  window.size.back = 4
)
set <- ena.make.set(enadata = accum)

# Basic plot coloured by Condition
ena.plot.interactive(set, group_col = "Condition")

# Show only FirstGame mean network
ena.plot.interactive(set, group_col = "Condition", group = "FirstGame")

# Subtraction: FirstGame minus SecondGame
ena.plot.interactive(set, group_col = "Condition",
                     group = "FirstGame", compare = "SecondGame")

## End(Not run)

Animated movie of growing ENA trajectories

Description

Creates an animated Plotly visualization of trajectories growing across shared calendar time / conversation turns.

Usage

ena.plot.movie(
  enaplot,
  points,
  by,
  time,
  names = NULL,
  colors = NULL,
  smooth = c("none", "poly"),
  poly.degree = NULL,
  poly.max.degree = 3L,
  poly.eval.points = 100L,
  show.points = TRUE,
  frame_ms = 250,
  show_tips = TRUE,
  title = NULL
)

Arguments

enaplot

ENAplot object to use for plotting base canvas
points

Data frame or matrix of points with 2 coordinate dimensions
by

Vector identifying trajectory groupings (e.g. speaker/unit)
time

Monotonic time/turn index vector corresponding to points
names

Character vector of labels for each trajectory
colors

Character vector of colors for each trajectory
smooth

Character indicating smoothing method: "none" (default, point-to-point) or "poly" (LOOCV-2D polynomial curve)
poly.degree

Optional integer degree for polynomial fit. If NULL, selected automatically via LOOCV-2D
poly.max.degree

Maximum polynomial degree to test in LOOCV-2D (default 3)
poly.eval.points

Number of points along smooth curve (default 100)
show.points

Logical; whether to show discrete point markers along the trajectory (default TRUE)
frame_ms

Milliseconds per animation frame (default 250)
show_tips

Logical; whether to show glowing tip markers at current time position
title

Optional title string

Value

Plotly widget with play/pause controls and slider #####

Plot an ENA network

Description

Plot an ENA network: nodes and edges

Usage

ena.plot.network(
  enaplot = NULL,
  network = NULL,
  node.positions = enaplot$enaset$rotation$nodes,
  adjacency.key = NULL,
  colors = c(pos = enaplot$palette[1], enaplot$palette[2]),
  edge_type = "line",
  show.all.nodes = T,
  threshold = c(0),
  thin.lines.in.front = T,
  layers = c("nodes", "edges"),
  thickness = c(min(abs(network)), max(abs(network))),
  opacity = thickness,
  saturation = thickness,
  scale.range = c(ifelse(min(network) == 0, 0, 0.1), 1),
  node.size = c(3, 10),
  labels = NULL,
  label.offset = "middle right",
  label.font.size = enaplot$get("font.size"),
  label.font.color = enaplot$get("font.color"),
  label.font.family = enaplot$get("font.family"),
  legend.name = NULL,
  legend.include.edges = F,
  scale.weights = F,
  ...
)

Arguments

enaplot

ENAplot object to use for plotting
network

dataframe or matrix containing the edge weights for the network graph; typically comes from ENAset$line.weights
node.positions

matrix containing the positiions of the nodes. Defaults to enaplot$enaset$node.positions
adjacency.key

matrix containing the adjacency key for looking up the names and positions
colors

A String or vector of colors for positive and negative line weights. E.g. red or c(pos= red, neg = blue), default: c(pos= red, neg = blue)
edge_type

A String representing the type of line to draw, either "line", "dash", or "dot"
show.all.nodes

A Logical variable, default: true
threshold

A vector of numeric min/max values, default: c(0,Inf) plotting . Edge weights below the min value will not be displayed; edge weights above the max value will be shown at the max value.
thin.lines.in.front

A logical, default: true
layers

ordering of layers, default: c("nodes", "edges")
thickness

A vector of numeric min/max values for thickness, default: c(min(abs(network)), max(abs(network)))
opacity

A vector of numeric min/max values for opacity, default: thickness
saturation

A vector of numeric min/max values for saturation, default: thickness
scale.range

A vector of numeric min/max to scale from, default: c(0.1,1) or if min(network) is 0, c(0,1)
node.size

A lower and upper bound used for scaling the size of the nodes, default c(0, 20)
labels

A character vector of node labels, default: code names
label.offset

A character vector of representing the positional offset relative to the respective node. Defaults to "middle right" for all nodes. If a single values is provided, it is used for all positions, else the length of the
label.font.size

An integer which determines the font size for graph labels, default: enaplot$font.size
label.font.color

A character which determines the color of label font, default: enaplot$font.color
label.font.family

A character which determines font type, choices: Arial, Courier New, Times New Roman, default: enaplot$font.family
legend.name

A character name used in the plot legend. Not included in legend when NULL (Default), if legend.include.edges is TRUE will always be "Nodes"
legend.include.edges

Logical value indicating if the edge names should be included in the plot legend. Forces legend.name to be "Nodes"
scale.weights

Logical indicating to scale the supplied network
...

Additional parameters

Details

lots a network graph, including nodes (taken from codes in the ENAplot) and the edges (provided in network)

Value

The ENAplot provided to the function, with its plot updated to include the nodes and provided connecting lines.

See Also

ena.plot, ena.plot.points

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum,
  rotation.by = ena.rotate.by.mean,
  rotation.params = list(
    accum$meta.data$Condition=="FirstGame",
    accum$meta.data$Condition=="SecondGame"
  )
)

plot = ena.plot(set)

### Subset rotated points and plot Condition 1 Group Mean
as.matrix(set$points$Condition$FirstGame)

first.game.points = as.matrix(set$points$Condition$FirstGame)
plot = ena.plot.group(plot, first.game.points, labels = "FirstGame",
    colors = "red", confidence.interval = "box")

### Subset rotated points and plot Condition 2 Group Mean
second.game.points = as.matrix(set$points$Condition$SecondGame)
plot = ena.plot.group(plot, second.game.points, labels = "SecondGame",
    colors  = "blue", confidence.interval = "box")

### get mean network plots
first.game.lineweights = as.matrix(set$line.weights$Condition$FirstGame)
first.game.mean = colMeans(first.game.lineweights)

second.game.lineweights = as.matrix(set$line.weights$Condition$SecondGame)
second.game.mean = colMeans(second.game.lineweights)

subtracted.network = first.game.mean - second.game.mean
plot = ena.plot.network(plot, network = subtracted.network)
print(plot)

Plot points on an ENAplot

Description

Plot all or a subset of the points of an ENAplot using the plotly plotting library

Usage

ena.plot.points(
  enaplot,
  points = NULL,
  point.size = enaplot$point$size,
  labels = NULL,
  label.offset = "top left",
  label.group = NULL,
  label.font.size = NULL,
  label.font.color = NULL,
  label.font.family = NULL,
  shape = "circle",
  colors = NULL,
  confidence.interval.values = NULL,
  confidence.interval = c("none", "crosshairs", "box"),
  outlier.interval.values = NULL,
  outlier.interval = c("none", "crosshairs", "box"),
  show.legend = T,
  legend.name = "Points",
  texts = NULL,
  ...
)

Arguments

enaplot

ENAplot object to use for plotting
points

A dataframe of matrix where the first two column are X and Y coordinates
point.size

A data.frame or matrix where the first two column are X and Y coordinates of points to plot in a projected ENA space defined in ENAplot
labels

A character vector of point labels, length nrow(points); default: NULL
label.offset

character: top left (default), top center, top right, middle left, middle center, middle right, bottom left, bottom center, bottom right
label.group

A string used to group the labels in the legend. Items plotted with the same label.group will show/hide together when clicked within the legend.
label.font.size

An integer which determines the font size for point labels, default: enaplot$font.size
label.font.color

A character which determines the color of label font, default: enaplot$font.color
label.font.family

A character which determines label font type, choices: Arial, Courier New, Times New Roman, default: enaplot$font.family
shape

A character which determines the shape of point markers, choices: square, triangle, diamond, circle, default: circle
colors

A character vector of the point marker colors; if one given it is used for all, otherwise must be same length as points; default: black
confidence.interval.values

A matrix/dataframe where columns are CI x and y values for each point
confidence.interval

A character determining markings to use for confidence intervals, choices: none, box, crosshair, default: none
outlier.interval.values

A matrix/dataframe where columns are OI x and y values for each point
outlier.interval

A character determining markings to use for outlier interval, choices: none, box, crosshair, default: none
show.legend

Logical indicating whether to show the point labels in the in legend
legend.name

Character indicating the name to show above the plot legend
texts

[TBD]
...

additional parameters addressed in inner function

Value

ENAplot The ENAplot provided to the function, with its plot updated to include the new points.

See Also

ena.plot, ENAplot, ena.plot.group

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum,
  rotation.by = ena.rotate.by.mean,
  rotation.params = list(
      accum$meta.data$Condition=="FirstGame",
      accum$meta.data$Condition=="SecondGame"
  )
)

plot = ena.plot(set)

group1.points = set$points[set$meta.data$Condition == "FirstGame",]
group2.points = set$points[set$meta.data$Condition == "SecondGame",]
plot = ena.plot.points(plot, points = group1.points);
plot = ena.plot.points(plot, points = group2.points);
print(plot);

Plot of ENA trajectories

Description

Function used to plot trajectories

Usage

ena.plot.trajectory(
  enaplot,
  points,
  by = NULL,
  labels = NULL,
  labels.show = c("Always", "Hover", "Both"),
  names = NULL,
  label.offset = NULL,
  label.font.size = enaplot$get("font.size"),
  label.font.color = enaplot$get("font.color"),
  label.font.family = c("Arial", "Courier New", "Times New Roman"),
  shape = c("circle", "square", "triangle-up", "diamond"),
  colors = NULL,
  default.hidden = FALSE,
  smooth = c("none", "poly"),
  poly.degree = NULL,
  poly.max.degree = 3L,
  poly.criterion = c("loocv", "aic"),
  poly.n.eval = 200L,
  show.points = TRUE,
  show.curve = TRUE
)

Arguments

enaplot

ENAplot object to use for plotting
points

dataframe of matrix - first two column are X and Y coordinates, each row is a point in a trajectory
by

vector used to subset points into individual trajectories, length nrow(points)
labels

character vector - point labels, length nrow(points)
labels.show

A character choice: Always, Hover, Both. Default: Both
names

character vector - labels for each trajectory of points, length length(unique(by))
label.offset

A numeric vector of an x and y value to offset labels from the coordinates of the points
label.font.size

An integer which determines the font size for labels, default: enaplot$font.size
label.font.color

A character which determines the color of label font, default: enaplot$font.color
label.font.family

A character which determines font type, choices: Arial, Courier New, Times New Roman, default: enaplot$font.family
shape

A character which determines the shape of markers, choices: square, triangle, diamond, circle, default: circle
colors

A character vector, that determines marker color, default NULL results in alternating random colors. If single color is supplied, it will be used for all trajectories, otherwise the length of the supplied color vector should be equal to the length of the supplied names (i.e a color for each trajectory being plotted)
default.hidden

A logical indicating if the trajectories should start hidden (click on the legend to show them) Default: FALSE
smooth

Character choice: "none" (connect discrete points) or "poly" (fit orthogonal polynomial curve with LOOCV-2D). Default: "none"
poly.degree

Fixed integer polynomial degree (default NULL = auto-select via LOOCV-2D / AIC)
poly.max.degree

Maximum polynomial degree to search when auto-selecting (default: 3)
poly.criterion

Criterion for polynomial degree selection: "loocv" or "aic"
poly.n.eval

Number of evaluation points along the curve (default: 200)
show.points

Logical: whether to display original discrete points when smooth = "poly" (default: TRUE)
show.curve

Logical: whether to display smooth polynomial curve when smooth = "poly" (default: TRUE)

Value

The ENAplot provided to the function, with its plot updated to include the trajectories #####

See Also

ena.plot

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("GroupName","ActivityNumber")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post","C.Change")],
  codes = RS.data[,codeNames],
  window.size.back = 4,
  model = "A"
);

set = ena.make.set(accum);

### get mean network plots
first.game.lineweights = as.matrix(set$line.weights$Condition$FirstGame)
first.game.mean = colMeans(first.game.lineweights)

second.game.lineweights = as.matrix(set$line.weights$Condition$SecondGame)
second.game.mean = colMeans(second.game.lineweights)

subtracted.network = first.game.mean - second.game.mean

# Plot dimension 1 against ActivityNumber metadata
dim.by.activity = cbind(
    as.matrix(set$points)[,1],
    set$trajectories$ActivityNumber * .8/14-.4  #scale down to dimension 1
)

plot = ena.plot(set)
plot = ena.plot.network(plot, network = subtracted.network, legend.name="Network")
plot = ena.plot.trajectory(
  plot,
  points = dim.by.activity,
  names = unique(set$model$unit.label),
  by = set$trajectories$ENA_UNIT
);
print(plot)

Wrapper to generate plots of units, groups, and networks

Description

Plots individual units, all units, groups of units, networks, and network subtractions

Usage

ena.plotter(
  set,
  groupVar = NULL,
  groups = NULL,
  points = FALSE,
  mean = FALSE,
  network = TRUE,
  networkMultiplier = 1,
  subtractionMultiplier = 1,
  unit = NULL,
  colors = NULL,
  confidence.interval = "box",
  print.plots = F,
  backend = getOption("rENA.plot.backend", "plotly"),
  ...
)

Arguments

set

an ena.set object
groupVar

vector, character, of column name containing group identifiers.
groups

vector, character, of values of groupVar column you wish to plot. Maxium of two groups allowed.
points

logical, TRUE will plot points (default: FALSE)
mean

logical, TRUE will plot the mean position of the groups defined in the groups argument (default: FALSE)
network

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

numeric, scaling factor for non-subtracted networks (default: 1)
subtractionMultiplier

numeric, scaling factor for subtracted networks (default: 1)
unit

vector, character, name of a single unit to plot
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"
print.plots

logical, TRUE will show plots in the Viewer (default: FALSE)
backend

"plotly" (default) or "qeviz"; default getOption("rENA.plot.backend", "plotly"). On qeviz the weights are not multiplied: the multipliers become each plot's magnification (labelled "(scaled Nx)").
...

Additional parameters passed to set creation and plotting functions

Details

This function includes options to plots individual units, all units, groups of units, networks, and network subtractions, given an ena.set objects. Plots are stored on the supplied ena.set object.

Value

ena.set object

ENA Rotate by generalized means rotation (GMR)

Description

Computes a dimensional reduction from a matrix of ENA points such that the first dimension best represents the contribution of a target variable after controlling for covariates via Lasso. An optional second GMR axis can be computed for y_var; remaining dimensions are filled by SVD of the doubly-deflated space. Computed in C++ by libena's generalized_means_rotation.

Usage

ena.rotate.by.generalized(enaset, params)

Arguments

enaset

An ENAset or compatible list with model$points.for.projection (or points.normed.centered), line.weights, and rotation$codes.
params

A list with the following named elements:

x_var

Required. A data.frame (or character vector of column names in enaset$meta.data) whose first column is the target variable. Additional columns are treated as covariates and penalized via Lasso.

y_var

Optional. Same format as x_var. When provided a second GMR axis is computed.

select_2_groups

Optional length-2 list/vector of group labels. When given, the GMR fit for the x axis uses only rows whose target value is in these two groups. The group mean difference for x1 (the secondary axis that keeps group means on the x-axis) is always computed from the full data.

interactions

Logical; if TRUE (default) pairwise interaction terms are added to the model matrix when covariates are present. Set FALSE for main-effects-only Lasso.

Value

A list with rotation (q x q matrix, column names GMR1, GMR2|SVD2, SVD3, …), codes, eigenvalues, and node.positions = NULL, suitable for use inside rotate().

ENA Rotate by regression

Description

This function allows user to provide a regression formula for rotation on x and optionally on y. If regression formula for y is not provide, svd is applied to the residual data deflated by x to get y coordinates. The regression formula uses ENA dimensions are dependent variables. The first predictor has to be two-group categorical, binary, or numerical.

Usage

ena.rotate.by.hena.regression(enaset, params)

Arguments

enaset

An ENAset
params

list of parameters, may include: x_var: Regression formula for x direction, such as "lm(formula=V ~ Condition + GameHalf + Condition : GameHalf)", where V always stands for the ENA points. y_var: Regression formula, similar to x_var, for y direction (optional).

Value

ENARotationSet

ENA Rotate by regression (second way)

Description

This function allows user to provide a regression formula for rotation on x and optionally on y. If regression formula for y is not provide, svd is applied to the residual data deflated by x to get y coordinates. The regression formula should use ENA points as major predictors and a binary or numerical variable as dependent variable. Control and interaction variables are allowed to be included as predictors in the formula.

Usage

ena.rotate.by.hena.regression_2(enaset, params)

Arguments

enaset

An ENAset
params

list of parameters, may include: x_var: Regression formula for x direction, such as "lm(formula= Condition ~ V + GameHalf + Condition : GameHalf)", where V always stands for the ENA points. y_var: Regression formula, similar to x_var for y direction (optional).

Value

ENARotationSet

ENA Rotate by mean

Description

Computes a dimensional reduction from a matrix of points such that the first dimension of the projected space passes through the means of two groups in the original space. Subsequent dimensions are computed using SVD on the deflated data. Computed in C++ by libena's means_rotation.

Usage

ena.rotate.by.mean(enaset, groups = NULL, params = groups)

Arguments

enaset

An ENAset or compatible list with model$points.for.projection, connection.counts$ENA_UNIT, line.weights, and rotation$codes.
groups

A list containing one or more pairs; each pair is a length-2 list list(a, b) where a and b are either logical vectors (length = number of units) or character vectors of unit IDs.
params

Alias for groups; used when called from the pipe API.

Value

A list with rotation, codes, eigenvalues, and node.positions = NULL, suitable for use inside rotate().

ENA Rotate by SVD (Principal Components)

Description

Performs a standard SVD (principal components) rotation on the ENA points. This is the rotation method used by default in Ordered Network Analysis (ONA). Unlike the generalized means rotation, no group labels are required.

Usage

ena.rotate.by.svd(enaset, params = list())

Arguments

enaset

An ENAset or compatible list with a model$points.for.projection matrix.
params

A list of additional parameters (currently unused; kept for interface compatibility with other rotation functions).

Value

A list with:

rotation

Rotation matrix (connection columns × dimensions), with columns named SVD1, SVD2, …

codes

Character vector of code names

eigenvalues

Variance explained per component

node.positions

NULL (not computed here)

hENA rotation for ENA

Description

hENA rotation function.

Usage

ena.rotation.h(enaset, params)

Arguments

enaset

ena set
params

list of parameters

Value

ena set

Wrapper to generate an ENA model

Description

Generates an ENA model by constructing a dimensional reduction of adjacency (co-occurrence) vectors as defined by the supplied conversations, units, and codes.

Usage

ena.set.creator(
  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,
  ...
)

Arguments

data

data.frame with containing metadata and coded columns
codes

vector, numeric or character, of columns with codes
units

vector, numeric or character, of columns representing units
conversation

vector, numeric or character, of columns to segment conversations by
metadata

vector, numeric or character, of columns with additional meta information for units
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

"binary" is default, can supply a function to call (e.g. sum)
window

MovingStanzaWindow (default) or Conversation
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

vector, character, of column name containing group identifiers. If column contains at least two unique values, will generate model using a means rotation (a dimensional reduction maximizing the variance between the means of the two groups)
groups

vector, character, of values of groupVar column used for means rotation or statistical tests
runTest

logical, TRUE will run a Student's t-Test and a Wilcoxon test for groups defined by the groups argument
...

Additional parameters passed to model generation, 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)

Details

This function generates an ena.set object given a data.frame, units, conversations, and codes. After accumulating the adjacency (co-occurrence) vectors, computes a dimensional reduction (projection), and calculates node positions in the projected ENA space. Returns location of the units in the projected space, as well as locations for node positions, and normalized adjacency (co-occurrence) vectors to construct network graphs. Includes options for returning statistical tests between groups of units.

Value

ena.set object

ENA SVD

Description

Computes a dimensional reduction of points in an ENA set using Singular Value Decomposition (SVD).

Usage

ena.svd(enaset, params)

Arguments

enaset

An ENAset object containing the points to be reduced.
params

A list of parameters. Use params$as_object = TRUE to return an ENARotationSet object, or FALSE (default) to return a list.

Details

This function computes the SVD of the points in the ENA set and returns either an ENARotationSet object or a list with the rotation matrix, codes, node positions, and eigenvalues, depending on params$as_object.

Value

An ENARotationSet object or a list containing:

rotation

The rotation matrix from SVD
codes

The code names used for the matrix
node.positions

(Currently NULL) Node positions
eigenvalues

The eigenvalues (squared singular values) from SVD

Examples

data(RS.data)
codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  model()
# SVD as list:
svd_result <- ena.svd(enaset, list(as_object = FALSE))
# SVD as ENARotationSet object:
svd_obj <- ena.svd(enaset, list(as_object = TRUE))

Tune Window Size for ENA Accumulation

Description

Estimates the optimal moving window size for discourse accumulation and returns a new accumulation object constructed with the tuned window size. By default, uses Cross-Covariance Decay (CCD; method = "ccd") to estimate the discourse coherence length. Alternatively, the legacy SVD projection stability heuristic (method = "stability") can be used.

Usage

ena.tune.window.size(
  accum_object,
  min_size = 1,
  max_size = 20,
  method = c("ccd", "stability"),
  cutoff = 0.95,
  min_overlap = 10,
  ...
)

Arguments

accum_object

An ENAAccumulation/ENAdata/ena.set object.
min_size

Integer. The minimum window size (default=1) to test.
max_size

Integer. The maximum window size (default=20) to test.
method

Character. Window estimation method: "ccd" (default, Cross-Covariance Decay) or "stability" (legacy SVD stability plateau).
cutoff

Numeric. The threshold (default 0.95) of the maximum correlation used when method = "stability".
min_overlap

Integer. Minimum required overlapping rows per conversation when method = "ccd" (default=10).
...

Additional arguments passed to the underlying window estimation function.

Details

When method = "ccd" (default), the function uses ena.ccd.window to calculate the discourse coherence half-life decay lag directly from the conversation stream.

When method = "stability", the function iteratively rebuilds accumulation objects across candidate window sizes, generates ENA sets, and computes distance-space correlations between adjacent window sizes until reaching cutoff * max_correlation.

Value

A new ENAdata/ena.set object accumulated with the best_window_size.

Examples

## Not run: 
data(RS.data)
codeNames <- c("Data", "Technical.Constraints", "Performance.Parameters",
               "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration")
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("Condition", "GroupName")],
  codes = RS.data[, codeNames],
  window.size.back = 4
)
tuned_accum <- ena.tune.window.size(accum, method = "ccd")

## End(Not run)

Calculate the correlations

Description

Calculate both Spearman and Pearson correlations for the provided ENAset

Usage

ena.writeup(
  enaset,
  tool = "rENA",
  tool.version = as.character(packageVersion(tool)),
  comparison = NULL,
  comparison.groups = NULL,
  sig.dig = 2,
  output_dir = tempdir(),
  type = c("file", "stream"),
  theory = T,
  methods = T,
  params = NULL,
  output_file = NULL,
  output_format = NULL
)

Arguments

enaset

ENAset to view methods of
tool

c("rENA","webENA")
tool.version

as.character(packageVersion(tool))
comparison

character string representing the comparison used, c(NULL, "parametric", "non-parametric"). Default NULL
comparison.groups

Groups that were used for the comparison
sig.dig

Integer for the number of digits to round to
output_dir

Where to save the output file when type = "file". Default tempdir(); pass a directory to keep the report.
type

c("file","stream") File will save to a file in output_dir, Stream returns the contents directly
theory

Logical indicating whether to include theory in the writeup
methods

Logical indicating whether to include methods in the writeup
params

additional parameters for rmarkdown::render
output_file

character
output_format

character

Value

For type = "file", the path of the rendered file; for type = "stream", a string with the methods text.

ENAdata R6class

Description

ENAdata R6class

ENAdata R6class

Public fields

raw

A data frame constructed from the unit, convo, code, and metadata parameters of ena.accumulate.data

adjacency.vectors

A data frame of adjacency (co-occurrence) vectors by row

accumulated.adjacency.vectors

A data frame of adjacency (co-occurrence) vectors accumulated per unit

model

The type of ENA model: EndPoint, Accumulated Trajectory, or Separate Trajectory

units

A data frame of columns that were combined to make the unique units. Includes column for trajectory selections. (unique)

unit.names

A vector of unique unit values

metadata

A data frame of unique metadata for each unit

trajectories

A list: units - data frame, for a given row tells which trajectory it's a part; step - data frame, where along the trajectory a row sits

adjacency.matrix

TBD

adjacency.vectors.raw

TBD

codes

A vector of code names

function.call

The string representation of function called and parameters provided

function.params

A list of all parameters sent to function call Construct ENAdata

Methods

Public methods

Method new()

Usage
ENAdata$new(
  file,
  units = NULL,
  units.used = NULL,
  units.by = NULL,
  conversations.by = NULL,
  codes = NULL,
  model = NULL,
  weight.by = "binary",
  window.size.back = 1,
  window.size.forward = 0,
  mask = NULL,
  include.meta = T,
  ...
)
Arguments
file

TBD

units

TBD

units.used

TBD

units.by

TBD

conversations.by

TBD

codes

TBD

model

TBD

weight.by

TBD

window.size.back

TBD

window.size.forward

TBD

mask

TBD

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

...

TBD

Returns

Process accumulation

Method process()

Usage
ENAdata$process()
Returns

ENAdata Get property from object

Method get()

Usage
ENAdata$get(x = "data")
Arguments
x

character key to retrieve from object

Returns

value from object at x Add metadata

Method add.metadata()

Usage
ENAdata$add.metadata(merge = F)
Arguments
merge

logical (default: FALSE)

Returns

data.frame

Method clone()

The objects of this class are cloneable with this method.

Usage
ENAdata$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Shiny output binding for interactive ENA plots

Description

Equivalent to qeviz::qeOutput().

Usage

enaInteractiveOutput(outputId, width = "100%", height = "600px")

Arguments

outputId

Shiny output ID.
width, height

CSS dimensions. Defaults: "100%", "600px".

ENAplot Class

Description

The ENAplot R6 class provides a structure for visualizing ENAset objects using plotly. It encapsulates the ENAset data, the plotly visualization, and related plotting parameters.

Fields

enaset

The ENAset object from which the ENAplot was constructed.

plot

The plot as an htmlwidget: a plotly object, or a qeviz widget when the plot was created with backend = "qeviz".

qe

With backend = "qeviz", the qeviz::qe_plot() the layer functions build on; NULL for plotly.

axes

Axes information for the plot (TBD).

point

Point information for the plot (TBD).

palette

Color palette used for plotting (TBD).

plotted

Indicates whether the plot has been rendered (TBD).

Public fields

enaset

- The ENAset object from which the ENAplot was constructed

qe

- The qeviz::qe_plot() behind a qeviz-backend plot, else NULL

axes

A list or object specifying the axes configuration for the ENA plot, such as axis labels, limits, or scaling.

point

A structure representing the data points to be plotted, including coordinates and visual properties.

palette

A set of colors or a function defining the color scheme used for plotting elements in the ENA plot.

plotted

A logical or status indicator showing whether the plot has been rendered or updated.

title

Character. The title of the plot.

showticklabels

Logical. Indicates whether to show tick labels on the axes.

autosize

Logical. Indicates whether the plot should automatically resize.

automargin

Logical. Indicates whether the plot should automatically adjust margins.

axispadding

Numeric. Padding factor for the axes. Create ENApolot

Active bindings

plot

- The plot as an htmlwidget (plotly, or qeviz with backend = "qeviz")

Methods

Public methods

Method new()

Usage
ENAplot$new(
  enaset = NULL,
  title = "ENA Plot",
  dimension.labels = c("", ""),
  font.size = 14,
  font.color = "#000000",
  font.family = "Arial",
  scale.to = "network",
  backend = c("plotly", "qeviz"),
  ...
)
Arguments
enaset

An ENA set object containing the data to be plotted.

title

The title of the plot.

dimension.labels

Labels for the dimensions shown in the plot.

font.size

Numeric value specifying the font size for plot text.

font.color

Color value for the plot text.

font.family

Font family to use for plot text.

scale.to

Numeric value to scale the plot axes.

...

Additional arguments passed to the plotting function. #'

showticklabels

Logical; whether to display axis tick labels.

autosize

Logical; whether the plot should automatically size itself.

automargin

Logical; whether the plot should automatically adjust margins.

axispadding

Numeric value specifying padding around axes.

Returns

ENAplot Print ENA plot

Method print()

Usage
ENAplot$print()
Returns

Get property from object

Method get()

Usage
ENAplot$get(x)
Arguments
x

character key to retrieve from object

Returns

value from object at x

Method clone()

The objects of this class are cloneable with this method.

Usage
ENAplot$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples

# Example usage:
# enaplot <- ENAplot$new(enaset = myENAset)

ENARotationSet R6class

Description

ENARotationSet R6class

ENARotationSet R6class

Public fields

rotation

TBD

node.positions

TBD

codes

TBD

eigenvalues

TBD Create ENARotationSet

Methods

Public methods

Method new()

Usage
ENARotationSet$new(rotation, codes, node.positions, eigenvalues = NULL)
Arguments
rotation

TBD

codes

TBD

node.positions

TBD

eigenvalues

TBD

Returns

ENARotationsSet

Method clone()

The objects of this class are cloneable with this method.

Usage
ENARotationSet$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

ENAset R6class

Description

ENAset R6class

ENAset R6class

Public fields

enadata

An ENAdata object originally used to create the set

points.raw

A data frame containing accumulated adjacency (co-occurrence) vectors per unit

points.normed.centered

A data frame of centered normed accumulated adjacency (co-occurrence) vectors for each unit

points.rotated

A data frame of point positions for number of dimensions specified in ena.make.set (i.e., the centered, normed, and rotated data)

line.weights

A data frame of connections strengths per unit (Data frame of normed accumu- lated adjacency (co-occurrence) vectors for each unit)

node.positions

- A data frame of positions for each code

codes

- A vector of code names

rotation.set

- An ENARotationSet object

variance

- A vector of variance accounted for by each dimension specified

centroids

- A matrix of the calculated centroid positions

function.call

- The string representation of function called

function.params

- A list of all parameters sent to function call

rotation_dists

TBD

points.rotated.scaled

TBD

points.rotated.non.zero

TBD

line.weights.unrotated

TBD

line.weights.non.zero

TBD

correlations

A data frame of spearman and pearson correlations for each dimension specified

center.align.to.origin

- align point and centroid centers to origin Create ENAset

Methods

Public methods

Method new()

Usage
ENAset$new(
  enadata,
  dimensions = 2,
  norm.by = fun_sphere_norm,
  rotation.by = ena.svd.R6,
  rotation.params = NULL,
  rotation.set = NULL,
  node.position.method = lws.positions.sq.R6,
  endpoints.only = TRUE,
  center.align.to.origin = TRUE,
  ...
)
Arguments
enadata

TBD

dimensions

TBD

norm.by

TBD

rotation.by

TBD

rotation.params

TBD

rotation.set

TBD

node.position.method

TBD

endpoints.only

TBD

center.align.to.origin

TBD

...

TBD

Returns

ENAset Process ENAset

Method process()

Usage
ENAset$process()
Returns

ENASet Get property from object

Method get()

Usage
ENAset$get(x = "enadata")
Arguments
x

character key to retrieve from object

Returns

value from object at x

Method clone()

The objects of this class are cloneable with this method.

Usage
ENAset$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Find Binary Columns

Description

Identifies columns in a data.frame or data.table that are binary (i.e., contain only two unique values), optionally including logical columns.

Usage

find_binary_cols(x, include_logical = FALSE)

Arguments

x

A data.frame or data.table to search for binary columns.
include_logical

Logical. If TRUE, logical columns are also considered binary. Default is FALSE.

Value

A character vector of column names that are binary, or NULL if none are found.

Examples

df <- data.frame(a = c(0, 1, 1), b = c(TRUE, FALSE, TRUE), c = c(1, 2, 3))
find_binary_cols(df)
find_binary_cols(df, include_logical = TRUE)

Find code columns

Description

Find code columns

Usage

find_code_cols(x)

Arguments

x

data.table (or frame) to search for columns of class ena.co.occurrence

Value

logical vector

Find dimension columns

Description

Find dimension columns

Usage

find_dimension_cols(x)

Arguments

x

data.table (or frame) to search for columns of class ena.dimension

Value

logical vector

Find metadata columns

Description

Find metadata columns

Usage

find_meta_cols(x)

Arguments

x

data.table (or frame) to search for columns of class ena.metadata

Value

logical vector

Cohen's d

Description

Calculate Conhen's d

Usage

fun_cohens.d(x, y)

Arguments

x

[TBD]
y

[TBD]

Details

Cohen's d calculation

[TBD]

Value

numeric Cohen's d calculation

Row-wise Max-Norm Scaling

Description

Scales all rows of a numeric data frame by dividing by the largest row L2 norm.

Usage

fun_skip_sphere_norm(dfM)

Arguments

dfM

A data.frame or matrix

Value

A numeric matrix scaled by the largest row L2 norm

Row-wise L2 (Sphere) Normalization

Description

Normalizes each row of a numeric data frame or matrix to unit L2 norm.

Usage

fun_sphere_norm(dfM)

Arguments

dfM

A data.frame or matrix

Value

A numeric matrix with each row normalized to unit L2 length

Extract the Main Effect of X on V with Optional Interactions

Description

Computes the main-effect contribution of the first column of 'X' (the "target") to the multivariate ENA matrix 'V'. The function fits penalized regression models (via glmnet) and can optionally include interactions between the target and other covariates. It returns the fitted contribution matrix (units x connections).

Usage

get_x1_main_effect(
  V,
  X,
  alpha = 1,
  lambda = "lambda.min",
  include_interactions = FALSE
)

Arguments

V

A numeric matrix (units x connections) of dependent variables.
X

A data frame or matrix of predictors / covariates. The **first** column is treated as the target variable whose contribution will be extracted.
alpha

Elastic-net mixing parameter passed to 'cv.glmnet'. 'alpha = 1' (default) is Lasso; 'alpha = 0' is ridge.
lambda

Character or numeric. Which lambda from the 'cv.glmnet' fit to use; e.g. '"lambda.min"' (default) or '"lambda.1se"', or a numeric value.
include_interactions

Logical; if 'TRUE', include main-effect columns **and** all interaction columns that begin with the target name (default: 'FALSE', only main-effect columns).

Details

The function can compute contributions using either only main-effect columns (no interactions) or main-effect plus all interaction columns that start with the target name. If no matching columns are found or all fitted coefficients are zero, the function returns a zero matrix and emits a warning.

Internally this function builds 'model.matrix(~ .^2, data = X)' to obtain main effects and pairwise interactions. It sets a 'penalty.factor' that leaves the target-related columns unpenalized (0) and fits a multivariate 'glmnet' ('family = "mgaussian"'). The returned matrix is dense (numeric).

Value

A numeric matrix with the same dimensions as 'V' containing the estimated contribution of 'X[,1]' to each response. If no columns are matched or all coefficients are zero, a zero matrix is returned and a warning is issued.

See Also

[gmr2()] for the rotation routine that uses this function.

Examples

## Not run: 
set.seed(1)
V <- matrix(rnorm(50), ncol = 5)
X <- data.frame(CONFIDENCE = rnorm(10), Condition = factor(rep(1:2, 5)))
# main effects only
Vx_main <- get_x1_main_effect(V, X, include_interactions = FALSE)
# include interactions
Vx_full <- get_x1_main_effect(V, X, include_interactions = TRUE, alpha = 0) # ridge

## End(Not run)

Generalized Means Rotation (GMR) with optional subsetting and interaction control

Description

Computes a rotation (direction) 'r' representing the contribution of the first column of 'X' to the multivariate ENA matrix 'V'. Supports optional subsetting by 'groups', optional inclusion of interaction terms when computing adjusted contributions.

Usage

gmr(
  V,
  X,
  groups = NULL,
  alpha = 1,
  lambda = "lambda.min",
  interactions = TRUE,
  verbose = TRUE
)

Arguments

V

Numeric ENA matrix (units x connections) ready for rotation.
X

Data frame or matrix of predictors; the first column is the target.
groups

Optional vector specifying target groups to subset. If 'NULL' (default), all rows are used.
alpha

Elastic-net mixing parameter forwarded to 'get_x1_main_effect' (default '1' - Lasso).
lambda

Lambda selection for 'cv.glmnet' forwarded to 'get_x1_main_effect' (default '"lambda.min"').
interactions

Logical; if 'TRUE' (default) interactions are included when computing the adjusted contribution.
verbose

Logical; if 'TRUE' (default) the function emits messages about fails or successes.

Value

A numeric vector 'r' (length = ncol(V)) giving the normalized rotation direction. Attributes attached:

'target'

The full-length target vector (un-subsetted).

'Vx1'

The unadjusted fitted values ('lm(V ~ target)') embedded in a full-length matrix (rows outside subset filled with zeros).

If no valid direction can be found (including SVD failure), returns 'NULL' and issues a warning.

See Also

[get_x1_main_effect()]

Examples

## Not run: 
set.seed(1)
V <- matrix(rnorm(200), nrow = 40)
X <- data.frame(group = rep(letters[1:4], each = 10),
                x2 = rnorm(40), x3 = rnorm(40))
r_all <- gmr2(V, X)
r_subset <- gmr2(V, X, groups = c("a", "b"), interactions = TRUE)

## End(Not run)

Add all groups to an ENA plot

Description

This function iterates over all unique values of the first metadata column (excluding 'QEUNIT' and 'ENA_UNIT') in the ENA set and adds each group as a set of points to the ENA plot. This is useful for quickly visualizing all groups in a categorical variable on the same plot.

Usage

group(x, wh = NULL)

Arguments

x

An 'ENAplot' object (as returned by 'plot.ena.set').
wh

(Ignored) Included for compatibility with other plotting functions.

Details

The function finds the first metadata column in the ENA set (excluding 'QEUNIT' and 'ENA_UNIT'), and for each unique value in that column, calls ‘add_points()' to add the group’s points to the plot.

Value

The modified 'ENAplot' object with all groups added as points.

Examples

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Reclassify specified columns as horizon or list horizon columns in a data.table

Description

This function reclassifies specified columns of a data.table to the 'qe.horizon' format if column names are provided. If no column names are provided, it returns the names of columns that are already classified as 'qe.horizon'.

Usage

horizon(x, ...)

Arguments

x

A data.table. The data.table containing the columns to be reclassified or checked.
...

Additional arguments specifying the names of the columns to be reclassified.

Value

The modified data.table with specified columns reclassified as 'qe.horizon', or a character vector of column names already classified as 'qe.horizon'.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
# Reclassify columns 'a' and 'b' as 'qe.horizon'
dt <- horizon(dt, "a", "b")
# List columns classified as 'qe.horizon'
horizon_columns <- horizon(dt)

Check if an object is of class 'qe.code'

Description

This function checks if an object is of class 'qe.code'.

Usage

is.qe.code(x)

Arguments

x

An object. The object to be checked.

Value

A logical value. TRUE if the object is of class 'qe.code', otherwise FALSE.

Examples

dt <- 1:5
class(dt) <- c("qe.code", class(dt))
is.qe.code(dt) # Should return TRUE

Check if an object is of class 'qe.data'

Description

This function checks if an object is of class 'qe.data'.

Usage

is.qe.data(x)

Arguments

x

An object. The object to be checked.

Value

A logical value. TRUE if the object is of class 'qe.data', otherwise FALSE.

Examples

library(data.table)

dt <- data.table(ID = 1:5)
class(dt) <- c("qe.data", class(dt))
is.qe.data(dt) # Should return TRUE

Check if an object is of class 'qe.horizon'

Description

This function checks if an object is of class 'qe.horizon'.

Usage

is.qe.horizon(x)

Arguments

x

An object. The object to be checked.

Value

A logical value. TRUE if the object is of class 'qe.horizon', otherwise FALSE.

Examples

dt <- 1:5
class(dt) <- c("qe.horizon", class(dt))
is.qe.horizon(dt) # Should return TRUE

Check if an object is of class 'qe.metadata'

Description

This function checks if an object is of class 'qe.metadata'.

Usage

is.qe.metadata(x)

Arguments

x

An object. The object to be checked.

Value

A logical value. TRUE if the object is of class 'qe.metadata', otherwise FALSE.

Examples

dt <- 1:5
class(dt) <- c("qe.metadata", class(dt))
is.qe.metadata(dt) # Should return TRUE

Check if an object is of class 'qe.unit'

Description

This function checks if an object is of class 'qe.unit'.

Usage

is.qe.unit(x)

Arguments

x

An object. The object to be checked.

Value

A logical value. TRUE if the object is of class 'qe.unit', otherwise FALSE.

Examples

dt <- 1:5
class(dt) <- c("qe.unit", class(dt))
is.qe.unit(dt) # Should return TRUE

Title

Description

Title

Usage

means_rotate(x, on = NULL)

Arguments

x

[TBD]
on

[TBD]

Value

[TBD]

Merge data frame columns

Description

Paste together multiple columns of a data frame or data.table with a separator, used internally to construct unit-ID strings.

Usage

merge_columns_c(df, cols, sep = "::")

Arguments

df

A data.frame or data.table
cols

Character vector of column names to paste together
sep

Separator string (default "::")

Value

A character vector of length nrow(df)

Reclassify specified columns as metadata or list metadata columns in a data.table

Description

This function reclassifies specified columns of a data.table to the 'qe.metadata' format if column names are provided. If no column names are provided, it returns the names of columns that are already classified as 'qe.metadata'.

Usage

metadata(x, ...)

Arguments

x

A data.table. The data.table containing the columns to be reclassified or checked.
...

Additional arguments specifying the names of the columns to be reclassified.

Value

The modified data.table with specified columns reclassified as 'qe.metadata', or a character vector of column names already classified as 'qe.metadata'.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
# Reclassify columns 'a' and 'b' as 'qe.metadata'
dt <- metadata(dt, "a", "b")
# List columns classified as 'qe.metadata'
metadata_columns <- metadata(dt)

methods_report

Description

Methods report for rmarkdwon

Usage

methods_report(
  toc = FALSE,
  toc_depth = 3,
  fig_width = 5,
  fig_height = 4,
  keep_md = FALSE,
  md_extensions = NULL,
  pandoc_args = NULL
)

Arguments

toc

[TBD]
toc_depth

[TBD]
fig_width

[TBD]
fig_height

[TBD]
keep_md

[TBD]
md_extensions

[TBD]
pandoc_args

[TBD]

methods_report_stream

Description

Methods report for rmarkdwon

Usage

methods_report_stream(
  toc = FALSE,
  toc_depth = 3,
  fig_width = 5,
  fig_height = 4,
  keep_md = FALSE,
  md_extensions = NULL,
  pandoc_args = NULL
)

Arguments

toc

[TBD]
toc_depth

[TBD]
fig_width

[TBD]
fig_height

[TBD]
keep_md

[TBD]
md_extensions

[TBD]
pandoc_args

[TBD]

Build a Complete ENA Model

Description

This function applies a full ENA modeling pipeline to accumulated data. It is a convenience wrapper that chains together normalization, centering, rotation, projection, and optional optimization. Each step can be customized by supplying an alternative function.

Usage

model(
  data,
  ...,
  normalize = sphere_norm,
  center_with = center,
  rotate_with = rotate,
  project_with = project,
  optimize_with = optimize,
  rotate_fun = ena.rotate.by.generalized,
  rotate_params = list(),
  exclude_zero_networks = is(data, "ena.ordered.set"),
  center_to_origin = FALSE
)

Arguments

data

An 'ena.set' object, typically the result of 'accumulate()'.
...

Additional arguments passed to the rotation function specified by 'rotate_fun'.
normalize

A function to normalize the connection counts. Defaults to 'sphere_norm'.
center_with

A function to center the normalized data. Defaults to 'center'.
rotate_with

A function to perform the rotation (e.g., SVD). Defaults to 'rotate'.
project_with

A function to project the points into the rotated space. Defaults to 'project'.
optimize_with

A function to optimize node positions. Defaults to 'optimize'. Can be set to 'NULL' or 'FALSE' to skip.
rotate_fun

The specific rotation function to be used by 'rotate_with'. Defaults to 'ena.rotate.by.generalized'.
rotate_params

A list of parameters passed to 'rotate_fun' as its 'params' argument – for example the two group-membership vectors for 'ena.rotate.by.mean', or 'list(x_var = "Condition")' for 'ena.rotate.by.generalized'. The nested form 'list(params = <params>)' is also accepted. When empty (the default), 'rotate()' picks its default parameters.
exclude_zero_networks

A logical value passed to 'center_with'. When 'TRUE', units with all-zero line weights are excluded from the mean computation during centering (but all units are still shifted by that mean). Defaults to 'TRUE' automatically for ordered sets ('accumulate(ordered = TRUE)'), 'FALSE' otherwise.
center_to_origin

A logical value. When 'TRUE', the mean of all projected points is subtracted from both the points and the node positions after optimization, placing the centroid of the space at the origin. This is the default behavior for ONA (Ordered Network Analysis). Defaults to 'FALSE'.

Value

An 'ena.set' object with a complete ENA model, including projected points and node positions.

Examples

data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  model()

Title

Description

Title

Usage

move_nodes_to_unit_circle(
  set,
  dimension_name_1 = colnames(as.matrix(set$rotation$nodes))[1],
  dimension_name_2 = colnames(as.matrix(set$rotation$nodes))[2]
)

Arguments

set

TBD
dimension_name_1

TBD
dimension_name_2

TBD

Value

TBD

Title

Description

Title

Usage

move_nodes_to_unit_circle_with_equal_space(
  set,
  dimension_name_1 = colnames(as.matrix(set$rotation$nodes))[1],
  dimension_name_2 = colnames(as.matrix(set$rotation$nodes))[2]
)

Arguments

set

TBD
dimension_name_1

TBD
dimension_name_2

TBD

Value

TBD

Names to Adjacency Key

Description

Convert a vector of strings, representing names of a square matrix, to an adjacency

Usage

namesToAdjacencyKey(vector, upper_triangle = TRUE)

Arguments

vector

Vector representing the names of a square matrix
upper_triangle

Not Implemented

Details

Returns a matrix of 2 rows by choose(length(vector), 2) columns

Optimize Node and Centroid Positions in ENA Set

Description

This function computes and assigns node positions and centroids for an ENA set object using the current points and rotation information.

Usage

optimize(x, weights = NULL)

Arguments

x

An ena.set object for which to optimize node and centroid positions.
weights

Optional. A numeric matrix of connection weights. If provided, the function will use this matrix instead of the connection counts from the ena.set.

Value

The input ena.set object with updated node and centroid positions.

Examples

# Assuming 'set' is an ena.set object:
data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  sphere_norm() |>
  center() |>
  rotate() |>
  project() |>
  optimize()

Plot Cross-Covariance Decay Curve

Description

Plots the noise-corrected Frobenius norm across lags with the half-life threshold marker.

Usage

## S3 method for class 'ena.ccd'
plot(x, ...)

Arguments

x

An object of class ena.ccd.
...

Additional arguments passed to plot.

Value

The ena.ccd object invisibly.

Plot an ena.set object

Description

Plot an ena.set object

Usage

## S3 method for class 'ena.set'
plot(x, y, ..., empty = TRUE, title = "ENA Plot")

Arguments

x

ena.set to plot
y

ignored.
...

Additional parameters passed along to ena.plot functions
empty

Logical; if TRUE, creates an empty plot without points. Default is TRUE.
title

Character; title for the plot. Default is "ENA Plot".

Value

ena.plot.object

Examples

data(RS.data)

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

accum = ena.accumulate.data(
  units = RS.data[,c("UserName","Condition")],
  conversation = RS.data[,c("Condition","GroupName")],
  metadata = RS.data[,c("CONFIDENCE.Change","CONFIDENCE.Pre","CONFIDENCE.Post")],
  codes = RS.data[,codeNames],
  window.size.back = 4
)

set = ena.make.set(
  enadata = accum
)

plot(set) |>
  add_points(Condition$FirstGame, colors = "blue", with.mean = TRUE) |>
  add_points(Condition$SecondGame, colors = "red", with.mean = TRUE) |>
  with_means() |>
  add_nodes()

myENAplot <- plot(set) |>
  add_network(Condition$FirstGame - Condition$SecondGame)


# Add a group mean to an existing ENA plot
add_group(myENAplot, wh = Condition$FirstGame)

# Add a trajectory to an existing ENA plot
add_trajectory(myENAplot, wh = Condition$FirstGame)

# Load test data
data(RS.data);

# Define codenames for the test
codenames <- c("Data", "Technical.Constraints", "Performance.Parameters",
  "Client.and.Consultant.Requests", "Design.Reasoning", "Collaboration");

# Standard ENA accumulation
accum <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames]
);
# Create a standard ENA set 
newset <- ena.make.set(accum);

# Simple plot for a set of points, and their mean
newplot <- plot(newset) |> 
  add_points(Condition$FirstGame, mean = TRUE, colors = "blue") |> 
  add_network();

# Plot a single unit's point and it's line.weights
plot(newset) |> 
  add_points(UserName$`steven z`) |> 
  add_network();

# Trajectory accumulation and plotting
trajectory_accumulation <- ena.accumulate.data(
  units = RS.data[, c("UserName", "Condition")],
  conversation = RS.data[, c("ActivityNumber", "GroupName")],
  codes = RS.data[, codenames],
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

newplot3 <- plot(trajectory_model) |> 
  add_trajectory(Condition$FirstGame);

Prepares trajectory data for an ENA plot.

Description

This function processes and prepares trajectory data for plotting in an ENA set. It handles rotation, grouping, and filling missing steps in the trajectory.

Usage

prepare_trajectory_data(
  x = NULL,
  by = x$`_function.params`$conversation[1],
  rotation_matrix = x$rotation.matrix,
  points = NULL,
  units = points,
  units_by = x$`_function.params`$units,
  steps = NULL
)

Arguments

x

An ENA set object. If 'NULL', other parameters must be provided.
by

A character vector specifying the grouping variables for the trajectory. Default is the first conversation parameter in the ENA set.
rotation_matrix

A matrix used to rotate the points. Default is the rotation matrix from the ENA set.
points

A data table of points to be processed. Default is the points from the ENA set.
units

A data table of units corresponding to the points. Default is the trajectories or points from the ENA set.
units_by

A character vector specifying the unit grouping variables. Default is the unit parameters from the ENA set.
steps

A data table specifying the steps for the trajectory. If 'NULL', steps are generated automatically.

Value

A data table containing the processed trajectory data, including dimensions and metadata.

Title

Description

Title

Usage

## S3 method for class 'ena.set'
print(x, ..., plot = FALSE, set = TRUE)

Arguments

x

[TBD]
...

[TBD]
plot

[TBD]
set

[TBD]

Value

[TBD]

Project ENA Points onto Rotated Space

Description

This function projects ENA points onto the rotated space using the rotation matrix. Optionally, metadata can be included in the resulting points matrix.

Usage

project(x, rotation = NULL, add.meta = TRUE)

Arguments

x

An ena.set object containing the points for projection and rotation matrix.
rotation

Optional. A rotation matrix to use for projection if x is not an ena.set.
add.meta

Logical. If TRUE (default), metadata will be included in the output.

Value

The input ena.set object with the projected points matrix (and metadata if requested).

Examples

# Assuming 'set' is an ena.set object:
data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  sphere_norm() |>
  center() |>
  rotate() |>
  project()

Title

Description

Title

Usage

project_in(x, by = NULL, ...)

Arguments

x

[TBD]
by

[TBD]
...

[TBD]

Value

[TBD]

Reclassify specified columns in a data.table

Description

This function reclassifies specified columns of a data.table using a provided function.

Usage

reclassify(x, v, ...)

Arguments

x

A data.table. The data.table containing the columns to be reclassified.
v

A function. The function to apply to each specified column for reclassification.
...

Additional arguments specifying the names of the columns to be reclassified.

Value

The modified data.table with specified columns reclassified.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
dt <- reclassify(dt, as.qe.code, "a", "b")

Remove meta columns from data.table

Description

Remove meta columns from data.table

Usage

remove_meta_data(x)

Arguments

x

[TBD]

Value

data.table withe columns of class ena.meta.data removed

rENA creates ENA sets

Description

rENA is used to create and visualize network models of discourse and other phenomena from coded data using Epistemic Network Analysis (ENA). A more complete description of the methods will be provided with the next release. See also XXXXX

Shiny render function for interactive ENA plots

Description

Equivalent to qeviz::renderQe(); expr may return an ena.plot.interactive widget or a qeviz::qe_plot().

Usage

renderEnaInteractive(expr, env = parent.frame(), quoted = FALSE)

Arguments

expr

Expression that returns an ena.plot.interactive widget.
env

Environment for expr. Default: parent.frame().
quoted

Logical. Is expr already quoted? Default FALSE.

Rotate ENA Data

Description

Rotates ENA data using a specified rotation function (default: SVD), optionally using formulas or grouping variables.

Usage

rotate(x, ..., wh = ena.rotate.by.generalized)

Arguments

x

An ena.set object to be rotated.
...

Optional formulas or additional arguments for rotation.
wh

Function to use for rotation (default: ena.svd).

Value

The rotated ena.set object with updated rotation matrices.

Examples

# Assuming 'set' is an ena.set object:
data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  sphere_norm() |>
  center() |>
  rotate()

Coded Rescushell Chat Data

Description

A dataset containing sample chat data from the Rescushell Virtual Internship

Usage

RS.data

Format

An object of class data.frame with 3824 rows and 20 columns.

Scales the points in an ENA set.

Description

This function adjusts the scale of the points in the ENA set to match the range of the network.

Usage

## S3 method for class 'ENAplot'
scale(x, center = NULL, scale = NULL)

Arguments

x

An ENAplot object containing the set to scale.
center

Unused parameter, included for compatibility.
scale

A numeric value specifying the scaling factor. If 'NULL', the function will determine the scale based on the data.

Value

The modified ENAplot object with scaled points.

Display and update plot objects within a custom object

Description

This function updates the plots within the provided object by applying the 'check_range' function to each plot. It then prints the updated object using custom print options and returns the object invisibly.

Usage

show(x, ...)

Arguments

x

An object containing a list of plots in the 'plots' field.
...

Additional arguments passed to the 'print' method.

Value

The updated object 'x', returned invisibly.

Scale ENA Data Without Spherical Normalization

Description

The counterpart of [sphere_norm()] for 'norm.by = fun_skip_sphere_norm': instead of scaling each unit's network to length 1, every network is divided by the length of the longest one, so relative magnitudes across units are kept. Pass it as 'normalize' to [model()] (or to 'ona::model()', which hands it on) to build a model without sphere normalization.

Usage

skip_sphere_norm(x, add.meta = TRUE)

Arguments

x

An 'ena.set' object or a numeric matrix of connection counts.
add.meta

A logical value. If 'TRUE' (the default), metadata from the 'ena.set' is preserved and included in the output. This parameter is ignored if 'x' is a matrix.

Value

If 'x' is an 'ena.set', it returns the modified 'ena.set' with a new 'line.weights' matrix and an updated 'centervec' in the 'rotation' object. If 'x' is a matrix, it returns a matrix of scaled line weights.

Examples

data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  model(normalize = skip_sphere_norm)

Apply Spherical Normalization to ENA Data

Description

This function applies spherical normalization to the connection counts in an 'ena.set' object or to a raw matrix of connection counts. Normalization is a key step before centering and rotation in ENA.

Usage

sphere_norm(x, add.meta = TRUE)

Arguments

x

An 'ena.set' object or a numeric matrix of connection counts.
add.meta

A logical value. If 'TRUE' (the default), metadata from the 'ena.set' is preserved and included in the output. This parameter is ignored if 'x' is a matrix.

Value

If 'x' is an 'ena.set', it returns the modified 'ena.set' with a new 'line.weights' matrix and an updated 'centervec' in the 'rotation' object. If 'x' is a matrix, it returns a matrix of normalized line weights.

Examples

data(RS.data)

codes <- c("Data", "Technical.Constraints", "Performance.Parameters",
           "Client.and.Consultant.Requests", "Design.Reasoning",
           "Collaboration")
units <- c("Condition", "UserName")
horizon <- c("Condition", "GroupName")
enaset <- RS.data |>
  accumulate(units, codes, horizon) |>
  sphere_norm()

Reclassify specified columns as units or list unit columns in a data.table

Description

This function reclassifies specified columns of a data.table to the 'qe.unit' format if column names are provided. If no column names are provided, it returns the names of columns that are already classified as 'qe.unit'.

Usage

units(x, ...)

Arguments

x

A data.table. The data.table containing the columns to be reclassified or checked.
...

Additional arguments specifying the names of the columns to be reclassified.

Value

The modified data.table with specified columns reclassified as 'qe.unit', or a character vector of column names already classified as 'qe.unit'.

Examples

library(data.table)
dt <- data.table(a = 1:5, b = 6:10)
# Reclassify columns 'a' and 'b' as 'qe.unit'
dt <- units(dt, "a", "b")
# List columns classified as 'qe.unit'
unit_columns <- units(dt)

Upper Triangle from Vector (numeric)

Description

Compute pairwise products v[j] * v[i] for all j < i.

Usage

vector_to_ut(v)

Arguments

v

Numeric vector or single-row matrix

Value

Numeric row vector of pairwise products

Adds group means to the ENA plot.

Description

This function iterates over the plotted points in the ENA plot and calculates the mean for each group of points. The calculated means are then added to the plot as group means.

Usage

with_means(x)

Arguments

x

An ENA set object containing the plots.

Value

Invisibly returns the modified ENA set object with updated plots.

Adds trajectories to an ENA plot.

Description

This function generates trajectories for the plotted points in the ENA plot based on the specified grouping variables. It supports options for jittering, animation, and scaling.

Usage

with_trajectory(
  x,
  ...,
  by = x$`_function.params`$conversation[1],
  add_jitter = TRUE,
  frame = 1100,
  transition = 1000,
  easing = "circle-in-out"
)

Arguments

x

An ENA set object containing the plots.
...

Additional arguments passed to the plotting functions.
by

A character vector specifying the grouping variables for the trajectories. Default is the first conversation parameter in the ENA set.
add_jitter

Logical; if 'TRUE', adds jitter to the trajectory points. Default is 'TRUE'.
frame

Numeric; the duration of each frame in the animation. Default is 1100.
transition

Numeric; the duration of the transition between frames. Default is 1000.
easing

A character string specifying the easing function for the animation. Default is "circle-in-out".

Value

Invisibly returns the modified ENA set object with updated plots.

with.ena.matrix

Description

This function sets up a context using the provided data (typically an ENA matrix), allowing the evaluation of an expression ('expr') with access to both the matrix and its metadata. Optionally, a custom matrix 'V' and other arguments can be supplied.

Usage

## S3 method for class 'ena.matrix'
with(data, expr, ...)

Arguments

data

An ENA matrix or data frame containing the data to be used.
expr

An R expression to be evaluated within the context of the ENA matrix.
...

Additional arguments, including an optional custom matrix 'V' and other parameters.

Details

- If a custom matrix 'V' is provided in '...', it will be used; otherwise, 'data' is converted to a matrix. - Metadata columns are coerced to numeric if they are character vectors. - The expression is evaluated with access to both the matrix ('V') and metadata.

Value

The result of evaluating 'expr' in the constructed context.