skfolio.portfolio.dependency_exposure#

skfolio.portfolio.dependency_exposure(graph, *, asset_names, weights, max_hops=None, nodes=None)[source]#

Compute portfolio exposure to direct and indirect dependencies.

The exposure to a node is the sum of portfolio weights of assets that depend on it, directly or indirectly, plus the portfolio weight of the node itself. An edge from A to B represents a dependency of A on B. Each asset is counted once per node. Any positive edge counts as a dependency, regardless of its weight.

Parameters:
graphGraph or GraphSeries

Dependency graph with nonnegative edge weights. For a GraphSeries, exposure is computed separately for each observation using its graph and weights.

asset_namesarray-like of shape (n_assets,)

Unique asset names corresponding to weights. Names must be strings. Assets with nonzero weights must appear in the corresponding graph.

weightsarray-like of shape (n_assets,) or (n_observations, n_assets)

Portfolio weights in the order of asset_names. A Graph requires one weight per asset. For a GraphSeries, a 1D array applies the same weights to every observation. A 2D array provides weights for each observation, in the order of graph.observations. Pandas index and column labels are not used. Weights are not normalized. Negative weights reduce exposure. Each row must contain only finite values or only NaN.

max_hopsint, optional

Maximum number of edges traversed when computing dependencies. Must be at least 1. If None, all direct and indirect dependencies are included.

nodesarray-like of shape (n_nodes,), optional

Unique string node names for which exposure is returned. If None, all graph nodes are included in order of first appearance. Paths can pass through other nodes. Required when every graph in a GraphSeries is None.

Returns:
exposureDataFrame

Exposure to each node, with columns:

  • weight: portfolio weight of the node itself.

  • direct: sum of weights of other assets with an edge to the node.

  • indirect: sum of weights of other assets connected to the node only through intermediate nodes.

  • total: sum of weight, direct and indirect.

Rows are indexed by dependency for a Graph, or by (observation, dependency) for a GraphSeries. Missing graphs or all-NaN weights give NaN exposure. A node absent from the graph at an observation has zero exposure.

Raises:
ValueError

If an asset with a nonzero weight is missing from its graph, or a requested node is missing from all graphs.

Notes

Let \(w_i\) denote the weight of asset \(i\). The exposure to node \(j\) is

\[e_j = \sum_i w_i \mathbf{1}\{i = j \text{ or } i \text{ reaches } j\}.\]

An asset’s own weight is included only in weight, even when a path returns to that asset. The same asset can contribute to several nodes, so exposures across nodes need not sum to one. Absolute portfolio weights give gross exposure.

Examples

Token B depends on Token A, which depends on a protocol:

>>> from skfolio.containers import Graph
>>> from skfolio.portfolio import dependency_exposure
>>> graph = Graph.from_edges(
...     [("Token A", "Protocol", 1), ("Token B", "Token A", 3)],
...     nodes=["Token A", "Token B", "Protocol"],
... )
>>> exposure = dependency_exposure(
...     graph, asset_names=["Token A", "Token B"], weights=[0.6, 0.4]
... )
>>> exposure
            weight  direct  indirect  total
dependency
Token A        0.6     0.4       0.0    1.0
Token B        0.4     0.0       0.0    0.4
Protocol       0.0     0.6       0.4    1.0