<a id="skfolio-containers-graphseries"></a>

# skfolio.containers.GraphSeries

<a id="skfolio.containers.GraphSeries"></a>

### *class* skfolio.containers.GraphSeries(graphs, \*, observations=None)

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:**
  **graphs** *finite iterable of Graph or None*
  : Graph for each observation. Use `None` when no graph is available.

  **observations** *array-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_observations`](#skfolio.containers.GraphSeries.n_observations) *int*
  : Number of observations.

  [`missing_mask`](#skfolio.containers.GraphSeries.missing_mask) *ndarray of bool of shape (n_observations,)*
  : Boolean mask indicating observations with no graph.

### Methods

| [`copy`](#skfolio.containers.GraphSeries.copy)(\*[, deep])            | Return a copy of the series.                |
|------------------------------------------------------------------------------|---------------------------------------------|
| [`items`](#skfolio.containers.GraphSeries.items)()                     | Iterate over observation labels and graphs. |
| [`load`](#skfolio.containers.GraphSeries.load)(path)                  | Load a saved graph series.                  |
| [`save`](#skfolio.containers.GraphSeries.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:

```pycon
>>> 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:

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

Select the last two observations:

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

Iterate over the selected graphs:

```pycon
>>> 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:

```pycon
>>> from itertools import repeat
>>> static_graphs = GraphSeries(repeat(initial_graph, len(dates)), observations=dates)
```

<a id="skfolio.containers.GraphSeries.copy"></a>

#### copy(\*, deep=False)

Return a copy of the series.

The copy retains only graphs used by its observations.

* **Parameters:**
  **deep** *bool, default=False*
  : If True, copy each distinct graph. If False, share the original graphs.
* **Returns:**
  **series** *GraphSeries*
  : Copy with independent observation labels.

<a id="skfolio.containers.GraphSeries.items"></a>

#### items()

Iterate over observation labels and graphs.

* **Returns:**
  **items** *iterator of (observation, graph) tuples*
  : Observation labels paired with their `Graph` or `None`, in series order.

<a id="skfolio.containers.GraphSeries.load"></a>

#### *classmethod* load(path)

Load a saved graph series.

* **Parameters:**
  **path** *str or pathlib.Path*
  : Directory containing a saved `GraphSeries`.
* **Returns:**
  **series** *GraphSeries*
  : Loaded series. Repeated graphs remain shared.

<a id="skfolio.containers.GraphSeries.missing_mask"></a>

#### *property* missing_mask

Boolean mask indicating observations with no graph.

<a id="skfolio.containers.GraphSeries.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.GraphSeries.ndim"></a>

#### *property* ndim

Number of dimensions, always 1.

<a id="skfolio.containers.GraphSeries.save"></a>

#### save(path, \*, overwrite=False)

Save the series to a directory.

* **Parameters:**
  **path** *str or pathlib.Path*
  : Destination directory.

  **overwrite** *bool, 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.

<a id="skfolio.containers.GraphSeries.shape"></a>

#### *property* shape

Shape of the series, `(n_observations,)`.

