dfm-python 0.2.8__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.8"
+__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

dfm_python/config_sources.py

@@ -10,11 +10,62 @@ This module provides adapters for loading DFMConfig from various sources:
 All adapters implement the ConfigSource protocol and return DFMConfig objects.
 """
 
-from typing import Protocol, Optional, Dict, Any, Union
+import warnings
+from typing import Protocol, Optional, Dict, Any, Union, Tuple
 from pathlib import Path
 from dataclasses import is_dataclass, asdict
 
 from .config import DFMConfig, SeriesConfig, BlockConfig, DEFAULT_GLOBAL_BLOCK_NAME
+import pandas as pd
+
+
+def _load_config_from_defaults(cfg, root_config_dir, config_type: str) -> Optional[dict]:
+    """Load config from defaults or direct path (helper for series/blocks loading).
+    
+    Parameters
+    ----------
+    cfg : OmegaConf.DictConfig
+        Main config object
+    root_config_dir : Path
+        Root config directory (contains series/ and blocks/ subdirectories)
+    config_type : str
+        Type of config to load: 'series' or 'blocks'
+        
+    Returns
+    -------
+    Optional[dict]
+        Loaded config dict or None if not found
+    """
+    from omegaconf import OmegaConf
+    
+    config_dict = None
+    config_loaded = False
+    
+    # Try loading from defaults
+    if 'defaults' in cfg:
+        defaults_list = cfg.defaults
+        for default_item in defaults_list:
+            default_dict = OmegaConf.to_container(default_item, resolve=False) if hasattr(default_item, 'keys') else default_item
+            
+            # Handle dict format: {'series': 'default'} or {'blocks': 'default'}
+            if isinstance(default_dict, dict) and config_type in default_dict:
+                config_name = default_dict[config_type]
+                config_path = root_config_dir / config_type / f'{config_name}.yaml'
+                if config_path.exists():
+                    config_cfg = OmegaConf.load(config_path)
+                    config_dict = OmegaConf.to_container(config_cfg, resolve=True)
+                    config_loaded = True
+                    break
+    
+    # If not loaded from defaults, try direct path
+    if not config_loaded:
+        config_path = root_config_dir / config_type / 'default.yaml'
+        if config_path.exists():
+            config_cfg = OmegaConf.load(config_path)
+            config_dict = OmegaConf.to_container(config_cfg, resolve=True)
+            config_loaded = True
+    
+    return config_dict if config_loaded else None
 
 
 class ConfigSource(Protocol):
@@ -55,6 +106,14 @@ class YamlSource:
             raise FileNotFoundError(f"Configuration file not found: {configfile}")
         
         config_dir = configfile.parent
+        # If config file is in a subdirectory (e.g., experiment/), find the root config directory
+        # Look for series/ or blocks/ directories to identify config root
+        root_config_dir = config_dir
+        while root_config_dir.parent != root_config_dir:  # Not at filesystem root
+            if (root_config_dir / 'series').exists() or (root_config_dir / 'blocks').exists():
+                break
+            root_config_dir = root_config_dir.parent
+        
         cfg = OmegaConf.load(configfile)
         cfg_dict = OmegaConf.to_container(cfg, resolve=True)
         
@@ -64,44 +123,28 @@ class YamlSource:
         
         # Load series from config/series/default.yaml
         series_list = []
-        series_loaded = False
-        series_dict = None
-        
-        if 'defaults' in cfg:
-            defaults_list = cfg.defaults
-            for default_item in defaults_list:
-                default_dict = OmegaConf.to_container(default_item, resolve=False) if hasattr(default_item, 'keys') else default_item
-                
-                # Handle dict format: {'series': 'default'}
-                if isinstance(default_dict, dict) and 'series' in default_dict:
-                    series_config_name = default_dict['series']
-                    series_config_path = config_dir / 'series' / f'{series_config_name}.yaml'
-                    if series_config_path.exists():
-                        series_cfg = OmegaConf.load(series_config_path)
-                        series_dict = OmegaConf.to_container(series_cfg, resolve=True)
-                        series_loaded = True
-                        break
-        
-        # If not loaded from defaults, try direct path
-        if not series_loaded:
-            series_config_path = config_dir / 'series' / 'default.yaml'
-            if series_config_path.exists():
-                series_cfg = OmegaConf.load(series_config_path)
-                series_dict = OmegaConf.to_container(series_cfg, resolve=True)
-                series_loaded = True
+        series_dict = _load_config_from_defaults(cfg, root_config_dir, 'series')
+        series_loaded = series_dict is not None
         
         # Convert series dict to SeriesConfig objects
         if series_loaded and series_dict is not None:
             for series_id, series_data in series_dict.items():
                 if isinstance(series_data, dict):
+                    # Parse release_date if available
+                    release_date = series_data.get('release', series_data.get('release_date', None))
+                    if release_date is not None:
+                        try:
+                            release_date = int(release_date)
+                        except (ValueError, TypeError):
+                            release_date = None
+                    
                     series_list.append(SeriesConfig(
                         series_id=series_id,
                         series_name=series_data.get('series_name', series_id),
                         frequency=series_data.get('frequency', 'm'),
                         transformation=series_data.get('transformation', 'lin'),
-                        category=series_data.get('category', ''),
-                        units=series_data.get('units', ''),
-                        blocks=series_data.get('blocks', [])
+                        blocks=series_data.get('blocks', []),
+                        release_date=release_date
                     ))
         
         # If no series loaded from separate files, try to get from main config
@@ -118,31 +161,8 @@ class YamlSource:
         
         # Load blocks from config/blocks/default.yaml
         blocks_dict = {}
-        blocks_loaded = False
-        blocks_dict_raw = None
-        
-        if 'defaults' in cfg:
-            defaults_list = cfg.defaults
-            for default_item in defaults_list:
-                default_dict = OmegaConf.to_container(default_item, resolve=False) if hasattr(default_item, 'keys') else default_item
-                
-                # Handle dict format: {'blocks': 'default'}
-                if isinstance(default_dict, dict) and 'blocks' in default_dict:
-                    blocks_config_name = default_dict['blocks']
-                    blocks_config_path = config_dir / 'blocks' / f'{blocks_config_name}.yaml'
-                    if blocks_config_path.exists():
-                        blocks_cfg = OmegaConf.load(blocks_config_path)
-                        blocks_dict_raw = OmegaConf.to_container(blocks_cfg, resolve=True)
-                        blocks_loaded = True
-                        break
-        
-        # If not loaded from defaults, try direct path
-        if not blocks_loaded:
-            blocks_config_path = config_dir / 'blocks' / 'default.yaml'
-            if blocks_config_path.exists():
-                blocks_cfg = OmegaConf.load(blocks_config_path)
-                blocks_dict_raw = OmegaConf.to_container(blocks_cfg, resolve=True)
-                blocks_loaded = True
+        blocks_dict_raw = _load_config_from_defaults(cfg, root_config_dir, 'blocks')
+        blocks_loaded = blocks_dict_raw is not None
         
         # Convert blocks dict to BlockConfig objects
         if blocks_loaded and blocks_dict_raw is not None:
@@ -241,9 +261,6 @@ class SpecCSVSource:
     
     def load(self) -> DFMConfig:
         """Load series definitions from spec CSV."""
-        import pandas as pd
-        from .data import _load_config_from_dataframe
-        
         specfile = Path(self.spec_path)
         if not specfile.exists():
             raise FileNotFoundError(f"Spec file not found: {specfile}")
@@ -371,6 +388,190 @@ class MergedConfigSource:
         )
 
 
+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.
+    
+    This function reads a spec CSV file and generates two YAML files:
+    - config/series/{basename}.yaml - series definitions
+    - config/blocks/{basename}.yaml - block definitions
+    
+    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
+    """
+    
+    csv_path = Path(csv_path)
+    if not csv_path.exists():
+        raise FileNotFoundError(f"CSV file not found: {csv_path}")
+    
+    # Determine output directory
+    if output_dir is None:
+        # Default: config/ directory relative to CSV file's parent
+        output_dir = csv_path.parent.parent / 'config'
+    else:
+        output_dir = Path(output_dir)
+    
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Determine filenames
+    csv_basename = csv_path.stem
+    series_filename = series_filename or csv_basename
+    blocks_filename = blocks_filename or csv_basename
+    
+    # Read CSV and convert to DFMConfig
+    try:
+        df = pd.read_csv(csv_path)
+    except Exception as e:
+        raise ValueError(f"Failed to read CSV file {csv_path}: {e}")
+    
+    config = _load_config_from_dataframe(df)
+    
+    # Prepare series YAML content
+    series_dir = output_dir / 'series'
+    series_dir.mkdir(parents=True, exist_ok=True)
+    series_path = series_dir / f'{series_filename}.yaml'
+    
+    series_dict = {}
+    # Get block names in order (from config.block_names)
+    block_names = config.block_names
+    
+    for series in config.series:
+        # Convert blocks from indices to block names if needed
+        if isinstance(series.blocks, list) and len(series.blocks) > 0:
+            if isinstance(series.blocks[0], int):
+                # Blocks are indices - convert to block names
+                blocks_names = [block_names[i] for i, val in enumerate(series.blocks) if val != 0]
+            else:
+                # Blocks are already names
+                blocks_names = list(series.blocks)
+        else:
+            blocks_names = ['Block_Global']  # Default
+        
+        series_entry = {
+            'series_name': series.series_name,
+            'frequency': series.frequency,
+            'transformation': series.transformation,
+            'blocks': blocks_names
+        }
+        if series.release_date is not None:
+            series_entry['release'] = series.release_date
+        series_dict[series.series_id] = series_entry
+    
+    # Prepare blocks YAML content
+    blocks_dir = output_dir / 'blocks'
+    blocks_dir.mkdir(parents=True, exist_ok=True)
+    blocks_path = blocks_dir / f'{blocks_filename}.yaml'
+    
+    blocks_dict = {}
+    for block_name, block_config in config.blocks.items():
+        block_entry = {
+            'factors': block_config.factors,
+            'ar_lag': block_config.ar_lag,
+            'clock': block_config.clock
+        }
+        if block_config.notes:
+            block_entry['notes'] = block_config.notes
+        blocks_dict[block_name] = block_entry
+    
+    # Write YAML files
+    try:
+        try:
+            import yaml
+            yaml_lib = yaml
+            yaml_kwargs = {'default_flow_style': False, 'sort_keys': False, 'allow_unicode': True}
+        except ImportError:
+            try:
+                from omegaconf import OmegaConf
+                yaml_lib = OmegaConf
+                yaml_kwargs = {}
+            except ImportError:
+                raise ImportError(
+                    "Either PyYAML or omegaconf is required for YAML generation. "
+                    "Install with: pip install pyyaml or pip install omegaconf"
+                )
+        
+        # Write series YAML
+        if hasattr(yaml_lib, 'dump'):
+            # PyYAML - add blank lines between series for better readability
+            import io
+            stream = io.StringIO()
+            yaml_lib.dump(series_dict, stream, **yaml_kwargs)
+            yaml_content = stream.getvalue()
+            
+            # Add blank line before each series key (except the first one)
+            lines = yaml_content.split('\n')
+            formatted_lines = []
+            for i, line in enumerate(lines):
+                # If line starts a new series (starts with a key and colon, not indented)
+                if line and not line.startswith(' ') and ':' in line and not line.strip().startswith('#'):
+                    # Add blank line before this line (except for the first series)
+                    if i > 0 and formatted_lines and formatted_lines[-1].strip():
+                        formatted_lines.append('')
+                formatted_lines.append(line)
+            
+            with open(series_path, 'w', encoding='utf-8') as f:
+                f.write('\n'.join(formatted_lines))
+        else:
+            # OmegaConf
+            series_cfg = OmegaConf.create(series_dict)
+            OmegaConf.save(series_cfg, series_path)
+        
+        # Write blocks YAML
+        if hasattr(yaml_lib, 'dump'):
+            # PyYAML - add blank lines between blocks for better readability
+            import io
+            stream = io.StringIO()
+            yaml_lib.dump(blocks_dict, stream, **yaml_kwargs)
+            yaml_content = stream.getvalue()
+            
+            # Add blank line before each block key (except the first one)
+            lines = yaml_content.split('\n')
+            formatted_lines = []
+            for i, line in enumerate(lines):
+                # If line starts a new block (starts with a key and colon, not indented)
+                if line and not line.startswith(' ') and ':' in line and not line.strip().startswith('#'):
+                    # Add blank line before this line (except for the first block)
+                    if i > 0 and formatted_lines and formatted_lines[-1].strip():
+                        formatted_lines.append('')
+                formatted_lines.append(line)
+            
+            with open(blocks_path, 'w', encoding='utf-8') as f:
+                f.write('\n'.join(formatted_lines))
+        else:
+            # OmegaConf
+            blocks_cfg = OmegaConf.create(blocks_dict)
+            OmegaConf.save(blocks_cfg, blocks_path)
+            
+    except Exception as e:
+        raise RuntimeError(f"Failed to write YAML files: {e}")
+    
+    return series_path, blocks_path
+
+
 def make_config_source(
     source: Optional[Union[str, Path, Dict[str, Any], ConfigSource]] = None,
     *,
@@ -503,6 +704,101 @@ def make_config_source(
     )
 
 
+# ============================================================================
+# Internal helper: Load config from DataFrame
+# ============================================================================
+
+def _load_config_from_dataframe(df: pd.DataFrame) -> DFMConfig:
+    """Load configuration from DataFrame (internal helper).
+    
+    This function converts a DataFrame with series specifications into a DFMConfig.
+    It's used internally by SpecCSVSource and other config loaders.
+    
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame with columns: series_id, series_name, frequency, transformation, blocks
+        Optional columns: Release (release date)
+        Block_* columns: Binary indicators for block membership
+        
+    Returns
+    -------
+    DFMConfig
+        Model configuration object
+    """
+    series_list = []
+    block_names_set = set()
+    
+    for _, row in df.iterrows():
+        # Parse blocks from Block_* columns or 'blocks' column
+        blocks = []
+        
+        # First, try to find Block_* columns (CSV format)
+        block_cols = [col for col in df.columns 
+                     if (col.startswith('Block_') or col.startswith('Block-')) 
+                     and col not in ['blocks']]
+        
+        if block_cols:
+            # CSV format: Block_Global, Block_Consumption, etc. columns with 1/0 values
+            for block_col in block_cols:
+                block_value = row.get(block_col, 0)
+                # Handle various types: int, float, numpy int/float, bool, string "1"/"0"
+                # Check numpy types first (numpy.int64, numpy.float64, etc.)
+                if hasattr(block_value, 'item'):
+                    # numpy scalar - convert to Python native type
+                    block_value = block_value.item()
+                
+                if isinstance(block_value, (int, float)) and block_value != 0:
+                    blocks.append(block_col)
+                elif isinstance(block_value, bool) and block_value:
+                    blocks.append(block_col)
+                elif isinstance(block_value, str) and block_value.strip() in ['1', 'True', 'true']:
+                    blocks.append(block_col)
+        else:
+            # Fallback: try 'blocks' column (comma-separated string or list)
+            blocks_str = row.get('blocks', 'Block_Global')
+            if isinstance(blocks_str, str):
+                blocks = [b.strip() for b in blocks_str.split(',')]
+            elif isinstance(blocks_str, list):
+                blocks = blocks_str
+            else:
+                blocks = ['Block_Global']
+        
+        # Ensure at least Block_Global
+        if not blocks:
+            blocks = ['Block_Global']
+        
+        # Track block names
+        for block in blocks:
+            block_names_set.add(block)
+        
+        # Parse release_date if available
+        release_date = row.get('Release', None)
+        if release_date is not None:
+            try:
+                release_date = int(release_date)
+            except (ValueError, TypeError):
+                release_date = None
+        
+        series_list.append(SeriesConfig(
+            series_id=row.get('series_id', f"series_{len(series_list)}"),
+            series_name=row.get('series_name', row.get('series_id', f"Series {len(series_list)}")),
+            frequency=row.get('frequency', 'm'),
+            transformation=row.get('transformation', 'lin'),
+            blocks=blocks,
+            release_date=release_date
+        ))
+    
+    # Create default blocks if none specified
+    block_names = sorted(block_names_set) if block_names_set else ['Block_Global']
+    blocks = {}
+    for block_name in block_names:
+        blocks[block_name] = BlockConfig(factors=1, ar_lag=1, clock='m')
+    
+    # block_names is derived automatically in DFMConfig.__post_init__ from blocks dict
+    return DFMConfig(series=series_list, blocks=blocks)
+
+
 # ============================================================================
 # Hydra ConfigStore Registration (optional - only if Hydra is available)
 # ============================================================================
@@ -527,10 +823,9 @@ if HYDRA_AVAILABLE and ConfigStore is not None:
                 series_id: str
                 series_name: str
                 frequency: str
-                units: str
                 transformation: str
-                category: str
                 blocks: ListType[int]
+                units: Optional[str] = None  # Optional, for display only
             
             @schema_dataclass
             class DFMConfigSchema:

dfm_python/core/helpers.py

@@ -996,3 +996,79 @@ def validate_params(
         V_0 = np.eye(V_0.shape[0]) * default_idio_init_covariance
     
     return A, Q, R, C, Z_0, V_0
+
+
+# ============================================================================
+# Legacy config compatibility helpers
+# ============================================================================
+
+def _get_frequencies_from_config(config: Any) -> list:
+    """Get frequencies from config, supporting both new and legacy formats.
+    
+    This function provides a unified interface for accessing frequencies
+    from DFMConfig objects, handling both:
+    - New format: config.get_frequencies() method
+    - Legacy format: config.Frequency attribute
+    
+    Parameters
+    ----------
+    config : Any
+        Configuration object (DFMConfig or legacy format)
+        
+    Returns
+    -------
+    list
+        List of frequency codes for each series
+        
+    Notes
+    -----
+    - Maintains backward compatibility with legacy configuration formats
+    - Returns empty list if neither format is available
+    """
+    if hasattr(config, 'get_frequencies'):
+        return config.get_frequencies()
+    elif hasattr(config, 'Frequency'):
+        # Legacy format support: Frequency attribute (for backward compatibility)
+        freq_attr = config.Frequency
+        if hasattr(freq_attr, '__iter__') and not isinstance(freq_attr, str):
+            return list(freq_attr)
+        else:
+            return [freq_attr] if freq_attr is not None else []
+    else:
+        return []
+
+
+def _get_units_from_config(config: Any, series_index: int) -> Optional[str]:
+    """Get units for a series from config, supporting both new and legacy formats.
+    
+    This function provides a unified interface for accessing units from config,
+    handling both:
+    - New format: config.series[series_index].units
+    - Legacy format: config.UnitsTransformed[series_index]
+    
+    Parameters
+    ----------
+    config : Any
+        Configuration object (DFMConfig or legacy format)
+    series_index : int
+        Index of the series (0-based)
+        
+    Returns
+    -------
+    Optional[str]
+        Units string or None if not available
+        
+    Notes
+    -----
+    - Maintains backward compatibility with legacy configuration formats
+    - Returns None if units are not available for the series
+    """
+    # New format: SeriesConfig.units
+    if hasattr(config, 'series') and series_index < len(config.series):
+        return config.series[series_index].units
+    
+    # Legacy format: UnitsTransformed attribute
+    if hasattr(config, 'UnitsTransformed') and series_index < len(config.UnitsTransformed):
+        return config.UnitsTransformed[series_index]
+    
+    return None

dfm_python/data.py

@@ -5,6 +5,7 @@ for Dynamic Factor Model estimation.
 """
 
 import logging
+import warnings
 from pathlib import Path
 from typing import List, Optional, Tuple, Union
 
@@ -408,7 +409,6 @@ def load_data(datafile: Union[str, Path], config: DFMConfig,
         if len(warnings_list) > 5:
             logger.warning(f"... and {len(warnings_list) - 5} more series with T < N")
         
-        import warnings
         warnings.warn(
             f"Insufficient data: {len(warnings_list)} series have T < N (time periods < number of series). "
             f"This may cause numerical issues. Suggested fix: increase sample size or reduce number of series. "
@@ -434,7 +434,6 @@ def load_data(datafile: Union[str, Path], config: DFMConfig,
         if len(extreme_missing_series) > 5:
             logger.warning(f"... and {len(extreme_missing_series) - 5} more series with >90% missing data")
         
-        import warnings
         warnings.warn(
             f"Extreme missing data detected: {len(extreme_missing_series)} series have >90% missing values. "
             f"Estimation may be unreliable. Consider removing these series or increasing data coverage. "
@@ -446,55 +445,6 @@ def load_data(datafile: Union[str, Path], config: DFMConfig,
     return X, Time, Z
 
 
-def _load_config_from_dataframe(df: pd.DataFrame) -> DFMConfig:
-    """Load configuration from DataFrame (internal helper).
-    
-    This function converts a DataFrame with series specifications into a DFMConfig.
-    It's used internally by SpecCSVSource and other config loaders.
-    
-    Parameters
-    ----------
-    df : pd.DataFrame
-        DataFrame with columns: series_id, series_name, frequency, transformation, blocks
-        
-    Returns
-    -------
-    DFMConfig
-        Model configuration object
-    """
-    series_list = []
-    block_names_set = set()
-    
-    for _, row in df.iterrows():
-        # Parse blocks (can be comma-separated string or list)
-        blocks_str = row.get('blocks', 'Block_Global')
-        if isinstance(blocks_str, str):
-            blocks = [b.strip() for b in blocks_str.split(',')]
-        else:
-            blocks = blocks_str if isinstance(blocks_str, list) else ['Block_Global']
-        
-        # Track block names
-        for block in blocks:
-            block_names_set.add(block)
-        
-        series_list.append(SeriesConfig(
-            series_id=row.get('series_id', f"series_{len(series_list)}"),
-            series_name=row.get('series_name', row.get('series_id', f"Series {len(series_list)}")),
-            frequency=row.get('frequency', 'm'),
-            transformation=row.get('transformation', 'lin'),
-            blocks=blocks
-        ))
-    
-    # Create default blocks if none specified
-    block_names = sorted(block_names_set) if block_names_set else ['Block_Global']
-    blocks = {}
-    for block_name in block_names:
-        blocks[block_name] = BlockConfig(factors=1, ar_lag=1, clock='m')
-    
-    # block_names is derived automatically in DFMConfig.__post_init__ from blocks dict
-    return DFMConfig(series=series_list, blocks=blocks)
-
-
 def rem_nans_spline(X: np.ndarray, method: int = 2, k: int = 3) -> Tuple[np.ndarray, np.ndarray]:
     """Treat NaNs in dataset for DFM estimation using standard interpolation methods.
     

dfm_python/dfm.py

@@ -301,11 +301,14 @@ class EMAlgorithmParams:
 # Core functions are imported directly from core modules - no proxy functions needed
 
 
-class DFM:
+class DFMCore:
     """Core Dynamic Factor Model class.
     
     This class provides the main DFM estimation functionality. The core algorithm
     is implemented in the `fit()` method, which performs EM estimation.
+    
+    Note: This is the core implementation class. For high-level API with
+    convenience methods, use the `DFM` class from `api.py` which extends this class.
     """
     
     def __init__(self):

dfm_python/news.py

@@ -18,6 +18,7 @@ import numpy as np
 from scipy.linalg import pinv, inv
 from typing import Tuple, Optional, Dict, Union, List, Any, Callable
 import pandas as pd
+import warnings
 import logging
 
 from .kalman import skf, fis, miss_data
@@ -61,7 +62,6 @@ def _check_config_consistency(saved_config: Any, current_config: DFMConfig) -> N
         else:
             current_ids = []
         if saved_ids != current_ids:
-                import warnings
                 warnings.warn(
                     "Config used in estimation differs from current config. "
                     "Results may be inconsistent. Consider re-estimating.",
@@ -552,12 +552,9 @@ def update_nowcast(X_old: np.ndarray, X_new: np.ndarray, Time: pd.DatetimeIndex,
     # Validate period format
     try:
         i_series = series_ids.index(series)
-        if hasattr(config, 'get_frequencies'):
-            frequencies = config.get_frequencies()
-        elif hasattr(config, 'Frequency'):
-            frequencies = config.Frequency
-        else:
-            frequencies = []
+        # Get frequencies using unified helper function (supports both new and legacy formats)
+        from .core.helpers import _get_frequencies_from_config
+        frequencies = _get_frequencies_from_config(config)
         freq = frequencies[i_series] if i_series < len(frequencies) else 'm'
         if freq == 'm':
             # Format: YYYYmMM (e.g., "2016m12")
@@ -650,12 +647,9 @@ def update_nowcast(X_old: np.ndarray, X_new: np.ndarray, Time: pd.DatetimeIndex,
     else:
         series_names = []
     
-    if hasattr(config, 'get_frequencies'):
-        frequencies = config.get_frequencies()
-    elif hasattr(config, 'Frequency'):
-        frequencies = config.Frequency
-    else:
-        frequencies = []
+    # Get frequencies using unified helper function (supports both new and legacy formats)
+    from .core.helpers import _get_frequencies_from_config
+    frequencies = _get_frequencies_from_config(config)
     series_name = series_names[i_series] if i_series < len(series_names) else series
     freq = frequencies[i_series] if i_series < len(frequencies) else 'm'
     
@@ -705,14 +699,13 @@ def update_nowcast(X_old: np.ndarray, X_new: np.ndarray, Time: pd.DatetimeIndex,
     else:
         period_str = pd.Timestamp(Time[t_nowcast]).strftime('%Y-%m')
     
-    # Get units
-    if hasattr(config, 'series') and i_series < len(config.series):
-        units = config.series[i_series].units
-    elif hasattr(config, 'UnitsTransformed') and i_series < len(config.UnitsTransformed):
-        units = config.UnitsTransformed[i_series]
-    else:
-        units = ""
-    print(f'Nowcast for {series_name} ({units}), {period_str}')
+    # Get units using unified helper function (supports both new and legacy formats)
+    from .core.helpers import _get_units_from_config
+    units = _get_units_from_config(config, i_series)
+    
+    # Format units for display
+    units_str = f" ({units})" if units else ""
+    print(f'Nowcast for {series_name}{units_str}, {period_str}')
     
     if len(forecast) == 0 or np.all(np.isnan(forecast)):
         print('\n  No forecast was made.\n')
@@ -774,7 +767,6 @@ def update_nowcast(X_old: np.ndarray, X_new: np.ndarray, Time: pd.DatetimeIndex,
                     Res=Res
                 )
             except Exception as e:
-                import warnings
                 warnings.warn(
                     f"save_callback failed: {e}. Continuing without saving.",
                     UserWarning

dfm_python/utils.py

@@ -224,13 +224,10 @@ def get_aggregation_structure(
     >>> print(agg_info['tent_weights'])
     {'q': array([1, 2, 3, 2, 1]), 'sa': array([1, 2, 3, 4, 3, 2, 1])}
     """
-    # Get frequencies using new API with fallback for legacy configs
-    if hasattr(config, 'get_frequencies'):
-        frequencies = set(config.get_frequencies())
-    elif hasattr(config, 'Frequency'):
-        frequencies = set(config.Frequency)
-    else:
-        frequencies = set()
+    # Get frequencies using unified helper function (supports both new and legacy formats)
+    from .core.helpers import _get_frequencies_from_config
+    frequencies_list = _get_frequencies_from_config(config)
+    frequencies = set(frequencies_list)
     structures = {}
     tent_weights = {}
     n_periods_map = {}

{dfm_python-0.2.8.dist-info → dfm_python-0.2.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.2.8
+Version: 0.2.9
 Summary: Dynamic Factor Model (DFM) estimation and nowcasting in Python
 Project-URL: Homepage, https://github.com/yourusername/dfm-python
 Project-URL: Documentation, https://github.com/yourusername/dfm-python#readme
@@ -25,18 +25,12 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: scipy>=1.10.0
 Provides-Extra: all
-Requires-Dist: httpx>=0.24.0; extra == 'all'
 Requires-Dist: hydra-core>=1.3.0; extra == 'all'
 Requires-Dist: omegaconf>=2.3.0; extra == 'all'
-Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
-Requires-Dist: pydantic-settings>=2.11.0; extra == 'all'
 Requires-Dist: pytest>=7.0.0; extra == 'all'
-Requires-Dist: supabase>=2.0.0; extra == 'all'
-Provides-Extra: database
-Requires-Dist: httpx>=0.24.0; extra == 'database'
-Requires-Dist: psycopg2-binary>=2.9.0; extra == 'database'
-Requires-Dist: pydantic-settings>=2.11.0; extra == 'database'
-Requires-Dist: supabase>=2.0.0; extra == 'database'
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'all'
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'db'
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Provides-Extra: hydra

dfm_python-0.2.9.dist-info/RECORD

@@ -0,0 +1,18 @@
+dfm_python/__init__.py,sha256=ygVrK-7Q8VPyOIPMib15hVu5AFQO-ILSCgFR8fsXcyU,4844
+dfm_python/api.py,sha256=d18qOn1XG5F7gTuoFWxQ_6xhGff9AjGbym5Ji3m6Qfw,16989
+dfm_python/config.py,sha256=-SkouUFq38-rQKfyFcg1nI4_YkNbwGCwogNQiyOOT8A,47193
+dfm_python/config_sources.py,sha256=0e5_yOWUlMZA7bEgSAJF_ZFqr-vKTlhsqpl84GB2ySY,33193
+dfm_python/data.py,sha256=22M9zn2fS1yaZvJe94k2BgOkH9LFwVKw_WltnVu-qFs,20380
+dfm_python/dfm.py,sha256=ANG_-7qCizp8VS5tdR_aJoBtPhvRR4QGJjvntEpA6KY,35109
+dfm_python/kalman.py,sha256=EXhloLbpzy7GKG9KFrSZt9pRp0y3CZyvycPVbvUWxq8,18074
+dfm_python/news.py,sha256=abt6X7q-9b6TL0aRcCjhLUGuBOEnjo-pfK4kXgkLo8A,32503
+dfm_python/utils.py,sha256=cRb3afQzpbh_RqoScaq25jH08bn1qImz_MADdFWRteY,15674
+dfm_python/core/__init__.py,sha256=oDrhAoc1W_ODohgufQ-gN0uri8-vZI0EXsF0dysth_A,331
+dfm_python/core/diagnostics.py,sha256=1ninWcQlWhJmfUZq9kky7IQoRf_6fI_IlVzzSb7apRQ,28085
+dfm_python/core/em.py,sha256=jbtsFHynMDtblZTtlzgodX04e86BBB9hPn20MMnV3w0,72705
+dfm_python/core/helpers.py,sha256=NMM04OdSbrG73QDciuue8x0XvxleLYWr-OBzvG1wQ8c,34109
+dfm_python/core/numeric.py,sha256=IcIwcKtMhIoJ5-7Mz6UNYwTUtEa5W_ZMnQtF87v0SSc,26431
+dfm_python-0.2.9.dist-info/METADATA,sha256=0sOxEYOl7hJhj3vGe9CTLoj8D59Q1bbuqvkOjnresfQ,28264
+dfm_python-0.2.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dfm_python-0.2.9.dist-info/licenses/LICENSE,sha256=6e87br6LCDHjy2hdIR1-sdBQy351qdmSEbOg6jQ7ZXY,1063
+dfm_python-0.2.9.dist-info/RECORD,,

dfm_python-0.2.8.dist-info/RECORD

@@ -1,18 +0,0 @@
-dfm_python/__init__.py,sha256=oz0p9JreUg6D9SfU2vUAFMRwf7JwHaa3dQDy87YHtIw,5589
-dfm_python/api.py,sha256=-mmV7aaXOAqVW9HPhTEut7T6wN1EyW0rS3J0y-z-MRs,16221
-dfm_python/config.py,sha256=bBiKfoETohNVJ3brRbY1330C1nQROybCR3co9iagIKs,46978
-dfm_python/config_sources.py,sha256=6LTK7k5WJpnayMmtxtYwZ9SQi_hGXoz-Vg4sRGTabI0,21798
-dfm_python/data.py,sha256=GpvI4dZ48-uUI_rbsQhCq2WcbhyHJ-foER7-baTyHo8,22223
-dfm_python/dfm.py,sha256=9k_0RyxtsbZZrfqhAKmxX4CQy41CCoPolbe_oi8a_K8,34942
-dfm_python/kalman.py,sha256=EXhloLbpzy7GKG9KFrSZt9pRp0y3CZyvycPVbvUWxq8,18074
-dfm_python/news.py,sha256=iXbJnsvH5FgKToPzKnqIpTosrZu-QHXBNHjsqwMYrHo,32583
-dfm_python/utils.py,sha256=qOAJm2KG71yP2a29iJVDGOC-ZUS_HPL5oAo16EgNXA4,15709
-dfm_python/core/__init__.py,sha256=oDrhAoc1W_ODohgufQ-gN0uri8-vZI0EXsF0dysth_A,331
-dfm_python/core/diagnostics.py,sha256=1ninWcQlWhJmfUZq9kky7IQoRf_6fI_IlVzzSb7apRQ,28085
-dfm_python/core/em.py,sha256=jbtsFHynMDtblZTtlzgodX04e86BBB9hPn20MMnV3w0,72705
-dfm_python/core/helpers.py,sha256=XJvWWEZlUqozBfFNcENKgbOOFkwlm-tGwO-u0LnAf-E,31541
-dfm_python/core/numeric.py,sha256=IcIwcKtMhIoJ5-7Mz6UNYwTUtEa5W_ZMnQtF87v0SSc,26431
-dfm_python-0.2.8.dist-info/METADATA,sha256=wY69TZa4fK9I4zY4t7hQUJksWuMCyxtGUS0Nr_C3SPk,28599
-dfm_python-0.2.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dfm_python-0.2.8.dist-info/licenses/LICENSE,sha256=6e87br6LCDHjy2hdIR1-sdBQy351qdmSEbOg6jQ7ZXY,1063
-dfm_python-0.2.8.dist-info/RECORD,,