DataFrames

DataFrame conversion helpers from annnet.io.dataframes.

AnnNet accepts Narwhals-compatible eager dataframe inputs. When AnnNet creates new dataframe outputs, the default backend is selected centrally in preference order: Polars, pandas, then PyArrow. Pass annotations_backend to AnnNet when you need a specific backend for one graph, or use set_default_dataframe_backend to configure the process-wide default for new graphs.

annnet.io.dataframes

Classes

Functions

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': Vertex 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.

from_dataframes

from_dataframes(
    nodes=None,
    edges=None,
    hyperedges=None,
    slices=None,
    slice_weights=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: vertex_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, vertex_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 vertex_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 directed: Default directedness (None = mixed graph) exploded_hyperedges: If True, hyperedges DataFrame is in exploded format

Returns:

Type	Description
AnnNet instance