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

dfm_python/__init__.py

@@ -50,22 +50,17 @@ Example (Low-level API - For advanced usage):
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"
 
-from .config import DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME
 from .config import (
-    ConfigSource,
-    YamlSource,
-    DictSource,
-    SpecCSVSource,
-    HydraSource,
-    MergedConfigSource,
-    make_config_source,
+    DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME,
+    ConfigSource, YamlSource, DictSource, SpecCSVSource, HydraSource,
+    MergedConfigSource, make_config_source,
 )
 from .data import transform_data
 from .dfm import DFMResult
 from .core import calculate_rmse, diagnose_series, print_series_diagnosis
-from .dfm import DFM as _DFMCore  # Core DFM class from dfm.py
+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
 
@@ -100,27 +95,9 @@ def get_original_data():
     """Get original (untransformed) data matrix."""
     return _dfm_instance.original_data
 
-# For direct attribute access, we'll use __getattr__ but handle config module conflict
-
-def __getattr__(name):
-    """Allow access to DFM instance properties at module level."""
-    # Handle special cases that conflict with submodules
-    if name == 'config' and _dfm_instance.config is not None:
-        return _dfm_instance.config
-    elif name == 'data':
-        return _dfm_instance.data
-    elif name == 'time':
-        return _dfm_instance.time
-    elif name == 'result':
-        return _dfm_instance.result
-    elif name == 'original_data':
-        return _dfm_instance.original_data
-    # For other attributes, try normal import
-    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
-
 __all__ = [
     # Core classes
-    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params', 'DFM',
+    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params', 'DFM', 'DFMCore',
     # Constants
     'DEFAULT_GLOBAL_BLOCK_NAME',
     # Config sources

dfm_python/api.py

@@ -29,11 +29,11 @@ from .config import (
     ConfigSource,
     MergedConfigSource,
 )
-from .dfm import DFM as _DFMCore, DFMResult
+from .dfm import DFMCore, DFMResult
 from .core.helpers import safe_get_method, safe_get_attr
 
 
-class DFM(_DFMCore):
+class DFM(DFMCore):
     """High-level API for Dynamic Factor Model estimation.
     
     This class provides a simple, object-oriented interface for DFM operations.
@@ -368,29 +368,48 @@ def from_yaml(yaml_path: Union[str, Path]) -> DFM:
     return _dfm_instance.load_config(yaml=yaml_path)
 
 
-def from_spec(spec_path: Union[str, Path], params: Optional[Params] = None) -> DFM:
-    """Load configuration from spec CSV file (convenience constructor)."""
-    from .config import SpecCSVSource
+def from_spec(
+    csv_path: Union[str, Path],
+    output_dir: Optional[Union[str, Path]] = None,
+    series_filename: Optional[str] = None,
+    blocks_filename: Optional[str] = None
+) -> Tuple[Path, Path]:
+    """Convert spec CSV file to YAML configuration files.
     
-    if params is None:
-        params = Params()
+    This function reads a spec CSV file and generates two YAML files:
+    - config/series/{basename}.yaml - series definitions
+    - config/blocks/{basename}.yaml - block definitions
     
-    # Load config from spec CSV using ConfigSource pattern
-    spec_source = SpecCSVSource(spec_path)
-    config = spec_source.load()
-    
-    # Override estimation parameters from params
-    for key, value in params.__dict__.items():
-        if hasattr(config, key):
-            setattr(config, key, value)
-    
-    _dfm_instance._config = config
-    return _dfm_instance
+    Parameters
+    ----------
+    csv_path : str or Path
+        Path to the spec CSV file
+    output_dir : str or Path, optional
+        Output directory for YAML files. Defaults to config/ directory relative to CSV.
+    series_filename : str, optional
+        Custom filename for series YAML (without .yaml extension).
+        Defaults to CSV basename.
+    blocks_filename : str, optional
+        Custom filename for blocks YAML (without .yaml extension).
+        Defaults to CSV basename.
+        
+    Returns
+    -------
+    Tuple[Path, Path]
+        Paths to generated series YAML and blocks YAML files
+        
+    Examples
+    --------
+    >>> series_path, blocks_path = from_spec('data/sample_spec.csv')
+    >>> # Creates config/series/sample_spec.yaml and config/blocks/sample_spec.yaml
+    """
+    from .config_sources import from_spec as _from_spec
+    return _from_spec(csv_path, output_dir, series_filename, blocks_filename)
 
 
 def from_spec_df(spec_df: pd.DataFrame, params: Optional[Params] = None) -> DFM:
     """Load configuration from spec DataFrame (convenience constructor)."""
-    from .data import _load_config_from_dataframe
+    from .config_sources import _load_config_from_dataframe
     
     if params is None:
         params = Params()

dfm_python/config.py

@@ -21,6 +21,7 @@ from config_sources for backward compatibility.
 """
 
 import numpy as np
+import warnings
 from typing import List, Optional, Dict, Any, Union
 from dataclasses import dataclass, field
 
@@ -102,10 +103,14 @@ class SeriesConfig:
         Unique identifier (auto-generated if None)
     series_name : str, optional
         Human-readable name (defaults to series_id if None)
-    units : str
-        Units of measurement
-    category : str
-        Category/group name
+    units : str, optional
+        Units of measurement (optional metadata for display purposes only).
+        Used in news decomposition output for readability. Not used in model estimation.
+    release_date : int, optional
+        Release date information for pseudo real-time nowcasting.
+        - Positive value (1-31): Day of month when data is released
+        - Negative value: Days before end of previous month when data is released
+        Example: 25 = released on 25th of each month, -5 = released 5 days before end of previous month
     """
     # Required fields (no defaults)
     frequency: str
@@ -114,9 +119,8 @@ class SeriesConfig:
     # Optional fields (with defaults - must come after required fields)
     series_id: Optional[str] = None  # Auto-generated if None: "series_0", "series_1", etc.
     series_name: Optional[str] = None  # Optional metadata for display
-    units: str = ""  # Optional metadata
-    category: str = ""  # Optional metadata
-    aggregate: Optional[str] = None  # Aggregation method (deprecated: higher frequencies than clock are not supported)
+    units: Optional[str] = None  # Optional metadata for display only (used in news.py output)
+    release_date: Optional[int] = None  # Release date for pseudo real-time nowcasting
     
     def __post_init__(self):
         """Validate fields after initialization."""
@@ -716,9 +720,7 @@ class DFMConfig:
                 blocks=series_blocks,
                 series_id=get_list_value('SeriesID', i, None),
                 series_name=get_list_value('SeriesName', i, None),
-                units=str(get_list_value('Units', i, '')),
-                category=str(get_list_value('Category', i, '')),
-                aggregate=get_list_value('Aggregate', i, None)
+                units=get_list_value('Units', i, None)  # Optional, for display only
             ))
         
         # Convert block_names to blocks dict
@@ -805,9 +807,7 @@ class DFMConfig:
                     frequency=series_cfg.get('frequency', 'm'),
                     transformation=series_cfg.get('transformation', 'lin'),
                     blocks=series_blocks,
-                    units=series_cfg.get('units', ''),
-                    category=series_cfg.get('category', ''),
-                    aggregate=series_cfg.get('aggregate', None)  # Deprecated
+                    units=series_cfg.get('units', None)  # Optional, for display only
                 ))
         
         # Convert blocks_dict to BlockConfig dict
@@ -1031,7 +1031,6 @@ def validate_transformation(transformation: str) -> str:
     >>> validate_transformation('unknown')  # Issues warning but returns value
     'unknown'
     """
-    import warnings
     if transformation not in _VALID_TRANSFORMATIONS:
         warnings.warn(f"Unknown transformation code: {transformation}. Will use untransformed data.")
     return transformation