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.2.1

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.2.1
File Size Uploaded Provenance Actions
rwls-0.2.1.tar.gz 54.8 kB With provenance Details for rwls-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 90.8 kB

Release files / rwls-0.2.1.tar.gz

Download URL rwls-0.2.1.tar.gz
Size 54.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7e17407a3f9939c198cae23a471cda6fb4da5060cce2a883f471c45294499ef8
BLAKE2b-256 checksum
How to use checksums
215315c5b2ea123f166e33606498c12d074190057e7ed28ddb385cc04622572d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 7, 2026.

Transparency log

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

Download URL rwls-0.2.1-py3-none-any.whl
Size 36.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8562ed2a4cd12d925be9790ee877892753213c4a4475b6421d702ad1451f8518
BLAKE2b-256 checksum
How to use checksums
776dc23a9e9eee037f3af6ba368c0444f4454dba4795120cdbb0955d2ea16b48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 7, 2026.

Transparency log

Security for rwls 0.2.1

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.2.1.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 Nov 7, 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