Slices

Slice management from annnet.core._Slices.

Use G.slices and the AnnNet slice methods for slice workflows. Direct imports from underscore modules follow the internal API policy.

annnet.core._Slices.SliceManager

Namespace for all slice operations, exposed as G.slices.

Attributes

active property writable

active

Currently active slice identifier.

Functions

add

add(slice_id, *, nodes=None, edges=None, **attributes)

Create a new slice, optionally with its members.

Parameters:

Name	Type	Description	Default
slice_id	str		required
nodes	Iterable[str]	Node ids to attach. The three-call opening — create, add nodes, add edges — is what every caller wrote, so it is one call.	None
edges	Iterable[str]	Edge ids to attach. Their incident nodes come with them, as :meth:add_edges does.	None
**attributes	Any	Slice attributes.	{}

Returns:

Type	Description
str

Examples:

>>> G.slices.add('prior', edges=prior_ids, role='input')

remove

remove(slice_id)

Remove a non-default slice and its per-slice attributes.

Parameters:

Name	Type	Description	Default
slice_id	str		required

Raises:

Type	Description
ValueError	If attempting to remove the internal default slice.
KeyError	If the slice does not exist.

add_edge_to_slice

add_edge_to_slice(lid, eid)

Attach an existing edge to a slice (no weight changes).

Parameters:

Name	Type	Description	Default
lid	str		required
eid	str		required

Raises:

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

add_edges

add_edges(slice_id, edge_ids)

Attach many existing edges to a slice and include their incident nodes.

add_nodes

add_nodes(slice_id, node_ids)

Attach many existing nodes to a slice.

The bulk counterpart of :meth:add_node_to_slice, and the node-side mirror of :meth:add_edges. A reader that has just built a membership set writes it in one call rather than reaching into the registry.

Membership names bare node ids, so a multilayer entity key is reduced to its id the way the rest of the slice API does.

Parameters:

Name	Type	Description	Default
slice_id	str | None	The slice to extend, or None for the current slice.	required
node_ids	Iterable[str]	Node identifiers. One the graph does not hold is ignored, which is what :meth:add_edges does with an edge it does not hold.	required

attach_edges

attach_edges(slice_id, edge_ids)

Attach every edge the graph holds to a slice, and derive no nodes.

Unlike :meth:add_edges, this keeps an edge that occupies no column, so a placeholder edge survives a round trip. It also leaves the node memberships alone. A reader that restores the node memberships from the file itself needs both, and deriving them again is the dearest loop of a load.

get_slices_dict

get_slices_dict(include_default=True)

Return the raw slice_id → SliceRecord mapping (distinct from list).

list

list(include_default=True)

Slice IDs as a list.

exists

exists(slice_id)

Return True if a slice exists.

count

count()

Return the number of registered slices.

info

info(slice_id)

Nodes, edges, and attributes of a slice.

attrs

attrs(slice_id)

Return every attribute of one slice.

A slice is a level of its own, so its attributes are held apart from the attributes of the nodes and the edges it holds.

nodes

nodes(slice_id)

Return a copy of the node IDs in a slice.

edges

edges(slice_id)

Return a copy of the edge IDs in a slice.

union

union(slice_ids)

Return the union of nodes and edges across multiple slices.

intersect

intersect(slice_ids)

Return the intersection of nodes and edges across multiple slices.

difference

difference(slice_a, slice_b)

Return the nodes and edges present in one slice but not another.

create_slice_from_operation

create_slice_from_operation(
    result_slice_id, operation_result, **attributes
)

Create a new slice from a precomputed membership result.

add_node_to_slice

add_node_to_slice(lid, vid)

Attach an existing node to a slice.

Raises:

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

union_create

union_create(slice_ids, name, **attributes)

Create a slice from the union of existing slices.

intersect_create

intersect_create(slice_ids, name, **attributes)

Create a slice from the intersection of existing slices.

difference_create

difference_create(slice_a, slice_b, name, **attributes)

Create a slice from the difference of two slices.

aggregate

aggregate(
    source_slice_ids,
    target_slice_id,
    method="union",
    weight_func=None,
    **attributes
)

Build a target slice from sources via 'union' or 'intersection'.

stats

stats(include_default=True)

Return per-slice counts and attributes.

node_presence

node_presence(node_id, include_default=False)

List slices that contain a given node.

edge_presence

edge_presence(
    edge_id=None,
    source=None,
    target=None,
    *,
    include_default=False,
    undirected_match=None
)

Slices containing an edge by id, or by (source, target) endpoint pair.

hyperedge_presence

hyperedge_presence(
    *,
    members=None,
    head=None,
    tail=None,
    include_default=False
)

Slices containing a hyperedge by undirected members or directed head+tail.

conserved_edges

conserved_edges(min_slices=2, include_default=False)

Count edges that appear in at least min_slices slices.

specific_edges

specific_edges(slice_id)

Return edges that appear only in the given slice.

temporal_dynamics

temporal_dynamics(ordered_slices, metric='edge_change')

Summarize added and removed members across an ordered slice sequence.

summary

summary()

Return a compact human-readable summary of all slices.

edge_frame

edge_frame(
    edges=None,
    slices=None,
    attrs=None,
    *,
    pairs=None,
    format="wide",
    missing=None,
    backend=None
)

Read per-slice edge attributes as a table.

The scalar accessor answers for one (slice, edge, name), so reading an edge by slice by attribute cube meant a Python loop with a default in it. This is that cube, and it is the shape the question which interactions carried signal in which condition actually has — one a source/target/weight frame cannot express at all.

Parameters:

Name	Type	Description	Default
edges	Sequence[str]	Edge ids. Default: every edge that carries a per-slice attribute.	None
slices	Sequence[str]	Slice ids. Default: every slice that carries one.	None
attrs	Sequence[str]	Attribute names. Default: every name present.	None
pairs	Mapping[str, tuple[str, str]] | Sequence[tuple[str, str]]	Explicit (edge_id, attr) columns, optionally labelled. Given this, edges and attrs are not used, and the frame costs the pairs asked for rather than their cross product.	None
format	('wide', 'long')	"wide" is one row per slice, one column per (edge, attr). "long" is one row per (edge, slice, attr, value), which is the shape to group and pivot yourself.	"wide"
missing	Any	What a cell with no value holds. Default None.	None
backend	str	Dataframe backend. Defaults to the graph's.	None

Returns:

Type	Description
DataFrame - like

Raises:

Type	Description
ValueError	If format is neither "wide" nor "long".

Examples:

>>> G.slices.edge_frame(attrs=['activity'])
>>> G.slices.edge_frame(slices=fit, attrs=['activity'], format='long')

compare

compare(slice_a, slice_b, *, axis='edges', backend=None)

Compare the membership of two slices, as a table.

The set operations answer how many; this answers which, and where. One row per element in either slice, with a status naming the side it is on — the shape a diff of a prior against a fit wants, and which callers otherwise built from three set expressions and a loop.

Parameters:

Name	Type	Description	Default
slice_a	str		required
slice_b	str		required
axis	('edges', 'nodes')		"edges"
backend	str		None

Returns:

Type	Description
DataFrame - like	Columns edge_id or node_id, and status — one of "both", "a_only", "b_only".

Raises:

Type	Description
ValueError	If axis is neither "edges" nor "nodes".
KeyError	If either slice is unknown.

Examples:

>>> G.slices.compare('prior', 'fitted', axis='edges')

induce_edges

induce_edges(slice_id, *, mode='both', hyper='all')

Attach the edges this slice's nodes already imply.

A slice built by naming nodes holds no edges, so every read of it sees an edgeless graph. Induction is the missing half, and which edges it means is a choice rather than an obvious default.

Parameters:

Name	Type	Description	Default
slice_id	str		required
mode	('both', 'any')	"both" attaches an edge when every endpoint is in the slice — the induced subgraph. "any" attaches it when one endpoint is, which reaches outside the slice.	"both"
hyper	('all', 'skip')	Whether a hyperedge may be induced. "skip" leaves them out, for a reader that cannot hold one.	"all"

Returns:

Type	Description
int	The number of edges attached.

Raises:

Type	Description
ValueError	If mode or hyper is unknown.
KeyError	If the slice is unknown.

Examples:

>>> G.slices.induce_edges('selected')