skfolio.containers.GraphSeries#
- class skfolio.containers.GraphSeries(graphs, *, observations=None)[source]#
Graphs indexed by observation.
Each observation has a
GraphorNone. 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
Nonewhen 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 ton_observations - 1. Timezone-aware dates retain their timezone and must share one timezone.
- Attributes:
n_observationsintNumber 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
Graphobject 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
GraphorNone, 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
GraphSeriesatpath. 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,).