DataFrames

Build a graph from a table of edges, and exchange a whole graph as a set of tables.

from_edge_frame makes a graph from a table with one row per edge: a source column, a target column, and optional columns for the edge ID and the edge attributes. add_edges_from_frame adds such a table to a graph that exists. When the table has no edge IDs, edge_id_for makes one from what the edge is: its endpoints, its place and its attributes. So a sorted copy of the same table gives the same IDs. The quickstart reads a table this way.

to_dataframes gives a dictionary of tables, with the metadata that is not a table beside them. from_dataframes rebuilds the graph. Keep the complete dictionary for a round trip.

annnet accepts any eager dataframe that Narwhals supports. The tables that annnet makes use Polars, pandas or PyArrow, the first one installed in this order. To use one library for one graph, give annotations_backend to AnnNet. To change the default for all new graphs, call annnet.set_default_dataframe_backend.

annnet.io.edge_frame.from_edge_frame

from_edge_frame(
    frame,
    *,
    directed=True,
    aspects=None,
    node_attrs=None,
    **kwargs
)

Build a graph from an edge table.

Parameters:

Name	Type	Description	Default
`frame`	`DataFrame - like \| list[dict]`	One row per edge.	required
`directed`	`bool`	The graph's default direction.	`True`
`aspects`	`dict`	Aspect declarations, as :meth:`LayerAccessor.set_aspects` takes them. Declared before the edges land, so a layer named on a row already exists.	`None`
`node_attrs`	`Mapping[str, dict]`	Attributes to set on nodes once they exist.	`None`
`**kwargs`	`Any`	Passed to :func:`add_edges_from_frame`.	`{}`

Returns:

Type	Description
`AnnNet`

Examples:

>>> anet = from_edge_frame(table, sign='effect', slice='prior')

annnet.io.edge_frame.add_edges_from_frame

add_edges_from_frame(
    graph,
    frame,
    *,
    source="source",
    target="target",
    edge_id=None,
    weight=None,
    sign=None,
    attrs=None,
    directed=None,
    slice=None,
    layer=None,
    id_prefix="e",
    on_conflict="error"
)

Add every row of an edge table to a graph.

Parameters:

Name	Type	Description	Default
`graph`	`AnnNet`		required
`frame`	`DataFrame - like \| list[dict]`	One row per edge. Any backend Narwhals reads, or plain dicts.	required
`source`	`str`	The columns naming the endpoints.	`'source'`
`target`	`str`	The columns naming the endpoints.	`'source'`
`edge_id`	`str`	A column holding the id. Without it, an id is derived from the row — see :func:`edge_id_for`.	`None`
`weight`	`str`	A column holding the incidence weight.	`None`
`sign`	`str`	A column holding a direction of effect, written to an attribute named `"sign"` whatever the column is called. The name is a convention this module carries and does not interpret; what it means belongs to whatever declares the vocabulary.	`None`
`attrs`	`list[str]`	Which other columns to carry as edge attributes. Default: all of them.	`None`
`directed`	`bool`	Directedness for these edges. Defaults to the graph's.	`None`
`slice`	`str`	The slice these edges land in — which is also what answers which edges came from this table, so no side list is needed.	`None`
`layer`	`tuple[str, ...]`	The layer these edges land in.	`None`
`id_prefix`	`str`	The prefix derived ids carry.	`"e"`
`on_conflict`	`str`	What to do about an id the graph already holds. See :data:`annnet.io.edge_frame.ON_CONFLICT`.	`"error"`

Returns:

Type	Description
`list[str]`	The edge ids, in row order — which is the mapping back to the rows.

Raises:

Type	Description
`KeyError`	If a named column is not in the table.
`ValueError`	If `on_conflict` is unknown.
`EdgeIdConflict`	If `on_conflict='error'` and an id is already taken. Nothing lands.

Examples:

>>> ids = add_edges_from_frame(anet, table, sign='effect', slice='prior')

annnet.io.edge_frame.edge_id_for

edge_id_for(payload, *, prefix='e')

A deterministic id for one edge, derived from what it is.

The payload is serialized in sorted key order, so two rows describing the same edge give the same id however the table was sorted, and two rows differing in any recorded value do not.

Parameters:

Name	Type	Description	Default
`payload`	`dict`	Everything that identifies the edge — its endpoints, its placement, and the values it carries.	required
`prefix`	`str`	What the id begins with, so a reader can tell where it came from.	`"e"`

Returns:

Type	Description
`str`

Examples:

>>> edge_id_for({'source': 'A', 'target': 'B'}) == edge_id_for({'target': 'B', 'source': 'A'})
True

annnet.io.dataframes.from_dataframes

from_dataframes(
    nodes=None,
    edges=None,
    hyperedges=None,
    slices=None,
    slice_weights=None,
    *,
    multilayer=None,
    edge_entities=None,
    directed=None,
    exploded_hyperedges=False
)

Import graph from any DataFrame (Pandas, Polars, PyArrow, etc.).

Accepts DataFrames in the format produced by to_dataframes():

Nodes DataFrame (optional): - Required: node_id - Optional: any attribute columns

Edges DataFrame (optional): - Required: source, target - Optional: edge_id, weight, directed, edge_type, attribute columns

Hyperedges DataFrame (optional): - Compact format: edge_id, directed, weight, head (list), tail (list), members (list) - Exploded format: edge_id, node_id, role, weight, directed

slices DataFrame (optional): - Required: slice_id, edge_id

slice_weights DataFrame (optional): - Required: slice_id, edge_id, weight

Args: nodes: DataFrame with node_id and attributes (Pandas/Polars/PyArrow/etc.) edges: DataFrame with binary edges hyperedges: DataFrame with hyperedges slices: DataFrame with slice membership slice_weights: DataFrame with per-slice edge weights multilayer: The multilayer record to_dataframes returned, if any edge_entities: The edge-entity record to_dataframes returned, if any directed: Default directedness (None = mixed graph) exploded_hyperedges: If True, hyperedges DataFrame is in exploded format

Returns:

Type	Description
`AnnNet instance`

annnet.io.dataframes.to_dataframes

to_dataframes(
    graph,
    *,
    include_slices=True,
    include_hyperedges=True,
    explode_hyperedges=False,
    public_only=True
)

Export graph to DataFrames using AnnNet's selected dataframe backend.

Returns a dictionary of DataFrames representing different aspects of the graph: - 'nodes': Node IDs and attributes - 'edges': Binary edges with source, target, weight, directed, attributes - 'hyperedges': Hyperedges with head/tail sets (if include_hyperedges=True) - 'slices': slice membership (if include_slices=True) - 'slice_weights': Per-slice edge weights (if include_slices=True)

Args: graph: AnnNet instance to export include_slices: Include slice membership tables include_hyperedges: Include hyperedge table explode_hyperedges: If True, explode hyperedges to one row per endpoint public_only: If True, filter out attributes starting with '__'

Returns:

Type	Description
`Dictionary mapping table names to DataFrames.`