---
title: "Generating and Analyzing Brain Networks with Community Structures"
author: "Maximiliano Martino, Daniel Fraiman"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Generating and Analyzing Brain Networks with Community Structures}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>"
)
```

## Overview

This vignette shows the full `BrainNetTest` workflow on synthetic populations
of brain networks with community (block) structure. We simulate two groups of
graphs with different intra- and inter-community connection probabilities,
run the global L1-distance ANOVA test, and identify the edges and nodes that
drive the observed difference.

```{r}
library(BrainNetTest)
```

## Generating a single community-structured graph

`generate_community_graph()` samples a symmetric binary adjacency matrix with
a block-stochastic structure: edges within a community are drawn with
probability `intra_prob`, edges between communities with `inter_prob`.

```{r}
set.seed(42)
G <- generate_community_graph(
  n_nodes       = 40,
  n_communities = 4,
  intra_prob    = 0.8,
  inter_prob    = 0.2)

dim(G)
mean(G[upper.tri(G)])
```

### Visualising the network

A single community-structured adjacency matrix is best inspected directly
with `igraph`. The package's own visualisation helper,
`plot_critical_edges()`, is designed to summarise the *result* of an analysis
(per-population central graphs plus the identified critical edges) and is
illustrated at the end of this vignette.

## Simulating populations of graphs

`generate_category_graphs()` produces a list of graphs that share a common
community structure but vary slightly in their edge probabilities across
replicates, modelling natural between-subject variability.

```{r}
control <- generate_category_graphs(
  n_graphs             = 20,
  n_nodes              = 20,
  n_communities        = 2,
  base_intra_prob      = 0.8,
  base_inter_prob      = 0.2,
  intra_prob_variation = 0.05,
  inter_prob_variation = 0.05,
  seed                 = 1)

patient <- generate_category_graphs(
  n_graphs             = 20,
  n_nodes              = 20,
  n_communities        = 2,
  base_intra_prob      = 0.6,
  base_inter_prob      = 0.4,
  intra_prob_variation = 0.05,
  inter_prob_variation = 0.05,
  seed                 = 2)

populations <- list(Control = control, Patient = patient)
lengths(populations)
```

## Global test statistic

```{r}
T_obs <- compute_test_statistic(populations, a = 1)
T_obs
```

## Identifying critical edges

`identify_critical_links()` performs the full pipeline: marginal edge
p-values, permutation null for `T`, and iterative edge removal. It returns
the edges whose removal eliminates the group-level difference.

```{r}
result <- identify_critical_links(
  populations,
  alpha          = 0.05,
  method         = "fisher",
  n_permutations = 500,
  seed           = 42)

nrow(result$critical_edges)
head(result$critical_edges)
```

### Critical nodes

`get_critical_nodes()` aggregates the critical edges at the node level,
reporting the *critical degree* (number of critical edges incident on each
node):

```{r}
get_critical_nodes(result)
```

## Visualising the result

`plot_critical_edges()` produces a multi-panel figure that summarises the
analysis: one panel per population showing the (weighted) central graph,
plus a final panel that highlights the critical edges on the chosen
reference central graph. Communities can be passed in to color the vertices
consistently across panels.

```{r, eval = requireNamespace("igraph", quietly = TRUE), fig.width=7, fig.height=7}
plot_critical_edges(
  populations,
  result,
  communities = rep(seq_len(2), each = 10),
  reference   = "Control")
```

## References

Fraiman, D. and Fraiman, R. (2018) An ANOVA approach for statistical
comparisons of brain networks. *Scientific Reports*, 8, 4746.
<https://doi.org/10.1038/s41598-018-21688-0>