pyhrp
A recursive implementation of the Hierarchical Risk Parity (HRP) approach by Marcos Lopez de Prado. We take advantage of the scipy.cluster.hierarchy package.
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.
1 maintainer
Metadata
1 maintainer
Release files for pyhrp 2.3.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyhrp-2.3.4.tar.gz | 340.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyhrp-2.3.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 363.1 kB
Release files / pyhrp-2.3.4.tar.gz
| Download URL | pyhrp-2.3.4.tar.gz |
|---|---|
| Size | 340.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d74ff2a852ea806b7068fdbbf8f235f42094787f78f55f4a515b0fbbb3f3b20
|
|
BLAKE2b-256 checksum How to use checksums |
f3ab1b417c83de77bd33d18358a230ad1275fbefb27d698ad70cae1dd64b5559
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / pyhrp-2.3.4-py3-none-any.whl
| Download URL | pyhrp-2.3.4-py3-none-any.whl |
|---|---|
| Size | 23.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a174a0522bbff0135bc83f0c136f5001feb63b8bd2ed0a98734208c71b8348e4
|
|
BLAKE2b-256 checksum How to use checksums |
80c914db1ecb88337f5e8f0a33b8ce715028c179828a5fbd4606442e11d8cb49
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
