Skip to main content

rwls

Regime-weighted least squares (RWLS) for estimating regime-dependent factor models.

The estimator

Factor models usually assume that an asset's exposures to common risk factors are constant. In practice, betas, factor premia and idiosyncratic risk shift with market conditions. RWLS estimates a separate factor model for every asset in every latent market regime, without fitting a regime-switching model asset by asset.

Estimation proceeds in two stages.

  1. Regime identification. A multivariate Gaussian hidden Markov model is fitted to a small set of common factor returns f_t. Its posterior probabilities γ_t(s) = P(S_t = s | data) measure how strongly each period belongs to each regime s.

  2. Regime-weighted regressions. For each asset i and regime s, the loadings solve a weighted least-squares problem in which each observation is weighted by its posterior regime probability:

    (α_is, β_is) = argmin  Σ_t γ_t(s) * (r_it - α - β' f_t)^2
    

    The regime-specific residual variance is measured on the regime's effective sample, the posterior mass n_s = Σ_t γ_t(s):

    σ²_is = Σ_t γ_t(s) * e_it^2 / (n_s - k)
    

    where k is the number of regression coefficients.

Every observation contributes to every regime in proportion to the evidence that it belongs there. Assets are not hard-classified, and no observation is discarded. Because all assets share the same factor history and weights, the regressions for a whole cross-section are solved jointly. The cost of adding an asset is one weighted regression per regime, which makes the approach practical for universes of thousands of securities.

From loadings to regime-conditional moments

The factor means m_s and covariances V_s of each regime are computed with the same posterior weights as the regressions. Together with the loadings they imply asset-level moments in each regime:

μ_s = α_s + B_s m_s
Σ_s = B_s V_s B_s' + diag(σ²_s)

Weighting these by forecast regime probabilities gives the distribution of next period's asset returns as a Gaussian mixture, whose mean and covariance are available in closed form.

The full specification, including every estimation choice and default, is in docs/methodology.md.

Installation

pip install rwls

Python 3.10 or later. The dependencies are numpy, pandas, scipy, scikit-learn, joblib and hmmlearn.

Usage

Factor returns can come from any source as a pandas DataFrame, or from the Kenneth R. French Data Library through the built-in loader. Models are "capm", "ff3", "ff3+mom", "ff5" and "ff5+mom"; returns are monthly and in decimals.

import rwls

factors = rwls.load_factors("ff5+mom", start="1963-07", end="2024-12")
X = factors.drop(columns="RF")
excess = returns.sub(factors["RF"], axis=0)  # returns: monthly stock returns

French revises his factors when CRSP is updated. factors.attrs records the CRSP vintage and the download date, and cache_dir= keeps the downloaded files so that later runs use the same vintage.

Fit the regime model, then renumber the regimes by a rule of your choice, since EM numbers them arbitrarily:

regimes = rwls.RegimeModel(n_regimes=3).fit(X).sort_by("Mkt-RF")
print(regimes.summary(periods_per_year=12))
regimes.posteriors        # smoothed regime probabilities, one column per regime
regimes.forecast()        # probabilities for the next period

Estimate the regime-specific factor models of every asset:

res = rwls.RWLS(excess, X, regimes).fit()
print(res["AAPL"].summary())    # regression table of one asset, by regime
print(res.summary())            # loadings across assets, by regime

res.params                      # coefficients: rows (regime, term), one column per asset
res.bse, res.pvalues            # sandwich standard errors and p-values
res.conf_int()
res.rsquared                    # weighted R-squared by regime
res.wald_equal_loadings()       # test that loadings are equal in every regime

Assets with missing returns are estimated on the periods they are observed.

Regime-conditional and mixture moments of asset returns, in factor form:

m = res.moments()
m.mean(1), m.cov(1)                         # regime 1
mean, cov = m.mixture(regimes.forecast())   # next period's mixture
m.mixture_variance(weights, regimes.forecast())

Choose the number of regimes by information criteria over many starts:

sel = rwls.select_regimes(X, n_regimes=range(1, 7), n_starts=100, n_jobs=-1)
sel.table       # log-likelihood, AIC, BIC, HQIC, ICL, distinct optima
sel.selected    # the number of regimes each criterion selects

Re-estimate through time on the data available at each date, with each regime fit starting from the previous one:

for step in rwls.expanding(excess, X, start=600):
    step.date, step.forecast, step.results.moments()

Every constant of the estimators is a setting with a documented default:

rwls.RegimeSettings()   # number of regimes, starts, tolerance, variance prior, ...
rwls.RWLSSettings()     # intercept, weighting, fallback, t or normal inference, ...
rwls.RegimeModel(n_regimes=3, n_starts=1000, selection="modal")

With selection="modal", the model kept is the one reached by the most starts rather than the one of highest likelihood.

Status

The API may still change before version 1.0.

License

MIT

Metadata

Release files for rwls 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rwls 0.1.0
File Size Uploaded Provenance Actions
rwls-0.1.0.tar.gz 52.0 kB With provenance Details for rwls-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rwls 0.1.0
File Interpreter ABI Platform Actions
rwls-0.1.0-py3-none-any.whl Python 3 none any Details for rwls-0.1.0-py3-none-any.whl

Total release size: 86.9 kB

Release files / rwls-0.1.0.tar.gz

Download URL rwls-0.1.0.tar.gz
Size 52.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fd2ad884806317bf723aa251c2943b46c677fc351e58015e2d52b3aaf30eec3a
BLAKE2b-256 checksum
How to use checksums
af874055d0bc3d4d61b79854241122cad9f5a57da8ee48ee61e6fa3097844550
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 Oct 18, 2026.

Transparency log

Release files / rwls-0.1.0-py3-none-any.whl

Download URL rwls-0.1.0-py3-none-any.whl
Size 35.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91e6c37d6062467d4ee215e6501121f19014d80b794a2a7027ee4548e871a498
BLAKE2b-256 checksum
How to use checksums
80f810ce6f2614af6b33e34bb7747b26c1a725fd85bcd3425a77a5bc29824027
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 Oct 18, 2026.

Transparency log

Security for rwls 0.1.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rwls-0.1.0.tar.gz

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 Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page