cograph: Complex Network Analysis and Visualization

cograph is our latest methodological work that aims to offer a powerful toolset for network analysis. The package provides tools for the analysis, visualization, and manipulation of dynamical, social, and complex networks. It supports multiple network formats and offers flexible tools for heterogeneous, multi-layer, and hierarchical network analysis — with simple syntax and an extensive toolset. Hand it a matrix, a tna object, an igraph graph, or a data frame, and get a publication-quality plot in one line. Override what you want; the defaults handle the rest. For a comprehensive overview of all functions and parameters, see the full cograph reference and the plotting reference.

1. Universal Network Import

No format conversion needed. Pass a matrix, edge list, igraph object, statnet network, qgraph object, or tna model to any cograph function and it just works. Directionality is auto-detected from matrix symmetry or the source object — override with directed = TRUE/FALSE when needed. Conversion utilities like to_igraph(), to_matrix(), to_network(), to_data_frame(), and as_tna() let you move freely between all six formats. Import from any source, analyze in cograph, export back to whatever your downstream pipeline expects.

2. Fully Compatible with tna

cograph is built to work seamlessly with the tna package. Pass any tna object directly to splot() and get a publication-ready network plot — no conversion, no extra arguments. The same applies to group models: splot(group_model) plots all groups in a grid, or use splot(group_model, i = "Treatment") to plot a single group. Bootstrap results from tna::bootstrap() render with solid edges for significant transitions and dashed edges for non-significant ones. Permutation test results from tna::permutation_test() are plotted with color-coded edges showing which group has stronger transitions. plot_compare() produces difference networks between groups. Every tna object type — tna, group_tna, tna_bootstrap, tna_permutation, group_tna_permutation — is recognized and plotted with appropriate defaults.

library(tna)
model <- tna(group_regulation)

# Plot a tna model directly
splot(model)

# Plot bootstrap results
splot(bootstrap(model, iter = 1000))

3. Pipe-Friendly Network Utilities

The entire workflow chains with R’s native pipe. Getters like get_nodes(), get_edges(), get_layout(), and get_groups() extract network structure. Setters like set_nodes(), set_groups(), and the sn_* family — sn_nodes(), sn_edges(), sn_layout(), sn_theme(), sn_palette() — modify it. Every function returns the network object, so you build incrementally: set layout, style nodes, adjust edges, pick a palette, render. No intermediate variables, no juggling objects between packages.

4. Filter and Select

cograph makes subsetting networks as intuitive as subsetting a data frame:

# Filter: keep only edges with weight above 0.3
filter_edges(net, weight > 0.3)

# Select: keep the top 5 nodes by PageRank
select_nodes(net, top = 5, by = "pagerank")

Every function returns a cograph object, so filtering, selecting, and plotting chain together seamlessly. You think in terms of what you want to keep, and the syntax follows.

5. Centrality and Network Properties

One call to centrality(x) computes 25 measures and returns a tidy data frame. Or use individual functions like centrality_degree(x), centrality_betweenness(x), or centrality_pagerank(x) for a named vector. Each function has its own focused help page — no digging through irrelevant parameters. The full list covers degree, strength, closeness, harmonic, betweenness, eigenvector, hub, authority, PageRank, eccentricity, coreness, constraint, laplacian, leverage, power, percolation, subgraph, diffusion, voterank, k-reach, transitivity, and current flow variants. Network-level properties — density, diameter, efficiency, small-world coefficient, rich-club coefficient, bridge detection — are equally accessible through network_summary() and individual functions.

6. Community Detection

Eleven algorithms through a single interface: Louvain, Leiden, Infomap, walktrap, fast greedy, label propagation, edge betweenness, leading eigenvector, spinglass, optimal, and fluid communities — plus consensus clustering for robustness. Each returns a community object with membership vector, modularity score, and a built-in plot() method. Compare partitions with VI, NMI, Rand, or adjusted Rand. Assess quality with modularity, silhouette, and Dunn index. Test significance with permutation-based p-values.

7. Rich Plotting

splot(mat) — that is it. One function, any format, publication-ready output. Customize with 80+ parameters for nodes, edges, labels, donuts, pies, and more. soplot() provides the same interface via grid/ggplot2 for layered composition. The range of what cograph draws and how little you need to ask for is what makes it stand out.

Node Shapes, Pies, and Donuts

Ten node shapes are available out of the box: circle, square, triangle, diamond, pentagon, hexagon, ellipse, heart, star, and cross. Beyond shapes, nodes can carry data. Pie charts encode category compositions inside the node. Donut rings show proportions around it. You can stack up to three data layers — outer donut, inner donut, and pie core — to encode multiple variables per node, which is particularly useful for representing multidimensional data at a glance.

Visualizing Statistical Data on Networks

Network plots often live in one world and statistical results in another — tables of coefficients, separate forest plots, lists of p-values. cograph brings them together. Confidence intervals render as semi-transparent bands along the edges. P-values map to significance stars directly on the edge labels. The edge label template system lets you compose estimates, CI bounds, and stars in any combination, so regression coefficients, bootstrap intervals, or effect sizes sit on the network itself rather than in a separate table.

Bootstrap analysis results can be plotted directly: edges that survive resampling appear solid, those that do not appear dashed, with significance stars on the labels. Permutation tests between groups receive the same visual treatment — color-coded by which group shows a stronger edge, with non-significant edges suppressed. The package also supports side-by-side group comparison plots, difference networks, and network overlay views, giving you multiple ways to present the same statistical story depending on the audience and the question.

Heatmaps, Chord Diagrams, and Flow Plots

When the node-and-edge view gets too dense, cograph offers alternative representations. plot_heatmap() renders the adjacency or transition matrix as a color-coded grid with optional value overlays. plot_chord() draws circular flow diagrams that emphasize the volume and direction of transitions between states. plot_alluvial() traces how states flow across time points in aggregate, while plot_trajectories() draws each individual as a separate line — useful for seeing whether a group trend actually reflects individual paths or masks divergent behavior. All of these are rendered in base R with no JavaScript dependencies.

Multi-Cluster Networks for Multidimensional Analysis

Networks often have internal structure — nodes that group into clusters representing different dimensions, levels, or categories. plot_mcml() facilitates multidimensional network analysis by showing both levels simultaneously: individual nodes arranged inside colored cluster shells on the detail layer, with cluster-level aggregate transitions on the summary layer above. This makes it possible to see micro-level connections and macro-level patterns at the same time, which is essential when studying systems where behavior operates across multiple dimensions such as social, emotional, cognitive, and regulatory processes.

Multilayer and Heterogeneous Networks

When your network has natural layers — different interaction types, time periods, or modalities — plot_mlna() stacks them in a 3D perspective view with cross-layer connections visible. When you have multiple node types, such as students and teachers or proteins and genes, plot_htna() arranges them in grouped layouts that respect the categorical structure.

Mixed Networks

Some networks combine symmetric and asymmetric relationships — co-occurrence alongside directed influence, or undirected social ties alongside directed information flow. plot_mixed_network() renders both in one plot with distinct visual styles, so the nature of each relationship is immediately clear.

Getting Started

install.packages("cograph")
# or
remotes::install_github("sonsoleslp/cograph")

cograph provides a unified environment for network analysis and visualization — from importing and converting network data, through computing centrality and detecting communities, to producing publication-ready plots that carry statistical annotations. The goal is simple: write one line, get a result you can put in a paper. For a full reference of all functions, parameters, and examples, read the cograph introduction.

cograph is primarily conceptualized and developed by Mohammed Saqr, Professor of Computer Science at the University of Eastern Finland, and co-developed by Sonsoles López-Pernas, Academy Fellow at the University of Eastern Finland.