dfm-python 0.1.8__py3-none-any.whl → 0.2.0__py3-none-any.whl

dfm_python/__init__.py

@@ -27,11 +27,14 @@ 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()
-    >>> factors = dfm.result.Z  # Direct access to results
+    >>> 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
     
 Example (Low-level API - For advanced usage):
-    >>> from dfm_python import load_config, load_data, dfm, DFMConfig, SeriesConfig
+    >>> from dfm_python import DFM, DFMConfig, SeriesConfig
+    >>> from dfm_python.data_loader import load_data
     >>> # Option 1: Load from YAML
     >>> config = load_config('config.yaml')
     >>> # Option 2: Create directly
@@ -40,41 +43,61 @@ Example (Low-level API - For advanced usage):
     ...     block_names=['Global']
     ... )
     >>> X, Time, _ = load_data('data.csv', config)  # or use database adapter
-    >>> result = dfm(X, config)
+    >>> model = DFM()
+    >>> result = model.fit(X, config)
     >>> factors = result.Z  # Extract estimated factors
 
-For detailed documentation, see the README.md file.
+For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.1.7"
-
-from .config import DFMConfig, SeriesConfig, BlockConfig
-from .data_loader import (
-    load_config_from_yaml,
-    load_config_from_spec,
-    load_data,
-    transform_data
+__version__ = "0.2.0"
+
+from .config import DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME
+from .config import (
+    ConfigSource,
+    YamlSource,
+    DictSource,
+    SpecCSVSource,
+    HydraSource,
+    MergedConfigSource,
+    make_config_source,
 )
-from .dfm import DFMResult, dfm, calculate_rmse, diagnose_series, print_series_diagnosis
+from .data_loader import transform_data
+from .dfm import DFMResult, calculate_rmse, diagnose_series, print_series_diagnosis
+from .dfm import DFM as _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
 
-# Import high-level API
-from .dfm_api import DFM, _dfm_instance
+# Import high-level API (extends core DFM with convenience methods)
+from .dfm_api import DFM, _dfm_instance, from_yaml, from_spec, from_spec_df, from_dict
 
 # Module-level API: expose singleton instance methods and properties
 # This allows: import dfm_python as dfm; dfm.load_config(...); dfm.result
-def load_config(config):
-    """Load configuration (module-level convenience function)."""
-    return _dfm_instance.load_config(config)
-
-def load_config_from_yaml(yaml_path):
-    """Load configuration from YAML (module-level convenience function)."""
-    return _dfm_instance.load_config_from_yaml(yaml_path)
-
-def load_config_from_spec(spec_path):
-    """Load configuration from spec CSV (module-level convenience function)."""
-    return _dfm_instance.load_config_from_spec(spec_path)
+def load_config(
+    source=None,
+    *,
+    yaml=None,
+    mapping=None,
+    spec=None,
+    hydra=None,
+    base=None,
+    override=None,
+    config=None,
+):
+    """Load configuration (module-level convenience function).
+    
+    See DFM.load_config() for parameter documentation.
+    """
+    return _dfm_instance.load_config(
+        source=source,
+        yaml=yaml,
+        mapping=mapping,
+        spec=spec,
+        hydra=hydra,
+        base=base,
+        override=override,
+        config=config,
+    )
 
 def load_data(data_path=None, data=None, **kwargs):
     """Load data (module-level convenience function)."""
@@ -84,6 +107,14 @@ def train(threshold=None, max_iter=None, **kwargs):
     """Train the model (module-level convenience function)."""
     return _dfm_instance.train(threshold=threshold, max_iter=max_iter, **kwargs)
 
+def predict(horizon=12, **kwargs):
+    """Forecast using the trained model (module-level convenience function)."""
+    return _dfm_instance.predict(horizon=horizon, **kwargs)
+
+def plot(**kwargs):
+    """Plot common visualizations (module-level convenience function)."""
+    return _dfm_instance.plot(**kwargs)
+
 def reset():
     """Reset state (module-level convenience function)."""
     return _dfm_instance.reset()
@@ -132,14 +163,21 @@ def __getattr__(name):
 
 __all__ = [
     # Core classes
-    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'DFM',
+    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params', 'DFM',
+    # Constants
+    'DEFAULT_GLOBAL_BLOCK_NAME',
+    # Config sources
+    'ConfigSource', 'YamlSource', 'DictSource', 'SpecCSVSource', 'HydraSource',
+    'MergedConfigSource', 'make_config_source',
     # High-level API (module-level - recommended)
-    'load_config', 'load_config_from_yaml', 'load_config_from_spec',
-    'load_data', 'train', 'reset',
+    'load_config',
+    'load_data', 'train', 'predict', 'plot', 'reset',
     'get_config', 'get_data', 'get_time', 'get_result', 'get_original_data',
+    # Convenience constructors (cleaner API)
+    'from_yaml', 'from_spec', 'from_spec_df', 'from_dict',
     # Low-level API (functional interface - advanced usage)
     'transform_data',
-    'DFMResult', 'dfm', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
+    'DFMResult', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
     'run_kf', 'skf', 'fis', 'miss_data',
     'update_nowcast', 'news_dfm', 'para_const',
 ]