skfolio.containers.GraphSeries#

class skfolio.containers.GraphSeries(graphs, *, observations=None)[source]#

Graphs indexed by observation.

Each observation has a Graph or None. Repeated uses of the same graph share storage. Graphs can contain different nodes.

Parameters:
graphsfinite iterable of Graph or None

Graph for each observation. Use None when no graph is available.

observationsarray-like of shape (n_observations,), optional

Observation labels in the same order as graphs. If None, use integer labels from 0 to n_observations - 1. Timezone-aware dates retain their timezone and must share one timezone.

Attributes:
n_observationsint

Number of observations.

missing_maskndarray of bool of shape (n_observations,)

Boolean mask indicating observations with no graph.

Methods

copy(*[, deep])

Return a copy of the series.

items()

Iterate over observation labels and graphs.

load(path)

Load a saved graph series.

save(path, *[, overwrite])

Save the series to a directory.

Notes

For point-in-time use, supply only information available at each observation. Reuse the last known graph while it remains applicable. Missing graphs are not filled automatically.

When used as metadata, the series must have the same observation order and length as X. Selecting observations preserves the graphs and their complete node sets.

For a static graph, repeat the same Graph object for every observation.

Examples

A supplier relationship is known from January 2, and a second is added on January 4. No graph is available before January 2:

>>> import pandas as pd
>>> from skfolio.containers import Graph, GraphSeries
>>> dates = pd.date_range("2025-01-01", periods=4)
>>> nodes = ["A", "Supplier 1", "Supplier 2"]
>>> initial_graph = Graph.from_edges([("A", "Supplier 1", 1)], nodes=nodes)
>>> updated_graph = Graph.from_edges(
...     [("A", "Supplier 1", 1), ("A", "Supplier 2", 1)], nodes=nodes
... )
>>> graphs = GraphSeries(
...     [None, initial_graph, initial_graph, updated_graph], observations=dates
... )
>>> graphs
GraphSeries(n_observations=4, n_graphs=2)

The graph at the final observation contains both relationships:

>>> graphs[-1]
Graph(n_nodes=3, n_edges=2)

Select the last two observations:

>>> recent_graphs = graphs[2:]
>>> recent_graphs
GraphSeries(n_observations=2, n_graphs=2)

Iterate over the selected graphs:

>>> list(recent_graphs)
[Graph(n_nodes=3, n_edges=1), Graph(n_nodes=3, n_edges=2)]

For a static graph known throughout the sample:

>>> from itertools import repeat
>>> static_graphs = GraphSeries(repeat(initial_graph, len(dates)), observations=dates)
copy(*, deep=False)[source]#

Return a copy of the series.

The copy retains only graphs used by its observations.

Parameters:
deepbool, default=False

If True, copy each distinct graph. If False, share the original graphs.

Returns:
seriesGraphSeries

Copy with independent observation labels.

items()[source]#

Iterate over observation labels and graphs.

Returns:
itemsiterator of (observation, graph) tuples

Observation labels paired with their Graph or None, in series order.

classmethod load(path)[source]#

Load a saved graph series.

Parameters:
pathstr or pathlib.Path

Directory containing a saved GraphSeries.

Returns:
seriesGraphSeries

Loaded series. Repeated graphs remain shared.

property missing_mask#

Boolean mask indicating observations with no graph.

property n_observations#

Number of observations.

property ndim#

Number of dimensions, always 1.

save(path, *, overwrite=False)[source]#

Save the series to a directory.

Parameters:
pathstr or pathlib.Path

Destination directory.

overwritebool, default=False

If True, replace an existing saved GraphSeries at path. Other directories cannot be overwritten.

Raises:
ValueError

If the destination is invalid or the observations’ timezone cannot be saved.

property shape#

Shape of the series, (n_observations,).