Output example for a bootstrapping analysis conducted with the ResIN package

Description

Output example for a bootstrapping analysis conducted with the ResIN package

Usage

data(Bootstrap_example)

Format

An object of class "rda"

References

This dataset was made available by Lüders et.al. 2024.

Examples

data(Bootstrap_example)
names(Bootstrap_example[[1]])

Source data for Lüders, A., Carpentras, D. and Quayle, M., 2024. Attitude networks as intergroup realities: Using network‐modelling to research attitude‐identity relationships in polarized political contexts. British Journal of Social Psychology, 63(1), pp.37-51.

Description

The sample of N = 402 paid participants through the crowd working platform Prolific Academic. The core of the survey consists of A set of eight political attitude items abortion, immigration, gun control, and gay marriage. Each item followed a 5-point scale ranging from strong disagreement to strong agreement. The survey also includes items on partisanship, affective polarization, and a short vignette experiment.

Usage

data(BrJSocPsychol_2024)

Format

An object of class "data.frame"

References

This dataset was made available by Lüders et.al. 2024.

Examples

data(BrJSocPsychol_2024)
head(BrJSocPsychol_2024)

Flagship function that implements Response Item Network (ResIN) analysis

Description

Performs Response Item-Network (ResIN) analysis in one go. Users minimally need to supply a dataframe or matrix of discrete response data. If needed for step-wise analysis, all intermediate outputs can still be accessed as part of the aux_objects output list.

Usage

ResIN(
  df,
  node_vars = NULL,
  left_anchor = NULL,
  cor_method = "pearson",
  weights = NULL,
  missing_cor = "pairwise",
  offset = 0,
  ResIN_scores = TRUE,
  remove_nonsignificant = FALSE,
  remove_nonsignificant_method = "default",
  sign_threshold = 0.05,
  node_covars = NULL,
  node_costats = NULL,
  network_stats = TRUE,
  detect_clusters = FALSE,
  cluster_method = NULL,
  cluster_arglist = NULL,
  cluster_assignment = TRUE,
  generate_ggplot = TRUE,
  plot_ggplot = TRUE,
  plot_whichstat = NULL,
  plot_edgestat = NULL,
  color_palette = "RdBu",
  direction = 1,
  plot_responselabels = TRUE,
  response_levels = NULL,
  plot_title = NULL,
  bipartite = FALSE,
  save_input = TRUE,
  remove_negative = TRUE,
  EBICglasso = FALSE,
  EBICglasso_arglist = NULL,
  seed = NULL
)

Arguments

Value

An edge-list type data-frame, ResIN_edgelist, a node-level data-frame, ResIN_nodeframe, an n*2 data-frame of individual-level spatial scores along the major (x) and minor(y) axis, ResIN_scores a list of graph-level statistics graph_stats including (graph_structuration), and centralization (graph_centralization). Further, a bipartite_output list which includes an igraph class bipartite graph (bipartite_igraph), a data frame, coordinate_df, with spatial coordinates of respondents, and a plot-able ggraph-object called bipartite_ggraph is optionally generated. Lastly, the output includes a list of auxiliary objects, aux_objects, including the ResIN adjacency matrix (adj_matrix), a numeric vector detailing which item responses belong to which item (same_items), and the dummy-coded item-response data-frame (df_dummies). For reproducibility, (aux_objects$meta stores a numeric dataframe identifier (df_id, the random seed, call, and the (ResIN package version used to create the object.”

Examples

## Load the 12-item simulated Likert-type toy dataset
data(lik_data)

# Apply the ResIN function to toy Likert data:
ResIN_obj <- ResIN(lik_data, network_stats = TRUE, remove_nonsignificant = TRUE)

Internal coercion generics

Description

These functions are S3 generics used for object coercion in ResIN. End users should typically consult the class methods: as.igraph.ResIN, as.qgraph.ResIN, and as.gephi.ResIN.

Usage

as.qgraph(x, ...)

as.gephi(x, ...)

as.tidygraph(x, ...)

Re-exported functions used by ResIN

Description

These functions are re-exported so users can call common coercion generics (e.g., as.igraph() and as.network()) directly after loading ResIN, with S3 dispatch to ResIN methods.

Usage

as.igraph(x, ...)

as.network(x, ...)

Extract bootstrap draws from ResIN objects

Description

"ResIN_boots_draws" objects are typically returned by ResIN_boots_extract when the requested quantity is scalar per bootstrap iteration (e.g., "global_clustering"). The object is a numeric vector with attributes describing the bootstrap context.

Details

Common attributes include:

what

Name of the extracted quantity.

n_total, n_ok, n_failed

Counts of total, successful, and failed iterations.

plan

The "ResIN_boots_prepped" plan used to generate the results (if attached).

created

Timestamp of execution (if attached).

Methods

print(x)

Compact display including median and 95% CI.

summary(object)

Return descriptive statistics and quantiles.

confint(object)

Quantile-based confidence intervals.

plot(x)

Histogram with CI markers.

Carry out prepared bootstrap analyses on ResIN networks

Description

Executes a bootstrap plan created by ResIN_boots_prepare by repeatedly re-estimating ResIN on resampled or permuted versions of the original data. Can optionally leverage CPU parallelism.

Usage

ResIN_boots_execute(
  ResIN_boots_prepped,
  parallel = FALSE,
  detect_cores = TRUE,
  core_offset = 0L,
  n_cores = 2L,
  inorder = FALSE
)

Arguments

Value

An object of class "ResIN_boots_executed" containing n bootstrapped ResIN fits. Use print(), summary(), length(), and [ to inspect or subset results. See ResIN_boots_executed for details.

Examples

## Load the 12-item simulated Likert-type toy dataset
data(lik_data)

# Apply the ResIN function to toy Likert data:
ResIN_obj <- ResIN(lik_data, network_stats = TRUE,
                      generate_ggplot = FALSE, plot_ggplot = FALSE)


# Prepare for bootstrapping
prepped_boots <- ResIN_boots_prepare(ResIN_obj, n=100, boots_type="resample")

# Execute the prepared bootstrap list
executed_boots <-  ResIN_boots_execute(prepped_boots, parallel = TRUE, detect_cores = TRUE)

# Extract results - here for example, the network (global)-clustering coefficient
ResIN_boots_extract(executed_boots, what = "global_clustering", summarize_results = TRUE)

Bootstrapped results

Description

The "ResIN_boots_executed" object is returned by ResIN_boots_execute. It contains a list of fitted "ResIN" objects, typically produced by refitting ResIN on resampled/permuted versions of the original data.

Details

The object is a list of length n where each element is (typically) a ResIN fit. For reproducibility, the following attributes may be present:

plan

A "ResIN_boots_prepped" plan used to generate the results.

boot_inputs

Optional list of bootstrap input data sets (only if save_input = TRUE in the plan).

created

Time stamp when the executed object was created.

Methods

print(x)

Print a compact overview of the bootstrap results.

summary(object)

Summarize the results (iterations, successes/failures, plan details).

length(x)

Return the number of iterations.

x[i]

Subset the results while preserving attached attributes.

See Also

ResIN_boots_prepare, ResIN_boots_execute, ResIN_boots_extract, ResIN_boots_prepped

Extract and summarize the results of a bootstrap simulation undertaken on a ResIN object

Description

Extract bootstrap draws from "ResIN_boots_executed" results. Failed iterations (stored as NULL) are skipped automatically.

Usage

ResIN_boots_extract(
  ResIN_boots_executed,
  what,
  summarize_results = FALSE,
  allow_missing = FALSE
)

Arguments

Value

If the extracted quantity is scalar per iteration, returns an object of class "ResIN_boots_draws" (a numeric vector with attributes). If summarize_results = TRUE, returns a one-row data.frame of summary statistics.

Examples

## Load the 12-item simulated Likert-type toy dataset
data(lik_data)

# Apply the ResIN function to toy Likert data:
ResIN_obj <- ResIN(lik_data, network_stats = TRUE,
                      generate_ggplot = FALSE, plot_ggplot = FALSE)


# Prepare for bootstrapping
prepped_boots <- ResIN_boots_prepare(ResIN_obj, n=100, boots_type="resample")

# Execute the prepared bootstrap list
executed_boots <-  ResIN_boots_execute(prepped_boots, parallel = TRUE, detect_cores = TRUE)

# Extract results - here for example, the network (global)-clustering coefficient
ResIN_boots_extract(executed_boots, what = "global_clustering", summarize_results = TRUE)

Create a bootstrap plan for re-estimating ResIN objects to derive statistical uncertainty estimates

Description

Provides instructions for how to bootstrap a ResIN network to derive uncertainty estimates around core quantities of interest. Requires output of ResIN function.

Usage

ResIN_boots_prepare(
  ResIN_object,
  n = 10000,
  boots_type = "resample",
  resample_size = NULL,
  weights = NULL,
  save_input = FALSE,
  seed_boots = 42
)

Arguments

Value

An object of class "ResIN_boots_prepped" containing a bootstrap plan (specification) used by ResIN_boots_execute. Use print(), summary(), length(), and [ to inspect or subset the plan. See ResIN_boots_prepped for details.

Examples

## Load the 12-item simulated Likert-type toy dataset
data(lik_data)

# Apply the ResIN function to toy Likert data:
ResIN_obj <- ResIN(lik_data, network_stats = TRUE,
                      generate_ggplot = FALSE, plot_ggplot = FALSE)


# Prepare for bootstrapping
prepped_boots <- ResIN_boots_prepare(ResIN_obj, n=100, boots_type="resample")

# Execute the prepared bootstrap list
executed_boots <-  ResIN_boots_execute(prepped_boots, parallel = TRUE, detect_cores = TRUE)

# Extract results - here for example, the network (global)-clustering coefficient
ResIN_boots_extract(executed_boots, what = "global_clustering", summarize_results = TRUE)

Prepared bootstrap plan

Description

The "ResIN_boots_prepped" object is created by ResIN_boots_prepare and provides a reproducible specification for running a bootstrap with ResIN_boots_execute.

Details

A "ResIN_boots_prepped" object is a list with (at least) the following elements:

call

The matched call used to create the plan.

boots_type

Character; "resample" or "permute".

n

Integer; number of bootstrap iterations.

resample_size

Integer; sample size used when resampling rows.

weights

Optional numeric vector of sampling weights (or NULL).

save_input

Logical; whether to store bootstrap inputs during execution.

seed_boots

Integer; seed used to generate per-iteration seeds.

iter_seeds

Integer vector; per-iteration RNG seeds (useful for parallel execution).

arglist

A list of arguments passed to ResIN for each re-fit (typically based on the original ResIN call, with plotting disabled).

df_id

Character; MD5 hash identifying the raw data used to create the plan.

ResIN_version

Character; ResIN package version used to create the plan.

Methods

print(x)

Print a compact summary of the bootstrap plan.

summary(object)

Return a structured summary of the plan.

length(x)

Return the number of iterations n.

x[i]

Subset the plan to selected iteration indices (also updates n).

See Also

ResIN_boots_prepare, ResIN_boots_execute, ResIN_boots_extract

(Deprecated.) Convert ResIN networks to Gephi-readable csv tables. Use as.gephi() method instead.

Description

Deprecated/legacy function. Saves a ResIN graph as a series of csv files readable by Gephi. Now supplanted by as.gephi() method.

Usage

ResIN_to_gephi(
  ResIN_object,
  file = "ResIN_gephi.csv",
  edges_only = TRUE,
  dont_save_csv = FALSE
)

Arguments

Value

A series of csv files readable by Gephi

References

Source code of original function (< version 2.2.0) had been adapted from: https://github.com/RMHogervorst/gephi?tab=MIT-1-ov-file#readme

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Estimate a ResIN network
res <- ResIN(lik_data, generate_ggplot = FALSE)

## Create Gephi edge table without writing files
edges <- as.gephi(res, dont_save_csv = TRUE)
head(edges)

## Not run: 
## Write CSV file(s) for import to Gephi
## (writes "ResIN_gephi.csv" by default)
as.gephi(res, file = "ResIN_gephi.csv")

## Write both edges and nodes tables
## (writes "ResIN_gephi_edges.csv" and "ResIN_gephi_nodes.csv")
as.gephi(res, file = "ResIN_gephi.csv", edges_only = FALSE)

## End(Not run)

(Deprecated.) Convert a ResIN network into an igraph object. Use as.igraph() method instead.

Description

Deprecated/legacy function. Transforms the output of the ResIN function into an [igraph](https://igraph.org/r/doc/cluster_leading_eigen.html) object. Now simply a wrapper for the as.igraph() method.

Usage

ResIN_to_igraph(ResIN_object, igraph_arglist = NULL)

Arguments

Value

A class igraph object.

References

Csardi G, Nepusz T (2006). “The igraph software package for complex network research.” InterJournal, Complex Systems, 1695. https://igraph.org.

See Also

as.igraph as the recommended interface.

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Run the function:

igraph_output <-  as.igraph(ResIN(lik_data, plot_ggplot = FALSE))

class(igraph_output)

## Plot and/or investigate as you wish:

igraph::plot.igraph(igraph_output)

(Deprecated.) Convert a ResIN network into an qgraph object. Use as.qgraph() method instead.

Description

Deprecated/legacy function. Transforms the output of the ResIN function into an qgraph object. Use as.qgraph() method instead.

Usage

ResIN_to_qgraph(ResIN_object, qgraph_arglist = NULL)

Arguments

Value

A [qgraph]https://cran.r-project.org/web/packages/qgraph/index.html graph object.

References

Epskamp S, Cramer AOJ, Waldorp LJ, Schmittmann VD, Borsboom D (2012). “qgraph: Network Visualizations of Relationships in Psychometric Data.” Journal of Statistical Software, 48(4), 1–18.

See Also

as.qgraph as the recommended interface.

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Run the function:
ResIN_qgraph <-  as.qgraph(ResIN(lik_data, plot_ggplot = FALSE))

class(ResIN_qgraph)

Coerce a ResIN object to Gephi CSV table(s)

Description

Produces Gephi-readable edge (and optionally node) tables from a ResIN object and (by default) writes them to CSV. Set dont_save_csv = TRUE to return tables without writing files.

Usage

## S3 method for class 'ResIN'
as.gephi(
  x,
  file = "ResIN_gephi.csv",
  edges_only = TRUE,
  dont_save_csv = FALSE,
  weight_col = "weight",
  ...
)

Arguments

Value

If edges_only = TRUE, an edge table data.frame. Otherwise a list with edges and nodes. “When dont_save_csv = FALSE, the return value is returned invisibly.”

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Estimate a ResIN network
res <- ResIN(lik_data, plot_ggplot = FALSE)

## Create Gephi edge table without writing files
edges <- as.gephi(res, dont_save_csv = TRUE)
head(edges)

## Not run: 
## Write CSV file(s) for import to Gephi
## (writes "ResIN_gephi.csv" by default)
as.gephi(res, file = "ResIN_gephi.csv")

## Write both edges and nodes tables
## (writes "ResIN_gephi_edges.csv" and "ResIN_gephi_nodes.csv")
as.gephi(res, file = "ResIN_gephi.csv", edges_only = FALSE)

## End(Not run)

Julia Graphs.jl coercion helpers

Description

Generic for exporting objects to a lightweight Graphs.jl-ready representation. For ResIN objects, this creates edge and node CSV tables suitable for loading with CSV.jl/DataFrames.jl, with integer vertex IDs for direct use in Graphs.jl.

Usage

as.graphsjl(x, ...)

Arguments

Export a ResIN object to Graphs.jl (Julia) tables

Description

Produces Graphs.jl-style edge (and optionally node) tables from a ResIN object. Edge endpoints are mapped to integer vertex IDs (src, dst) to align with Graphs.jl in Julia. Node and edge metadata are preserved as table columns. The node table stores the vertex mapping and additional ResIN metadata.

Usage

## S3 method for class 'ResIN'
as.graphsjl(
  x,
  file = "ResIN_graphsjl.csv",
  edges_only = TRUE,
  dont_save_csv = FALSE,
  weight_col = "weight",
  ...
)

Arguments

Value

If edges_only = TRUE, an edge table data.frame. Otherwise a list with elements edges and nodes. The node table includes integer vertex_id values and preserved node metadata.

Examples

## Not run: 
data(lik_data)
res <- ResIN(lik_data, generate_ggplot = FALSE, plot_ggplot = FALSE)

# Return tables only (no files written)
jl_tbls <- as.graphsjl(res, dont_save_csv = TRUE, edges_only = FALSE)

# Default behavior writes CSV files
# as.graphsjl(res, file = "ResIN_graphsjl.csv", edges_only = FALSE)

## End(Not run)

Coerce a ResIN object to an igraph graph

Description

Converts a ResIN object to an igraph graph using the adjacency matrix stored in x$aux_objects$adj_matrix.

Usage

## S3 method for class 'ResIN'
as.igraph(x, mode = "undirected", weighted = TRUE, diag = FALSE, ...)

Arguments

Value

An igraph object.

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Run the function:

igraph_output <-  as.igraph(ResIN(lik_data, plot_ggplot = FALSE))

class(igraph_output)

## Plot and/or investigate as you wish:

igraph::plot.igraph(igraph_output)

Convert a ResIN object to a statnet/network object

Description

Coerces a ResIN object to a network object (from the network package used in the statnet ecosystem). The method preserves edge-level columns from x$ResIN_edgelist as edge attributes and node-level columns from x$ResIN_nodeframe as vertex attributes whenever available.

Usage

## S3 method for class 'ResIN'
as.network(x, directed = FALSE, loops = FALSE, multiple = FALSE, ...)

Arguments

Value

An object of class network.

Examples

data(lik_data)
res <- ResIN(lik_data, generate_ggplot = FALSE, plot_ggplot = FALSE)

# ResIN re-exports network::as.network()
net <- as.network.ResIN(res) ## alternatively: as.network(res)
class(net)

Python NetworkX coercion helpers

Description

Generic for exporting objects to a lightweight NetworkX-ready representation. For ResIN objects, this creates edge and node CSV tables that can be read via pandas and converted to a networkx graph.

Usage

as.networkx(x, ...)

Arguments

Export a ResIN object to NetworkX (Python) tables

Description

Produces NetworkX-ready edge (and optionally node) tables from a ResIN object for further manipulation in Python. By default, this method writes CSV files that can be imported into Python via pandas and networkx. Node and edge metadata are preserved as table columns.

Usage

## S3 method for class 'ResIN'
as.networkx(
  x,
  file = "ResIN_networkx.csv",
  edges_only = TRUE,
  dont_save_csv = FALSE,
  weight_col = "weight",
  ...
)

Arguments

Value

If edges_only = TRUE, an edge table data.frame. Otherwise a list with elements edges and nodes.

Examples

## Not run: 
data(lik_data)
res <- ResIN(lik_data, generate_ggplot = FALSE, plot_ggplot = FALSE)

# Return tables only (no files written)
nx_tbls <- as.networkx(res, dont_save_csv = TRUE, edges_only = FALSE)

# Default behavior writes CSV files
# as.networkx(res, file = "ResIN_networkx.csv", edges_only = FALSE)

## End(Not run)

Coerce a ResIN object to a qgraph object

Description

Converts a ResIN object to a qgraph object using the adjacency matrix stored in x$aux_objects$adj_matrix.

Usage

## S3 method for class 'ResIN'
as.qgraph(
  x,
  layout = "spring",
  maximum = 1,
  vsize = 6,
  DoNotPlot = TRUE,
  sampleSize = NULL,
  title = "ResIN graph in qgraph",
  mar = c(3, 8, 3, 8),
  normalize = FALSE,
  ...
)

Arguments

Value

A qgraph object.

Examples

## Load the 12-item simulated Likert-type ResIN toy dataset
data(lik_data)

## Run the function:
ResIN_qgraph <-  as.qgraph(ResIN(lik_data, plot_ggplot = FALSE))

class(ResIN_qgraph)

Coerce a ResIN object to a tidygraph graph

Description

Converts a ResIN object to a tidygraph::tbl_graph object while preserving as much node- and edge-level information as possible from x$ResIN_nodeframe and x$ResIN_edgelist.

Because tidygraph stores edge endpoints as integer node indices, the original edge endpoint labels are preserved in additional edge columns from_name and to_name.

If ResIN_nodeframe or ResIN_edgelist are unavailable, the method falls back to a simpler conversion via as.igraph() followed by tidygraph::as_tbl_graph(), which may not preserve all metadata.

Usage

## S3 method for class 'ResIN'
as.tidygraph(x, directed = FALSE, ...)

Arguments

Value

A tidygraph::tbl_graph object. Node data include (when present) all columns from x$ResIN_nodeframe; edge data include (when present) all columns from x$ResIN_edgelist, plus from_name/to_name preserving original endpoint labels.

Examples

## Load toy data and estimate ResIN
data(lik_data)
res <- ResIN(lik_data, network_stats = TRUE, detect_clusters = TRUE,
             plot_ggplot = FALSE)

## Convert to tidygraph
tg <- as.tidygraph(res)

class(tg)

Likert-type, mock-response data for "ResIN" package examples

Description

An artificially created data-set (n=1000) of 12, 5-point Likert data. Modeled on the basis of a standard normal data-generating process. Likert scales contain 20 percent uncorrelated, homoscedastic measurement error. This data-set is used for the examples in the "ResIN" package vignette.

Usage

data(lik_data)

Format

An object of class "data.frame"

References

This data set was artificially created for the ResIN package.

Examples

data(lik_data)
head(lik_data)

Plot a ResIN object

Description

Plot a ResIN object

Usage

## S3 method for class 'ResIN'
plot(x, which = c("network", "bipartite"), print_plot = TRUE, ...)

Arguments

Value

The plot object (invisibly if print_plot = TRUE).

Print a ResIN object

Description

Print a ResIN object

Usage

## S3 method for class 'ResIN'
print(x, ...)

Arguments

Summarize a ResIN object

Description

Summarize a ResIN object

Usage

## S3 method for class 'ResIN'
summary(object, ...)

Arguments

Value

An object of class summary.ResIN.