setse_auto: SETSe embedding with automatic drag and timestep selection

Description Usage Arguments Details Value See Also Examples

View source: R/setse_auto.R

Description

Embeds/smooths a feature network using the SETSe algorithm automatically finding convergence parameters using a grid search.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
setse_auto(
  g,
  force = "force",
  distance = "distance",
  edge_name = "edge_name",
  k = "k",
  tstep = 0.02,
  mass = 1,
  max_iter = 1e+05,
  tol = 0.002,
  sparse = FALSE,
  hyper_iters = 100,
  hyper_tol = 0.01,
  hyper_max = 30000,
  drag_min = 0.01,
  drag_max = 100,
  tstep_change = 0.2,
  sample = 100,
  static_limit = NULL,
  verbose = FALSE,
  include_edges = TRUE,
  noisy_termination = TRUE
)

Arguments

g

An igraph object

force

A character string. This is the node attribute that contains the force the nodes exert on the network.

distance

A character string. The edge attribute that contains the original/horizontal distance between nodes.

edge_name

A character string. This is the edge attribute that contains the edge_name of the edges.

k

A character string. This is k for the moment don't change it.

tstep

A numeric. The time interval used to iterate through the network dynamics.

mass

A numeric. This is the mass constant of the nodes in normalised networks this is set to 1.

max_iter

An integer. The maximum number of iterations before stopping. Larger networks usually need more iterations.

tol

A numeric. The tolerance factor for early stopping.

sparse

Logical. Whether or not the function should be run using sparse matrices. must match the actual matrix, this could prob be automated

hyper_iters

integer. The hyper parameter that determines the number of iterations allowed to find an acceptable convergence value.

hyper_tol

numeric. The convergence tolerance when trying to find the minimum value

hyper_max

integer. The maximum number of iterations that SETSe will go through whilst searching for the minimum.

drag_min

integer. A power of ten. The lowest drag value to be used in the search

drag_max

integer. A power of ten. if the drag exceeds this value the tstep is reduced

tstep_change

numeric. A value between 0 and 1 that determines how much the time step will be reduced by default value is 0.5

sample

Integer. The dynamics will be stored only if the iteration number is a multiple of the sample. This can greatly reduce the size of the results file for large numbers of iterations. Must be a multiple of the max_iter

static_limit

Numeric. The maximum value the static force can reach before the algorithm terminates early. This prevents calculation in a diverging system. The value should be set to some multiple greater than one of the force in the system. If left blank the static limit is the system absolute mean force.

verbose

Logical. This value sets whether messages generated during the process are suppressed or not.

include_edges

logical. An optional variable on whether to calculate the edge tension and strain. Default is TRUE. included for ease of integration into the bicomponent functions.

noisy_termination

Stop the process if the static force does not monotonically decrease.

Details

This is one of the most commonly used SETSe functions. It automatically selects the convergence time-step and drag values to ensure efficient convergence.

The noisy_termination parameter is used as in some cases the convergence process can get stuck in the noisy zone of SETSe space. To prevent this the process is stopped early if the static force does not monotonically decrease. On large networks this greatly speeds up the search for good parameter values. It increases the chance of successful convergence. More detail on auto-SETSe can be found in the paper "The spring bounces back" (Bourne 2020).

Value

A list containing 5 dataframes.

  1. The network dynamics describing several key figures of the network during the convergence process, this includes the static_force

  2. The node embeddings. Includes all data on the nodes the forces exerted on them position and dynamics at simulation termination

  3. time taken. the amount of time taken per component, includes the edge and nodes of each component

  4. The edge embeddings. Includes all data on the edges as well as the strain and tension values.

  5. memory_df A dataframe recording the iteration history of the convergence of each component.

See Also

Other setse: setse_auto_hd(), setse_bicomp(), setse_expanded(), setse()

Examples

1
2
3
4
5
6
7
8
9
set.seed(234) #set the random see for generating the network
g <- generate_peels_network(type = "E")
embeddings <- g %>%
prepare_edges(k = 500, distance = 1) %>%
#prepare the network for a binary embedding
prepare_categorical_force(., node_names = "name",
                     force_var = "class") %>%
#embed the network using auto_setse
  setse_auto(., force = "class_A")

rsetse documentation built on June 11, 2021, 5:07 p.m.