<a id="sphx-glr-auto-examples-clustering-plot-graph-distance-py"></a>

<a id="hierarchical-equal-risk-contribution-with-graph-distance"></a>

# Hierarchical Equal Risk Contribution with Graph Distance

[`GraphDistance`](https://skfolio.org/generated/skfolio.distance.GraphDistance.html.md#skfolio.distance.GraphDistance) measures similarity between assets based on
their dependencies. This supports diversification across underlying vulnerabilities,
including risks that have not materialized historically and are not captured by
return correlations.

This tutorial compares two
[`HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution) (HERC) models for a
portfolio of six electric car manufacturers. The first uses return correlations to
cluster the stocks. The second uses [`GraphDistance`](https://skfolio.org/generated/skfolio.distance.GraphDistance.html.md#skfolio.distance.GraphDistance), based on
shared dependencies on battery, lithium and chip suppliers. Both models then allocate
weights using risks estimated from returns.

<a id="returns"></a>

## Returns

We’ll simulate returns for six stocks, Stock1 through Stock6, representing fictional
electric car manufacturers, in 2024 and 2025. Each return combines a shared sector
component with independent company noise:

```Python
from itertools import repeat

import numpy as np
import pandas as pd
from plotly.io import show
from sklearn import set_config
from sklearn.model_selection import train_test_split

from skfolio.containers import Graph, GraphSeries
from skfolio.distance import GraphDistance
from skfolio.optimization import HierarchicalEqualRiskContribution

set_config(enable_metadata_routing=True)

asset_names = ["Stock1", "Stock2", "Stock3", "Stock4", "Stock5", "Stock6"]
dates = pd.date_range("2024-01-01", "2025-12-31", freq="B")

rng = np.random.default_rng(0)
sector_returns = rng.normal(0.0002, 0.01, size=(len(dates), 1))
stock_returns = sector_returns + rng.normal(0, 0.005, size=(len(dates), 6))

X = pd.DataFrame(stock_returns, index=dates, columns=asset_names)
X.head()
```

<div class="output_subarea output_html rendered_html output_result">
<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Stock1</th>
      <th>Stock2</th>
      <th>Stock3</th>
      <th>Stock4</th>
      <th>Stock5</th>
      <th>Stock6</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>2024-01-01</th>
      <td>0.000270</td>
      <td>0.005153</td>
      <td>-0.001099</td>
      <td>0.010591</td>
      <td>0.002907</td>
      <td>0.000944</td>
    </tr>
    <tr>
      <th>2024-01-02</th>
      <td>0.006125</td>
      <td>0.002010</td>
      <td>0.000725</td>
      <td>-0.002777</td>
      <td>0.007949</td>
      <td>0.002938</td>
    </tr>
    <tr>
      <th>2024-01-03</th>
      <td>0.005587</td>
      <td>-0.001282</td>
      <td>0.008469</td>
      <td>0.000886</td>
      <td>-0.001976</td>
      <td>0.005208</td>
    </tr>
    <tr>
      <th>2024-01-04</th>
      <td>0.002656</td>
      <td>0.007661</td>
      <td>0.002661</td>
      <td>0.005279</td>
      <td>-0.004880</td>
      <td>0.001136</td>
    </tr>
    <tr>
      <th>2024-01-05</th>
      <td>-0.004536</td>
      <td>-0.000845</td>
      <td>-0.004576</td>
      <td>-0.001136</td>
      <td>-0.007678</td>
      <td>-0.003367</td>
    </tr>
  </tbody>
</table>
</div>
</div>
<br />
<br />

<a id="dependency-graph"></a>

## Dependency Graph

Let’s assume each company buys batteries from a different supplier. Several
battery suppliers depend on the same lithium producer, while the manufacturers
also share chip suppliers.

A disruption at a lithium producer can therefore affect manufacturers that buy
batteries from different companies. The graph records these direct and indirect
dependencies.

Edge weights express relative dependency strengths. We’ll use illustrative weights
of 3 for each manufacturer’s battery dependency and 1 for its chip dependency.
Each battery supplier’s link to its lithium producer has weight 1:

```Python
graph = Graph.from_edges(
    edges=[
        ("Stock1", "Battery1", 3),
        ("Stock1", "ChipA", 1),
        ("Stock2", "Battery2", 3),
        ("Stock2", "ChipA", 1),
        ("Stock3", "Battery3", 3),
        ("Stock3", "ChipA", 1),
        ("Stock4", "Battery4", 3),
        ("Stock4", "ChipB", 1),
        ("Stock5", "Battery5", 3),
        ("Stock5", "ChipA", 1),
        ("Stock6", "Battery6", 3),
        ("Stock6", "ChipB", 1),
        ("Battery1", "LithiumA", 1),
        ("Battery2", "LithiumA", 1),
        ("Battery3", "LithiumA", 1),
        ("Battery4", "LithiumA", 1),
        ("Battery5", "LithiumB", 1),
        ("Battery6", "LithiumB", 1),
    ],
    nodes=[
        *asset_names,
        "Battery1",
        "Battery2",
        "Battery3",
        "Battery4",
        "Battery5",
        "Battery6",
        "LithiumA",
        "LithiumB",
        "ChipA",
        "ChipB",
    ],
)
```

Let’s plot the graph with a color for each type of node. Hovering over an edge shows
its weight:

```Python
fig = graph.plot(
    groups={
        "Stock1": "Stocks",
        "Stock2": "Stocks",
        "Stock3": "Stocks",
        "Stock4": "Stocks",
        "Stock5": "Stocks",
        "Stock6": "Stocks",
        "Battery1": "Battery suppliers",
        "Battery2": "Battery suppliers",
        "Battery3": "Battery suppliers",
        "Battery4": "Battery suppliers",
        "Battery5": "Battery suppliers",
        "Battery6": "Battery suppliers",
        "LithiumA": "Lithium producers",
        "LithiumB": "Lithium producers",
        "ChipA": "Chip suppliers",
        "ChipB": "Chip suppliers",
    },
    title="Automotive Supply Chain",
)
show(fig)
```

[plotly figure stripped from llms output]

Relationships can change over time. A point-in-time (PIT) history records the graph
known at each return date. We’ll use a [`GraphSeries`](https://skfolio.org/generated/skfolio.containers.GraphSeries.html.md#skfolio.containers.GraphSeries) to
keep this history aligned with `X`.

Here, we’ll assume the relationships were known throughout the sample and remained
unchanged. Each observation uses the same graph, which `GraphSeries` stores only
once:

```Python
graphs = GraphSeries(repeat(graph, len(X)), observations=X.index)
```

<a id="models"></a>

## Models

We’ll use the first 75% of observations for training and the remaining 25% for
testing. Splitting returns and graphs together keeps them aligned. Setting
`shuffle=False` preserves their chronological order:

```Python
X_train, X_test, graphs_train, graphs_test = train_test_split(
    X, graphs, test_size=0.25, shuffle=False
)
```

The first model uses HERC’s default Pearson distance:

```Python
default_model = HierarchicalEqualRiskContribution()
default_model.fit(X_train)
print(default_model.weights_)
```

```none
[0.10957878 0.46190787 0.10816811 0.1106225  0.10720999 0.10251276]
```

Stock2 receives 46.2% of the portfolio. Together, Stock1, Stock2 and Stock3 account for
68.0%. Although they buy from different battery suppliers, all three depend on
LithiumA and ChipA.

The second model uses graph distances. By default, dependencies up to two edges
away are included, such as `Stock1 -> Battery1 -> LithiumA`.
Metadata routing passes the training graphs to the distance estimator:

```Python
graph_model = HierarchicalEqualRiskContribution(distance_estimator=GraphDistance())
graph_model.fit(X_train, graphs=graphs_train)
print(graph_model.weights_)
```

```none
[0.09453738 0.09357702 0.09332034 0.24755087 0.24078193 0.23023246]
```

With graph distances, the combined weight of Stock1, Stock2 and Stock3 falls from
68.0% to 28.1%. Stock4, Stock5 and Stock6 each receive about 23% to 25%.

The portfolio is less concentrated in companies that depend on both LithiumA and
ChipA. Both models use the same returns to estimate risk, so this change comes from
clustering stocks by their dependencies.

<a id="clustering"></a>

## Clustering

Let’s compare the two dendrograms and distance heatmaps. The yellow boxes mark the
clusters used by HERC:

```Python
fig = default_model.hierarchical_clustering_estimator_.plot_dendrogram()
fig.update_layout(title="HERC with Return Distances")
```

[plotly figure stripped from llms output]
<br />
<br />

```Python
fig = graph_model.hierarchical_clustering_estimator_.plot_dendrogram()
fig.update_layout(title="HERC with Graph Distances")
```

[plotly figure stripped from llms output]
<br />
<br />

With return distances, Stock2 forms a cluster on its own, while the other five
stocks form the second cluster.

With graph distances, Stock1, Stock2 and Stock3 form a cluster because they share
LithiumA and ChipA. Following the battery suppliers’ dependencies identifies their
common lithium producer. Stock4, Stock5 and Stock6 form separate clusters, each with
a different combination of lithium and chip suppliers.

<a id="dependency-exposure"></a>

## Dependency Exposure

Let’s compare supplier exposures for both portfolios using
[`dependency_exposure`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.dependency_exposure). A supplier’s exposure is
the combined initial weight of manufacturers that depend on it, directly or
indirectly. Each stock is counted once per supplier, regardless of edge weights.

For the model using return distances:

```Python
default_portfolio = default_model.predict(X_test)
default_portfolio.dependency_exposure(graph)
```

<div class="output_subarea output_html rendered_html output_result">
<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>weight</th>
      <th>direct</th>
      <th>indirect</th>
      <th>total</th>
    </tr>
    <tr>
      <th>dependency</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Stock1</th>
      <td>0.109579</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.109579</td>
    </tr>
    <tr>
      <th>Stock2</th>
      <td>0.461908</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.461908</td>
    </tr>
    <tr>
      <th>Stock3</th>
      <td>0.108168</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.108168</td>
    </tr>
    <tr>
      <th>Stock4</th>
      <td>0.110622</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.110622</td>
    </tr>
    <tr>
      <th>Stock5</th>
      <td>0.107210</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.107210</td>
    </tr>
    <tr>
      <th>Stock6</th>
      <td>0.102513</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.102513</td>
    </tr>
    <tr>
      <th>Battery1</th>
      <td>0.000000</td>
      <td>0.109579</td>
      <td>0.000000</td>
      <td>0.109579</td>
    </tr>
    <tr>
      <th>Battery2</th>
      <td>0.000000</td>
      <td>0.461908</td>
      <td>0.000000</td>
      <td>0.461908</td>
    </tr>
    <tr>
      <th>Battery3</th>
      <td>0.000000</td>
      <td>0.108168</td>
      <td>0.000000</td>
      <td>0.108168</td>
    </tr>
    <tr>
      <th>Battery4</th>
      <td>0.000000</td>
      <td>0.110622</td>
      <td>0.000000</td>
      <td>0.110622</td>
    </tr>
    <tr>
      <th>Battery5</th>
      <td>0.000000</td>
      <td>0.107210</td>
      <td>0.000000</td>
      <td>0.107210</td>
    </tr>
    <tr>
      <th>Battery6</th>
      <td>0.000000</td>
      <td>0.102513</td>
      <td>0.000000</td>
      <td>0.102513</td>
    </tr>
    <tr>
      <th>LithiumA</th>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.790277</td>
      <td>0.790277</td>
    </tr>
    <tr>
      <th>LithiumB</th>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.209723</td>
      <td>0.209723</td>
    </tr>
    <tr>
      <th>ChipA</th>
      <td>0.000000</td>
      <td>0.786865</td>
      <td>0.000000</td>
      <td>0.786865</td>
    </tr>
    <tr>
      <th>ChipB</th>
      <td>0.000000</td>
      <td>0.213135</td>
      <td>0.000000</td>
      <td>0.213135</td>
    </tr>
  </tbody>
</table>
</div>
</div>
<br />
<br />

For the model using graph distances:

```Python
graph_portfolio = graph_model.predict(X_test)
graph_portfolio.dependency_exposure(graph)
```

<div class="output_subarea output_html rendered_html output_result">
<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>weight</th>
      <th>direct</th>
      <th>indirect</th>
      <th>total</th>
    </tr>
    <tr>
      <th>dependency</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Stock1</th>
      <td>0.094537</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.094537</td>
    </tr>
    <tr>
      <th>Stock2</th>
      <td>0.093577</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.093577</td>
    </tr>
    <tr>
      <th>Stock3</th>
      <td>0.093320</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.093320</td>
    </tr>
    <tr>
      <th>Stock4</th>
      <td>0.247551</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.247551</td>
    </tr>
    <tr>
      <th>Stock5</th>
      <td>0.240782</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.240782</td>
    </tr>
    <tr>
      <th>Stock6</th>
      <td>0.230232</td>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.230232</td>
    </tr>
    <tr>
      <th>Battery1</th>
      <td>0.000000</td>
      <td>0.094537</td>
      <td>0.000000</td>
      <td>0.094537</td>
    </tr>
    <tr>
      <th>Battery2</th>
      <td>0.000000</td>
      <td>0.093577</td>
      <td>0.000000</td>
      <td>0.093577</td>
    </tr>
    <tr>
      <th>Battery3</th>
      <td>0.000000</td>
      <td>0.093320</td>
      <td>0.000000</td>
      <td>0.093320</td>
    </tr>
    <tr>
      <th>Battery4</th>
      <td>0.000000</td>
      <td>0.247551</td>
      <td>0.000000</td>
      <td>0.247551</td>
    </tr>
    <tr>
      <th>Battery5</th>
      <td>0.000000</td>
      <td>0.240782</td>
      <td>0.000000</td>
      <td>0.240782</td>
    </tr>
    <tr>
      <th>Battery6</th>
      <td>0.000000</td>
      <td>0.230232</td>
      <td>0.000000</td>
      <td>0.230232</td>
    </tr>
    <tr>
      <th>LithiumA</th>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.528986</td>
      <td>0.528986</td>
    </tr>
    <tr>
      <th>LithiumB</th>
      <td>0.000000</td>
      <td>0.000000</td>
      <td>0.471014</td>
      <td>0.471014</td>
    </tr>
    <tr>
      <th>ChipA</th>
      <td>0.000000</td>
      <td>0.522217</td>
      <td>0.000000</td>
      <td>0.522217</td>
    </tr>
    <tr>
      <th>ChipB</th>
      <td>0.000000</td>
      <td>0.477783</td>
      <td>0.000000</td>
      <td>0.477783</td>
    </tr>
  </tbody>
</table>
</div>
</div>
<br />
<br />

LithiumA exposure falls from 79.0% to 52.9%, and ChipA exposure from 78.7% to 52.2%.
Both lithium producers and both chip suppliers now have exposures close to 50%.

The graph shows that companies with different battery suppliers can still depend
on the same lithium producer. Using these dependencies in HERC reduces the
portfolio’s concentration in companies exposed to the same supplier disruption,
even though their returns are correlated.

**Total running time of the script:** (0 minutes 0.703 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-graph-distance-py"></a>
[![Launch JupyterLite](auto_examples/clustering/images/jupyterlite_badge_logo.svg)](../../lite/lab/index.html?path=auto_examples/clustering/plot_graph_distance.ipynb)

[`Download Jupyter notebook: plot_graph_distance.ipynb`](https://skfolio.org/auto_examples/clustering/_downloads/82122cc0cd884f9272515bbe97726799/plot_graph_distance.ipynb)

[`Download Python source code: plot_graph_distance.py`](https://skfolio.org/auto_examples/clustering/_downloads/bbcbc0bb0c9034e818bb3b6fd9ec0d9b/plot_graph_distance.py)

[`Download zipped: plot_graph_distance.zip`](https://skfolio.org/auto_examples/clustering/_downloads/753ce7dc0175425441f1bd47c0664c25/plot_graph_distance.zip)

[Gallery generated by Sphinx-Gallery](https://sphinx-gallery.github.io)
