Module attributes 

Graph, vertex and edge attributes (igraph_attributes.h).

igraph can attach attributes to a graph as a whole, to its vertices and to its edges: a vertex name, an edge weight, a graph title, … The C core does not store attributes by itself: it notifies an attribute handler (a table of callbacks, igraph_attribute_table_t) of every structural change so that the handler can keep its data aligned with the vertex and edge ids. This module plugs igraph’s own C attribute handler (igraph_cattribute_table, the one behind the VAN/SETVAN/… macros of the C API) into the crate and exposes it with a typed, Rusty API on Graph.

Enabling attributes

The attribute handler is a process-wide setting of the C library (it is not thread-local, even in a thread-safe igraph build, see src/graph/attributes.c). It is turned on with enable:

• it is idempotent and irreversible: once enabled, attributes stay enabled for the rest of the process (detaching a handler would make igraph leak the attribute storage and let it get out of sync with the graphs);
• it is also called implicitly by every attribute setter, so writing an attribute simply works;
• it must be called before reading graphs from files if you want the foreign readers (GraphML, GML, Pajek, NCOL, LGL, …) to keep vertex names, edge weights and the other attributes found in the file, and before writing them if you want the writers to emit your attributes;
• graphs created before enable carry no attribute storage: they keep working (this crate installs a guarded version of the C handler that ignores attribute-less graphs instead of crashing, as the raw C handler would), and their storage is created lazily by the first setter call;
• call it early (e.g. at the start of main): the C library stores the handler in a plain global variable, so enabling it while other threads are in the middle of igraph calls is best avoided.

Semantics of the C attribute handler

• Attribute values are numbers (f64), booleans or strings (AttributeType); an attribute has a single type for all the vertices (or edges) of a graph, fixed when it is first created. Writing a value of another type is an error.
• Setting a vertex (edge) attribute on a single vertex (edge) creates it for all the vertices (edges), with the default value (NaN, false or "") everywhere else. Vertices and edges added later also get the default value.
• Attributes follow the structure: deleting vertices or edges (Graph::delete_vertices, Graph::delete_edges), taking subgraphs (Graph::induced_subgraph), permuting vertices (Graph::permute_vertices), copying (and Clone-ing) a graph keep every value attached to the right vertex or edge.
• Operations that merge vertices or edges decide what to do with the attributes of the merged elements via an AttributeCombination. The plain wrappers Graph::simplify, Graph::contract_vertices and Graph::to_undirected pass no combination, so they drop the attributes of the kind they merge: vertex attributes for contract_vertices; edge attributes for to_undirected (except in ToUndirected::Each mode) and for simplify when it actually merges multi-edges (when it only deletes loops, or igraph already knows there are no multi-edges, the remaining edges keep their attributes). Use their attribute-aware twins Graph::simplify_with_attributes, Graph::contract_vertices_with_attributes and Graph::to_undirected_with_attributes to keep them.
• The Random combination and the tie-breaking of boolean majority votes use the default random number generator of the calling thread: seed it with rng::seed for reproducible results.

Example

use igraph::prelude::*;
use igraph::attributes::{self, AttributeKind, AttributeValue};

attributes::enable().unwrap();
let mut g = Graph::from_edges(&[(0, 1), (1, 2), (2, 0)], 3, false).unwrap();

g.set_graph_attr_str("title", "triangle").unwrap();
g.set_vertex_attr_str_values("name", &["alice", "bob", "carol"]).unwrap();
g.set_edge_attr_numeric_values("weight", &[1.0, 2.5, 4.0]).unwrap();
g.set_vertex_attr_bool("admin", 0, true).unwrap();

assert_eq!(g.graph_attr_str("title").unwrap(), "triangle");
assert_eq!(g.vertex_attr_str("name", 1).unwrap(), "bob");
assert_eq!(g.vertex_attr("admin", 2).unwrap(), AttributeValue::Boolean(false));
assert!(g.has_attribute(AttributeKind::Vertex, "name"));

// Numeric edge attributes are the weight vectors of weighted algorithms.
let w = g.edge_attr_numeric_values("weight", ..).unwrap();
assert_eq!(w, vec![1.0, 2.5, 4.0]);
let strength = g.strength(.., NeighborMode::All, Loops::Twice, Some(&w)).unwrap();
assert_eq!(strength, vec![5.0, 3.5, 6.5]);

// Attributes follow the structure of the graph.
g.delete_vertices(0).unwrap();
assert_eq!(g.vertex_attr_str_values("name", ..).unwrap(), vec!["bob", "carol"]);
assert_eq!(g.edge_attr_numeric_values("weight", ..).unwrap(), vec![2.5]);

Provided functionality

Rust	C
enable, is_enabled, has_attribute_table	igraph_set_attribute_table(&igraph_cattribute_table), igraph_has_attribute_table
Graph::graph_attr_numeric, Graph::graph_attr_bool, Graph::graph_attr_str, Graph::graph_attr	igraph_cattribute_GAN, GAB, GAS
Graph::vertex_attr_numeric, Graph::vertex_attr_bool, Graph::vertex_attr_str, Graph::vertex_attr	igraph_cattribute_VAN, VAB, VAS
Graph::edge_attr_numeric, Graph::edge_attr_bool, Graph::edge_attr_str, Graph::edge_attr	igraph_cattribute_EAN, EAB, EAS
Graph::vertex_attr_numeric_values, Graph::vertex_attr_bool_values, Graph::vertex_attr_str_values, Graph::vertex_attr_values	igraph_cattribute_VANV, VABV, VASV
Graph::edge_attr_numeric_values, Graph::edge_attr_bool_values, Graph::edge_attr_str_values, Graph::edge_attr_values	igraph_cattribute_EANV, EABV, EASV
Graph::set_graph_attr_numeric, Graph::set_graph_attr_bool, Graph::set_graph_attr_str, Graph::set_graph_attr	igraph_cattribute_GAN_set, GAB_set, GAS_set
Graph::set_vertex_attr_numeric, Graph::set_vertex_attr_bool, Graph::set_vertex_attr_str, Graph::set_vertex_attr	igraph_cattribute_VAN_set, VAB_set, VAS_set
Graph::set_edge_attr_numeric, Graph::set_edge_attr_bool, Graph::set_edge_attr_str, Graph::set_edge_attr	igraph_cattribute_EAN_set, EAB_set, EAS_set
Graph::set_vertex_attr_numeric_values, Graph::set_vertex_attr_bool_values, Graph::set_vertex_attr_str_values, Graph::set_vertex_attr_values	igraph_cattribute_VAN_setv, VAB_setv, VAS_setv
Graph::set_edge_attr_numeric_values, Graph::set_edge_attr_bool_values, Graph::set_edge_attr_str_values, Graph::set_edge_attr_values	igraph_cattribute_EAN_setv, EAB_setv, EAS_setv
Graph::attribute_list, Graph::attribute_names, Graph::attribute_type	igraph_cattribute_list
Graph::has_attribute	igraph_cattribute_has_attr
Graph::remove_graph_attr, Graph::remove_vertex_attr, Graph::remove_edge_attr, Graph::remove_all_attributes	igraph_cattribute_remove_g, remove_v, remove_e, remove_all
Graph::add_vertices_with_attributes, Graph::add_edges_with_attributes	igraph_add_vertices, igraph_add_edges with an attribute record list
Graph::simplify_with_attributes, Graph::contract_vertices_with_attributes, Graph::to_undirected_with_attributes	igraph_simplify, igraph_contract_vertices, igraph_to_undirected with an attribute combination
AttributeRecord	igraph_attribute_record_*
AttributeCombination	igraph_attribute_combination_*

See also

• crate::foreign: the GraphML, GML, Pajek, NCOL, LGL, … readers and writers load and save attributes once enable has been called, e.g. Graph::read_graph_graphml_from_str and Graph::write_graph_graphml_to_string.
• crate::operators and crate::conversion: the structural operations whose attribute handling is described above.
• Weighted algorithms take the weights as a slice: feed them g.edge_attr_numeric_values("weight", ..), e.g. Graph::strength, Graph::distances_dijkstra or Graph::community_multilevel.

Structs

AttributeList

Names and types of all the attributes of a graph, see Graph::attribute_list.

Enums

AttributeCombinationType

How to combine the attribute values of vertices or edges that are merged into one (igraph_attribute_combination_type_t).

AttributeKind

What an attribute is attached to (igraph_attribute_elemtype_t).

AttributeType

The type of an attribute (igraph_attribute_type_t).

AttributeValue

A single attribute value, as stored by the C attribute handler.

AttributeValues

The values of an attribute for several vertices or edges.

CombineFunction

A user supplied C function combining attribute values, see AttributeCombination::add_function.

Functions

enable

Turns on igraph’s C attribute handler for the whole process.

has_attribute_table

Whether some attribute handler is attached to igraph (igraph_has_attribute_table).

is_enabled

Whether this crate’s attribute handler is attached (see enable).

Type Aliases

AttributeCombination

How to combine attributes when vertices or edges are merged (igraph_attribute_combination_t).

AttributeRecord

A named, typed vector of attribute values (igraph_attribute_record_t).

BooleanCombineFn

Signature of a boolean combination function of the C attribute handler.

NumericCombineFn

Signature of a numeric combination function of the C attribute handler: input holds the values of the merged elements, the result goes to output.