"""Portfolio analytics and shared helpers."""
# Copyright (c) 2023-2026
# Author: Hugo Delatte <hugo.delatte@skfoliolabs.com>
# SPDX-License-Identifier: BSD-3-Clause
from __future__ import annotations
from collections.abc import Sequence
from typing import TYPE_CHECKING
import numpy as np
import pandas as pd
import scipy.sparse as sps
import sklearn.utils.validation as skv
from scipy.sparse.csgraph import dijkstra
from skfolio.containers import Graph, GraphSeries
from skfolio.containers._utils import _as_string_labels
from skfolio.typing import AnyArray, ArrayLike, FloatArray, StrArray
from skfolio.utils.tools import _validate_positive_integer
if TYPE_CHECKING:
from skfolio.portfolio._portfolio import Portfolio
__all__ = ["dependency_exposure"]
_MAX_ARRAY_ELEMENTS = 1_000_000
[docs]
def dependency_exposure(
graph: Graph | GraphSeries,
*,
asset_names: ArrayLike,
weights: ArrayLike,
max_hops: int | None = None,
nodes: ArrayLike | None = None,
) -> pd.DataFrame:
r"""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`.
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 :math:`w_i` denote the weight of asset :math:`i`. The exposure to node
:math:`j` is
.. math::
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
"""
if not isinstance(graph, (Graph, GraphSeries)):
raise TypeError("graph must be a Graph or GraphSeries.")
if max_hops is not None:
_validate_positive_integer(max_hops, "max_hops")
asset_names = _as_string_labels(values=asset_names, name="asset_names")
is_history = isinstance(graph, GraphSeries)
n_observations = len(graph) if is_history else 1
weights = skv.check_array(
weights,
dtype=np.float64,
ensure_2d=False,
ensure_min_samples=0,
ensure_min_features=0,
ensure_all_finite="allow-nan",
input_name="weights",
)
if weights.shape != (len(asset_names),) and (
not is_history or weights.shape != (n_observations, len(asset_names))
):
raise ValueError(
"weights must have shape (n_assets,), or "
"(n_observations, n_assets) for a GraphSeries."
)
missing_weights = np.isnan(weights)
missing_weight_rows = missing_weights.any(axis=-1)
if np.any(missing_weight_rows & ~missing_weights.all(axis=-1)):
raise ValueError("weights must be finite or contain an entirely NaN row.")
missing_weight_rows = np.broadcast_to(missing_weight_rows, (n_observations,))
weights = np.broadcast_to(weights, (n_observations, len(asset_names)))
graph_observations: dict[Graph, list[int]] = {}
for position, snapshot in enumerate(graph if is_history else [graph]):
if snapshot is not None:
graph_observations.setdefault(snapshot, []).append(position)
all_nodes = np.asarray(
list(
dict.fromkeys(
node for snapshot in graph_observations for node in snapshot.nodes
)
),
dtype=str,
)
if nodes is None:
if n_observations and not graph_observations:
raise ValueError("nodes is required when every graph is missing.")
nodes = all_nodes
else:
nodes = _as_string_labels(values=nodes, name="nodes")
if graph_observations:
unknown = nodes[pd.Index(all_nodes).get_indexer(nodes) < 0]
if len(unknown):
raise ValueError(
f"Nodes absent from graphs ({len(unknown)}): "
f"{unknown[:5].tolist()}{'...' if len(unknown) > 5 else ''}."
)
contributions = np.full((n_observations, len(nodes), 3), np.nan)
for snapshot, positions in graph_observations.items():
positions = np.asarray(positions, dtype=np.intp)
positions = positions[~missing_weight_rows[positions]]
contributions[positions] = _graph_dependency_exposure(
graph=snapshot,
asset_names=asset_names,
weights=weights[positions],
nodes=nodes,
max_hops=max_hops,
observations=graph.observations[positions] if is_history else None,
)
index = (
pd.MultiIndex.from_product(
[graph.observations, nodes], names=["observation", "dependency"]
)
if is_history
else pd.Index(nodes, name="dependency")
)
exposure = pd.DataFrame(
contributions.reshape(-1, 3),
index=index,
columns=["weight", "direct", "indirect"],
)
exposure["total"] = contributions.sum(axis=2).ravel()
return exposure
def _graph_dependency_exposure(
*,
graph: Graph,
asset_names: StrArray,
weights: FloatArray,
nodes: StrArray,
max_hops: int | None,
observations: AnyArray | None,
) -> FloatArray:
"""Dependency exposure for observations sharing a graph.
Parameters
----------
graph : Graph
Graph used for all weight rows.
asset_names : StrArray of shape (n_assets,)
Asset identifiers corresponding to the weights.
weights : FloatArray of shape (n_observations, n_assets)
Finite portfolio weights for the selected observations.
nodes : StrArray of shape (n_nodes,)
Nodes for which exposure is computed, including nodes absent from this graph.
max_hops : int or None
Maximum number of edges traversed. If None, all direct and indirect
dependencies are included.
observations : AnyArray of shape (n_observations,) or None
Observation labels included in errors for missing assets. If None, errors do
not include an observation label.
Returns
-------
contributions : FloatArray of shape (n_observations, n_nodes, 3)
Portfolio weight, direct and indirect contributions for each node.
"""
adjacency = graph.adjacency
edge_weights = adjacency.data if isinstance(adjacency, sps.csr_array) else adjacency
if np.any(edge_weights < 0):
raise ValueError("dependency_exposure requires nonnegative graph edge weights.")
node_index = pd.Index(graph.nodes)
asset_node_positions = node_index.get_indexer(asset_names)
missing_assets = asset_node_positions < 0
missing_holdings = weights[:, missing_assets] != 0
if missing_holdings.any():
row = np.flatnonzero(missing_holdings.any(axis=1))[0]
missing_asset_names = asset_names[missing_assets][missing_holdings[row]]
when = "" if observations is None else f" at observation {observations[row]!r}"
raise ValueError(
f"Assets absent from graph{when} ({len(missing_asset_names)}): "
f"{missing_asset_names[:5].tolist()}"
f"{'...' if len(missing_asset_names) > 5 else ''}."
)
contributions = np.zeros((len(weights), len(nodes), 3))
held_assets = np.flatnonzero(np.any(weights != 0, axis=0))
node_positions = node_index.get_indexer(nodes)
report_positions = np.flatnonzero(node_positions >= 0)
if not len(held_assets) or not len(report_positions):
return contributions
# CSR conversion preserves tiny positive edges that SciPy's dense input treats
# as zero when constructing its graph.
adjacency = sps.csr_array(adjacency)
source_positions = asset_node_positions[held_assets]
target_positions = node_positions[report_positions]
# Starting at selected nodes in the reversed graph gives the same hop counts
# to assets, with fewer traversals when few nodes are selected.
reverse = len(target_positions) < len(source_positions)
if reverse:
adjacency = adjacency.T.tocsr()
source_positions, target_positions = target_positions, source_positions
chunk_size = max(1, _MAX_ARRAY_ELEMENTS // graph.n_nodes)
for start in range(0, len(source_positions), chunk_size):
chunk = slice(start, start + chunk_size)
hop_counts = dijkstra(
csgraph=adjacency,
directed=True,
indices=source_positions[chunk],
return_predecessors=False,
unweighted=True,
limit=np.inf if max_hops is None else max_hops,
)[:, target_positions]
if reverse:
hop_counts = hop_counts.T
asset_indices = held_assets
report_indices = report_positions[chunk]
else:
asset_indices = held_assets[chunk]
report_indices = report_positions
chunk_weights = weights[:, asset_indices]
contributions[:, report_indices, 0] += chunk_weights @ (hop_counts == 0)
contributions[:, report_indices, 1] += chunk_weights @ (hop_counts == 1)
contributions[:, report_indices, 2] += chunk_weights @ (
(hop_counts > 1) & np.isfinite(hop_counts)
)
return contributions
def _select_graph_observations(
*, graphs: GraphSeries, observations: AnyArray
) -> GraphSeries:
"""Graphs selected by portfolio observation labels.
Parameters
----------
graphs : GraphSeries
Graph history covering the requested observations.
observations : AnyArray of shape (n_observations,)
Portfolio observation labels in the order to return.
Returns
-------
selected : GraphSeries
Graph series matching the requested observations.
Raises
------
ValueError
If an observation is missing, or `graphs.observations` contains duplicates and
does not match `observations` in both values and order.
"""
if np.array_equal(graphs.observations, observations):
return graphs
graph_index = pd.Index(graphs.observations)
if not graph_index.is_unique:
raise ValueError(
"GraphSeries observations must be unique unless they match the "
"portfolio observations exactly."
)
positions = graph_index.get_indexer(observations)
if np.any(positions < 0):
missing = observations[positions < 0]
raise ValueError(
f"Portfolio observations absent from GraphSeries ({len(missing)}): "
f"{missing[:5].tolist()}{'...' if len(missing) > 5 else ''}."
)
return graphs[positions] # ty: ignore[invalid-return-type] # array selectors return GraphSeries
def _get_weights_per_observation(
*,
portfolios: Sequence[Portfolio],
asset_names: StrArray,
source: str = "target assets",
) -> FloatArray:
"""Asset weights at the start of each observation across portfolios.
Parameters
----------
portfolios : sequence of Portfolio
Portfolios in the order to concatenate.
asset_names : StrArray of shape (n_assets,)
Target asset names defining the output columns.
source : str, default="target assets"
Label identifying the target assets in error messages.
Returns
-------
weights : FloatArray of shape (n_observations, n_assets)
Weights following each portfolio's `weight_drift` setting, including small and
zero positions. Assets absent from a portfolio receive zero weight. Missing
allocations give NaN rows.
Raises
------
ValueError
If a portfolio with known weights contains an asset absent from `asset_names`.
"""
n_observations = sum(portfolio.n_observations for portfolio in portfolios)
weights = np.full((n_observations, len(asset_names)), np.nan)
start = 0
for portfolio in portfolios:
stop = start + portfolio.n_observations
if not np.isnan(portfolio.weights).any():
weights[start:stop] = _align_weights(
weights=portfolio._get_weights_per_observation(),
asset_names=portfolio.assets,
target_asset_names=asset_names,
source=source,
)
start = stop
return weights
def _align_weights(
*,
weights: FloatArray,
asset_names: StrArray,
target_asset_names: StrArray,
source: str = "target assets",
) -> FloatArray:
"""Align portfolio weights with target asset names.
Parameters
----------
weights : FloatArray of shape (..., n_assets)
Portfolio weights. The last axis corresponds to `asset_names`.
asset_names : StrArray of shape (n_assets,)
Asset identifiers corresponding to the weights.
target_asset_names : StrArray of shape (n_target_assets,)
Target asset identifiers in the desired order.
source : str, default="target assets"
Label identifying the target in error messages.
Returns
-------
aligned : FloatArray of shape (..., n_target_assets)
Weights in target asset order. Additional target assets receive zero.
Raises
------
ValueError
If an input asset is absent from `target_asset_names`.
"""
if np.array_equal(asset_names, target_asset_names):
return weights
positions = pd.Index(target_asset_names).get_indexer(asset_names)
missing = asset_names[positions < 0]
if len(missing):
raise ValueError(
f"Portfolio contains {len(missing)} asset(s) not in {source}: "
f"{missing[:5].tolist()}{'...' if len(missing) > 5 else ''}."
)
aligned = np.zeros(
(*weights.shape[:-1], len(target_asset_names)), dtype=weights.dtype
)
aligned[..., positions] = weights
return aligned