Attributes

Attribute table helpers from annnet.core._Annotation.

These methods are mixed into AnnNet. Direct imports from underscore modules follow the internal API policy.

AttributesAccessor is what G.attrs gives back: the eight attribute tables and the setters that write them. For how those tables relate to the frames under G.views, and to the older obs/var/slice_attributes spellings, see Reading the graph and Internal representation.

annnet.core._Annotation.AttributesClass

Attribute accessors and upsert helpers (graph/node/edge/slice/edge-slice).

Functions

set_graph_attribute

set_graph_attribute(key, value)

Set a graph-level attribute.

Parameters:

Name	Type	Description	Default
key	str	Attribute name.	required
value	Any	Attribute value.	required

get_graph_attribute

get_graph_attribute(key, default=None)

Get a graph-level attribute.

Parameters:

Name	Type	Description	Default
key	str	Attribute name.	required
default	Any	Value to return if the attribute is missing.	None

Returns:

Type	Description
Any

set_node_attrs

set_node_attrs(node_id, **attrs)

Upsert pure node attributes (non-structural) into the node table.

Parameters:

Name	Type	Description	Default
node_id	str	Node identifier.	required
**attrs		Attribute key/value pairs.	{}

Raises:

Type	Description
ValueError	If any key is structurally reserved (e.g. node_id).

set_node_attrs_bulk

set_node_attrs_bulk(updates)

Upsert node attributes in bulk.

Parameters:

Name	Type	Description	Default
updates	dict[str, dict] | Iterable[tuple[str, dict]]	Mapping or iterable of (node_id, attrs) pairs.	required

get_attr_node

get_attr_node(node_id, key, default=None)

Get a single node attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
node_id	str	Node identifier.	required
key	str	Attribute name.	required
default	Any	Value to return if missing.	None

Returns:

Type	Description
Any

set_edge_attrs

set_edge_attrs(edge_id, **attrs)

Upsert pure edge attributes (non-structural) into the edge DF.

Parameters:

Name	Type	Description	Default
edge_id	str	Edge identifier.	required
**attrs		Attribute key/value pairs.	{}

Raises:

Type	Description
ValueError	If any key is structurally reserved (e.g. edge_id, source, target, weight, members, head, tail, flexible).

set_edge_attrs_bulk

set_edge_attrs_bulk(updates)

Upsert edge attributes in bulk.

Parameters:

Name	Type	Description	Default
updates	dict[str, dict] | Iterable[tuple[str, dict]]	Mapping or iterable of (edge_id, attrs) pairs.	required

get_attr_edge

get_attr_edge(edge_id, key, default=None)

Get a single edge attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
edge_id	str	Edge identifier.	required
key	str	Attribute name.	required
default	Any	Value to return if missing.	None

Returns:

Type	Description
Any

set_slice_attrs

set_slice_attrs(slice_id, **attrs)

Upsert pure slice attributes.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
**attrs		Attribute key/value pairs. Structural keys are ignored.	{}

get_slice_attr

get_slice_attr(slice_id, key, default=None)

Get a single slice attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
key	str	Attribute name.	required
default	Any	Value to return if missing.	None

Returns:

Type	Description
Any

set_edge_slice_attrs

set_edge_slice_attrs(slice_id, edge_id, **attrs)

Upsert per-slice attributes for a specific edge.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
edge_id	str	Edge identifier.	required
**attrs		Attribute key/value pairs. Structural keys are ignored except weight.	{}

edge_slice

edge_slice(slice_id, edge_id)

Return every attribute one edge carries in one slice.

The level of this store is the pair, so an edge that carries nothing in this slice answers with an empty mapping rather than with the attributes it carries elsewhere.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
edge_id	str	Edge identifier.	required

Returns:

Type	Description
dict

get_edge_slice_attr

get_edge_slice_attr(slice_id, edge_id, key, default=None)

Get a per-slice attribute for an edge.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
edge_id	str	Edge identifier.	required
key	str	Attribute name.	required
default	Any	Value to return if missing.	None

Returns:

Type	Description
Any

set_slice_edge_weight

set_slice_edge_weight(slice_id, edge_id, weight)

Set a legacy per-slice weight override for an edge.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
edge_id	str	Edge identifier.	required
weight	float	Weight override.	required

Raises:

Type	Description
KeyError	If the slice or edge does not exist.

See Also

get_effective_edge_weight

get_effective_edge_weight

get_effective_edge_weight(edge_id, slice=None)

Resolve the effective weight for an edge, optionally within a slice.

Parameters:

Name	Type	Description	Default
edge_id	str	Edge identifier.	required
slice	str	Slice to read the override from. When omitted, the graph's currently active slice is used. Pass an explicit slice ID to override the active-slice resolution.	None

Returns:

Type	Description
float	Effective weight.

audit_attributes

audit_attributes()

Audit attribute tables for extra/missing rows and invalid edge-slice pairs.

Returns:

Type	Description
dict	Summary with keys: - extra_node_rows - extra_edge_rows - missing_node_rows - missing_edge_rows - invalid_edge_slice_rows

Notes

The node table and the edge table are derived from columns addressed by slot, so a row of either names an element the graph holds and every element the graph holds has one. The first four lists are therefore always empty, and what this still finds is an edge-by-slice row that names a slice or an edge the graph does not hold.

get_edge_attrs

get_edge_attrs(edge)

Return the full attribute dict for a single edge.

Parameters:

Name	Type	Description	Default
edge	int | str	Edge index or edge ID.	required

Returns:

Type	Description
dict	Attribute dictionary for that edge. Empty if not found.

get_node_attrs

get_node_attrs(node)

Return the full attribute dict for a single node.

Parameters:

Name	Type	Description	Default
node	str	Node ID.	required

Returns:

Type	Description
dict	Attribute dictionary for that node. Empty if not found.

get_attr_edges

get_attr_edges(indexes=None)

Retrieve edge attributes as a dictionary.

Parameters:

Name	Type	Description	Default
indexes	Iterable[int] | None	Edge indices to retrieve. If None, returns all edges.	None

Returns:

Type	Description
dict[str, dict]	Mapping of edge_id to attribute dictionaries.

get_attr_nodes

get_attr_nodes(nodes=None)

Retrieve node (node) attributes as a dictionary.

Parameters:

Name	Type	Description	Default
nodes	Iterable[str] | None	Node IDs to retrieve. If None, returns all nodes.	None

Returns:

Type	Description
dict[str, dict]	Mapping of node_id to attribute dictionaries.

get_attr_from_edges

get_attr_from_edges(key, default=None)

Extract a specific attribute column for all edges.

Parameters:

Name	Type	Description	Default
key	str	Attribute column name to extract.	required
default	Any	Value to use if the column or value is missing.	None

Returns:

Type	Description
dict[str, Any]	Mapping of edge_id to attribute values.

get_edges_by_attr

get_edges_by_attr(key, value)

Retrieve all edges where a given attribute equals a specific value.

Parameters:

Name	Type	Description	Default
key	str	Attribute column name to filter on.	required
value	Any	Value to match.	required

Returns:

Type	Description
list[str]	Edge IDs where the attribute equals value.

get_graph_attributes

get_graph_attributes()

Return a shallow copy of the graph-level attributes dictionary.

Returns:

Type	Description
dict	Shallow copy of global graph metadata.

Notes

Returned value is a shallow copy to prevent external mutation.

set_edge_slice_attrs_bulk

set_edge_slice_attrs_bulk(slice_id, items)

Upsert edge-slice attributes for a single slice in bulk.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
items	Iterable[tuple[str, dict]] | dict[str, dict]	Iterable or mapping of (edge_id, attrs) pairs.	required

annnet.core._Annotation.AttributesAccessor

Every attribute of a graph, read and written (G.attrs).

Eight tables, each named for what addresses it — :attr:nodes, :attr:edges, :attr:slices, :attr:aspects, :attr:layers, :attr:edge_slices, :attr:node_layers and :attr:elementary_layers — beside the setters that write them. Each is a property, because a table takes no arguments. :meth:table is the one call, for naming a backend.

A table here holds what was written. The frames under G.views hold everything derivable, take filters and joins, and are calls rather than properties. Five names appear in both namespaces and mean those two different things.

Attributes

nodes property

nodes

Attributes keyed by node, as a table.

edges property

edges

Attributes keyed by edge, as a table.

slices property

slices

Attributes keyed by slice, as a table.

aspects property

aspects

Attributes keyed by aspect, as a table.

layers property

layers

Attributes keyed by layer coordinate, as a table.

The whole coordinate across every aspect. One elementary label inside one aspect is :attr:elementary_layers, which is a different table.

edge_slices property

edge_slices

Attributes keyed by one edge inside one slice, as a table.

node_layers property

node_layers

Attributes keyed by one node inside one layer, as a table.

elementary_layers property

elementary_layers

Attributes keyed by elementary layer id, as a table.

One label inside one aspect, addressed by the layer_id that G.layers.set_elementary_attrs composes from the two.

G.layer_attributes also accepts a table this API cannot address — one carrying no layer_id — and hands that back exactly as it was given, because an adapter round-trips it. That promise is the old property's. Here every table answers in one backend, so a table given in another is rendered into it.

backend property writable

backend

The dataframe backend every table is rendered in.

Functions

table

table(name, *, backend=None)

Return one table by name, optionally in a backend of its own.

The table is the one the property of the same name gives, so the two cannot answer differently. Naming a backend converts, which costs something, so it is worth it only for the genuinely mixed case. Set :attr:backend when every table should answer in the same one. Naming the backend a table already has — or "auto" — is the table itself and costs nothing.

Parameters:

Name	Type	Description	Default
name	str	One of :data:TABLE_NAMES.	required
backend	(polars, pandas, pyarrow, auto)	Defaults to the ambient :attr:backend.	"polars"

Returns:

Type	Description
DataFrame - like

__getattr__

__getattr__(name)

Every name of _ATTR_DELEGATED, installed at import.