FeaturedGraph

Construct a FeaturedGraph and graph representations

A FeaturedGraph is aimed to represent a composition of graph representation and graph signals. A graph representation is required to construct a FeaturedGraph object. Graph representation can be accepted in several forms: adjacency matrix, adjacency list or graph representation provided from JuliaGraphs.

julia> adj = [0 1 1;
              1 0 1;
              1 1 0]
3×3 Matrix{Int64}:
 0  1  1
 1  0  1
 1  1  0

julia> FeaturedGraph(adj)
FeaturedGraph(
	Undirected graph with (#V=3, #E=3) in adjacency matrix,
)

Currently, SimpleGraph and SimpleDiGraph from LightGraphs.jl, SimpleWeightedGraph and SimpleWeightedDiGraph from SimpleWeightedGraphs.jl, as well as MetaGraph and MetaDiGraph from MetaGraphs.jl are supported.

If a graph representation is not given, a FeaturedGraph object will be regarded as a NullGraph. A NullGraph object is just used as a special case of FeaturedGraph to represent a null object.

julia> FeaturedGraph()
NullGraph()

FeaturedGraph constructors

Missing docstring.

Missing docstring for NullGraph(). Check Documenter's build log for details.

GraphSignals.FeaturedGraph — Type
FeaturedGraph(g, [mt]; directed=:auto, nf, ef, gf, pf=nothing,
    T, N, E, with_batch=false)

A type representing a graph structure and storing also arrays that contain features associated to nodes, edges, and the whole graph.

A FeaturedGraph can be constructed out of different objects g representing the connections inside the graph. When constructed from another featured graph fg, the internal graph representation is preserved and shared.

Arguments

  • g: Data representing the graph topology. Possible type are
    • An adjacency matrix.
    • An adjacency list.
    • A Graphs' graph, i.e. SimpleGraph, SimpleDiGraph from Graphs, or SimpleWeightedGraph, SimpleWeightedDiGraph from SimpleWeightedGraphs.
    • An AbstractFeaturedGraph object.
  • mt::Symbol: Matrix type for g in matrix form. if graph is in matrix form, mt is recorded as one of :adjm, :normedadjm, :laplacian, :normalized or :scaled.
  • directed: It specify that direction of a graph. It can be :auto, :directed and :undirected. Default value is :auto, which infers direction automatically.
  • nf: Node features.
  • ef: Edge features.
  • gf: Global features.
  • pf: Positional features. If nothing is given, positional encoding is turned off. If an array is given, positional encoding is assigned as given array. If :auto is given, positional encoding is generated automatically for node features and with_batch is considered.
  • T: It specifies the element type of graph. Default value is the element type of g.
  • N: Number of nodes for g.
  • E: Number of edges for g.
  • with_batch::Bool: Consider last dimension of all features as batch dimension.

Usage

using GraphSignals, CUDA

# Construct from adjacency list representation
g = [[2,3], [1,4,5], [1], [2,5], [2,4]]
fg = FeaturedGraph(g)

# Number of nodes and edges
nv(fg)  # 5
ne(fg)  # 10

# From a Graphs' graph
fg = FeaturedGraph(erdos_renyi(100, 20))

# Copy featured graph while also adding node features
fg = FeaturedGraph(fg, nf=rand(100, 5))

# Send to gpu
fg = fg |> cu

See also graph, node_feature, edge_feature, and global_feature.

Graph Signals

Graph signals is a collection of any signals defined on a graph. Graph signals can be the signals related to vertex, edges or graph itself. If a vertex signal is given, it is recorded as a node feature in FeaturedGraph. A node feature is stored as the form of generic array, of which type is AbstractArray. A node feature can be indexed by the node index, which is the same index for given graph.

Node features can be optionally given in construction of a FeaturedGraph.

julia> fg = FeaturedGraph(adj, nf=rand(5, 3))
FeaturedGraph(
	Undirected graph with (#V=3, #E=3) in adjacency matrix,
	Node feature:	ℝ^5 <Matrix{Float64}>,
)

julia> has_node_feature(fg)
true

julia> node_feature(fg)
5×3 Matrix{Float64}:
 0.534928  0.719566  0.952673
 0.395465  0.268515  0.335446
 0.79428   0.18623   0.454377
 0.530675  0.402474  0.00920068
 0.642556  0.719674  0.772497

Users check node/edge/graph features are available by has_node_feature, has_edge_feature and has_global_feature, respectively, and fetch these features by node_feature, edge_feature and global_feature.

Getter methods

GraphSignals.graph — Function
graph(fg)

Get referenced graph in fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.node_feature — Function
node_feature(fg)

Get node feature attached to fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.edge_feature — Function
edge_feature(fg)

Get edge feature attached to fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.global_feature — Function
global_feature(fg)

Get global feature attached to fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.

Check methods

GraphSignals.has_graph — Function
has_graph(fg)

Check if graph is available or not for fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.has_node_feature — Function
has_node_feature(::AbstractFeaturedGraph)

Check if node_feature is available or not for fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.has_edge_feature — Function
has_edge_feature(::AbstractFeaturedGraph)

Check if edge_feature is available or not for fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.
GraphSignals.has_global_feature — Function
has_global_feature(::AbstractFeaturedGraph)

Check if global_feature is available or not for fg.

Arguments

  • fg::AbstractFeaturedGraph: A concrete object of AbstractFeaturedGraph type.

Graph properties

FeaturedGraph is itself a graph, so we can query some graph properties from a FeaturedGraph.

julia> nv(fg)
3

julia> ne(fg)
3

julia> is_directed(fg)
false

Users can query number of vertex and number of edge by nv and ne, respectively. is_directed checks if the underlying graph is a directed graph or not.

Missing docstring.

Missing docstring for nv. Check Documenter's build log for details.

Missing docstring.

Missing docstring for ne. Check Documenter's build log for details.

Missing docstring.

Missing docstring for is_directed. Check Documenter's build log for details.

Pass FeaturedGraph to CUDA

Passing a FeaturedGraph to CUDA is easy. Just pipe a FeaturedGraph object to gpu provided by Flux.

julia> using Flux

julia> fg = fg |> gpu
FeaturedGraph(
	Undirected graph with (#V=3, #E=3) in adjacency matrix,
	Node feature:	ℝ^5 <CuArray{Float32, 2, CUDA.Mem.DeviceBuffer}>,
)

Linear algebra for FeaturedGraph

FeaturedGraph supports the calculation of graph Laplacian matrix in inplace manner.

julia> fg = FeaturedGraph(adj, nf=rand(5, 3))
FeaturedGraph(
	Undirected graph with (#V=3, #E=3) in adjacency matrix,
	Node feature:	ℝ^5 <Matrix{Float64}>,
)

julia> laplacian_matrix!(fg)
FeaturedGraph(
	Undirected graph with (#V=3, #E=3) in Laplacian matrix,
	Node feature:	ℝ^5 <Matrix{Float64}>,
)

julia> laplacian_matrix(fg)
3×3 SparseArrays.SparseMatrixCSC{Int64, Int64} with 9 stored entries:
 -2   1   1
  1  -2   1
  1   1  -2

laplacian_matrix! mutates the adjacency matrix into a Laplacian matrix in a FeaturedGraph object and the Laplacian matrix can be fetched by laplacian_matrix. The Laplacian matrix is cached in a FeaturedGraph object and can be passed to a graph neural network model for training or inference. This way reduces the calculation overhead for Laplacian matrix during the training process.

FeaturedGraph supports not only Laplacian matrix, but also normalized Laplacian matrix and scaled Laplacian matrix calculation.

Inplaced linear algebraic APIs

Missing docstring.

Missing docstring for laplacian_matrix!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for normalized_laplacian!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for scaled_laplacian!. Check Documenter's build log for details.

Linear algebraic APIs

Non-inplaced APIs returns a vector or a matrix directly.

Missing docstring.

Missing docstring for adjacency_matrix. Check Documenter's build log for details.

Missing docstring.

Missing docstring for degrees. Check Documenter's build log for details.

Missing docstring.

Missing docstring for degree_matrix. Check Documenter's build log for details.

Graphs.LinAlg.laplacian_matrix — Function
laplacian_matrix(g, [T]; dir=:out)

Laplacian matrix of graph g.

Arguments

  • g: should be a adjacency matrix, FeaturedGraph, SimpleGraph, SimpleDiGraph (from Graphs) or SimpleWeightedGraph, SimpleWeightedDiGraph (from SimpleWeightedGraphs).
  • T: result element type of degree vector; default is the element type of g (optional).
  • dir: direction of degree; should be :in, :out, or :both (optional).
GraphSignals.normalized_laplacian — Function
normalized_laplacian(g, [T]; dir=:both, selfloop=false)

Normalized Laplacian matrix of graph g.

Arguments

  • g: should be a adjacency matrix, FeaturedGraph, SimpleGraph, SimpleDiGraph (from Graphs) or SimpleWeightedGraph, SimpleWeightedDiGraph (from SimpleWeightedGraphs).
  • T: result element type of degree vector; default is the element type of g (optional).
  • selfloop: adding self loop while calculating the matrix (optional).
  • dir: direction of graph; should be :in or :out (optional).
GraphSignals.scaled_laplacian — Function
scaled_laplacian(g, [T])

Scaled Laplacien matrix of graph g, defined as $\hat{L} = \frac{2}{\lambda_{max}} L - I$ where $L$ is the normalized Laplacian matrix.

Arguments

  • g: should be a adjacency matrix, FeaturedGraph, SimpleGraph, SimpleDiGraph (from Graphs) or SimpleWeightedGraph, SimpleWeightedDiGraph (from SimpleWeightedGraphs).
  • T: result element type of degree vector; default is the element type of g (optional).