factormodels

Author: Artur Sepp / First recorded: 2026-10-18

Implemented in FactorModels. Software citation: CITATION.cff.

Factor construction, GLS premia, capital market assumptions and factor covariance estimation.

FactorModels implements multi-asset tradable factor models (MATF): construct factor net asset value histories, estimate asset loadings and covariance, and analyse forecasts with generalized least squares (GLS) and capital market assumption (CMA) diagnostics. See the package README and software citation.

Start with the synthetic reference workflow, then inspect the completed model. The GLS/CMA guide connects the fitted model to annual arithmetic forecasts using an explicit mean bridge and log-risk approximation. Read the Docs hosts the online documentation. Committed-source links identify their stated revision; the local guides describe the checked-out source.

Installation and documentation versions

The completed-result interfaces in this handbook require FactorModels 0.3.0 or later and Python 3.11 or later:

python -m pip install "factormodels>=0.3.0"

The stable handbook follows the released documentation; latest follows the development branch and can include changes after a release. Check your installed version with python -m pip show factormodels and consult the changelog. The 0.3.0 release removes .data and retired deep imports; use the migration table when upgrading from 0.2.0.

Library APIs are installed by pip. Scripts under examples/ belong to the source checkout, so run their commands from that checkout. The README quickstart also supplies its inputs and works with the installed package alone. See CONTRIBUTING.md for an external build environment; keep environments and generated output outside OneDrive on Windows. The optional OP handoff has its own explicit dependency requirement.

Handbook

• Canonical numerical API
  • Choose an entry point
  • factormodels.analytics.definitions
  • factormodels.analytics.construction
  • factormodels.analytics.beta_constraints
  • GLS geometry, inference and Sharpe accounting
  • CMA diagnostics and conditional inference
  • factormodels.estimation
  • factormodels.analytics.models
  • Repository teaching inputs
  • Explicit adapters and diagnostic preparation
  • factormodels.analytics.risk
  • Completed model contract
  • factormodels.analytics.portfolio_context
  • factormodels.estimation.cluster_scores
  • Opportunity and alpha uncertainty
  • Method reports
  • Local paths
• The completed factor model
  • Inputs and completion points
  • Inspectable fields and units
  • Ownership, mutability and persistence
  • Interpretation and limitations
  • Separate downstream usage
• Three reference workflows
  • Reproduce offline
  • Local path configuration
  • Optional public acquisition
  • Inspect or consume
• Factor estimation from supplied CSVs
  • Supplied histories
  • Configure the estimator explicitly
  • Currency preparation and persistence
• Consume a completed model
• Constructing a factor model
  • Inputs and outputs
  • Construction and timing
  • Offline example
  • Consumer boundary
• Factor covariance with HCGL
  • Overview
  • Inputs, notation, and assumptions
  • Methodology
  • Worked example
  • Implementation in factormodels
  • Interpretation and limitations
  • See also
  • References
• GLS inference of factor risk premia
  • Overview
  • Inputs, notation, and assumptions
  • Methodology
  • Worked example
  • Implementation in factormodels
  • Interpretation and limitations
  • See also
  • References
• GLS risk-premia diagnostics
  • Ownership and workflow
  • Public entry points
  • Input contract
  • Results and interpretation
  • Extension contracts
  • CMA and provider report integration
  • Development and verification
  • Related documentation
• CMA diagnostics and reports
  • Inputs and computation
  • Interpretation
  • Rendering and persistence
  • Factor identification and forecast influence
  • Conditional GLS confidence intervals
  • Individual and pair identification
  • Extended inference reports
  • References
• Direct migration to FactorModels
  • Removing the input bundle API
  • 0.3.0 completed-result migration
  • Estimation and completed results
  • Consumer verification and adoption
  • Named implementation modules
  • Volatility targeting belongs to the factor
• Source and dependency licensing
  • FactorLasso minimum
  • Reviewed Windows installation
  • Explicit downstream composition

Start with the completed model: definitions and histories, fitted loadings, selected covariance, diagnostics and provenance. Loading supplied inputs, fitting them, exporting tables and consuming risk in another package are explicit separate steps. FactorLasso supplies statistical estimation, OptimalPortfolios consumes alphas and covariance for optimisation, and QIS supplies portfolio risk and stress reports. The integration guide describes these handoffs.