Title:	Epistemic Network Analysis
Type:	Package
Author:	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 <cody.marquart@wisc.edu>
Version:	0.3.0
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).
LazyData:	TRUE
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
License:	GPL-3 | file LICENSE
URL:	https://gitlab.com/epistemic-analytics/qe-packages/rENA
BugReports:	https://gitlab.com/epistemic-analytics/qe-packages/rENA/-/issues
LinkingTo:	Rcpp, RcppArmadillo
Imports:	data.table, Rcpp, R6, methods, stats, plotly, doParallel, parallel, scales, glmnet, tma
Suggests:	testthat (≥ 2.1.0), knitr, rmarkdown
RoxygenNote:	7.3.2
NeedsCompilation:	yes
Packaged:	2025-09-29 22:39:42 UTC; clmarquart
Repository:	CRAN
Date/Publication:	2025-09-29 23:40:08 UTC

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

Value

[TBD]

Extract metadata easily

Description

Extract metadata easily

Usage

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

Arguments

Value

[TBD]

Extract points easily

Description

Extract points easily

Usage

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

Arguments

Value

[TBD]

Extract line.weignts easily

Description

Extract line.weignts easily

Usage

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

Arguments

Value

[TBD]

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

Value

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

ENARotationSet R6class

Description

ENARotationSet R6class

ENARotationSet R6class

Public fields

Methods

Public methods

• ENARotationSet$new()

• ENARotationSet$clone()

Method new()

Usage

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

Arguments

Returns

ENARotationsSet

Method clone()

The objects of this class are cloneable with this method.

Usage

ENARotationSet$clone(deep = FALSE)

Arguments

ENAdata R6class

Description

ENAdata R6class

ENAdata R6class

Public fields

Methods

Public methods

• ENAdata$new()

• ENAdata$process()

• ENAdata$get()

• ENAdata$add.metadata()

• ENAdata$clone()

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

Returns

Process accumulation

Method process()

Usage

ENAdata$process()

Returns

ENAdata Get property from object

Method get()

Usage

ENAdata$get(x = "data")

Arguments

Returns

value from object at x Add metadata

Method add.metadata()

Usage

ENAdata$add.metadata(merge = F)

Arguments

Returns

data.frame

Method clone()

The objects of this class are cloneable with this method.

Usage

ENAdata$clone(deep = FALSE)

Arguments

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 plotly object used for data visualization.

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

Methods

Public methods

• ENAplot$new()

• ENAplot$print()

• ENAplot$get()

• ENAplot$clone()

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",
  ...
)

Arguments

Returns

ENAplot Print ENA plot

Method print()

Usage

ENAplot$print()

Returns

Get property from object

Method get()

Usage

ENAplot$get(x)

Arguments

Returns

value from object at x

Method clone()

The objects of this class are cloneable with this method.

Usage

ENAplot$clone(deep = FALSE)

Arguments

Examples

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

ENAset R6class

Description

ENAset R6class

ENAset R6class

Public fields

Methods

Public methods

• ENAset$new()

• ENAset$process()

• ENAset$get()

• ENAset$clone()

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

Returns

ENAset Process ENAset

Method process()

Usage

ENAset$process()

Returns

ENASet Get property from object

Method get()

Usage

ENAset$get(x = "enadata")

Arguments

Returns

value from object at x

Method clone()

The objects of this class are cloneable with this method.

Usage

ENAset$clone(deep = FALSE)

Arguments

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.

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
)

Arguments

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)

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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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, it is used directly as the network data.

• 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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = codenames,
  model = "A"
);
trajectory_model <- ena.make.set(trajectory_accumulation);

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

Re-class vector as ena.co.occurrence

Description

Re-class vector as ena.co.occurrence

Usage

as.ena.co.occurrence(x)

Arguments

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

Value

Object of same st

Re-class matrix as ena.metadata

Description

Re-class matrix as ena.metadata

Usage

as.ena.metadata(x)

Arguments

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

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

Value

matrix

Matrix without metadata

Description

Matrix without metadata

Usage

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

Arguments

Value

matrix

ENA nodes as matrix

Description

ENA nodes as matrix

Usage

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

Arguments

Value

matrix

ENA points as matrix

Description

ENA points as matrix

Usage

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

Arguments

Value

matrix

ENA rotations as matrix

Description

ENA rotations as matrix

Usage

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

Arguments

Value

matrix

ENA row connections as matrix

Description

ENA row connections as matrix

Usage

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

Arguments

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

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

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

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

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

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

Title

Description

Title

Usage

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

Arguments

Value

[TBD]

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)

Arguments

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

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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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)

Fast combn choose 2

Description

faster combn alternative

Usage

combn_c2(n)

Arguments

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

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

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

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"))

Multiobjective, Component by Component, with Ellipsoidal Scaling, for directed ENA

Description

TBD

Usage

directed_node_positions(line_weights, points, numDims)

Arguments

Details

Multiobjective, Component by Component, with Ellipsoidal Scaling, for directed ENA

Node position optimization with ground and response weights/points added

Description

TBD

Usage

directed_node_positions_with_ground_response_added(
  line_weights,
  points,
  numDims
)

Arguments

Details

Node position optimization with ground and response weights/points added

Wrapper to generate, and optionally plot, 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(
  data,
  codes,
  units,
  conversation,
  metadata = NULL,
  model = c("EndPoint", "AccumulatedTrajectory", "SeparateTrajectory"),
  weight.by = "binary",
  window = c("MovingStanzaWindow", "Conversation"),
  window.size.back = 1,
  include.meta = TRUE,
  groupVar = NULL,
  groups = NULL,
  runTest = FALSE,
  points = FALSE,
  mean = FALSE,
  network = TRUE,
  networkMultiplier = 1,
  subtractionMultiplier = 1,
  unit = NULL,
  include.plots = T,
  print.plots = F,
  ...
)

Arguments

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, as well as plots of units, groups, and networks.

Value

ena.set object

Examples

data(RS.data)

rs = ena(
  data = RS.data,
  units = c("UserName","Condition", "GroupName"),
  conversation = c("Condition","GroupName"),
  codes = c('Data',
            'Technical.Constraints',
            'Performance.Parameters',
            'Client.and.Consultant.Requests',
            'Design.Reasoning',
            'Collaboration'),
  window.size.back = 4,
  print.plots = FALSE,
  groupVar = "Condition",
  groups = c("FirstGame", "SecondGame")
)

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

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

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

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

Value

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

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

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

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",
  ...
)

Arguments

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

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);

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

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

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 = F
)

Arguments

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,
  print.plots = F,
  ...
)

Arguments

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

ENA Rotate by generalized means rotation (gmr)

Usage

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

Arguments

Value

ENARotationSet

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

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

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 a the original space. Subsequent dimensions of the projected space are computed using ena.svd

Usage

ena.rotate.by.mean(enaset, groups)

Arguments

Value

ENARotationSet

hENA rotation for ENA

Description

hENA rotation function.

Usage

ena.rotation.h(enaset, params)

Arguments

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,
  include.meta = TRUE,
  groupVar = NULL,
  groups = NULL,
  runTest = FALSE,
  ...
)

Arguments

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

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:

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))

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 = getwd(),
  type = c("file", "stream"),
  theory = T,
  methods = T,
  params = NULL,
  output_file = NULL,
  output_format = NULL
)

Arguments

Value

String representing the methods used to generate the model

Calculate the correlations

Description

Calculate both Pearson correlations for the provided points and centorids

Usage

ena_correlation(points, centroids, conf_level = 0.95)

Arguments

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

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

Value

logical vector

Find dimension columns

Description

Find dimension columns

Usage

find_dimension_cols(x)

Arguments

Value

logical vector

Find metadata columns

Description

Find metadata columns

Usage

find_meta_cols(x)

Arguments

Value

logical vector

Cohen's d

Description

Calculate Conhen's d

Usage

fun_cohens.d(x, y)

Arguments

Details

Cohen's d calculation

[TBD]

Value

numeric Cohen's d calculation

Row-wise Max-Norm Scaling

Description

Scales all rows of a numeric dataframe by dividing by the largest row vector length (L2 norm) found in the dataframe. This preserves the relative magnitudes between rows but does not normalize each row to unit length. Useful for analyses where relative scale is important but full normalization is not desired.

Usage

fun_skip_sphere_norm(dfM)

Arguments

Details

Row-wise Max-Norm Scaling

This function finds the row with the largest L2 norm (Euclidean length) and divides all entries in the matrix by this value. It does not normalize each row individually.

Value

A numeric matrix with the same dimensions as 'dfM', with all values divided by the largest row L2 norm.

Examples

df <- data.frame(a = c(3, 4), b = c(0, 0))
fun_skip_sphere_norm(df)

Row-wise L2 (Sphere) Normalization

Description

Normalizes each row of a numeric dataframe or matrix to have unit L2 norm (Euclidean length). Each row is divided by its own length, projecting all rows onto the unit hypersphere. Useful for analyses where direction is important but magnitude should be removed.

Usage

fun_sphere_norm(dfM)

Arguments

Details

Row-wise L2 (Sphere) Normalization

This function computes the L2 norm (Euclidean length) of each row and divides the row by this value. Rows with zero length are left unchanged.

Value

A numeric matrix with the same dimensions as 'dfM', with each row normalized to unit length (L2 norm = 1), unless the row is all zeros (in which case it remains zeros).

Examples

df <- data.frame(a = c(3, 4), b = c(0, 0))
fun_sphere_norm(df)

Extract Main Effect Contribution of the First Predictor Using Elastic Net

Description

This function fits a multivariate elastic net regression model (using glmnet) to estimate the main effect contribution of the first predictor variable (x1) in the provided data frame X for each response variable in V. The main effect is forced into the model by setting its penalty factor to zero.

Usage

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

Arguments

Details

The function constructs a model matrix including all main effects and two-way interactions. It then fits a multivariate elastic net model using cv.glmnet, forcing the inclusion of the main effect of x1 by setting its penalty factor to zero. The resulting coefficients for x1 are used to compute its contribution to the fitted values for each response variable.

Value

A numeric matrix of the same dimensions as V, where each column contains the estimated main effect contribution of x1 for the corresponding response variable.

Examples

## Not run: 
set.seed(123)
V <- matrix(rnorm(100 * 2), ncol = 2)
X <- data.frame(x1 = rnorm(100), x2 = sample(letters[1:3], 100, TRUE))
result <- get_x1_main_effect(V, X)

## End(Not run)

Generalized Means Rotation (GMR)

Description

Computes the generalized means rotation for a given set of ENA points and predictor variables.

Usage

gmr(V, X)

Arguments

Details

If X has only one column, a linear model is fit between V and the single predictor. Otherwise, the main effect of the first predictor is extracted using get_x1_main_effect. Singular value decomposition (SVD) is then performed, and the first right singular vector is used to project the data. A linear model is fit to the projected data, and the coefficients are normalized to produce the rotation vector.

Value

A numeric vector representing the rotation.

See Also

get_x1_main_effect

Examples

## Not run: 
V <- matrix(rnorm(100), ncol = 5)
X <- data.frame(target = rnorm(20), predictor1 = rnorm(20), predictor2 = rnorm(20))
r <- gmr(V, X)

## 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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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

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

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

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

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

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

Value

[TBD]

Merge data frame columns

Description

TBD

Usage

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

Arguments

Details

Merge data frame columns

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

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

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

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()
)

Arguments

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

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

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

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

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 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

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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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 <- rENA:::ena.accumulate.data.file(
  RS.data, units.by = c("UserName", "Condition"),
  conversations.by = c("ActivityNumber", "GroupName"),
  codes = 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

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

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

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

Value

[TBD]

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

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

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

Value

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

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

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()

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

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

Value

The updated object 'x', returned invisibly.

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

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

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)

vector to upper triangle

Description

TBD

Usage

vector_to_ut(v)

Arguments

Details

Upper Triangle from Vector

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

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.

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

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

Value

Invisibly returns the modified ENA set object with updated plots.