dfm-python 0.2.9__py3-none-any.whl → 0.3.1__py3-none-any.whl

dfm_python/__init__.py

@@ -7,6 +7,7 @@ This package implements a comprehensive Dynamic Factor Model framework with supp
 - Expectation-Maximization (EM) algorithm for parameter estimation
 - Kalman filtering and smoothing for factor extraction
 - News decomposition for nowcasting
+- Deep Dynamic Factor Models (DDFM) with nonlinear encoders (optional, requires PyTorch)
 
 The package implements a clock-based approach to mixed-frequency DFMs, where all latent 
 factors (global and block-level) are synchronized to a common "clock" frequency, typically 
@@ -25,16 +26,23 @@ Key Features:
 
 Example (High-level API - Recommended):
     >>> import dfm_python as dfm
-    >>> dfm.load_config('config/default.yaml')
-    >>> dfm.load_data('data/sample_data.csv')
-    >>> dfm.train(max_iter=1)
-    >>> Xf, Zf = dfm.predict(horizon=6)
-    >>> dfm.plot(kind='factor', factor_index=0, forecast_horizon=6, save_path='outputs/factor_forecast.png')
-    >>> factors = dfm.get_result().Z  # Access factors via result
+    >>> # Linear DFM
+    >>> model = dfm.DFM()
+    >>> model.load_config('config/default.yaml')
+    >>> model.load_data('data/sample_data.csv')
+    >>> model.train(max_iter=100)
+    >>> Xf, Zf = model.predict(horizon=6)
+    >>> 
+    >>> # Or use DDFM (separate class)
+    >>> ddfm_model = dfm.DDFM(encoder_layers=[64, 32], num_factors=2)
+    >>> ddfm_model.load_config('config/default.yaml')
+    >>> ddfm_model.load_data('data/sample_data.csv')
+    >>> ddfm_model.train(epochs=100)
+    >>> Xf, Zf = ddfm_model.predict(horizon=6)
     
 Example (Low-level API - For advanced usage):
     >>> from dfm_python import DFM, DFMConfig, SeriesConfig
-    >>> from dfm_python.data import load_data  # Preferred import
+    >>> from dfm_python.dataloader import load_data  # Preferred import
     >>> # Option 1: Load from YAML
     >>> config = load_config('config.yaml')
     >>> # Option 2: Create directly
@@ -50,27 +58,82 @@ Example (Low-level API - For advanced usage):
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.2.9"
-
+__version__ = "0.3.1"
+
+# ============================================================================
+# PUBLIC API DEFINITION
+# ============================================================================
+# This __init__.py is the single source of truth for the public API.
+# All symbols exported here are considered stable public API.
+# Internal reorganization should not break these imports.
+#
+# Public API categories:
+# 1. Configuration: DFMConfig, SeriesConfig, BlockConfig, Params, config sources
+# 2. High-level API: DFM, DDFM, module-level convenience functions
+# 3. Core utilities: DFMCore, run_kf, TimeIndex, diagnostics
+# 4. Models: BaseFactorModel, DFMLinear, DDFM (low-level)
+# 5. Nowcasting: Nowcast, result classes, para_const
+# 6. Data & Results: DFMResult, transform_data
+# ============================================================================
+
+# Configuration (from config/ subpackage)
 from .config import (
     DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME,
-    ConfigSource, YamlSource, DictSource, SpecCSVSource, HydraSource,
+    ConfigSource, YamlSource, DictSource, HydraSource,
     MergedConfigSource, make_config_source,
 )
-from .data import transform_data
-from .dfm import DFMResult
+
+# Data utilities
+from .dataloader import transform_data
+
+# Results
+from .core import DFMResult
+
+# Core utilities (from core/ subpackage)
 from .core import calculate_rmse, diagnose_series, print_series_diagnosis
-from .dfm import DFMCore  # Core DFM class from dfm.py
-from .kalman import run_kf, skf, fis, miss_data
-from .news import update_nowcast, news_dfm, para_const
+from .core.state_space import run_kf, skf, fis, miss_data
+# DFMCore is now an alias for DFMLinear (backward compatibility)
+from .models.dfm import DFMLinear
+DFMCore = DFMLinear
+
+# Nowcasting (already in nowcasting/ subpackage)
+from .nowcasting import (
+    Nowcast,
+    para_const,
+    NowcastResult,
+    NewsDecompResult,
+    BacktestResult,
+)
 
-# Import high-level API (extends core DFM with convenience methods)
-# Import module-level convenience functions directly from api.py to avoid duplication
+# High-level API (from api/ subpackage)
 from .api import (
     DFM, _dfm_instance, from_yaml, from_spec, from_spec_df, from_dict,
-    load_config, load_data, train, predict, plot, reset
+    load_config, load_data, load_pickle, train, predict, plot, reset, create_model
 )
 
+# Model implementations
+from .models.base import BaseFactorModel
+from .models.dfm import DFMLinear
+
+# DDFM high-level API and low-level model (both optional, requires PyTorch)
+try:
+    from .api import DDFM as DDFMAPI, _ddfm_instance
+    from .api import load_config_ddfm, load_data_ddfm, train_ddfm, predict_ddfm, plot_ddfm, reset_ddfm
+    from .models.ddfm import DDFM as DDFMModel
+    _has_ddfm = True
+    # Export high-level API as DDFM
+    DDFM = DDFMAPI
+except ImportError:
+    _has_ddfm = False
+    DDFM = None  # type: ignore
+    DDFMModel = None  # type: ignore
+    load_config_ddfm = None  # type: ignore
+    load_data_ddfm = None  # type: ignore
+    train_ddfm = None  # type: ignore
+    predict_ddfm = None  # type: ignore
+    plot_ddfm = None  # type: ignore
+    reset_ddfm = None  # type: ignore
+
 # Expose properties as module-level attributes
 # Use property-like access via functions or direct attribute access
 # Since 'config' conflicts with the config module, we'll use a different approach
@@ -97,15 +160,19 @@ def get_original_data():
 
 __all__ = [
     # Core classes
-    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params', 'DFM', 'DFMCore',
+    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params', 'DFM', 'DFMCore', 'Nowcast',
+    # Model base and implementations
+    'BaseFactorModel', 'DFMLinear',
+    # Nowcast result classes
+    'NowcastResult', 'NewsDecompResult', 'BacktestResult',
     # Constants
     'DEFAULT_GLOBAL_BLOCK_NAME',
     # Config sources
-    'ConfigSource', 'YamlSource', 'DictSource', 'SpecCSVSource', 'HydraSource',
+    'ConfigSource', 'YamlSource', 'DictSource', 'HydraSource',
     'MergedConfigSource', 'make_config_source',
     # High-level API (module-level - recommended)
     'load_config',
-    'load_data', 'train', 'predict', 'plot', 'reset',
+    'load_data', 'load_pickle', 'train', 'predict', 'plot', 'reset', 'create_model',
     'get_config', 'get_data', 'get_time', 'get_result', 'get_original_data',
     # Convenience constructors (cleaner API)
     'from_yaml', 'from_spec', 'from_spec_df', 'from_dict',
@@ -113,6 +180,14 @@ __all__ = [
     'transform_data',
     'DFMResult', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
     'run_kf', 'skf', 'fis', 'miss_data',
-    'update_nowcast', 'news_dfm', 'para_const',
+    'para_const',  # Internal utility, kept for backward compatibility
 ]
 
+# Add DDFM high-level API and convenience functions if available
+if _has_ddfm:
+    __all__.extend([
+        'DDFM',  # High-level API class
+        'load_config_ddfm', 'load_data_ddfm', 'train_ddfm', 
+        'predict_ddfm', 'plot_ddfm', 'reset_ddfm'
+    ])
+

dfm_python/api/__init__.py

@@ -0,0 +1,44 @@
+"""High-level API subpackage for Dynamic Factor Models.
+
+This subpackage provides:
+- Model API classes (DFMBase, DFM, DDFM) in model_api.py
+- Session API (singleton instances and module-level functions) in session_api.py
+"""
+
+from .model_api import DFMBase, DFM, DDFM
+from .session_api import (
+    _dfm_instance,
+    _ddfm_instance,
+    load_config,
+    load_data,
+    train,
+    predict,
+    plot,
+    load_pickle,
+    reset,
+    load_config_ddfm,
+    load_data_ddfm,
+    train_ddfm,
+    predict_ddfm,
+    plot_ddfm,
+    reset_ddfm,
+    create_model,
+    from_yaml,
+    from_spec,
+    from_spec_df,
+    from_dict,
+)
+
+__all__ = [
+    # High-level API classes
+    'DFMBase', 'DFM', 'DDFM',
+    # Singleton instances (internal use)
+    '_dfm_instance', '_ddfm_instance',
+    # Module-level convenience functions (DFM)
+    'load_config', 'load_data', 'load_pickle', 'train', 'predict', 'plot', 'reset',
+    # Module-level convenience functions (DDFM)
+    'load_config_ddfm', 'load_data_ddfm', 'train_ddfm', 'predict_ddfm', 'plot_ddfm', 'reset_ddfm',
+    # Factory and convenience constructors
+    'create_model', 'from_yaml', 'from_spec', 'from_spec_df', 'from_dict',
+]
+