Argument Passing

A big change to the {EGAnet} structure in version +2.0.0 was that nearly every argument can be passed down through sub-functions in a main function. Sounds useful, but what does that actually mean?

Let’s take the EGA function as an example. The EGA function has several other {EGAnet} functions that it uses to perform it’s operations. These functions include:

auto.correlate
- cor
- polychoric.matrix
EGA.estimate
- auto.correlate (see functions above)
- network.estimation
  - BGGM
  - EBICglasso.qgraph
  - TMFG
- community.detection (see igraph::cluster_* functions)
- community.consensus
community.unidimensional
- auto.correlate (see functions above)
- network.estimation (see functions above)
plot

The first-level points are all functions called by EGA. The second-level points are called by their first level functions and so on down the line. This function tree shows that (1) EGA calls a lot of functions but (2) all of these functions have their own arguments that can be called by EGA.

EGA passes arguments that are not listed as default arguments (see ?EGA) using the ... argument. For every function in {EGAnet} that has the ... means that you can pass along arguments to other functions in the package (and other packages). How do you know what arguments can be passed? The documentation for the ... argument in every function with tell you. Let’s take a look at EGA’s ... argument documentation:

Additional arguments to be passed on to auto.correlate, network.estimation, community.detection, community.consensus, and community.unidimensional

Each of these functions are linked directly to their documentation, so you can navigate to each function when specifying arguments of an {EGAnet} function.

OK, let’s see this flexibility in action.

Passing through `auto.correlate`

Changing `corr`

# Load packages
library(EGAnet); library(psychTools)

# Use Spearman correlation
bfi_ega_spearman <- EGA(bfi[,1:25], corr = "spearman", plot.EGA = FALSE)

# Print result
summary(bfi_ega_spearman)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: spearman
Lambda: 0.0703394074817376 (n = 100, ratio = 0.1)

Number of nodes: 25
Number of edges: 122
Edge density: 0.407

Non-zero edge weights: 
     M    SD    Min   Max
 0.041 0.111 -0.240 0.502

----

Algorithm:  Walktrap

Number of communities:  5

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  3  3  3  4  4  4  4  4  5  5  5  5  5 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -27.036

How do you know whether something has changed? In general, most changes to methods will show up in the summary of the output. In this example, we can see that Correlations: spearman meaning that the correlations were changed to Spearman.

Changing `ordinal.categories`

# 5 categories and higher are treated as continuous
bfi_ega_continuous <- EGA(bfi[,1:25], ordinal.categories = 4, plot.EGA = FALSE)

# Print result
summary(bfi_ega_continuous)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: auto
Lambda: 0.0706980955149606 (n = 100, ratio = 0.1)

Number of nodes: 25
Number of edges: 120
Edge density: 0.400

Non-zero edge weights: 
     M    SD    Min   Max
 0.042 0.108 -0.245 0.504

----

Algorithm:  Walktrap

Number of communities:  5

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  3  3  3  4  4  4  4  4  5  5  5  5  5 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -26.924

There usually isn’t a case where you would want to change ordinal.categories argument of auto.correlate to be lower than its default value of 7. The argument sets what data the function should consider as ordinal (defaults to up to 7 categories). For demonstration purposes, ordinal.categories is used to show that arguments from EGA are passed on to auto.correlate.

Passing through `network.estimation`

# Change the lambda.min.ratio
bfi_ega_qgraph <- EGA(bfi[,1:25], lambda.min.ratio = 0.01, plot.EGA = FALSE)

# Print result
summary(bfi_ega_qgraph)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: auto
Lambda: 0.0244632691767234 (n = 100, ratio = 0.01)

Number of nodes: 25
Number of edges: 191
Edge density: 0.637

Non-zero edge weights: 
     M    SD    Min   Max
 0.035 0.104 -0.276 0.572

----

Algorithm:  Walktrap

Number of communities:  5

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  1  1  3  4  4  4  5  5  3  3  3  3  3 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -22.817

The lambda.min.ratio parameter was passed to network.estimation and on to EBICglasso.qgraph. The parameter is output in the summary above (see Lambda:). The lambda.min.ratio value used in this example is the default in qgraph::EBICglasso.

Passing through `community.detection`

# Change the algorithm and its arguments
bfi_ega_leiden <- EGA(
  bfi[,1:25], algorithm = "leiden",
  objective_function = "CPM", # in {igraph}
  resolution_parameter = 0.05, # in {igraph}
  plot.EGA = FALSE
)

# Print result
summary(bfi_ega_leiden)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: auto
Lambda: 0.0764652282008741 (n = 100, ratio = 0.1)

Number of nodes: 25
Number of edges: 117
Edge density: 0.390

Non-zero edge weights: 
     M    SD    Min   Max
 0.046 0.119 -0.269 0.548

----

Algorithm:  Leiden with Constant Potts Model

Number of communities:  5

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  3  3  3  4  4  4  4  4  5  5  5  5  5 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -27.335

The above code shows off a lot of {EGAnet}’s flexibility. First, the algorithm is being changed to "leiden" which is switched in the community.detection function. Second, the arguments objective_function and resolution_parameter are being passed to igraph::cluster_leiden and aren’t even handled in {EGAnet}. The summary reflects these changes: Algorithm: Leiden with Constant Potts Model.

Passing through `community.consensus`

Changing `consensus.iter`

# More consensus iterations
bfi_ega_consensus <- EGA(
  bfi[,1:25], algorithm = "louvain",
  consensus.iter = 10000, plot.EGA = FALSE
)

# Print result
summary(bfi_ega_consensus)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: auto
Lambda: 0.0764652282008741 (n = 100, ratio = 0.1)

Number of nodes: 25
Number of edges: 117
Edge density: 0.390

Non-zero edge weights: 
     M    SD    Min   Max
 0.046 0.119 -0.269 0.548

----

Consensus Method: Most Common (10000 iterations)
Algorithm: Louvain
Order: Higher

Number of communities:  5

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  3  3  3  4  4  4  4  4  5  5  5  5  5 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -27.335

By default, the consensus clustering method performs 1000 iterations (see ?consensus.clustering) but the iterations can be changed as well as the method (using consensus.method argument). This change is also reflected in the summary output with number of iterations in parentheses.

Changing `order`

# Get lower order result
bfi_ega_lower <- EGA(
  bfi[,1:25], algorithm = "louvain",
  order = "lower", plot.EGA = FALSE
)

# Print result
summary(bfi_ega_lower)

Model: GLASSO (EBIC with gamma = 0.5)
Correlations: auto
Lambda: 0.0764652282008741 (n = 100, ratio = 0.1)

Number of nodes: 25
Number of edges: 117
Edge density: 0.390

Non-zero edge weights: 
     M    SD    Min   Max
 0.046 0.119 -0.269 0.548

----

Consensus Method: Most Common (1000 iterations)
Algorithm: Louvain
Order: Lower

Number of communities:  6

A1 A2 A3 A4 A5 C1 C2 C3 C4 C5 E1 E2 E3 E4 E5 N1 N2 N3 N4 N5 O1 O2 O3 O4 O5 
 1  1  1  1  1  2  2  2  2  2  3  3  3  3  3  4  4  5  5  5  6  6  6  6  6 

----

Unidimensional Method: Louvain
Unidimensional: No

----

TEFI: -24.718

The order can also be changed. The "lower" order is used in Hierarchical EGA (hierEGA; Jiménez et al., 2023) method but can be replicated using EGA and specifying the order argument.

Passing through auto.correlate

Changing corr

Changing ordinal.categories

Passing through network.estimation

Passing through community.detection

Passing through community.consensus

Changing consensus.iter

Changing order