dfm-python 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

dfm_python/config.py

@@ -1,48 +1,35 @@
-"""Configuration models and source adapters for DFM nowcasting.
+"""Configuration models and factory methods for DFM nowcasting.
 
-This module provides a unified configuration system for Dynamic Factor Models:
+This module provides the core configuration system for Dynamic Factor Models:
 - Configuration dataclasses (DFMConfig, SeriesConfig, BlockConfig, Params)
-- Configuration source adapters (YAML, Dict, Spec CSV, Hydra)
-- Factory functions for flexible config loading
+- Factory methods for creating DFMConfig from dictionaries and Hydra configs
 
-The configuration system supports:
-- YAML files (with Hydra/OmegaConf support)
-- Direct DFMConfig object creation
-- Spec CSV files (series definitions)
-- Dictionary configurations
-- Merging multiple configuration sources
+The configuration dataclasses define:
+- Model structure (series, blocks, factors)
+- Estimation parameters (EM algorithm settings)
+- Numerical stability controls (regularization, clipping, damping)
 
-All adapters return a DFMConfig object, ensuring a consistent interface
-regardless of the source format.
+Factory methods support:
+- Dictionary configurations (legacy format, new format, Hydra format)
+- Hydra DictConfig objects (via from_hydra())
+
+For loading configurations from files (YAML, Spec CSV) or other sources,
+see the config_sources module which provides source adapters.
+
+Note: Source adapter classes (YamlSource, DictSource, etc.) are re-exported
+from config_sources for backward compatibility.
 """
 
 import numpy as np
 from typing import List, Optional, Dict, Any, Union
-from pathlib import Path
-import warnings
-import logging
-from dataclasses import dataclass, field, is_dataclass, asdict
+from dataclasses import dataclass, field
 
 try:
     from typing import Protocol
 except ImportError:
     from typing_extensions import Protocol
 
-try:
-    from hydra.core.config_store import ConfigStore
-    HYDRA_AVAILABLE = True
-except ImportError:
-    HYDRA_AVAILABLE = False
-    ConfigStore = None
-
-# Valid frequency codes
-_VALID_FREQUENCIES = {'d', 'w', 'm', 'q', 'sa', 'a'}
-
-# Valid transformation codes
-_VALID_TRANSFORMATIONS = {
-    'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 
-    'cch', 'cca', 'log'
-}
+# Validation functions are defined at the end of this file
 
 # Default global block name (can be overridden in config)
 DEFAULT_GLOBAL_BLOCK_NAME = 'Block_Global'
@@ -61,20 +48,6 @@ _TRANSFORM_UNITS_MAP = {
 }
 
 
-def validate_frequency(frequency: str) -> str:
-    """Validate frequency code."""
-    if frequency not in _VALID_FREQUENCIES:
-        raise ValueError(f"Invalid frequency: {frequency}. Must be one of {_VALID_FREQUENCIES}")
-    return frequency
-
-
-def validate_transformation(transformation: str) -> str:
-    """Validate transformation code."""
-    if transformation not in _VALID_TRANSFORMATIONS:
-        warnings.warn(f"Unknown transformation code: {transformation}. Will use untransformed data.")
-    return transformation
-
-
 @dataclass
 class BlockConfig:
     """Configuration for a single factor block.
@@ -224,9 +197,12 @@ class Params:
     max_iter : int
         Maximum EM iterations (default: 5000)
     nan_method : int
-        Missing data handling method (1-5, default: 2 = spline interpolation)
+        Missing data handling method (1-5, default: 2 = spline interpolation).
+        This preprocessing step is followed by Kalman Filter-based missing data
+        handling during DFM estimation, following standard practice in state-space
+        models (Mariano & Murasawa 2003, Harvey 1989).
     nan_k : int
-        Spline parameter for NaN interpolation (default: 3)
+        Spline parameter for NaN interpolation (default: 3 for cubic spline)
     clock : str
         Base frequency for all latent factors (default: 'm' for monthly)
     clip_ar_coefficients : bool
@@ -259,6 +235,14 @@ class Params:
         Damping factor: 0.8 = 80% new, 20% old (default: 0.8)
     warn_on_damped_update : bool
         Warn when damped updates are used (default: True)
+    augment_idio : bool
+        Enable state augmentation with idiosyncratic components (default: True)
+    augment_idio_slow : bool
+        Enable tent-length chains for slower-frequency series (default: True)
+    idio_rho0 : float
+        Initial AR coefficient for idiosyncratic components (default: 0.1)
+    idio_min_var : float
+        Minimum variance for idiosyncratic innovation covariance (default: 1e-8)
     
     Examples
     --------
@@ -297,6 +281,12 @@ class Params:
     damping_factor: float = 0.8
     warn_on_damped_update: bool = True
     
+    # Idiosyncratic component augmentation
+    augment_idio: bool = True  # Enable state augmentation with idiosyncratic components (default: True)
+    augment_idio_slow: bool = True  # Enable tent-length chains for slower-frequency series (default: True)
+    idio_rho0: float = 0.1  # Initial AR coefficient for idiosyncratic components (default: 0.1)
+    idio_min_var: float = 1e-8  # Minimum variance for idiosyncratic innovation covariance (default: 1e-8)
+    
     def __post_init__(self):
         """Validate parameters."""
         self.clock = validate_frequency(self.clock)
@@ -340,8 +330,8 @@ class DFMConfig:
     ar_lag: int = 1  # Number of lags in AR transition equation (lookback window)
     threshold: float = 1e-5  # EM convergence threshold
     max_iter: int = 5000  # Maximum EM iterations
-    nan_method: int = 2  # Missing data handling method (1-5)
-    nan_k: int = 3  # Spline parameter for NaN interpolation
+    nan_method: int = 2  # Missing data handling method (1-5). Preprocessing step before Kalman Filter-based handling
+    nan_k: int = 3  # Spline parameter for NaN interpolation (cubic spline)
     clock: str = 'm'  # Base frequency for nowcasting (global clock): 'd', 'w', 'm', 'q', 'sa', 'a' (defaults to 'm' for monthly)
     
     # ========================================================================
@@ -370,6 +360,12 @@ class DFMConfig:
     damping_factor: float = 0.8  # Damping factor (0.8 = 80% new, 20% old)
     warn_on_damped_update: bool = True  # Warn when damped updates are used
     
+    # Idiosyncratic Component Augmentation
+    augment_idio: bool = True  # Enable state augmentation with idiosyncratic components (default: True)
+    augment_idio_slow: bool = True  # Enable tent-length chains for slower-frequency series (default: True)
+    idio_rho0: float = 0.1  # Initial AR coefficient for idiosyncratic components (default: 0.1)
+    idio_min_var: float = 1e-8  # Minimum variance for idiosyncratic innovation covariance (default: 1e-8)
+    
     # ========================================================================
     # Internal cache (not user-configurable)
     # ========================================================================
@@ -394,7 +390,7 @@ class DFMConfig:
             indicating what needs to be fixed.
         """
         # Import frequency hierarchy for validation
-        from .utils.aggregation import FREQUENCY_HIERARCHY
+        from .utils import FREQUENCY_HIERARCHY
         
         if not self.series:
             raise ValueError(
@@ -443,7 +439,9 @@ class DFMConfig:
             if block_clock_hierarchy < global_clock_hierarchy:
                 raise ValueError(
                     f"Block '{block_name}' has clock '{block_cfg.clock}' which is faster than "
-                    f"global clock '{self.clock}'. Block clocks must be >= global clock."
+                    f"global clock '{self.clock}'. Block clocks must be >= global clock. "
+                    f"Suggested fix: change block '{block_name}' clock to '{self.clock}' or slower, "
+                    f"or set global clock to '{block_cfg.clock}' or faster."
                 )
         
         # Auto-generate series_id if not provided and convert blocks to indices
@@ -493,11 +491,17 @@ class DFMConfig:
                     
                     # Series frequency must be <= block clock (slower or equal)
                     if series_freq_hierarchy < block_clock_hierarchy:
+                        # Suggest valid frequencies for the series
+                        valid_freqs = [freq for freq, hier in FREQUENCY_HIERARCHY.items() 
+                                      if hier >= block_clock_hierarchy]
+                        valid_freqs_str = ', '.join(sorted(valid_freqs))
                         raise ValueError(
                             f"Series '{s.series_id}' has frequency '{s.frequency}' which is faster than "
                             f"block '{block_name}' clock '{block_cfg.clock}'. "
                             f"Series in a block must have frequency <= block clock. "
-                            f"Either change the series frequency or move it to a faster block."
+                            f"Suggested fix: change series frequency to one of [{valid_freqs_str}] "
+                            f"(slower or equal to block clock '{block_cfg.clock}'), "
+                            f"or set block clock to '{s.frequency}' or faster."
                         )
         
         # Validate factors_per_block
@@ -535,6 +539,106 @@ class DFMConfig:
             self._cached_blocks = np.array(blocks_list, dtype=int)
         return self._cached_blocks
     
+    def validate_and_report(self) -> Dict[str, Any]:
+        """Validate configuration and return structured report with issues and suggestions.
+        
+        This method performs validation checks without raising exceptions, returning
+        a structured report that can be used for debugging and user guidance.
+        
+        Returns
+        -------
+        Dict[str, Any]
+            Report dictionary with keys:
+            - 'valid': bool - Whether configuration is valid
+            - 'errors': List[str] - List of error messages
+            - 'warnings': List[str] - List of warning messages
+            - 'suggestions': List[str] - List of actionable suggestions
+            
+        Examples
+        --------
+        >>> config = DFMConfig(...)
+        >>> report = config.validate_and_report()
+        >>> if not report['valid']:
+        ...     print("Errors:", report['errors'])
+        ...     print("Suggestions:", report['suggestions'])
+        """
+        from .utils import FREQUENCY_HIERARCHY
+        
+        report = {
+            'valid': True,
+            'errors': [],
+            'warnings': [],
+            'suggestions': []
+        }
+        
+        # Check for empty series
+        if not self.series:
+            report['valid'] = False
+            report['errors'].append("DFM configuration must contain at least one series.")
+            report['suggestions'].append("Add series definitions to your configuration.")
+            return report
+        
+        # Check for empty blocks
+        if not self.blocks:
+            report['valid'] = False
+            report['errors'].append("DFM configuration must contain at least one block.")
+            report['suggestions'].append("Add block definitions to your configuration.")
+            return report
+        
+        # Check frequency constraints
+        global_clock_hierarchy = FREQUENCY_HIERARCHY.get(self.clock, 3)
+        for i, s in enumerate(self.series):
+            series_freq_hierarchy = FREQUENCY_HIERARCHY.get(s.frequency, 3)
+            
+            for block_idx, loads_on_block in enumerate(s.blocks):
+                if loads_on_block == 1:
+                    if block_idx < len(self.block_names):
+                        block_name = self.block_names[block_idx]
+                        block_cfg = self.blocks[block_name]
+                        block_clock_hierarchy = FREQUENCY_HIERARCHY.get(block_cfg.clock, 3)
+                        
+                        if series_freq_hierarchy < block_clock_hierarchy:
+                            valid_freqs = [freq for freq, hier in FREQUENCY_HIERARCHY.items() 
+                                          if hier >= block_clock_hierarchy]
+                            valid_freqs_str = ', '.join(sorted(valid_freqs))
+                            report['valid'] = False
+                            report['errors'].append(
+                                f"Series '{s.series_id}' has frequency '{s.frequency}' which is faster than "
+                                f"block '{block_name}' clock '{block_cfg.clock}'."
+                            )
+                            report['suggestions'].append(
+                                f"For series '{s.series_id}': change frequency to one of [{valid_freqs_str}], "
+                                f"or set block '{block_name}' clock to '{s.frequency}' or faster."
+                            )
+        
+        # Check block clock constraints
+        for block_name, block_cfg in self.blocks.items():
+            block_clock_hierarchy = FREQUENCY_HIERARCHY.get(block_cfg.clock, 3)
+            if block_clock_hierarchy < global_clock_hierarchy:
+                report['valid'] = False
+                report['errors'].append(
+                    f"Block '{block_name}' has clock '{block_cfg.clock}' which is faster than "
+                    f"global clock '{self.clock}'."
+                )
+                report['suggestions'].append(
+                    f"Change block '{block_name}' clock to '{self.clock}' or slower, "
+                    f"or set global clock to '{block_cfg.clock}' or faster."
+                )
+        
+        # Check factors_per_block
+        if any(f < 1 for f in self.factors_per_block):
+            invalid_blocks = [i for i, f in enumerate(self.factors_per_block) if f < 1]
+            report['valid'] = False
+            report['errors'].append(
+                f"factors_per_block must contain positive integers (>= 1). "
+                f"Invalid values found at block indices {invalid_blocks}."
+            )
+            report['suggestions'].append(
+                f"Set factors_per_block[{invalid_blocks[0]}] to at least 1 for block '{self.block_names[invalid_blocks[0]]}'."
+            )
+        
+        return report
+    
     # Note: Legacy PascalCase properties were removed to keep the API clean and generic.
     # Use the snake_case helper methods above.
     
@@ -567,7 +671,12 @@ class DFMConfig:
             'warn_on_regularization': data.get('warn_on_regularization', True),
             'use_damped_updates': data.get('use_damped_updates', True),
             'damping_factor': data.get('damping_factor', 0.8),
-            'warn_on_damped_update': data.get('warn_on_damped_update', True)
+            'warn_on_damped_update': data.get('warn_on_damped_update', True),
+            # Idiosyncratic component augmentation
+            'augment_idio': data.get('augment_idio', True),
+            'augment_idio_slow': data.get('augment_idio_slow', True),
+            'idio_rho0': data.get('idio_rho0', 0.1),
+            'idio_min_var': data.get('idio_min_var', 1e-8)
         }
     
     @classmethod
@@ -825,536 +934,104 @@ class DFMConfig:
         return cls.from_dict(cfg)
 
 
-# Register with Hydra ConfigStore (optional - only if Hydra is available)
-if HYDRA_AVAILABLE and ConfigStore is not None:
-    try:
-        cs = ConfigStore.instance()
-        if cs is not None:
-            from dataclasses import dataclass as schema_dataclass
-            
-            @schema_dataclass
-            class SeriesConfigSchema:
-                """Schema for SeriesConfig validation in Hydra."""
-                series_id: str
-                series_name: str
-                frequency: str
-                units: str
-                transformation: str
-                category: str
-                blocks: List[int]
-            
-            @schema_dataclass
-            class DFMConfigSchema:
-                """Schema for unified DFMConfig validation in Hydra."""
-                series: List[SeriesConfigSchema]
-                block_names: List[str]
-                factors_per_block: Optional[List[int]] = None
-                ar_lag: int = 1
-                threshold: float = 1e-5
-                max_iter: int = 5000
-                nan_method: int = 2
-                nan_k: int = 3
-                clock: str = 'm'
-            
-            # Register schemas
-            cs.store(group="dfm", name="base_dfm_config", node=DFMConfigSchema)
-            cs.store(group="model", name="base_model_config", node=DFMConfigSchema)
-            cs.store(name="dfm_config_schema", node=DFMConfigSchema)
-            cs.store(name="model_config_schema", node=DFMConfigSchema)
-            
-    except Exception as e:
-        warnings.warn(f"Could not register Hydra structured config schemas: {e}. "
-                     f"Configs will still work via from_dict() but without schema validation.")
-
-
 # ============================================================================
 # Configuration Source Adapters
 # ============================================================================
 
-logger = logging.getLogger(__name__)
+# Import ConfigSource classes from separate module
+from .config_sources import (
+    ConfigSource,
+    YamlSource,
+    DictSource,
+    SpecCSVSource,
+    HydraSource,
+    MergedConfigSource,
+    make_config_source,
+)
 
+# Re-export for backward compatibility
+__all__ = [
+    'DFMConfig', 'SeriesConfig', 'BlockConfig', 'Params',
+    'DEFAULT_GLOBAL_BLOCK_NAME',
+    'ConfigSource', 'YamlSource', 'DictSource', 'SpecCSVSource',
+    'HydraSource', 'MergedConfigSource', 'make_config_source',
+]
 
-class ConfigSource(Protocol):
-    """Protocol for configuration sources.
-    
-    Any object that implements a `load()` method returning a DFMConfig
-    can be used as a configuration source.
-    """
-    def load(self) -> DFMConfig:
-        """Load and return a DFMConfig object."""
-        ...
+# Legacy class definitions removed - now in config_sources.py
+# For backward compatibility, classes are imported and re-exported above
 
 
-class YamlSource:
-    """Load configuration from a YAML file.
-    
-    Supports Hydra-style configs with defaults for series and blocks.
-    """
-    def __init__(self, yaml_path: Union[str, Path]):
-        """Initialize YAML source.
-        
-        Parameters
-        ----------
-        yaml_path : str or Path
-            Path to YAML configuration file
-        """
-        self.yaml_path = Path(yaml_path)
-    
-    def load(self) -> DFMConfig:
-        """Load configuration from YAML file."""
-        try:
-            from omegaconf import OmegaConf
-        except ImportError:
-            raise ImportError("omegaconf is required for YAML config loading. Install with: pip install omegaconf")
-        
-        configfile = Path(self.yaml_path)
-        if not configfile.exists():
-            raise FileNotFoundError(f"Configuration file not found: {configfile}")
-        
-        config_dir = configfile.parent
-        cfg = OmegaConf.load(configfile)
-        cfg_dict = OmegaConf.to_container(cfg, resolve=True)
-        
-        # Extract main settings (estimation parameters)
-        excluded_keys = {'defaults', '_target_', '_recursive_', '_convert_'}
-        main_settings = {k: v for k, v in cfg_dict.items() if k not in excluded_keys}
-        
-        # 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
-        
-        # 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):
-                    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', [])
-                    ))
-        
-        # If no series loaded from separate files, try to get from main config
-        if not series_loaded and 'series' in cfg_dict:
-            series_data = cfg_dict['series']
-            if isinstance(series_data, list):
-                for series_item in series_data:
-                    series_list.append(SeriesConfig(**series_item))
-            elif isinstance(series_data, dict):
-                for series_id, series_item in series_data.items():
-                    if isinstance(series_item, dict):
-                        series_item['series_id'] = series_id
-                        series_list.append(SeriesConfig(**series_item))
-        
-        # 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
-        
-        # Convert blocks dict to BlockConfig objects
-        if blocks_loaded and blocks_dict_raw is not None:
-            for block_name, block_data in blocks_dict_raw.items():
-                if isinstance(block_data, dict):
-                    blocks_dict[block_name] = BlockConfig(
-                        factors=block_data.get('factors', 1),
-                        ar_lag=block_data.get('ar_lag', 1),
-                        clock=block_data.get('clock', 'm'),
-                        notes=block_data.get('notes', None)
-                    )
-        
-        # If no blocks loaded from separate files, try to get from main config
-        if not blocks_loaded and 'blocks' in cfg_dict:
-            blocks_data = cfg_dict['blocks']
-            if isinstance(blocks_data, dict):
-                for block_name, block_item in blocks_data.items():
-                    if isinstance(block_item, dict):
-                        blocks_dict[block_name] = BlockConfig(**block_item)
-        
-        # Ensure at least one block exists
-        if not blocks_dict:
-            blocks_dict[DEFAULT_GLOBAL_BLOCK_NAME] = BlockConfig(factors=1, clock=main_settings.get('clock', 'm'))
-        
-        return DFMConfig(
-            series=series_list,
-            blocks=blocks_dict,
-            **main_settings
-        )
+# ============================================================================
+# Configuration validation functions
+# ============================================================================
 
+# Valid frequency codes
+_VALID_FREQUENCIES = {'d', 'w', 'm', 'q', 'sa', 'a'}
 
-class DictSource:
-    """Load configuration from a dictionary.
-    
-    Supports multiple dict formats:
-    - Legacy format: {'SeriesID': [...], 'Frequency': [...], ...}
-    - New format (list): {'series': [{'series_id': ..., ...}], ...}
-    - Hydra format: {'series': {'series_id': {...}}, 'blocks': {...}}
-    """
-    def __init__(self, mapping: Dict[str, Any]):
-        """Initialize dictionary source.
-        
-        Parameters
-        ----------
-        mapping : dict
-            Dictionary containing configuration data
-        """
-        self.mapping = mapping
-    
-    def load(self) -> DFMConfig:
-        """Load configuration from dictionary.
-        
-        If the dictionary is partial (e.g., only max_iter, threshold),
-        it will be merged with a minimal default config.
-        """
-        # Check if this is a partial config (missing series or blocks)
-        has_series = 'series' in self.mapping and self.mapping['series']
-        has_blocks = 'blocks' in self.mapping and self.mapping['blocks']
-        
-        if not has_series or not has_blocks:
-            # This is a partial config - create a minimal default and merge
-            minimal_default = {
-                'series': [],
-                'blocks': {},
-                'clock': 'm',
-                'max_iter': 5000,
-                'threshold': 1e-5
-            }
-            # Merge: mapping takes precedence
-            merged = {**minimal_default, **self.mapping}
-            return DFMConfig.from_dict(merged)
-        
-        return DFMConfig.from_dict(self.mapping)
+# Valid transformation codes
+_VALID_TRANSFORMATIONS = {
+    'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 
+    'cch', 'cca', 'log'
+}
 
 
-class SpecCSVSource:
-    """Load series definitions from a spec CSV file.
-    
-    This source reads series definitions and block memberships from a CSV.
-    It constructs a valid DFMConfig with sensible defaults for other
-    parameters (e.g., clock='m', threshold=1e-5, max_iter=5000, factors=1).
-    
-    For custom main settings (threshold, max_iter, clock, per-block factors),
-    you can still merge with a base config via MergedConfigSource or
-    dfm.load_config(base=..., override=spec_path).
-    """
-    def __init__(self, spec_path: Union[str, Path]):
-        """Initialize spec CSV source.
-        
-        Parameters
-        ----------
-        spec_path : str or Path
-            Path to spec CSV file
-        """
-        self.spec_path = Path(spec_path)
+def validate_frequency(frequency: str) -> str:
+    """Validate frequency code.
     
-    def load(self) -> DFMConfig:
-        """Load series definitions from spec CSV."""
-        import pandas as pd
-        from .data_loader import _load_config_from_dataframe
-        
-        specfile = Path(self.spec_path)
-        if not specfile.exists():
-            raise FileNotFoundError(f"Spec file not found: {specfile}")
+    Parameters
+    ----------
+    frequency : str
+        Frequency code to validate
         
-        try:
-            df_full = pd.read_csv(specfile)
-        except Exception as e:
-            raise ValueError(f"Failed to read spec file {specfile}: {e}")
+    Returns
+    -------
+    str
+        Validated frequency code (same as input if valid)
         
-        return _load_config_from_dataframe(df_full)
-
-
-class HydraSource:
-    """Load configuration from a Hydra DictConfig or dict.
-    
-    This adapter handles Hydra's composed configuration objects,
-    converting them to DFMConfig format.
-    """
-    def __init__(self, cfg: Union[Dict[str, Any], 'DictConfig']):
-        """Initialize Hydra source.
+    Raises
+    ------
+    ValueError
+        If frequency is not in the set of valid frequencies
         
-        Parameters
-        ----------
-        cfg : DictConfig or dict
-            Hydra configuration object or dictionary in Hydra format
-        """
-        self.cfg = cfg
-    
-    def load(self) -> DFMConfig:
-        """Load configuration from Hydra DictConfig/dict."""
-        return DFMConfig.from_hydra(self.cfg)
-
-
-class MergedConfigSource:
-    """Merge multiple configuration sources.
-    
-    This allows combining configurations from different sources,
-    e.g., base YAML config + series from Spec CSV.
-    
-    The merge strategy:
-    - Base config provides main settings (threshold, max_iter, clock, blocks)
-    - Override config provides series definitions (replaces base series)
-    - Block definitions are merged (override takes precedence)
+    Examples
+    --------
+    >>> validate_frequency('m')
+    'm'
+    >>> validate_frequency('invalid')
+    ValueError: Invalid frequency: invalid. Must be one of {'d', 'w', 'm', 'q', 'sa', 'a'}
     """
-    def __init__(self, base: ConfigSource, override: ConfigSource):
-        """Initialize merged config source.
-        
-        Parameters
-        ----------
-        base : ConfigSource
-            Base configuration (provides main settings)
-        override : ConfigSource
-            Override configuration (provides series/block overrides)
-        """
-        self.base = base
-        self.override = override
-    
-    def load(self) -> DFMConfig:
-        """Load and merge configurations."""
-        from dataclasses import fields
-        
-        base_cfg = self.base.load()
-        
-        # Check if override is a partial config (DictSource with partial dict)
-        override_is_partial = False
-        if isinstance(self.override, DictSource):
-            has_series = 'series' in self.override.mapping and self.override.mapping['series']
-            has_blocks = 'blocks' in self.override.mapping and self.override.mapping['blocks']
-            override_is_partial = not (has_series and has_blocks)
-        
-        if override_is_partial:
-            # Handle partial override: merge fields directly without loading full DFMConfig
-            override_dict = self.override.mapping
-            override_cfg = base_cfg  # Use base as template
-        else:
-            override_cfg = self.override.load()
-        
-        # Merge blocks: override takes precedence
-        if override_is_partial and 'blocks' in override_dict:
-            # Merge block dicts
-            merged_blocks = {**base_cfg.blocks, **override_dict['blocks']}
-        else:
-            merged_blocks = {**base_cfg.blocks, **override_cfg.blocks}
-        
-        # Use override's series if provided and non-empty, otherwise use base's series
-        if override_is_partial:
-            if 'series' in override_dict and override_dict['series']:
-                merged_series = override_dict['series']
-            else:
-                merged_series = base_cfg.series
-        else:
-            merged_series = override_cfg.series if (override_cfg.series and len(override_cfg.series) > 0) else base_cfg.series
-        
-        # Get all config fields (excluding derived/computed fields)
-        excluded_fields = {'series', 'blocks', 'block_names', 'factors_per_block', '_cached_blocks'}
-        base_settings = {
-            field.name: getattr(base_cfg, field.name)
-            for field in fields(DFMConfig)
-            if field.name not in excluded_fields
-        }
-        
-        # Override settings from override_cfg or override_dict
-        if override_is_partial:
-            override_settings = {
-                field.name: override_dict.get(field.name, getattr(base_cfg, field.name))
-                for field in fields(DFMConfig)
-                if field.name not in excluded_fields
-            }
-        else:
-            override_settings = {
-                field.name: getattr(override_cfg, field.name)
-                for field in fields(DFMConfig)
-                if field.name not in excluded_fields
-                and hasattr(override_cfg, field.name)
-            }
-        
-        # Merge settings: base + override (override takes precedence)
-        merged_settings = {**base_settings, **override_settings}
-        
-        # Create merged config: merged settings + merged series + merged blocks
-        return DFMConfig(
-            series=merged_series,
-            blocks=merged_blocks,
-            **merged_settings
-        )
+    if frequency not in _VALID_FREQUENCIES:
+        raise ValueError(f"Invalid frequency: {frequency}. Must be one of {_VALID_FREQUENCIES}")
+    return frequency
 
 
-def make_config_source(
-    source: Optional[Union[str, Path, Dict[str, Any], ConfigSource]] = None,
-    *,
-    yaml: Optional[Union[str, Path]] = None,
-    mapping: Optional[Union[Dict[str, Any], Any]] = None,
-    spec: Optional[Union[str, Path]] = None,
-    hydra: Optional[Union[Dict[str, Any], 'DictConfig']] = None,
-) -> ConfigSource:
-    """Create a ConfigSource adapter from various input formats.
-    
-    This factory function automatically selects the appropriate adapter
-    based on the input type or explicit keyword arguments.
+def validate_transformation(transformation: str) -> str:
+    """Validate transformation code.
     
     Parameters
     ----------
-    source : str, Path, dict, or ConfigSource, optional
-        Configuration source. If a ConfigSource, returned as-is.
-        If str/Path, treated as YAML file path.
-        If dict, treated as dictionary config.
-    yaml : str or Path, optional
-        Explicit YAML file path
-    mapping : dict, optional
-        Explicit dictionary config
-    spec : str or Path, optional
-        Explicit spec CSV file path
-    hydra : DictConfig or dict, optional
-        Explicit Hydra config
+    transformation : str
+        Transformation code to validate
         
     Returns
     -------
-    ConfigSource
-        Appropriate adapter for the input
-        
+    str
+        Validated transformation code (same as input, even if unknown)
+        
+    Notes
+    -----
+    Unknown transformation codes trigger a warning but are not rejected,
+    allowing for extensibility. The code will be used as-is, and the
+    transformation logic should handle unknown codes appropriately.
+    
     Examples
     --------
-    >>> # From YAML file
-    >>> source = make_config_source('config/default.yaml')
-    >>> 
-    >>> # From dictionary
-    >>> source = make_config_source({'series': [...], 'clock': 'm'})
-    >>> 
-    >>> # Explicit keyword arguments
-    >>> source = make_config_source(yaml='config/default.yaml')
-    >>> source = make_config_source(spec='data/spec.csv')
-    >>> 
-    >>> # Merge YAML base + Spec CSV series
-    >>> base = make_config_source(yaml='config/default.yaml')
-    >>> override = make_config_source(spec='data/spec.csv')
-    >>> merged = MergedConfigSource(base, override)
+    >>> validate_transformation('lin')
+    'lin'
+    >>> validate_transformation('unknown')  # Issues warning but returns value
+    'unknown'
     """
-    # Check for explicit keyword arguments (only one allowed)
-    explicit_kwargs = [k for k, v in [('yaml', yaml), ('mapping', mapping), ('spec', spec), ('hydra', hydra)] if v is not None]
-    if len(explicit_kwargs) > 1:
-        raise ValueError(
-            f"Only one of yaml, mapping, spec, or hydra can be specified. "
-            f"Got: {', '.join(explicit_kwargs)}. "
-            f"For merging configs, use MergedConfigSource."
-        )
-    
-    # Helper: coerce arbitrary object with attributes into dict
-    def _coerce_to_mapping(obj: Any) -> Dict[str, Any]:
-        if isinstance(obj, dict):
-            return obj
-        if is_dataclass(obj):
-            return asdict(obj)
-        if hasattr(obj, "__dict__"):
-            try:
-                return dict(vars(obj))
-            except Exception:
-                pass
-        raise TypeError(
-            f"Unsupported mapping type: {type(obj)}. "
-            f"Provide a dict, dataclass instance, or an object with attributes."
-        )
-    
-    # Handle explicit keyword arguments
-    if yaml is not None:
-        return YamlSource(yaml)
-    if mapping is not None:
-        return DictSource(_coerce_to_mapping(mapping))
-    if spec is not None:
-        return SpecCSVSource(spec)
-    if hydra is not None:
-        return HydraSource(hydra)
-    
-    # Infer from source argument
-    if source is None:
-        raise ValueError(
-            "No configuration source provided. "
-            "Specify source, yaml, mapping, spec, or hydra."
-        )
-    
-    # If already a ConfigSource, return as-is
-    if hasattr(source, 'load') and callable(getattr(source, 'load')):
-        return source  # type: ignore
-    
-    # Infer type from source
-    if isinstance(source, DFMConfig):
-        # Wrap DFMConfig in a simple adapter
-        class DFMConfigAdapter:
-            def __init__(self, cfg: DFMConfig):
-                self._cfg = cfg
-            def load(self) -> DFMConfig:
-                return self._cfg
-        return DFMConfigAdapter(source)
-    
-    if isinstance(source, (str, Path)):
-        path = Path(source)
-        suffix = path.suffix.lower()
-        if suffix in ['.yaml', '.yml']:
-            return YamlSource(path)
-        elif suffix == '.csv':
-            return SpecCSVSource(path)
-        else:
-            # Default to YAML if extension unclear
-            return YamlSource(path)
-    
-    if isinstance(source, dict):
-        return DictSource(source)
-    # Accept objects that can be coerced into dict (dataclass or attribute bag)
-    try:
-        coerced = _coerce_to_mapping(source)
-        return DictSource(coerced)
-    except Exception:
-        pass
-    
-    raise TypeError(
-        f"Unsupported source type: {type(source)}. "
-        f"Expected str, Path, dict, ConfigSource, or DFMConfig."
-    )
+    import warnings
+    if transformation not in _VALID_TRANSFORMATIONS:
+        warnings.warn(f"Unknown transformation code: {transformation}. Will use untransformed data.")
+    return transformation