Package 'persistence'

Persistence

Description

Given a non-oriented graph, calculates the optimal vertex partition using persistence as the objective function.

Details

See manual entries.

Author(s)

Maintainer: Alessandro Avellone [email protected]

Authors:

• Alessandro Avellone [email protected]

• Paolo Bartesaghi [email protected]

• Stefano Benati [email protected]

• Rosanna Grassi [email protected]

---

cluster_milano

Description

Calculates the vertex partition with maximum global null-adjusted persistence. This function is polymorphic: it automatically detects the input type and accepts either a vertex vector (accompanied by an edge list) or directly an igraph object.

Usage

cluster_milano(x, ...)

## Default S3 method:
cluster_milano(
  x,
  edge_list,
  weights = NULL,
  membership = NULL,
  H0 = TRUE,
  seed = NULL,
  tol = NULL,
  max_level = 0L,
  ...
)

## S3 method for class 'igraph'
cluster_milano(
  x,
  membership = NULL,
  H0 = TRUE,
  seed = NULL,
  tol = NULL,
  max_level = 0L,
  ...
)

Arguments

x	An integer or character vector representing the graph vertices, OR an object of class igraph.
...	Additional arguments passed to specific methods (e.g., edge_list, weights, tol, max_level, etc.).
edge_list	Integer matrix with two columns representing the graph edge list.
weights	Numeric vector of positive edge weights. If NULL, all weights default to 1.
membership	Integer vector representing the starting partition: x_i = k if i in C_k. If NULL, each vertex starts in its own cluster.
H0	Logical value. Default is TRUE. If TRUE, returns the null-adjusted persistence. If FALSE, returns the persistence probability.
seed	Non-negative integer seed for the random number generator. If NULL, an internal default is used.
tol	Optional numeric tolerance for the stopping criterion. If NULL (default), an adaptive threshold is calculated dynamically in C++.
max_level	Optional integer representing the maximum number of aggregation levels. If 0 (default) or NULL, the algorithm runs until convergence.

Value

A list with three elements:

membership

The optimal vertex partition.

score

The measure value of the optimal partition.

seed

The seed used to generate random numbers.

Examples

library(persistence)

# --- EXAMPLE 1: Standard input (vectors and matrices) ---
edg <- c(1, 2, 1, 3, 1, 4, 2, 3, 3, 4, 4, 5, 5, 6, 5, 7, 6, 7)
edge_list <- matrix(edg, ncol = 2, byrow = TRUE)
vertex <- c(1, 2, 3, 4, 5, 6, 7)
cluster_milano(x = vertex, edge_list = edge_list)

# --- EXAMPLE 2: igraph input ---
if (requireNamespace("igraph", quietly = TRUE)) {
  g <- igraph::make_ring(10)
  cluster_milano(g)
}

---

global_persistence

Description

Given a partition of the graph vertices, calculates the global persistence as the sum of the local persistences of the individual clusters. Persistence can be either null-adjusted or probability-based. This function is polymorphic: it automatically detects the input type and accepts either a vertex vector (accompanied by an edge list) or directly an igraph object.

Usage

global_persistence(x, ...)

## Default S3 method:
global_persistence(x, edge_list, weights = NULL, membership, H0 = 0, ...)

## S3 method for class 'igraph'
global_persistence(x, membership, H0 = 0, ...)

Arguments

x	An integer or character vector representing the graph vertices, OR an object of class igraph.
...	Additional arguments passed to specific methods (e.g., edge_list, weights, membership, H0).
edge_list	Integer matrix with two columns representing the graph edge list.
weights	Numeric vector of edge weights. If NULL, all weights default to 1.
membership	Integer vector of vertex cluster assignments: x_i = k if i in C_k.
H0	Optional numeric value in $[0, 1]$, or NULL. Default is 0.

Value

A list with two elements:

score

The global persistence of the partition.

clusters_value

The local persistence of each cluster. A value of NaN indicates that cluster $C_k$ is empty in the input membership.

Examples

library(persistence)

# --- EXAMPLE 1: Standard input (vectors and matrices) ---
edg <- c(1, 2, 1, 3, 1, 4, 2, 3, 3, 4, 4, 5, 5, 6, 5, 7, 6, 7)
edge_list <- matrix(edg, ncol = 2, byrow = TRUE)
vertex <- c(1, 2, 3, 4, 5, 6, 7)
mem <- c(1, 1, 1, 1, 2, 2, 2)
global_persistence(x = vertex, edge_list = edge_list, membership = mem)

# --- EXAMPLE 2: igraph input ---
if (requireNamespace("igraph", quietly = TRUE)) {
  g <- igraph::make_ring(10)
  mem <- c(rep(1, 5), rep(2, 5))
  global_persistence(g, membership = mem)
}

---

local_persistence

Description

Given the incidence vector of a vertex subset, calculates either the persistence probability or the null-adjusted persistence of cluster C. This function is polymorphic: it automatically detects the input type and accepts either a vertex vector (accompanied by an edge list) or directly an igraph object.

Usage

local_persistence(x, ...)

## Default S3 method:
local_persistence(x, edge_list, weights = NULL, cluster, H0 = 0, ...)

## S3 method for class 'igraph'
local_persistence(x, cluster, H0 = 0, ...)

Arguments

x	An integer or character vector representing the graph vertices, OR an object of class igraph.
...	Additional arguments passed to specific methods (e.g., edge_list, weights, cluster, H0).
edge_list	Integer matrix with two columns representing the graph edge list.
weights	Numeric vector of edge weights. If NULL, all weights default to 1.
cluster	Binary incidence vector of the cluster: x_i = 1 if i in C, 0 otherwise.
H0	Optional numeric value in $[0, 1]$, or NULL. Default is 0.

Value

Numeric scalar: the persistence probability when H0 = NULL, the null-adjusted persistence when H0 = 0, or the null-adjusted persistence density when H0 is in $(0, 1]$.

Examples

library(persistence)

# --- EXAMPLE 1: Standard input (vectors and matrices) ---
edg <- c(1, 2, 1, 3, 1, 4, 2, 3, 3, 4, 4, 5, 5, 6, 5, 7, 6, 7)
edge_list <- matrix(edg, ncol = 2, byrow = TRUE)
vertex <- c(1, 2, 3, 4, 5, 6, 7)
cluster_bin <- c(1, 1, 1, 1, 0, 0, 0)
local_persistence(x = vertex, edge_list = edge_list, cluster = cluster_bin)

# --- EXAMPLE 2: igraph input ---
if (requireNamespace("igraph", quietly = TRUE)) {
  g <- igraph::make_ring(10)
  cluster_bin <- c(rep(1, 5), rep(0, 5))
  local_persistence(g, cluster = cluster_bin)
}

---