dfm-python 0.6.14__tar.gz → 0.7.0__tar.gz

{dfm_python-0.6.14 → dfm_python-0.7.0}/.gitignore

@@ -215,4 +215,5 @@ Nowcasting/
 agent/
 
 *.db
-*.pkl
+*.pkl
+*.pt

dfm_python-0.7.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.7.0
+
+- The Attention Factor Model (`dfm_python.models.afm`: `AFM`, attention and PCA
+  factors, LongConv filter, Avellaneda-Lee baseline) now ships in the
+  distribution; the 0.6.14 wheel on PyPI did not include it.
+- README added and used as the package long description.
+- Metadata: project URLs point to `github.com/minkeymouse/dfm-python`.
+- `build` and `twine` moved from runtime dependencies to the `dev` extra.
+- `__version__` now matches the release; the sdist no longer bundles the example CSVs or the lock file.

dfm_python-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minkey Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dfm_python-0.7.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: dfm-python
+Version: 0.7.0
+Summary: Dynamic Factor Model (DFM) estimation and forecasting in Python
+Project-URL: Homepage, https://github.com/minkeymouse/dfm-python
+Project-URL: Documentation, https://github.com/minkeymouse/dfm-python#readme
+Project-URL: Repository, https://github.com/minkeymouse/dfm-python
+Project-URL: Issues, https://github.com/minkeymouse/dfm-python/issues
+Author: Minkey Chang
+License: MIT
+License-File: LICENSE
+Keywords: dfm,dynamic-factor-model,econometrics,forecasting,time-series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: einops>=0.8.1
+Requires-Dist: hydra-core>=1.3.2
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: optuna>=4.7.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: pykalman>=0.11.0
+Requires-Dist: pytorch-lightning>=2.0.0
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: sktime>=0.40.1
+Requires-Dist: torch>=2.0.0
+Provides-Extra: all
+Requires-Dist: build>=1.4.0; extra == 'all'
+Requires-Dist: hydra-core>=1.3.0; extra == 'all'
+Requires-Dist: omegaconf>=2.3.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
+Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.0.0; extra == 'all'
+Requires-Dist: sktime>=0.27.0; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'all'
+Requires-Dist: twine>=6.2.0; extra == 'all'
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'db'
+Provides-Extra: deep
+Provides-Extra: dev
+Requires-Dist: build>=1.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: scikit-learn>=1.0.0; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Provides-Extra: forecasting
+Requires-Dist: sktime[forecasting]>=0.40.1; extra == 'forecasting'
+Provides-Extra: hydra
+Requires-Dist: hydra-core>=1.3.0; extra == 'hydra'
+Requires-Dist: omegaconf>=2.3.0; extra == 'hydra'
+Provides-Extra: transform
+Requires-Dist: sktime>=0.27.0; extra == 'transform'
+Description-Content-Type: text/markdown
+
+# dfm-python
+
+Dynamic factor models in Python.
+
+- **DFM**: linear, mixed-frequency Dynamic Factor Model estimated by EM with
+  Kalman filtering and smoothing.
+- **DDFM**: Deep Dynamic Factor Model with a nonlinear (PyTorch) encoder.
+- **iVDFM**: Identifiable Variational Dynamic Factor Model.
+- **AFM**: the Attention Factor Model of Epstein, Wang, Choi and Pelger (2025),
+  a cross-sectional conditional factor model whose residuals are traded
+  portfolios, with PCA and Avellaneda-Lee benchmarks.
+
+Mixed frequencies are handled with a clock: latent factors evolve at one
+frequency (for example monthly) and lower-frequency series load on them through
+tent-kernel aggregation in the observation equation. Series faster than the
+clock are not supported.
+
+## Install
+
+```bash
+pip install dfm-python        # or: uv add dfm-python
+```
+
+Requires Python 3.10 or later; PyTorch is a required dependency.
+
+## DFM
+
+Pass preprocessed data; the model standardizes it internally.
+
+```python
+import numpy as np
+import pandas as pd
+from dfm_python import DFM, DFMDataset
+from dfm_python.config import DFMConfig
+
+rng = np.random.default_rng(0)
+cols = ["s0", "s1", "s2", "s3"]
+df = pd.DataFrame(rng.standard_normal((120, 4)), columns=cols)
+df["date"] = pd.date_range("2010-01-31", periods=120, freq="ME")
+
+config = DFMConfig(
+    blocks={"global": {"num_factors": 1, "series": cols}},
+    frequency={c: "m" for c in cols},
+    clock="m",
+    max_iter=50,
+)
+dataset = DFMDataset(config=config, data=df, time_index="date")
+model = DFM(dataset=dataset, config=config)
+model.fit()                                     # EM + Kalman smoother
+X_forecast, Z_forecast = model.predict(horizon=6)
+print(X_forecast.shape, Z_forecast.shape)       # (6, 4) series, (6, state dim)
+```
+
+`DDFM` (`from dfm_python import DDFM, DDFMDataset`) and `iVDFM`
+(`from dfm_python.models.ivdfm import iVDFM`) follow the same
+dataset-then-model pattern. Hydra YAML configurations for each model are in
+[`config/`](https://github.com/minkeymouse/dfm-python/tree/main/config) and
+end-to-end scripts in
+[`tutorial/`](https://github.com/minkeymouse/dfm-python/tree/main/tutorial).
+
+## AFM
+
+AFM takes a returns panel `(T, N)` and, for learned attention factors, firm
+characteristics `(T, N, M)`. It is trained on an after-cost Sharpe ratio plus an
+explained-variance term (`lambda_var`).
+
+```python
+import numpy as np
+import torch
+from dfm_python import AFM, AFMDataset
+from dfm_python.models.afm.factors import residuals
+
+rng = np.random.default_rng(0)
+T, N, M = 120, 20, 8                        # dates, assets, characteristics
+returns = 0.01 * rng.standard_normal((T, N))
+characteristics = rng.standard_normal((T, N, M))
+
+ds = AFMDataset(returns=returns, characteristics=characteristics)
+model = AFM(dataset=ds, n_factors=3, hist_len=20, max_epochs=20, seed=0)
+model.fit()
+
+out = model.predict()
+out["residuals"].shape                      # (1, T, N) residual returns
+out["weights"].shape                        # (1, T - hist_len, N) portfolio weights
+out["book_returns"].shape                   # (1, T - hist_len) after-cost returns
+result = model.get_result()
+print(result.sharpe, result.explained_variance)
+
+# Residuals from the fitted factor block directly
+R, X = ds.get_tensors(model.device)
+with torch.no_grad():
+    omega_f, beta_t = model.factor_block(X)  # (T, K, N), (T, N, K)
+    eps = residuals(omega_f, beta_t, R)      # (T, N)
+
+# Benchmarks: PCA factors need no characteristics
+pca = AFM(dataset=AFMDataset(returns=returns), n_factors=3, hist_len=20,
+          factor_model="pca", trading="ou")  # or trading="longconv"
+pca.fit()
+```
+
+## Layout
+
+```
+src/dfm_python/
+  models/      dfm/, ddfm/, ivdfm/, afm/ model classes
+  dataset/     DFMDataset, DDFMDataset, iVDFMDataset, AFMDataset
+  config/      model configs (DFMConfig, ..., AFMConfig), YAML adapter, results
+  ssm/         state-space form and Kalman filtering
+  functional/  EM algorithm
+  numeric/, layer/, utils/, logger/   shared numerics, network layers, helpers
+src/test/      pytest suite
+config/        example Hydra YAML configurations
+tutorial/      end-to-end scripts per model and dataset
+```
+
+Tests, from a clone: `uv sync --group dev && uv run pytest src/test -q`.
+
+The paper repository [minkeymouse/nfe](https://github.com/minkeymouse/nfe) uses
+AFM as a baseline.
+
+## License
+
+MIT. See [LICENSE](https://github.com/minkeymouse/dfm-python/blob/main/LICENSE).

dfm_python-0.7.0/README.md

@@ -0,0 +1,123 @@
+# dfm-python
+
+Dynamic factor models in Python.
+
+- **DFM**: linear, mixed-frequency Dynamic Factor Model estimated by EM with
+  Kalman filtering and smoothing.
+- **DDFM**: Deep Dynamic Factor Model with a nonlinear (PyTorch) encoder.
+- **iVDFM**: Identifiable Variational Dynamic Factor Model.
+- **AFM**: the Attention Factor Model of Epstein, Wang, Choi and Pelger (2025),
+  a cross-sectional conditional factor model whose residuals are traded
+  portfolios, with PCA and Avellaneda-Lee benchmarks.
+
+Mixed frequencies are handled with a clock: latent factors evolve at one
+frequency (for example monthly) and lower-frequency series load on them through
+tent-kernel aggregation in the observation equation. Series faster than the
+clock are not supported.
+
+## Install
+
+```bash
+pip install dfm-python        # or: uv add dfm-python
+```
+
+Requires Python 3.10 or later; PyTorch is a required dependency.
+
+## DFM
+
+Pass preprocessed data; the model standardizes it internally.
+
+```python
+import numpy as np
+import pandas as pd
+from dfm_python import DFM, DFMDataset
+from dfm_python.config import DFMConfig
+
+rng = np.random.default_rng(0)
+cols = ["s0", "s1", "s2", "s3"]
+df = pd.DataFrame(rng.standard_normal((120, 4)), columns=cols)
+df["date"] = pd.date_range("2010-01-31", periods=120, freq="ME")
+
+config = DFMConfig(
+    blocks={"global": {"num_factors": 1, "series": cols}},
+    frequency={c: "m" for c in cols},
+    clock="m",
+    max_iter=50,
+)
+dataset = DFMDataset(config=config, data=df, time_index="date")
+model = DFM(dataset=dataset, config=config)
+model.fit()                                     # EM + Kalman smoother
+X_forecast, Z_forecast = model.predict(horizon=6)
+print(X_forecast.shape, Z_forecast.shape)       # (6, 4) series, (6, state dim)
+```
+
+`DDFM` (`from dfm_python import DDFM, DDFMDataset`) and `iVDFM`
+(`from dfm_python.models.ivdfm import iVDFM`) follow the same
+dataset-then-model pattern. Hydra YAML configurations for each model are in
+[`config/`](https://github.com/minkeymouse/dfm-python/tree/main/config) and
+end-to-end scripts in
+[`tutorial/`](https://github.com/minkeymouse/dfm-python/tree/main/tutorial).
+
+## AFM
+
+AFM takes a returns panel `(T, N)` and, for learned attention factors, firm
+characteristics `(T, N, M)`. It is trained on an after-cost Sharpe ratio plus an
+explained-variance term (`lambda_var`).
+
+```python
+import numpy as np
+import torch
+from dfm_python import AFM, AFMDataset
+from dfm_python.models.afm.factors import residuals
+
+rng = np.random.default_rng(0)
+T, N, M = 120, 20, 8                        # dates, assets, characteristics
+returns = 0.01 * rng.standard_normal((T, N))
+characteristics = rng.standard_normal((T, N, M))
+
+ds = AFMDataset(returns=returns, characteristics=characteristics)
+model = AFM(dataset=ds, n_factors=3, hist_len=20, max_epochs=20, seed=0)
+model.fit()
+
+out = model.predict()
+out["residuals"].shape                      # (1, T, N) residual returns
+out["weights"].shape                        # (1, T - hist_len, N) portfolio weights
+out["book_returns"].shape                   # (1, T - hist_len) after-cost returns
+result = model.get_result()
+print(result.sharpe, result.explained_variance)
+
+# Residuals from the fitted factor block directly
+R, X = ds.get_tensors(model.device)
+with torch.no_grad():
+    omega_f, beta_t = model.factor_block(X)  # (T, K, N), (T, N, K)
+    eps = residuals(omega_f, beta_t, R)      # (T, N)
+
+# Benchmarks: PCA factors need no characteristics
+pca = AFM(dataset=AFMDataset(returns=returns), n_factors=3, hist_len=20,
+          factor_model="pca", trading="ou")  # or trading="longconv"
+pca.fit()
+```
+
+## Layout
+
+```
+src/dfm_python/
+  models/      dfm/, ddfm/, ivdfm/, afm/ model classes
+  dataset/     DFMDataset, DDFMDataset, iVDFMDataset, AFMDataset
+  config/      model configs (DFMConfig, ..., AFMConfig), YAML adapter, results
+  ssm/         state-space form and Kalman filtering
+  functional/  EM algorithm
+  numeric/, layer/, utils/, logger/   shared numerics, network layers, helpers
+src/test/      pytest suite
+config/        example Hydra YAML configurations
+tutorial/      end-to-end scripts per model and dataset
+```
+
+Tests, from a clone: `uv sync --group dev && uv run pytest src/test -q`.
+
+The paper repository [minkeymouse/nfe](https://github.com/minkeymouse/nfe) uses
+AFM as a baseline.
+
+## License
+
+MIT. See [LICENSE](https://github.com/minkeymouse/dfm-python/blob/main/LICENSE).

dfm_python-0.7.0/config/afm_finance.yaml

@@ -0,0 +1,27 @@
+# Attention Factor Model (Epstein et al., 2025) — finance / statistical arbitrage.
+# Flat AFMConfig keys; loaded via AFMConfig.from_dict(OmegaConf.to_container(cfg)).
+clock: d
+scaler: null
+
+# Factor / trading structure
+num_factors: 5
+factor_model: attention      # 'attention' (learned) | 'pca' (benchmark)
+trading: longconv            # 'longconv' (learned) | 'ou' (Avellaneda-Lee)
+
+# Architecture
+embed_dim: 32                # characteristic embedding dimension d
+hist_len: 20                 # residual-history length s for the trading filter
+n_kernels: 32                # number of long convolutions
+ridge: 0.01                  # ridge penalty for the closed-form loadings
+
+# Objective and costs (paper values: 5bps turnover, 1bp shorting)
+lambda_var: 0.1
+turnover_cost: 0.0005
+short_cost: 0.0001
+risk_free: 0.0
+
+# Training
+learning_rate: 0.001
+max_epochs: 50
+patience: 10
+seed: 0

{dfm_python-0.6.14 → dfm_python-0.7.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "dfm-python"
-version = "0.6.14"
+version = "0.7.0"
 description = "Dynamic Factor Model (DFM) estimation and forecasting in Python"
+readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
 authors = [
@@ -16,14 +17,15 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
 ]
 dependencies = [
-    "build>=1.4.0",
     "einops>=0.8.1",
     "hydra-core>=1.3.2",
     "matplotlib>=3.5.0",
     "numpy>=1.24.0",
+    "optuna>=4.7.0",
     "pandas>=2.0.0",
     "pyarrow>=22.0.0",
     "pykalman>=0.11.0",
@@ -32,7 +34,6 @@ dependencies = [
     "scipy>=1.10.0",
     "sktime>=0.40.1",
     "torch>=2.0.0",
-    "twine>=6.2.0",
 ]
 
 [project.optional-dependencies]
@@ -58,6 +59,8 @@ dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "scikit-learn>=1.0.0",
+    "build>=1.4.0",
+    "twine>=6.2.0",
 ]
 all = [
     "dfm-python[hydra,db,dev,deep,transform]",
@@ -83,7 +86,8 @@ packages = [
 exclude = [
     "test_venv",
     "test_venv/**",
-    "LICENSE",
+    "data/**",
+    "uv.lock",
 ]
 
 [dependency-groups]
@@ -92,7 +96,7 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/yourusername/dfm-python"
-Documentation = "https://github.com/yourusername/dfm-python#readme"
-Repository = "https://github.com/yourusername/dfm-python"
-Issues = "https://github.com/yourusername/dfm-python/issues"
+Homepage = "https://github.com/minkeymouse/dfm-python"
+Documentation = "https://github.com/minkeymouse/dfm-python#readme"
+Repository = "https://github.com/minkeymouse/dfm-python"
+Issues = "https://github.com/minkeymouse/dfm-python/issues"

{dfm_python-0.6.14 → dfm_python-0.7.0}/src/dfm_python/__init__.py

@@ -63,7 +63,7 @@ Note: DFMConfig uses frequency dict to specify series (column names -> frequenci
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.6.13"
+__version__ = "0.7.0"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -98,6 +98,7 @@ from .utils.metric import calculate_rmse
 # Users can import these directly from dfm_python
 from .dataset.dfm_dataset import DFMDataset
 from .dataset.ddfm_dataset import DDFMDataset
+from .dataset.afm_dataset import AFMDataset
 
 # Model implementations
 from .models.base import BaseFactorModel
@@ -109,6 +110,12 @@ try:
 except ImportError:
     DDFM = None
 
+# AFM high-level API (Attention Factor Model; PyTorch is mandatory)
+try:
+    from .models.afm.afm import AFM
+except ImportError:
+    AFM = None
+
 __all__ = [
     # Core classes
     'DFM',
@@ -121,14 +128,16 @@ __all__ = [
     'BaseResult', 'DFMResult', 'DDFMResult', 'calculate_rmse',
 ]
 
-# DDFM high-level API (PyTorch is mandatory)
+# DDFM / AFM high-level API (PyTorch is mandatory)
 __all__.extend([
     'DDFM',  # High-level API class
+    'AFM',   # Attention Factor Model
 ])
 
 # Dataset classes
 __all__.extend([
     'DFMDataset',  # DFM Dataset class
     'DDFMDataset',  # DDFM Dataset class
+    'AFMDataset',  # AFM Dataset class
 ])
 

{dfm_python-0.6.14 → dfm_python-0.7.0}/src/dfm_python/config/__init__.py

@@ -8,9 +8,9 @@ Note: Series are specified via frequency dict mapping column names to frequencie
 """
 
 from .schema import (
-    BaseModelConfig, DFMConfig, DDFMConfig,
-    BaseResult, DFMResult, DDFMResult,
-    DFMStateSpaceParams, DDFMStateSpaceParams,
+    BaseModelConfig, DFMConfig, DDFMConfig, AFMConfig,
+    BaseResult, DFMResult, DDFMResult, AFMResult,
+    DFMStateSpaceParams, DDFMStateSpaceParams, AFMModelState,
 )
 # DEFAULT_BLOCK_NAME is imported lazily where needed to avoid circular imports
 from .constants import (
@@ -97,11 +97,11 @@ __all__ = [
     'BaseModelConfig', 'BaseResult',
     # 'DEFAULT_BLOCK_NAME',  # Removed to avoid circular import
     # Model-specific configs (from schema.py)
-    'DFMConfig', 'DDFMConfig',
+    'DFMConfig', 'DDFMConfig', 'AFMConfig',
     # State-space parameters
-    'DFMStateSpaceParams', 'DDFMStateSpaceParams',
+    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'AFMModelState',
     # Model-specific results (from results.py)
-    'DFMResult', 'DDFMResult',
+    'DFMResult', 'DDFMResult', 'AFMResult',
     # Utilities
     'validate_frequency',
     # IO

{dfm_python-0.6.14 → dfm_python-0.7.0}/src/dfm_python/config/constants.py

@@ -348,18 +348,23 @@ DEFAULT_KDFM_MA_ORDER = 0  # Default MA order (MA lag order q) for KDFM (0 = pur
 # iVDFM Defaults
 # ============================================================================
 
-# iVDFM sequence and dimension defaults
-DEFAULT_IVDFM_SEQUENCE_LENGTH = 100  # Default sequence length for sliding windows
+# iVDFM dimension defaults
 DEFAULT_IVDFM_LATENT_DIM = 3  # Default number of factors
 DEFAULT_IVDFM_AUX_DIM = 1  # Default auxiliary variable dimension
 
+# iVDFM regime (K=1 = baseline iVDFM, no regime structure)
+DEFAULT_IVDFM_NUM_REGIMES = 1  # Number of discrete regimes; 1 = baseline iVDFM
+DEFAULT_IVDFM_REGIME_TEMPERATURE = 1.0  # Softmax temperature for π; τ < 1 sharpens (local commitment)
+DEFAULT_IVDFM_MIXING = False  # If True, apply global post-factor mixing f -> M f (identity init) before decode
+
 # iVDFM network architecture defaults
 DEFAULT_IVDFM_ENCODER_HIDDEN_DIM = 200  # Default encoder hidden dimension
-DEFAULT_IVDFM_ENCODER_N_LAYERS = 3  # Default encoder layers
+DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS = 2  # Default encoder hidden layers
+DEFAULT_IVDFM_DECODER_TYPE = "mlp"  # Default: 'linear', 'residual', or 'mlp' (mlp = current behavior)
 DEFAULT_IVDFM_DECODER_HIDDEN_DIM = 200  # Default decoder hidden dimension
-DEFAULT_IVDFM_DECODER_N_LAYERS = 3  # Default decoder layers
+DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS = 2  # Default decoder hidden layers
 DEFAULT_IVDFM_PRIOR_HIDDEN_DIM = 100  # Default prior network hidden dimension
-DEFAULT_IVDFM_PRIOR_N_LAYERS = 2  # Default prior network layers
+DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS = 1  # Default prior network hidden layers
 
 # iVDFM dynamics and distribution defaults
 DEFAULT_IVDFM_FACTOR_ORDER = 1  # Default AR order for factors
@@ -384,6 +389,7 @@ DEFAULT_IVDFM_SCHEDULER_GAMMA = 0.5  # Default gamma for StepLR/ExponentialLR
 DEFAULT_IVDFM_SCHEDULER_PATIENCE = 10  # Default patience for ReduceLROnPlateau
 DEFAULT_IVDFM_SCHEDULER_FACTOR = 0.1  # Default factor for ReduceLROnPlateau
 DEFAULT_IVDFM_SCHEDULER_MIN_LR = 0.0  # Default min_lr for ReduceLROnPlateau
+DEFAULT_IVDFM_EARLY_STOP_PATIENCE = 20  # Default patience for early stopping (epochs without improvement)
 
 # ============================================================================
 # Tutorial Defaults
@@ -451,11 +457,35 @@ FREQUENCY_HIERARCHY: Dict[str, int] = {
 # For frequency gaps larger than this, the missing data approach is used instead
 MAX_TENT_SIZE: int = 12
 
+# ============================================================================
+# AFM (Attention Factor Model) defaults
+# ============================================================================
+DEFAULT_AFM_NUM_FACTORS = 5          # K latent factors
+DEFAULT_AFM_FACTOR_MODEL = 'attention'  # 'attention' | 'pca'
+DEFAULT_AFM_TRADING = 'longconv'     # 'longconv' | 'ou'
+DEFAULT_AFM_EMBED_DIM = 32           # characteristic embedding dimension d
+DEFAULT_AFM_HIST_LEN = 20            # residual-history length s for the filter
+DEFAULT_AFM_N_KERNELS = 32           # number of long convolutions
+DEFAULT_AFM_RIDGE = 1e-2             # ridge penalty for closed-form loadings
+DEFAULT_AFM_SQUASH_LAMBDA = 1e-3     # LongConv Squash kernel regularizer strength
+DEFAULT_AFM_PCA_WINDOW = 252         # trailing window for the PCA benchmark
+DEFAULT_AFM_REESTIM = 21             # PCA re-estimation stride
+DEFAULT_AFM_LAMBDA_VAR = 0.1         # explained-variance regularizer weight
+DEFAULT_AFM_TURNOVER_COST = 5e-4     # 5bps per unit turnover (paper)
+DEFAULT_AFM_SHORT_COST = 1e-4        # 1bp shorting cost (paper)
+DEFAULT_AFM_MAX_EPOCHS = 50          # training epochs
+
 # ============================================================================
 # Export all constants
 # ============================================================================
 
 __all__ = [
+    # AFM
+    'DEFAULT_AFM_NUM_FACTORS', 'DEFAULT_AFM_FACTOR_MODEL', 'DEFAULT_AFM_TRADING',
+    'DEFAULT_AFM_EMBED_DIM', 'DEFAULT_AFM_HIST_LEN', 'DEFAULT_AFM_N_KERNELS',
+    'DEFAULT_AFM_RIDGE', 'DEFAULT_AFM_SQUASH_LAMBDA', 'DEFAULT_AFM_PCA_WINDOW',
+    'DEFAULT_AFM_REESTIM', 'DEFAULT_AFM_LAMBDA_VAR', 'DEFAULT_AFM_TURNOVER_COST',
+    'DEFAULT_AFM_SHORT_COST', 'DEFAULT_AFM_MAX_EPOCHS',
     # Convergence
     'DEFAULT_CONVERGENCE_THRESHOLD',
     'DEFAULT_EM_THRESHOLD',
@@ -606,15 +636,16 @@ __all__ = [
     'DEFAULT_KDFM_AR_ORDER',
     'DEFAULT_KDFM_MA_ORDER',
     # iVDFM defaults
-    'DEFAULT_IVDFM_SEQUENCE_LENGTH',
     'DEFAULT_IVDFM_LATENT_DIM',
     'DEFAULT_IVDFM_AUX_DIM',
     'DEFAULT_IVDFM_ENCODER_HIDDEN_DIM',
-    'DEFAULT_IVDFM_ENCODER_N_LAYERS',
+    'DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS',
+    'DEFAULT_IVDFM_NUM_REGIMES',
+    'DEFAULT_IVDFM_DECODER_TYPE',
     'DEFAULT_IVDFM_DECODER_HIDDEN_DIM',
-    'DEFAULT_IVDFM_DECODER_N_LAYERS',
+    'DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS',
     'DEFAULT_IVDFM_PRIOR_HIDDEN_DIM',
-    'DEFAULT_IVDFM_PRIOR_N_LAYERS',
+    'DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS',
     'DEFAULT_IVDFM_FACTOR_ORDER',
     'DEFAULT_IVDFM_INNOVATION_DIST',
     'DEFAULT_IVDFM_DECODER_VAR',

{dfm_python-0.6.14 → dfm_python-0.7.0}/src/dfm_python/config/schema/__init__.py

@@ -7,13 +7,13 @@ This package contains:
 Note: Series are specified via frequency dict mapping column names to frequencies.
 """
 
-from .model import BaseModelConfig, DFMConfig, DDFMConfig, iVDFMConfig
-from .results import BaseResult, DFMResult, DDFMResult, iVDFMResult
-from .params import DFMStateSpaceParams, DDFMStateSpaceParams, iVDFMModelState
+from .model import BaseModelConfig, DFMConfig, DDFMConfig, iVDFMConfig, AFMConfig
+from .results import BaseResult, DFMResult, DDFMResult, iVDFMResult, AFMResult
+from .params import DFMStateSpaceParams, DDFMStateSpaceParams, iVDFMModelState, AFMModelState
 
 __all__ = [
-    'BaseModelConfig', 'DFMConfig', 'DDFMConfig', 'iVDFMConfig',
-    'BaseResult', 'DFMResult', 'DDFMResult', 'iVDFMResult',
-    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'iVDFMModelState',
+    'BaseModelConfig', 'DFMConfig', 'DDFMConfig', 'iVDFMConfig', 'AFMConfig',
+    'BaseResult', 'DFMResult', 'DDFMResult', 'iVDFMResult', 'AFMResult',
+    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'iVDFMModelState', 'AFMModelState',
 ]