grand {grand}

Apply Guidelines for Reporting About Network Data (GRAND) to an igraph object

Description

The grand function stores characteristics about the graph as graph attributes that can be summarized in a narrative using the grand.text() or a table using grand.table().

Usage

grand(
  G,
  interactive = TRUE,
  name = NA,
  doi = NA,
  url = NA,
  vertex1 = NULL,
  vertex2 = NULL,
  vertex1.total = 0,
  vertex2.total = 0,
  edge.pos = NULL,
  edge.neg = NULL,
  weight = NULL,
  measure = NULL,
  mode = NULL,
  year = NULL,
  topology = character()
)

Arguments

G

An igraph object, with weights/signs (if present) stored in E(G)$weight

interactive

boolean: Should GRAND run interactively?

name

string: Name of the network

doi

string: DOI associated with the data

url

string: Link to data

vertex1

string: Entity represented by vertices

vertex2

string: Entity represented by vertices

vertex1.total

numeric: Number of entities in the network's boundary

vertex2.total

numeric: Number of entities in the network's boundary

edge.pos

string: Relationship represented by (positive) edges

edge.neg

string: Relationship represented by negative edges

weight

string: What the edge weights represent

measure

string: Scale on which edge weights are measured

mode

string: Mode of data collection

year

numeric: Year in which data was collected

topology

string: Vector of topological metrics to be computed in GRAND summaries

Details

The interactive mode (default) asks the user a series of questions based on the igraph object, while non-interactive mode allows the user to directly supply the relevant attributes.

Data

The first set of interactive questions ask about the data as a whole:

• name - This should usually be specified ending with the word "network" or "data" (e.g. "Florentine Families Network" or "Airline Traffic Data").

• doi - DOI for a manuscript describing the data.

• url - Link to a copy of the data.

• Data collection mode - This describes how the data was collected or generated. Chose one of the available options (Survey, Interview, Sensor, Observation, Archival, or Simulation) or choose Other to enter something else.

• year - In what year were the data collected?

Nodes

The second set of interactive questions ask about the nodes/vertices:

• vertex1 (and in bipartite graphs, vertex2) - What type of entity do the nodes/vertices represent? This should be specified as a plural noun (e.g., "People").

• vertex1.total (and in bipartite graphs, vertex2.total) - Networks often have an externally-defined boundary that determines which nodes/vertices should be included, even if some are missing from the network. These ask about the total number of nodes/vertices inside the boundary (if one exists) and are used to compute rates of missingness.

Edges

The third set of interactive questions ask about the edges:

• edge.pos (and in signed graphs, edge.neg) - What type of relationship do the edges represent? This should be specified as a plural noun (e.g., "Friendships").

• weight - What do the edge weights represent? Choose one of the available options (Frequency, Intensity, Multiplexity, or Valence) or choose Other to enter something else.

• measure - How are the edge weights measured? Choose one of the available options (Continuous, Count, Ordinal, or Categorical) or choose Other to enter something else.

Topology

The final set of interactive questions ask about relevant topological characteristics. You may choose to (1) use the defaults for this network type, (2) choose characteristics from a list, (3) compute all available characteristics, or (4) compute no characteristics. For comparability and to ensure they are well-defined, all characteristics are computed on an undirected and unweighted version of G using existing igraph functions. Available topological characteristics include:

• clustering coefficient - Computed using transitivity(G, type = "localaverage")

• degree centralization - Computed using centr_degree(G)$centralization

• degree distribution - Computed using fit_power_law(degree(G), implementation = "plfit")

• density - Computed using edge_density(G)

• diameter - Computed using diameter(G)

• efficiency - Computed using global_efficiency(G)

• mean degree - Computed using mean(degree(G))

• modularity - Computed from a partition generated by cluster_leiden(G, objective_function = "modularity")

• number of communities - Computed from a partition generated by cluster_leiden(G, objective_function = "modularity")

• number of components - Computed using count_components(G)

• transitivity - Computed using transitivity(G, type = "global")

• structural balance - Computed using the triangle index

Value

An igraph object

Examples

data(airport)  #Load example data
airport <- grand(airport)  #Apply GRAND interactively
airport <- grand(airport, interactive = FALSE, #Apply GRAND non-interactively
                 vertex1 = "Airports",
                 vertex1.total = 382,
                 edge.pos = "Routes",
                 weight = "Passengers",
                 measure = "Count",
                 mode = "Archival",
                 year = "2019",
                 topology = c("clustering coefficient", "mean path length", "degree distribution"))