8000 GitHub - tschm/pyhrp: Cluster-based portfolio allocation on an explicit, inspectable tree: hierarchical risk parity, Schur complementary allocation and hierarchical 1/N · GitHub
[go: up one dir, main page]

Skip to content
  • tschmPublic

    About

    Cluster-based portfolio allocation on an explicit, inspectable tree: hierarchical risk parity, Schur complementary allocation and hierarchical 1/N

    Topics

    Resources

    Code of conduct

    Contributing

    Security policy

    Stars

    55 stars

    Watchers

    2 watching

    Forks

    Repository files navigation

    PyPI version Python Downloads License CodeFactor

    Coverage

    A recursive implementation of the Hierarchical Risk Parity (HRP) approach by Marcos Lopez de Prado. We take advantage of the scipy.cluster.hierarchy package.

    Comparing 'ward' with 'single' and bisection

    Motivation

    Mean-variance optimisation is often unstable in practice because small estimation errors in expected returns can lead to large and concentrated weight shifts. Hierarchical Risk Parity avoids explicit return forecasting and instead allocates risk recursively along a clustering tree built from asset co-movement. By grouping correlated assets before sizing positions, HRP tends to distribute risk across more independent sources, which can improve diversification. In short, HRP keeps the intuition of risk budgeting while adding structure from correlation-based clustering.

    Method comparison

    The method argument controls how the first clustering tree is built:

    Linkage method When to use it
    ward Default choice when you want compact, variance-minimizing clusters and generally stable, balanced trees.
    single Useful when preserving nearest-neighbour chains matters (can create long, unbalanced trees on noisy data).
    average Middle ground between single and complete when you want moderate sensitivity to pairwise distances.
    complete Prefer when you want tighter, diameter-controlled clusters and to avoid chaining effects from single.

    Setting bisection=True keeps the leaf order induced by the chosen linkage method, then rebuilds the tree by repeatedly splitting that ordered list in half. This often produces a more balanced hierarchy than the raw linkage tree and matches the bisection-style construction discussed in HRP literature.

    Here's a simple example

    import polars as pl
    from pyhrp import build_tree, compute_cov, compute_corr, compute_returns, risk_parity
    
    prices = pl.read_csv("tests/resources/stock_prices.csv", try_parse_dates=True).drop("date")
    
    returns = compute_returns(prices)
    cov = compute_cov(returns)
    cor = compute_corr(returns)
    
    # Compute the dendrogram based on the correlation matrix and Ward's metric
    dendrogram = build_tree(cor, method="ward")
    dendrogram.plot()
    
    # Compute the weights on the dendrogram
    root = risk_parity(root=dendrogram.root, cov=cov)
    root.portfolio.plot(names=dendrogram.names)

    For your convenience you can bypass the construction of the covariance and correlation matrix, and the construction of the dendrogram.

    from pyhrp import hrp
    
    root = hrp(prices=prices, method="ward", bisection=False)

    Schur Complementary Allocation

    Plain HRP splits risk between two clusters using only the covariance within each cluster, discarding the cross-block terms. Schur Complementary Allocation (Peter Cotton, arXiv:2411.05807) augments each sub-block with that discarded information via a Schur complement before splitting, and gamma controls how much of it is put back:

    gamma Behaviour
    0.0 No augmentation — identical to plain HRP, weight for weight.
    0.5 Default. Half the cross-block information is restored; a middle ground that keeps HRP's diversification while trimming portfolio variance.
    1.0 Full augmentation — recovers the global minimum-variance portfolio, but through the same recursive hierarchy rather than a single unconstrained solve.

    Raising gamma trades HRP's robustness for lower in-sample variance, so it is the knob to reach for when the covariance estimate is trustworthy. Values outside [0, 1] raise ValueError. Use schur_hrp for the end-to-end pipeline, or schur_risk_parity to size a tree you already built.

    from pyhrp import schur_hrp
    
    conservative = schur_hrp(prices=prices, method="ward", gamma=0.0)
    balanced = schur_hrp(prices=prices, method="ward", gamma=0.5)
    min_variance = schur_hrp(prices=prices, method="ward", gamma=1.0)
    
    print("gamma=0 reproduces HRP:", conservative.portfolio.weights == root.portfolio.weights)
    print(
        "variance falls as gamma rises:",
        min_variance.portfolio.variance(cov) < balanced.portfolio.variance(cov) < conservative.portfolio.variance(cov),
    )
    gamma=0 reproduces HRP: True
    variance falls as gamma rises: True
    

    Interpreting results

    The hrp() function returns a Cluster node (the tree root), not a plain weight series. You can navigate the hierarchy directly via root.left and root.right to inspect how the recursive allocation split risk at each branch. To get a flat asset-to-weight mapping for downstream use, access root.portfolio.weights.

    weights = root.portfolio.weights
    variance = root.portfolio.variance(cov)
    
    # You can drill deeper into the tree
    left = root.left
    right = root.right

    The comparison image above is generated from code in book/scripts/demo.py. Regenerate it with:

    uv run --with kaleido book/scripts/demo.py

    Package layout

    The src/pyhrp/ package is split into small, focused modules:

    Module Responsibility
    hrp.py High-level entry points. Turns a price/return frame into a weighted tree: compute_returns/compute_cov/compute_corr build the matrices, build_tree produces the Dendrogram, and hrp/schur_hrp run the full pipeline end to end.
    algos.py The allocation algorithms that size a cluster tree: risk_parity (recursive HRP), schur_risk_parity (Schur Complementary Allocation), and one_over_n (equal weight).
    cluster.py Core data structures — Cluster (a node in the hierarchical tree) and Portfolio (an asset-to-weight mapping with analysis/plot helpers).
    treelib.py A minimal generic binary-tree Node, kept in-house to avoid a binarytree dependency.
    plot.py Plotly dendrogram rendering (plot_dendrogram), kept separate so the optional plotting dependency does not couple the algorithm modules.
    __init__.py Public API surface — re-exports the functions and classes above and exposes __version__.

    uv

    Starting with

    make install

    will install uv and create the virtual environment defined in pyproject.toml and locked in uv.lock.

    marimo

    We install marimo on the fly within the aforementioned virtual environment. Executing

    make marimo

    will install and start marimo.

    About

    Cluster-based portfolio allocation on an explicit, inspectable tree: hierarchical risk parity, Schur complementary allocation and hierarchical 1/N

    Topics

    Resources

    Code of conduct

    Contributing

    Security policy

    Stars

    55 stars

    Watchers

    2 watching

    Forks

    Releases

    Used by

    Contributors

    Languages

  • 0