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

# skfolio.portfolio.dependency_exposure

<a id="skfolio.portfolio.dependency_exposure"></a>

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

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:**
  **graph** *Graph or GraphSeries*
  : Dependency graph with nonnegative edge weights. For a `GraphSeries`, exposure
    is computed separately for each observation using its graph and weights.

  **asset_names** *array-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.

  **weights** *array-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_hops** *int, optional*
  : Maximum number of edges traversed when computing dependencies. Must be at
    least 1. If None, all direct and indirect dependencies are included.

  **nodes** *array-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:**
  **exposure** *DataFrame*
  : 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`.
    <br/>
    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:

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

