---
title: "Introduction to BrainNetTest"
author: "Maximiliano Martino, Daniel Fraiman"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to BrainNetTest}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`BrainNetTest` implements the non-parametric L1-distance ANOVA test of Fraiman
and Fraiman (2018) for comparing populations of brain networks represented as
graphs. The package provides:

* utilities to build a central (mean) graph for a population and measure
  Manhattan (L1) distances between adjacency matrices;
* the group test statistic `T` and its permutation test (`global_test`);
* a fast procedure (`identify_critical_links`) that pinpoints the edges
  driving between-group differences; and
* helpers to simulate synthetic community-structured graphs and to visualise
  networks.

This vignette introduces the basic API on simple synthetic data. The companion
vignette, *Generating and Analyzing Brain Networks with Community Structures*,
shows the full pipeline on community-structured populations.

## Installation

```r
# Release version
install.packages("BrainNetTest")

# Development version from GitHub
# install.packages("remotes")
remotes::install_github("mmaximiliano/BrainNetTest")
```

## A minimal example

```{r}
library(BrainNetTest)
set.seed(1)
```

### Generating random graphs

`generate_random_graph()` returns a symmetric binary adjacency matrix with no
self-loops:

```{r}
G <- generate_random_graph(n_nodes = 10, edge_prob = 0.2)
isSymmetric(G)
all(diag(G) == 0)
```

### Central graph and Manhattan distance

Given a population (list of adjacency matrices), the *central graph* is the
entry-wise mean; `compute_distance()` returns the L1 (Manhattan) distance
between two graphs:

```{r}
population <- replicate(
  5, generate_random_graph(n_nodes = 10, edge_prob = 0.2),
  simplify = FALSE)

central <- compute_central_graph(population)
compute_distance(population[[1]], central)
```

### The group test statistic `T`

`compute_test_statistic()` aggregates within- and between-group Manhattan
distances into the statistic `T`. Larger values indicate stronger evidence
that the groups differ:

```{r}
control <- replicate(
  15, generate_random_graph(n_nodes = 10, edge_prob = 0.20),
  simplify = FALSE)
patient <- replicate(
  15, generate_random_graph(n_nodes = 10, edge_prob = 0.40),
  simplify = FALSE)

populations <- list(Control = control, Patient = patient)
compute_test_statistic(populations, a = 1)
```

### The global test

`compute_test_statistic()` returns only the observed value. `global_test()`
assesses it: it permutes the group labels across the pooled sample, keeping
the group sizes, recomputes `T` for each permutation, and reports the
proportion of permutations with a statistic smaller than the observed one as
the p-value. The normalisation constant `a` is fixed at 1; the p-value does
not depend on it.

```{r}
gt <- global_test(populations, n_permutations = 500, seed = 42)
gt
```

The permutation null distribution is kept in `gt$null_distribution`, so it
can be inspected or plotted. With `B` permutations the p-value cannot resolve
below `1 / B`, which is how an estimate of zero is reported.

### Critical edges

Once a difference is established, `identify_critical_links()` looks for the
edges responsible. It runs the same global test first and then iteratively
removes edges, ranked by their marginal p-values, until the populations are no
longer distinguishable:

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

result
```

The result is a `critical_links` object. Printing it, as above, gives a
compact report; `summary()` adds the settings the analysis ran with and the
node-level ranking:

```{r}
summary(result)
```

The individual components remain available, `result$critical_edges` being the
ranked table of critical edges. The `get_critical_nodes()` helper summarises
the result at the node level on its own:

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

## 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-23152-5>