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. AGraphrequires one weight per asset. For aGraphSeries, a 1D array applies the same weights to every observation. A 2D array provides weights for each observation, in the order ofgraph.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
GraphSeriesis 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 ofweight,directandindirect.
Rows are indexed by
dependencyfor aGraph, or by (observation,dependency) for aGraphSeries. 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