API Manual

DataGraphUnion

Data type that is a union of DataGraph and DataDiGraph; used for functions that apply to both data types

DataDiGraph{T, T1, T2, T3, M1, M2}

Object for building and storing directed graphs that contain numerical data on nodes and/or edges.

DataDiGraphs have the following attributes: g: Graphs.SimpleDiGraph Object nodes: Vector of node names; node names are of type Any edges: Vector of edges; edges are tuples of integers node_map: dictionary pointing node name to node number edge_map: dictionary pointing tuple (nodename1, nodename2) to (nodenumber1, nodenumber2) node_data: NodeData object with attributes and data edge_data: EdgeData object with attributes and data graph_data: GraphData object with attributes and data

DataDiGraph(adjacency_matrix::AbstractMatrix)

Constructor for building a DataDiGraph object from an adjacency matrix.

DataDiGraph{T, T1, T2, M1, M2}()
DataDiGraph()

Constructor for initializing and empty DataDiGraph object. Datatypes are as follows: T is the integer type for indexing, T1 and T2 are the data type in the node and edge data respectively, and M1 <: AbstractMatrix{T1} corresponds to the node data and M2 <: AbstractMatrix{T2} corresponds to the edge data.

When T, T1, T2, M1, and M2 are not defined, the defaults are Int, Float64, Float64, Matrix{Float64}, and Matrix{Float64} respectively.

DataGraph{T, T1, T2, T3, M1, M2}

Object for building and storing undirected graphs that contain numerical data on nodes and/or edges.

DataGraphs have the following attributes: g: Graphs.SimpleGraph Object nodes: Vector of node names; node names are of type Any edges: Vector of edges; edges are tuples of integers node_map: dictionary pointing node name to node number edge_map: dictionary pointing tuple (nodename1, nodename2) to (nodenumber1, nodenumber2) node_data: NodeData object with attributes and data edge_data: EdgeData object with attributes and data graph_data: GraphData object with attributes and data

DataGraph(adjacency_matrix::AbstractMatrix)

Constructor for building a DataGraph object from an adjacency matrix.

DataGraph(edge_list)

Constructor for building a DataGraph object from a list of edges, where the edge list is a vector of Tuple{Any, Any}.

DataGraph(nodes, edges; kwargs)

Constructor for building a DataGraph object from a list of nodes and edges. Key word arguments include ne, fadjlist, node_attributes, edge_attributes, node_map, edge_map, node_data, and edge_data.

DataGraph{T, T1, T2, T3, M1, M2}()
DataGraph()

Constructor for initializing and empty DataGraph object. Datatypes are as follows: T is the integer type for indexing, T1, T2, and T3 are the data type in the node, edge, and graph data respectively, and M1 <: AbstractMatrix{T1} corresponds to the node data and M2 <: AbstractMatrix{T2} corresponds to the edge data.

When T, T1, T2, T3, M1, and M2 are not defined, the defaults are Int, Float64, Float64, Float64, Matrix{Float64}, and Matrix{Float64} respectively.

EdgeData{T, T2, M2}

Object for building and storing data corresponding to the edges of a graph. Data is stored in a matrix, but columns of the matrix have attribute names stored in this struct

EdgeData have the following attributes: attributes: vector of strings with length equal to the number of columns of data. Each entry is the name of the attribute of that column of data attribute_map: dictionary with keys matching the entries of attributes. Maps the key to the corresponding column index data: Matrix with the number of rows corresponding to the number of edgess in the graph and with a column for each attribute in attributes

EdgeData(attributes = Vector{String}(),
    attribute_map = Dict{String, Int}(),
    data = Array{Float64}(undef, (0, 0))
)

Constructor for building EdgeData{T, T2, M2}

GraphData{T, T2, M2}

Object for building and storing data corresponding to a graph. Data is stored in a vector, but entries of the vector have attribute names stored in this struct

GraphData have the following attributes: attributes: vector of strings with length equal to the length of data. Each entry is the name of the attribute of that column of data attribute_map: dictionary with keys matching the entries of attributes. Maps the key to the corresponding vector index data: Vector with length equal to the number of attributes

GraphData(attributes = Vector{String}(),
    attribute_map = Dict{String, Int}(),
    data = Vector{Float64}(undef, 0)
)

Constructor for building GraphData{T, T3}

NodeData{T, T1, M1}

Object for building and storing data corresponding to the nodes of a graph. Data is stored in a matrix, but columns of the matrix have attribute names stored in this struct

NodeData have the following attributes: attributes: vector of strings with length equal to the number of columns of data. Each entry is the name of the attribute of that column of data attribute_map: dictionary with keys matching the entries of attributes. Maps the key to the corresponding column index data: Matrix with the number of rows corresponding to the number of nodes in the graph and with a column for each attribute in attributes

NodeData(attributes = Vector{String}(),
    attribute_map = Dict{String, Int}(),
    data = Array{Float64}(undef, (0, 0))
)

Constructor for building NodeData{T, T1, M1}

add_edge!(dg, node_1, node_2)
add_edge!(dg, (node1, node2))

Add an edge to the DataDiGraph, dg. If the nodes are not defined in the graph, they are added to the graph

add_edge!(dg, node_1, node_2)
add_edge!(dg, (node1, node2))

Add an edge to the DataGraph, dg. If the nodes are not defined in the graph, they are added to the graph

_build_matrix_graph!

Constructs the graph structure for the function matrix_to_graph

_get_bfs_dfs_list(dg::DataDiGraph, node, algorithm, dir)

Returns the list of nodes that are upstream or downstream of node in the DataDiGraph dg

add_edge_attribute!(datagraph, attribute, default_weight = 0.0)
add_edge_attribute!(datadigraph, attribute, default_weight = 0.0)

Add a column filled with default_weight to the edge_data matrix with the name attribute. If attribute already exists in the edge data, an error is thrown.

add_edge_data!(datadigraph, node_name1, node_name2, edge_weight, attribute_name)
add_edge_data!(datadigraph, edge, edge_weight, attribute_name)

Add a weight value for the edge between nodename1 and nodename2 in the DataDiGraph object. When using the second function, edge must be a tuple with two node names. User must pass an "attribute name" for the given weight. All other edges that do not have an edge_weight value defined for that attribute name default to a value of zero.

add_edge_data!(datagraph, node_name1, node_name2, edge_weight, attribute_name)
add_edge_data!(datagraph, edge, edge_weight, attribute_name)

Add a weight value for the edge between nodename1 and nodename2 in the DataGraph object. When using the second function, edge must be a tuple with two node names. User must pass an "attribute name" for the given weight. All other edges that do not have an edge_weight value defined for that attribute name default to a value of zero.

add_edge_dataset!(dg::D, weight_dict, attribute) where {D <: DataGraphUnion}

Add the data in weight_dict as edge data on dg under the name attribute. weight_dict must contain keys that correspond to the edges (as node names, not integers) in dg.edges.

add_edge_dataset!(dg::D, weight_list, attribute) where {D <: DataGraphUnion}

Add the entries of weight_list as edge data on dg under the name attribute. weight_list must be the same length as the number of edges in dg. Entries of weight_list will be added as edge data in the order that edges are listed in dg.edges.

add_edge_dataset!(dg::D, edge_list, weight_list, attribute) where {D <: DataGraphUnion}

Add the edge data in weight_list to dg. edge_list is a list of edges (as node names, not integers) in dg and weight_list is a list of data/objects to be saved as edge data under the name attribute. edge_list and weight_list must have the same length, and entries of weight_list will be added to the corresponding edge in edge_list

add_graph_data!(dg::D, weight, attribute) where {D <: DataGraphUnion}

Add the value weight to the graph under the name attribute. If the attribute is already defined, the value will be reset to weight.

add_node!(dg, node_name)

Add the node node_name to the DataDiGraph dg

add_node!(dg, node_name)

Add the node node_name to the DataGraph dg

add_node_attribute!(datagraph, attribute, default_weight = 0.0)
add_node_attribute!(datadigraph, attribute, default_weight = 0.0)

Add a column filled with default_weight to the node_data matrix with the name attribute. If attribute already exists in the node data, an error is thrown.

add_node_data!(dg::D, node_name, node_weight, attribute_name) where {D <: DataGraphUnion}

Add a weight value for the given node name in the DataGraph object. User must pass an "attribute name" for the given weight. All other nodes that do not have a node_weight value defined for that attribute name default to a value of zero.

add_node_dataset!(dg::D, weight_dict, attribute) where {D <: DataGraphUnion}

Add the data in weight_dict as node data on dg under the name attribute. weight_dict must contain keys that correspond to the node names in dg.nodes.

add_node_dataset!(dg::D, weight_list, attribute) where {D <: DataGraphUnion}

Add the entries of weight_list as node data on dg under the name attribute. weight_list must be the same length as the number of nodes in dg. Entries of weight_list will be added as node data in the order that nodes are listed in dg.nodes.

add_node_dataset!(dg::D, node_list, weight_list, attribute) where {D <: DataGraphUnion}

Add the node data in weight_list to dg. node_list is a list of nodes in dg and weight_list is a list of values/things to be saved as node data under the name attribute. node_list and weight_list must have the same length, and entries of weight_list will be added to the corresponding node in node_list

adjacency_matrix(datagraph)
adjacency_matrix(datadigraph)

Return the adjacency matrix of a DataGraph object

aggregate(datadigraph, node_list, aggregated_node_name;
            node_fn = mean, edge_fn = mean, save_agg_edge_data = false,
            agg_edge_fn = mean, agg_edge_val = 0, node_attributes_to_add = String[]
)

Aggregates all the nodes in node_list into a single node which is called aggregated_node_name. If nodes have any weight/attribute values defined, these values are combined via the node_fn function. The default for node_fn is Statistics.mean which averages the data for the nodes in node_list. Edge data are also are also combined via the edge_fn when two or more nodes in the node_list are connected to the same node and these edges have data defined on them. The edge_fn also defaults to Statistics.mean

If edges exist between nodes in node_list, the data on these edges can optionally be saved on the aggregated_node_name node by setting save_agg_edge_data = true. If true, then the edge data on these edges is aggregated using agg_edge_fn. If the user wants to define new attribute names for this data, they can pass a vector to node_attributes_to_add; if no vector is defined, the data will be aggregated under the names of the edge_data attributes. All other nodes except the aggregated nodes will have these attributes initialized as agg_edge_val.

aggregate(datagraph, node_list, aggregated_node_name;
            node_fn = mean, edge_fn = mean, save_agg_edge_data = false,
            agg_edge_fn = mean, agg_edge_val = 0, node_attributes_to_add = String[]
)

Aggregates all the nodes in node_list into a single node which is called aggregated_node_name. If nodes have any weight/attribute values defined, these values are combined via the node_fn function. The default for node_fn is Statistics.mean which averages the data for the nodes in node_list. Edge data are also are also combined via the edge_fn when two or more nodes in the node_list are connected to the same node and these edges have data defined on them. The edge_fn also defaults to Statistics.mean

If edges exist between nodes in node_list, the data on these edges can optionally be saved on the aggregated_node_name node by setting save_agg_edge_data = true. If true, then the edge data on these edges is aggregated using agg_edge_fn. If the user wants to define new attribute names for this data, they can pass a vector to node_attributes_to_add; if no vector is defined, the data will be aggregated under the names of the edge_data attributes. All other nodes except the aggregated nodes will have these attributes initialized as agg_edge_val.

average_degree(datagraph)

Returns the average degree for datagraph

downstream_nodes(dg::DataDiGraph, node; algorithm = "bfs")

Return a list of all the nodes that are downstream of node in the DataDiGraph dg. Algorithm options are "bfs" and "dfs"

filter_edges(datadigraph, filter_value, attribute = dg.edge-data.attributes[1]; fn = isless)

Removes the edges of the graph whose data on attribute is does not meet the criteria of fn with respect to filter_value. If attribute is not specified, this defaults to the first attribute within the DataDiGraph's EdgeData.

fn is a function that takes an input of a edge's data on attribute and the filter_value and returns a true or false

filter_edges(datagraph, filter_value, attribute = dg.edge_data.attributes[1]; fn = isless)

Removes the edges of the graph whose data on attribute is does not meet the criteria of fn with respect to filter_value. If attribute is not specified, this defaults to the first attribute within the DataGraph's EdgeData.

fn is a function that takes an input of a edge's data on attribute and the filter_value and returns a true or false

filter_nodes(datadigraph, filter_value, attribute = dg.node_data.attributes[1]; fn = isless)

Removes the nodes of the graph whose data on attribute is does not meet the criteria of fn with respect to filter_value. If attribute is not specified, this defaults to the first attribute within the DataDiGraph's NodeData.

fn is a function that takes an input of a node's data on attribute and the filter_value and returns a true or false

filter_nodes(datagraph, filter_value, attribute = dg.node_data.attributes[1]; fn = isless)

Removes the nodes of the graph whose data on attribute is does not meet the criteria of fn with respect to filter_value. If attribute is not specified, this defaults to the first attribute within the DataGraph's NodeData.

fn is a function that takes an input of a node's data on attribute and the filter_value and returns a true or false

get_EC(datagraph)

Returns the Euler Characteristic for a DataGraph. The Euler Characteristic is equal to the number of nodes minus the number of edges or the number of connected components minus the number of cycles

get_edge_attributes(dg::D) where {D <: DataGraphUnion}

Returns the list of attributes contained in the EdgeData of dg

get_edge_data(dg::D) where {D <: DataGraphUnion}

Returns the data object from a DataGraph's or DataDiGraph's EdgeData

get_edge_data(dg::D, attribute) where {D <: DataGraphUnion}

Returns a vector of the edge data corresponding to the attribute

get_edge_data(dg::D, attribute_list; edges) where {D <: DataGraphUnion}

Returns a matrix of the edge data for the attributes in attribute list in the order that the attributes are defined in the list

get_edge_data(datagraph, node_name1, node_name2, attribute_name)
get_edge_data(datagraph, edge, attribute_name)

Returns the value of attribute name on the edge between node_name1 and node_name2. edge is a tuple containing node_name1 and node_name2.

get_edge_data(datagraph, node_name1, node_name2, attribute_name)
get_edge_data(datagraph, edge, attribute_name)

Returns the value of attribute name on the edge between node_name1 and node_name2. edge is a tuple containing node_name1 and node_name2.

get_graph_attributes(dg::D) where {D <: DataGraphUnion}

Returns the list of attributes contained in the GraphData of dg

get_graph_data(dg::D) where {D <: DataGraphUnion}

Returns the data object from a DataGraph's or DataDiGraph's GraphData

get_node_attributes(dg::D) where {D <: DataGraphUnion}

Returns the list of attributes contained in the NodeData of dg

get_node_data(dg::D) where {D <: DataGraphUnion}

Returns the data object from a DataGraph's or DataDiGraph's NodeData

get_node_data(dg::D, attribute::String) where {D <: DataGraphUnion}

Returns a vector of the edge data for the attribute

get_node_data(dg::D, attribute_list; nodes = dg.nodes) where {D <: DataGraphUnion}

Returns a matrix of the node data for the attributes in attribute list in the order that the attributes are defined in the list. If nodes is defined, returns the subset of data corresponding to nodes in the order that they are defined in nodes

get_node_data(datagraph, node_name, attribute_name)

Returns the value of attribute name on the given node

get_node_data(datagraph, node_name, attribute_name)

Returns the value of attribute name on the given node

get_ordered_edge_data(dg::D) where {D <: DataGraphUnion}

Returns the ordered edge data matrix. For DataGraphs, this means all edges connected to dg.nodes[1] are ordered first, and so on. For DataDiGraphs, this means that all edges originating at dg.nodes[1] are ordered first, and so on for length(dg.nodes)

get_ordered_edge_data(dg::D, attribute::String) where {D <: DataGraphUnion}

Returns the ordered edge data vector for attribute. For DataGraphs, this means all edges connected to dg.nodes[1] are ordered first, and so on. For DataDiGraphs, this means that all edges originating at dg.nodes[1] are ordered first, and so on for length(dg.nodes)

get_ordered_edge_data(dg::D, attribute_list) where {D <: DataGraphUnion}

Returns the ordered edge data matrix for the attributes in attribute_list. For DataGraphs, this means all edges connected to dg.nodes[1] are ordered first, and so on. For DataDiGraphs, this means that all edges originating at dg.nodes[1] are ordered first, and so on for length(dg.nodes)

get_path(datagraph, src_node, dst_node; algorithm = "Dijkstra")

Returns the shortest path in the datagraph between src_node and dst_node. Shortest path is computed by Dijkstra's algorithm

algorithm is a string key word. Options are limited to "Dijkstra", "BellmanFord"

get_path(datagraph, src_node, intermediate_node, dst_node; algorithm = "Dijkstra")

Returns the shortest path in the datagraph between src_node and dst_node which passes through intermediate node.

algorithm is a string key word. Options are limited to "Dijkstra", "BellmanFord"

has_edge(datagraph, node1, node2)

Return true if there is an edge going from node1 to node2 in datadigraph. Else return false

has_edge(datagraph, node1, node2)

Return true if there is an edge between node1 and node2 in datagraph. Else return false

has_node(datagraph, node)
has_node(datadigraph, node)

returns true if node is in the graph. Else return false

has_path(datagraph, src_node, dst_node)

Returns true if a path exists in the datagraph between src_node to dst_node. Else returns false

has_path(datagraph, src_node, intermediate_node, dst_node)

Returns true if a path exists in the datagraph between src_node and dst_node which passes through the intermediate node. Else returns false

index_to_nodes(datagraph, index_list)

From a list of integer indeices, return a list of corresponding nodes in the datagraph

matrix_to_graph(matrix; diagonal = true, attribute="weight")
matrix_to_graph(array_3d; diagonal = true, attributes = ["weight$i" for i in 1:size(array_3d)[3]])

Constructs a DataGraph object from a matrix and saves the matrix data as node attributes under the name attribute. If diagonal = false, the graph has a mesh structure, where each matrix entry is represented by a node, and each node is connected to the adjacent matrix entries/nodes. If diagonal = true, entries of the matrix are also connected to the nodes diagonal to them (i.e., entry (i,j) is connected to (i-1, j-1), (i + 1, j -1), etc.).

If a 3D matrix is passed to the function, it treats the first two dimensions as the matrix and then saves the data in the third dimension as different weights (i.e., for array of size dim1, dim2, and dim3, entry (i,j) has dim3 weights). attribute_list can be defined by the user to give names to each weight in the third dimension.

mvts_to_graph(mvts, attribute)

Converts a multivariate time series to a graph based on the covariance matrix. This first calculates the covariance of the multivariate time series (mvts) and then computes the covariance. It then forms the precision matrix by taking the inverse of the covariance and uses the function symmetric_matrix_to_graph to form the edge-weighted graph.

ne(dg::D) where {D <: DataGraphUnion}

Returns the number of edges in a DataGraph or DataDiGraph

nn(dg::D) where {D <: DataGraphUnion}
nv(dg::D) where {D <: DataGraphUnion}

Returns the number of nodes (vertices) in a DataGraph or DataDiGraph

nodes_to_index(datagraph, node_list)

From a list of nodes in the datagraph, return a list of their corresponding integer indices

order_edges!(dg) where {D <: DataGraphUnion}

Arranges in place the edges of dg so that they follow the order of dg.nodes. For DataGraphs, this means all edges connected to dg.nodes[1] are ordered first, and so on. For DataDiGraphs, this means that all edges originating at dg.nodes[1] are ordered first, and so on for length(dg.nodes)

remove_edge!(datadigraph, node1, node2)
remove_edge!(datadigraph, edge_tuple)

Remove the directed edge from node1 to node2 from the datadigraph.

remove_edge!(datagraph, node1, node2)
remove_edge!(datagraph, edge_tuple)

Remove the edge between node1 and node2 from the datagraph.

remove_node!(datadigraph, node_name)

Removes the node (and any node data) from datadigraph

remove_node!(datagraph, node_name)

Removes the node (and any node data) from datagraph

rename_edge_attribute!(dg::D, attribute, new_name) where {D <: DataGraphUnion}

Rename the edge data attribute as new_name. If attribute is not defined, returns an error.

rename_graph_attribute!(dg::D, attribute, new_name) where {D <: DataGraphUnion}

Rename the graph data attribute as new_name. If attribute is not defined, returns an error.

rename_node_attribute!(dg::D, attribute, new_name) where {D <: DataGraphUnion}

Rename the node data attribute as new_name. If attribute is not defined, returns an error.

run_EC_on_edges(dg, threshold_range; attribute = dg.edge_data.attributes[1], scale = false)

Returns the Euler Characteristic Curve by filtering the edges of the graph at each value in threshold_range and computing the Euler Characteristic after each filtration. If attribute is not defined, it defaults to the first attribute in the DataGraph's EdgeData. scale is a Boolean that indicates whether to scale the Euler Characteristic by the total number of objects (nodes + edges) in the original graph

run_EC_on_nodes(dg, threshold_range; attribute = dg.node_data.attributes[1], scale = false)

Returns the Euler Characteristic Curve by filtering the nodes of the graph at each value in threshold_range and computing the Euler Characteristic after each filtration. If attribute is not defined, it defaults to the first attribute in the DataGraph's NodeData. scale is a Boolean that indicates whether to scale the Euler Characteristic by the total number of objects (nodes + edges) in the original graph

symmetric_matrix_to_graph(matrix; attribute="weight", tol = 1e-9)

Constructs a DataGraph object from a symmetric matrix and saves the values of the matrix to their corresponding edges. The resulting graph is fully connected (every node is connected to every node) and the number of nodes is equal to the dimension of the matrix. Matrix values are saved as edge weights under the name attribute. tol is the tolerance used when testing that the matrix is symmetric.

tensor_to_graph(tensor, attribute)

Constructs a graph from a 3-D array (a tensor). Each entry of the tensor is represented by a node, and each node is connected to the adjacent nodes in each dimension. This function creates the graph structure and saves the values of the tensor to their corresponding nodes as weight values under the name attribute.

upstream_nodes(dg::DataDiGraph, node; algorithm = "bfs")

Return a list of all the nodes that are upstream of node in the DataDiGraph dg. Algorithm options are "bfs" and "dfs"