dfm-python 0.5.51__py3-none-any.whl → 0.5.53__py3-none-any.whl

dfm_python/__init__.py

@@ -28,7 +28,7 @@ Example (Standard Lightning Pattern):
     >>> import pandas as pd
     >>> 
     >>> # Step 1: Load and preprocess data
-    >>> df = pd.read_csv('data/sample_data.csv')
+    >>> df = pd.read_csv('data/your_data.csv')
     >>> df_processed = df[[col for col in df.columns if col != 'date']]
     >>> 
     >>> # Step 2: Create DataModule
@@ -59,13 +59,13 @@ Example (Standard Lightning Pattern):
     >>> trainer_ddfm.fit(ddfm_model, dm_ddfm)
     >>> Xf, Zf = ddfm_model.predict(horizon=6)
     
-Note: DFMConfig and SeriesConfig are internal implementation details.
+Note: DFMConfig uses frequency dict to specify series (column names -> frequencies).
     Users should use Hydra YAML configuration files instead.
 
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.5.5"
+__version__ = "0.5.53"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -75,7 +75,7 @@ __version__ = "0.5.5"
 # Internal reorganization should not break these imports.
 #
 # Public API categories:
-# 1. Configuration: DFMConfig, SeriesConfig, config sources
+# 1. Configuration: DFMConfig, config sources
 # 2. High-level API: DFM, DDFM, module-level convenience functions
 # 3. Core utilities: TimeIndex, diagnostics
 # 4. Models: BaseFactorModel, DDFM (low-level)
@@ -84,29 +84,27 @@ __version__ = "0.5.5"
 
 # Configuration (from config/ subpackage)
 from .config import (
-    DEFAULT_BLOCK_NAME,
-    ConfigSource, YamlSource, HydraSource,
+    # DEFAULT_BLOCK_NAME,  # Removed to avoid circular import - import directly from functional.dfm_block
+    ConfigSource, YamlSource,
     make_config_source,
 )
-# Internal imports (for backward compatibility, but not recommended)
-from .config import DFMConfig, SeriesConfig  # Internal use only
+# Internal imports (internal use only)
+from .config import DFMConfig
 
 # Results
-from .config.results import DFMResult, DDFMResult, BaseResult
+from .config import DFMResult, DDFMResult, KDFMResult, BaseResult
 
 # Utilities (from utils/ subpackage)
-from .utils.diagnostics import diagnose_series, print_series_diagnosis
-from .utils.time import calculate_rmse
+from .utils.metric import calculate_rmse
 
-# PyTorch Lightning modules (mandatory dependency)
+# DataModule classes (includes both Lightning and custom implementations)
 # Users can import these directly from dfm_python
-from .lightning import (
+from .datamodule import (
     DFMDataModule,
     DDFMDataModule,  # DDFM-specific DataModule
-    DFMDataset,  # Dataset class (usually not needed directly)
+    KDFMDataModule,  # KDFM-specific DataModule
     DDFMDataset,  # DDFM Dataset class (usually not needed directly)
-    KalmanFilter,  # Module class
-    EMAlgorithm,  # Module class
+    KDFMDataset,  # KDFM Dataset class (usually not needed directly)
 )
 
 # Model implementations
@@ -116,18 +114,19 @@ from .models.dfm import DFM
 # DDFM high-level API (PyTorch is mandatory)
 from .models.ddfm import DDFM
 
+# KDFM high-level API
+from .models.kdfm import KDFM
+
 __all__ = [
     # Core classes
     'DFM',
     # Model base and implementations
     'BaseFactorModel',
-    # Constants
-    'DEFAULT_BLOCK_NAME',
     # Config sources
-    'ConfigSource', 'YamlSource', 'HydraSource',
+    'ConfigSource', 'YamlSource',
     'make_config_source',
     # Low-level API (functional interface - advanced usage)
-    'BaseResult', 'DFMResult', 'DDFMResult', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
+    'BaseResult', 'DFMResult', 'DDFMResult', 'KDFMResult', 'calculate_rmse',
 ]
 
 # DDFM high-level API (PyTorch is mandatory)
@@ -135,22 +134,27 @@ __all__.extend([
     'DDFM',  # High-level API class
 ])
 
+# KDFM high-level API
+__all__.extend([
+    'KDFM',  # High-level API class
+])
+
 # Lightning modules (mandatory dependency)
 __all__.extend([
     'DFMDataModule',
     'DDFMDataModule',  # DDFM-specific DataModule
-    'DFMDataset',  # Dataset class (usually not needed directly)
+    'KDFMDataModule',  # KDFM-specific DataModule
     'DDFMDataset',  # DDFM Dataset class (usually not needed directly)
-    'KalmanFilter',  # Module class
-    'EMAlgorithm',  # Module class
+    'KDFMDataset',  # KDFM Dataset class (usually not needed directly)
 ])
 
 # Trainer classes (mandatory dependency)
-from .trainer import DFMTrainer, DDFMTrainer
+from .trainer import DFMTrainer, DDFMTrainer, KDFMTrainer
 
 __all__.extend([
     'DFMTrainer',
     'DDFMTrainer',
+    'KDFMTrainer',
 ])
 
 

dfm_python/config/__init__.py

@@ -1,60 +1,176 @@
 """Configuration subpackage for DFM.
 
 This subpackage provides:
-- Schema (DFMConfig, SeriesConfig) in schema.py
+- Schema (DFMConfig, etc.) in schema.py
 - IO (ConfigSource, YamlSource, etc.) in adapter.py
+
+Note: Series are specified via frequency dict mapping column names to frequencies.
 """
 
 from .schema import (
-    BaseModelConfig, DFMConfig, DDFMConfig, SeriesConfig,
-    DEFAULT_BLOCK_NAME,
+    BaseModelConfig, DFMConfig, DDFMConfig, KDFMConfig,
+    BaseResult, DFMResult, DDFMResult, KDFMResult, FitParams,
+)
+# DEFAULT_BLOCK_NAME is imported lazily where needed to avoid circular imports
+from .constants import (
+    DEFAULT_CONVERGENCE_THRESHOLD,
+    DEFAULT_TOLERANCE,
+    DEFAULT_MAX_ITER,
+    DEFAULT_MAX_EPOCHS,
+    DEFAULT_LEARNING_RATE,
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_CLOCK_FREQUENCY,
+    MIN_EIGENVALUE,
+    MIN_STD,
 )
-from .results import BaseResult, DFMResult, DDFMResult, FitParams
-from .utils import validate_frequency, validate_transformation
+from .schema.model import validate_frequency
 from .adapter import (
     ConfigSource,
     YamlSource,
     DictSource,
-    HydraSource,
-    MergedConfigSource,
     make_config_source,
+    detect_config_type,
 )
-from .utils import (
-    FREQUENCY_HIERARCHY,
-    PERIODS_PER_YEAR,
-    get_periods_per_year,
-    get_annual_factor,
-    compute_idio_lengths,
-    get_tent_weights,
-    generate_tent_weights,
-    generate_R_mat,
-    get_agg_structure,
-    group_by_freq,
+# Re-export types for convenience
+from .types import (
+    ArrayLike,
+    FloatArray,
+    IntArray,
+    BoolArray,
+    OptionalArray,
+    OptionalTensor,
+    OptionalArrayLike,
+    FactorState,
+    ObservationState,
+    ForecastResult,
+    CoefficientMatrix,
+    CovarianceMatrix,
+    IRFArray,
+    CompanionMatrix,
+    SeriesID,
+    Frequency,
+    DatasetName,
+    ModelName,
+    Batch,
+    Loss,
+    Optimizer,
+    ResultDict,
+    ForecastDict,
+    MetricsDict,
+    IRFResultDict,
+    CheckpointDict,
+    ConfigDict,
+    Device,
+    Shape,
+    Shape2D,
+    Shape3D,
+    Shape4D,
+    ForecastHorizon,
+    IRFHorizon,
+    LagOrder,
+    NumFactors,
+    NumVars,
+    PathLike,
+    ValidationIssue,
+    ValidationResult,
+    Tensor,
+    is_numpy_array,
+    is_torch_tensor,
+    is_array_like,
+    get_array_shape,
+    to_numpy,
+    to_tensor,
 )
+# Import lazily to avoid circular dependencies
+try:
+    from ..numeric.builder import compute_idio_lengths
+except ImportError:
+    compute_idio_lengths = None
+
+try:
+    from ..numeric.tent import get_tent_weights, get_agg_structure, group_by_freq
+except ImportError:
+    get_tent_weights = None
+    get_agg_structure = None
+    group_by_freq = None
+from .constants import FREQUENCY_HIERARCHY, PERIODS_PER_YEAR
+
+# Simple utility function
+def get_periods_per_year(frequency: str) -> int:
+    """Get number of periods per year for a given frequency."""
+    return PERIODS_PER_YEAR.get(frequency, PERIODS_PER_YEAR.get(DEFAULT_CLOCK_FREQUENCY, 12))
 
 __all__ = [
-    # Schema
-    'BaseModelConfig', 'DFMConfig', 'DDFMConfig', 'SeriesConfig',
-    'DEFAULT_BLOCK_NAME',
+    # Base classes
+    'BaseModelConfig', 'BaseResult',
+    # 'DEFAULT_BLOCK_NAME',  # Removed to avoid circular import - import directly from functional.dfm_block
+    # Model-specific configs (from schema.py)
+    'DFMConfig', 'DDFMConfig', 'KDFMConfig',
     # Parameter overrides
     'FitParams',
-    # Results
-    'BaseResult', 'DFMResult', 'DDFMResult',
+    # Model-specific results (from results.py)
+    'DFMResult', 'DDFMResult', 'KDFMResult',
     # Utilities
-    'validate_frequency', 'validate_transformation',
+    'validate_frequency',
     # IO
     'ConfigSource', 'YamlSource', 'DictSource',
-    'HydraSource', 'MergedConfigSource', 'make_config_source',
+    'make_config_source',
+    'detect_config_type',
     # Frequency and aggregation utilities
     'FREQUENCY_HIERARCHY',
     'PERIODS_PER_YEAR',
     'get_periods_per_year',
-    'get_annual_factor',
     'compute_idio_lengths',
     'get_tent_weights',
-    'generate_tent_weights',
-    'generate_R_mat',
     'get_agg_structure',
     'group_by_freq',
+    # Type definitions (from types.py)
+    'ArrayLike',
+    'FloatArray',
+    'IntArray',
+    'BoolArray',
+    'OptionalArray',
+    'OptionalTensor',
+    'OptionalArrayLike',
+    'FactorState',
+    'ObservationState',
+    'ForecastResult',
+    'CoefficientMatrix',
+    'CovarianceMatrix',
+    'IRFArray',
+    'CompanionMatrix',
+    'SeriesID',
+    'Frequency',
+    'DatasetName',
+    'ModelName',
+    'Batch',
+    'Loss',
+    'Optimizer',
+    'ResultDict',
+    'ForecastDict',
+    'MetricsDict',
+    'IRFResultDict',
+    'CheckpointDict',
+    'ConfigDict',
+    'Device',
+    'Shape',
+    'Shape2D',
+    'Shape3D',
+    'Shape4D',
+    'ForecastHorizon',
+    'IRFHorizon',
+    'LagOrder',
+    'NumFactors',
+    'NumVars',
+    'PathLike',
+    'ValidationIssue',
+    'ValidationResult',
+    'Tensor',
+    'is_numpy_array',
+    'is_torch_tensor',
+    'is_array_like',
+    'get_array_shape',
+    'to_numpy',
+    'to_tensor',
 ]