dfm-python 0.6.12__py3-none-any.whl → 0.6.13__py3-none-any.whl

dfm_python/__init__.py

@@ -63,7 +63,7 @@ Note: DFMConfig uses frequency dict to specify series (column names -> frequenci
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.5.60"
+__version__ = "0.6.13"
 
 # ============================================================================
 # PUBLIC API DEFINITION

dfm_python/dataset/ddfm_dataset.py

@@ -111,8 +111,10 @@ class DDFMDataset(Dataset):
     
     @property
     def target_indices(self) -> np.ndarray:
-        """Target series column indices in original data."""
-        return np.array([self.data_original.columns.get_loc(col) for col in self.target_series])
+        """Target series column indices in processed data (self.data, excluding time_idx)."""
+        # target_series are column names in the processed data (self.data)
+        # self.data contains X + y (or just y), but not time_idx
+        return np.array([self.data.columns.get_loc(col) for col in self.target_series])
     
     @classmethod
     def from_dataset(cls, new_data: Union[pd.DataFrame, PolarsDataFrame], dataset: 'DDFMDataset') -> 'DDFMDataset':

dfm_python/layer/mlp.py

@@ -0,0 +1,272 @@
+"""Multi-Layer Perceptron (MLP) for common usage across models.
+
+This module provides a flexible MLP implementation that can be used
+for encoders, decoders, and other neural network components.
+"""
+
+from numbers import Number
+from typing import Union, List, Optional
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from ..config.constants import (
+    DEFAULT_XAVIER_GAIN,
+    DEFAULT_ZERO_VALUE,
+)
+from ..logger import get_logger
+from ..utils.errors import ConfigurationError
+
+_logger = get_logger(__name__)
+
+
+class MLP(nn.Module):
+    """Multi-layer perceptron with flexible architecture.
+    
+    Supports various activation functions, custom hidden dimensions,
+    and proper weight initialization.
+    """
+    
+    def __init__(
+        self,
+        input_dim: int,
+        output_dim: int,
+        hidden_dim: Union[int, List[int]] = 200,
+        n_layers: int = 3,
+        activation: Union[str, List[str]] = 'relu',
+        slope: float = 0.1,
+        use_bias: bool = True,
+        dropout: float = 0.0,
+        use_batch_norm: bool = False,
+        device: Optional[Union[str, torch.device]] = None,
+        seed: Optional[int] = None,
+    ):
+        """Initialize MLP.
+        
+        Parameters
+        ----------
+        input_dim : int
+            Input dimension
+        output_dim : int
+            Output dimension
+        hidden_dim : Union[int, List[int]]
+            Hidden layer dimension(s). If int, all hidden layers use this dimension.
+            If list, specifies dimension for each hidden layer.
+        n_layers : int
+            Total number of layers (including input and output)
+        activation : Union[str, List[str]]
+            Activation function(s). Options: 'relu', 'lrelu', 'tanh', 'sigmoid', 'none'.
+            If str, all layers use this activation. If list, specifies activation per layer.
+        slope : float
+            Slope for leaky ReLU (negative_slope parameter)
+        use_bias : bool
+            Whether to use bias in linear layers
+        dropout : float
+            Dropout probability (0.0 = no dropout)
+        use_batch_norm : bool
+            Whether to use batch normalization after each hidden layer
+        device : Optional[Union[str, torch.device]]
+            Device to move model to (None = no move)
+        seed : Optional[int]
+            Random seed for weight initialization
+        """
+        super().__init__()
+        
+        self.input_dim = input_dim
+        self.output_dim = output_dim
+        self.n_layers = n_layers
+        self.use_bias = use_bias
+        self.dropout = dropout
+        self.use_batch_norm = use_batch_norm
+        
+        # Validate and set hidden dimensions
+        if isinstance(hidden_dim, Number):
+            if n_layers < 2:
+                raise ValueError(f"n_layers must be >= 2 when hidden_dim is int, got {n_layers}")
+            self.hidden_dim = [int(hidden_dim)] * (n_layers - 1)
+        elif isinstance(hidden_dim, list):
+            if len(hidden_dim) != n_layers - 1:
+                raise ValueError(
+                    f"hidden_dim list length ({len(hidden_dim)}) must equal n_layers - 1 ({n_layers - 1})"
+                )
+            self.hidden_dim = [int(d) for d in hidden_dim]
+        else:
+            raise ValueError(f'Wrong argument type for hidden_dim: {type(hidden_dim)}')
+        
+        # Validate and set activations
+        if isinstance(activation, str):
+            self.activation = [activation] * (n_layers - 1)
+        elif isinstance(activation, list):
+            if len(activation) != n_layers - 1:
+                raise ValueError(
+                    f"activation list length ({len(activation)}) must equal n_layers - 1 ({n_layers - 1})"
+                )
+            self.activation = activation
+        else:
+            raise ValueError(f'Wrong argument type for activation: {type(activation)}')
+        
+        # Set random seed if provided
+        if seed is not None:
+            torch.manual_seed(seed)
+        
+        # Build activation functions
+        self._act_f = []
+        for act in self.activation:
+            if act == 'lrelu':
+                self._act_f.append(lambda x, s=slope: F.leaky_relu(x, negative_slope=s))
+            elif act == 'relu':
+                self._act_f.append(F.relu)
+            elif act == 'tanh':
+                self._act_f.append(torch.tanh)
+            elif act == 'sigmoid':
+                self._act_f.append(torch.sigmoid)
+            elif act == 'none' or act is None:
+                self._act_f.append(lambda x: x)
+            else:
+                raise ValueError(f'Incorrect activation: {act}. Options: relu, lrelu, tanh, sigmoid, none')
+        
+        # Build layers
+        self.layers = nn.ModuleList()
+        self.batch_norms = nn.ModuleList() if use_batch_norm else None
+        
+        if n_layers == 1:
+            # Single layer: input -> output
+            layer = nn.Linear(input_dim, output_dim, bias=use_bias)
+            self._init_linear(layer)
+            self.layers.append(layer)
+        else:
+            # First hidden layer: input -> hidden[0]
+            layer = nn.Linear(input_dim, self.hidden_dim[0], bias=use_bias)
+            self._init_linear(layer)
+            self.layers.append(layer)
+            
+            if use_batch_norm:
+                self.batch_norms.append(nn.BatchNorm1d(self.hidden_dim[0]))
+            
+            # Hidden layers: hidden[i-1] -> hidden[i]
+            for i in range(1, len(self.hidden_dim)):
+                layer = nn.Linear(self.hidden_dim[i - 1], self.hidden_dim[i], bias=use_bias)
+                self._init_linear(layer)
+                self.layers.append(layer)
+                
+                if use_batch_norm:
+                    self.batch_norms.append(nn.BatchNorm1d(self.hidden_dim[i]))
+            
+            # Output layer: hidden[-1] -> output
+            layer = nn.Linear(self.hidden_dim[-1], output_dim, bias=use_bias)
+            self._init_linear(layer, is_output=True)
+            self.layers.append(layer)
+        
+        # Dropout layer
+        if dropout > 0.0:
+            self.dropout_layer = nn.Dropout(dropout)
+        else:
+            self.dropout_layer = None
+        
+        # Move to device if specified
+        if device is not None:
+            if isinstance(device, str):
+                device = torch.device(device)
+            self.to(device)
+    
+    @staticmethod
+    def _init_linear(layer: nn.Linear, is_output: bool = False) -> None:
+        """Initialize linear layer weights and bias.
+        
+        Parameters
+        ----------
+        layer : nn.Linear
+            Linear layer to initialize
+        is_output : bool
+            Whether this is the output layer (uses different initialization)
+        """
+        # Weight initialization
+        if is_output:
+            # Output layer: Xavier normal with default gain
+            nn.init.xavier_normal_(layer.weight, gain=DEFAULT_XAVIER_GAIN)
+        else:
+            # Hidden layers: Xavier normal
+            nn.init.xavier_normal_(layer.weight, gain=DEFAULT_XAVIER_GAIN)
+        
+        # Bias initialization
+        if layer.bias is not None:
+            nn.init.constant_(layer.bias, DEFAULT_ZERO_VALUE)
+    
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Forward pass through MLP.
+        
+        Parameters
+        ----------
+        x : torch.Tensor
+            Input tensor, shape (batch, input_dim) or (batch, *, input_dim)
+        
+        Returns
+        -------
+        torch.Tensor
+            Output tensor, shape (batch, output_dim) or (batch, *, output_dim)
+        """
+        # Handle multi-dimensional input (e.g., sequences)
+        original_shape = x.shape
+        if x.dim() > 2:
+            # Flatten all dimensions except last
+            x = x.view(-1, x.shape[-1])
+            needs_reshape = True
+        else:
+            needs_reshape = False
+        
+        # Forward through layers
+        h = x
+        n_hidden = len(self.layers) - 1  # Number of hidden layers
+        
+        for i, layer in enumerate(self.layers):
+            h = layer(h)
+            
+            # Apply activation, batch norm, and dropout (except on output layer)
+            if i < n_hidden:
+                # Activation
+                h = self._act_f[i](h)
+                
+                # Batch normalization
+                if self.use_batch_norm and self.batch_norms is not None:
+                    h = self.batch_norms[i](h)
+                
+                # Dropout
+                if self.dropout_layer is not None:
+                    h = self.dropout_layer(h)
+        
+        # Reshape if needed
+        if needs_reshape:
+            output_shape = list(original_shape[:-1]) + [self.output_dim]
+            h = h.view(*output_shape)
+        
+        return h
+    
+    def get_num_parameters(self) -> int:
+        """Get total number of trainable parameters.
+        
+        Returns
+        -------
+        int
+            Number of trainable parameters
+        """
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)
+    
+    def get_layer_info(self) -> dict:
+        """Get information about MLP architecture.
+        
+        Returns
+        -------
+        dict
+            Dictionary with architecture information
+        """
+        return {
+            'input_dim': self.input_dim,
+            'output_dim': self.output_dim,
+            'hidden_dims': self.hidden_dim,
+            'n_layers': self.n_layers,
+            'activations': self.activation,
+            'use_bias': self.use_bias,
+            'dropout': self.dropout,
+            'use_batch_norm': self.use_batch_norm,
+            'num_parameters': self.get_num_parameters(),
+        }

dfm_python/layer/pca.py

@@ -0,0 +1,304 @@
+"""Principal Component Analysis (PCA) utilities.
+
+This module provides pure PCA functions for factor extraction.
+Similar to MLP, this is a utility layer without class inheritance.
+"""
+
+import numpy as np
+from typing import Tuple, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import torch
+
+from ..logger import get_logger
+from ..numeric.stability import create_scaled_identity
+from ..config.constants import DEFAULT_IDENTITY_SCALE
+from ..config.types import to_numpy
+
+_logger = get_logger(__name__)
+
+
+def compute_principal_components(
+    cov_matrix: Union[np.ndarray, "torch.Tensor"],
+    n_components: int,
+    block_idx: Optional[int] = None
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Compute top principal components via eigendecomposition (NumPy-based).
+    
+    Accepts both NumPy arrays and PyTorch tensors, but performs all
+    computations in NumPy for consistency with the refactored codebase.
+    
+    Parameters
+    ----------
+    cov_matrix : np.ndarray or torch.Tensor
+        Covariance matrix (N x N)
+    n_components : int
+        Number of principal components to extract
+    block_idx : int, optional
+        Block index for error messages
+        
+    Returns
+    -------
+    eigenvalues : np.ndarray
+        Eigenvalues (n_components,)
+    eigenvectors : np.ndarray
+        Eigenvectors (N x n_components)
+    """
+    # Convert to NumPy if needed
+    cov_matrix = to_numpy(cov_matrix)
+    
+    if cov_matrix.size == 1:
+        eigenvector = np.array([[DEFAULT_IDENTITY_SCALE]])
+        eigenvalue = cov_matrix[0, 0] if np.isfinite(cov_matrix[0, 0]) else DEFAULT_IDENTITY_SCALE
+        return np.array([eigenvalue]), eigenvector
+    
+    n_series = cov_matrix.shape[0]
+    
+    try:
+        eigenvalues, eigenvectors = np.linalg.eigh(cov_matrix)
+        
+        # Sort by absolute value, descending
+        sort_idx = np.argsort(np.abs(eigenvalues))[::-1][:n_components]
+        eigenvalues_sorted = eigenvalues[sort_idx]
+        eigenvectors_sorted = eigenvectors[:, sort_idx]
+        return np.real(eigenvalues_sorted), np.real(eigenvectors_sorted)
+    except (ValueError, np.linalg.LinAlgError) as e:
+        if block_idx is not None:
+            _logger.warning(
+                f"PCA: Eigendecomposition failed for block {block_idx+1}, "
+                f"using identity matrix as fallback. Error: {type(e).__name__}"
+            )
+        else:
+            _logger.warning(
+                f"PCA: Eigendecomposition failed, using identity matrix as fallback. Error: {type(e).__name__}"
+            )
+        eigenvectors = create_scaled_identity(n_series, DEFAULT_IDENTITY_SCALE)[:, :n_components]
+        eigenvalues = np.ones(n_components)
+        return eigenvalues, eigenvectors
+
+
+def fit_pca(
+    X: Union[np.ndarray, "torch.Tensor"],
+    n_components: int,
+    cov_matrix: Optional[Union[np.ndarray, "torch.Tensor"]] = None,
+    block_idx: Optional[int] = None
+) -> Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]:
+    """Fit PCA by computing principal components.
+    
+    If cov_matrix is provided, uses eigendecomposition.
+    If X is provided, uses NumPy's SVD for efficiency.
+    All computations are performed in NumPy.
+    
+    Parameters
+    ----------
+    X : np.ndarray or torch.Tensor
+        Training data (T x N). If cov_matrix is provided, this is ignored.
+    n_components : int
+        Number of principal components to extract
+    cov_matrix : np.ndarray or torch.Tensor, optional
+        Precomputed covariance matrix (N x N). If None, computed from X.
+    block_idx : int, optional
+        Block index for error messages
+        
+    Returns
+    -------
+    Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]
+        (eigenvalues, eigenvectors, mean, cov_matrix)
+    """
+    if cov_matrix is not None:
+        # Use eigendecomposition for covariance matrix
+        eigenvalues, eigenvectors = compute_principal_components(
+            cov_matrix, n_components, block_idx=block_idx
+        )
+        # Store as NumPy array
+        cov_matrix_np = to_numpy(cov_matrix)
+        return eigenvalues, eigenvectors, None, cov_matrix_np
+    else:
+        # Convert to NumPy if needed
+        X = to_numpy(X)
+        
+        # Center the data
+        mean_ = np.mean(X, axis=0, keepdims=True)
+        X_centered = X - mean_
+        
+        # Use SVD for efficient low-rank PCA (NumPy equivalent of torch.pca_lowrank)
+        try:
+            # Check for NaN/Inf values before SVD
+            if np.any(~np.isfinite(X_centered)):
+                raise ValueError("Input contains non-finite values")
+            
+            # Check for zero variance columns (can cause SVD issues)
+            col_stds = np.std(X_centered, axis=0)
+            if np.any(col_stds < 1e-10):
+                _logger.warning(
+                    f"PCA: Some columns have near-zero variance (min_std={col_stds.min():.2e}). "
+                    "This may cause SVD convergence issues. Consider removing constant columns."
+                )
+            
+            # Use truncated SVD for efficiency
+            U, S, Vt = np.linalg.svd(X_centered, full_matrices=False, hermitian=False)
+            
+            # Validate SVD results
+            if not np.all(np.isfinite(S)):
+                raise ValueError("SVD produced non-finite singular values")
+            
+            # Take top n_components
+            n_components_actual = min(n_components, len(S))
+            if n_components_actual < n_components:
+                _logger.warning(
+                    f"PCA: Requested {n_components} components but only {len(S)} available. "
+                    f"Using {n_components_actual} components."
+                )
+            
+            U = U[:, :n_components_actual]
+            S = S[:n_components_actual]
+            Vt = Vt[:n_components_actual, :]
+            
+            # Vt contains the principal components (eigenvectors) as rows
+            # Transpose to get (N x n_components)
+            eigenvectors = Vt.T
+            # Convert singular values to eigenvalues
+            eigenvalues = S ** 2
+            
+            return eigenvalues, eigenvectors, mean_, None
+            
+        except (ValueError, np.linalg.LinAlgError) as e:
+            # Fallback: compute covariance and use eigendecomposition
+            error_msg = str(e) if str(e) else type(e).__name__
+            _logger.warning(
+                f"PCA SVD failed ({error_msg}), falling back to eigendecomposition. "
+                "This may be due to numerical instability or ill-conditioned data."
+            )
+            
+            # Clean data for covariance computation
+            X_centered_clean = np.nan_to_num(X_centered, nan=0.0, posinf=0.0, neginf=0.0)
+            T = X_centered_clean.shape[0]
+            
+            # Compute covariance with regularization for stability
+            cov_raw = (X_centered_clean.T @ X_centered_clean) / max(T - 1, 1)
+            
+            # Add small regularization to diagonal for numerical stability
+            reg = 1e-8 * np.eye(cov_raw.shape[0], dtype=cov_raw.dtype)
+            cov_matrix_np = cov_raw + reg
+            
+            try:
+                eigenvalues, eigenvectors = compute_principal_components(
+                    cov_matrix_np, n_components, block_idx=block_idx
+                )
+                return eigenvalues, eigenvectors, mean_, cov_matrix_np
+            except (ValueError, np.linalg.LinAlgError) as e2:
+                # If eigendecomposition also fails, raise with helpful message
+                raise RuntimeError(
+                    f"PCA failed: Both SVD and eigendecomposition failed. "
+                    f"Original error: {error_msg}, Eigendecomposition error: {str(e2)}. "
+                    "This may indicate severely ill-conditioned data. "
+                    "Consider: (1) Removing constant/near-constant columns, "
+                    "(2) Checking for outliers, (3) Using fewer components."
+                ) from e2
+
+
+def encode_pca(
+    X: Union[np.ndarray, "torch.Tensor"],
+    eigenvectors: np.ndarray,
+    mean: Optional[np.ndarray] = None
+) -> np.ndarray:
+    """Extract factors using PCA eigenvectors.
+    
+    All computations are performed in NumPy. Returns NumPy array.
+    
+    Parameters
+    ----------
+    X : np.ndarray or torch.Tensor
+        Observed data (T x N)
+    eigenvectors : np.ndarray
+        PCA eigenvectors (N x n_components) from fit_pca
+    mean : Optional[np.ndarray]
+        Mean vector (1 x N) from fit_pca. If None, centers using X's mean.
+        
+    Returns
+    -------
+    factors : np.ndarray
+        Extracted factors (T x n_components)
+    """
+    # Convert to NumPy if needed
+    X = to_numpy(X)
+    
+    # Center the data
+    if mean is not None:
+        X_centered = X - mean
+    else:
+        X_centered = X - np.mean(X, axis=0, keepdims=True)
+    
+    # Project: X @ eigenvectors
+    factors = X_centered @ eigenvectors
+    
+    return factors
+
+
+# Backward compatibility wrapper class (does not inherit from BaseEncoder)
+class PCAEncoder:
+    """Principal Component Analysis encoder for factor extraction (backward compatibility wrapper).
+    
+    This is a wrapper around pure PCA functions for backward compatibility.
+    The actual implementation uses pure functions in this module (layer.pca).
+    
+    Parameters
+    ----------
+    n_components : int
+        Number of factors to extract
+    block_idx : int, optional
+        Block index for error messages
+    """
+    
+    def __init__(
+        self,
+        n_components: int,
+        block_idx: Optional[int] = None
+    ):
+        self.n_components = n_components
+        self.block_idx = block_idx
+        
+        # Will be set in fit()
+        self.eigenvectors: Optional[np.ndarray] = None
+        self.eigenvalues: Optional[np.ndarray] = None
+        self.cov_matrix: Optional[np.ndarray] = None
+        self.mean_: Optional[np.ndarray] = None
+    
+    def fit(
+        self,
+        X: Union[np.ndarray, "torch.Tensor"],
+        cov_matrix: Optional[Union[np.ndarray, "torch.Tensor"]] = None,
+        **kwargs
+    ) -> "PCAEncoder":
+        """Fit PCA encoder by computing principal components."""
+        eigenvalues, eigenvectors, mean, cov_matrix_np = fit_pca(
+            X, self.n_components, cov_matrix=cov_matrix, block_idx=self.block_idx
+        )
+        self.eigenvalues = eigenvalues
+        self.eigenvectors = eigenvectors
+        self.mean_ = mean
+        self.cov_matrix = cov_matrix_np
+        return self
+    
+    def encode(
+        self,
+        X: Union[np.ndarray, "torch.Tensor"],
+        **kwargs
+    ) -> np.ndarray:
+        """Extract factors using fitted PCA encoder."""
+        if self.eigenvectors is None:
+            from ..utils.errors import ModelNotTrainedError
+            raise ModelNotTrainedError(
+                "PCAEncoder must be fitted before encoding. Call fit() first.",
+                details="The encoder has not been fitted with training data yet."
+            )
+        return encode_pca(X, self.eigenvectors, mean=self.mean_)
+    
+    def fit_encode(
+        self,
+        X: Union[np.ndarray, "torch.Tensor"],
+        **kwargs
+    ) -> np.ndarray:
+        """Fit encoder and extract factors in one step."""
+        self.fit(X, **kwargs)
+        return self.encode(X, **kwargs)

dfm_python/models/base.py

@@ -1,9 +1,11 @@
-"""Abstract base class for factor models."""
+"""Abstract base class for factor models and model components."""
 
 from abc import ABC, abstractmethod
 from typing import Optional, Any, Union, Tuple
 from pathlib import Path
 import numpy as np
+import torch
+import torch.nn as nn
 
 from ..config import BaseResult
 from ..utils.errors import ModelNotTrainedError
@@ -71,3 +73,51 @@ class BaseFactorModel(ABC):
     def load(cls, path: Union[str, Path], *args, **kwargs) -> 'BaseFactorModel':
         """Load model from file."""
         raise NotImplementedError("Subclasses must implement load()")
+
+
+class BaseEncoder(nn.Module, ABC):
+    """Abstract base class for model encoders.
+    
+    Model-specific encoder base class. Encoders extract latent factors
+    from observed data. This is a PyTorch module for neural encoders.
+    """
+    
+    @abstractmethod
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Forward pass through encoder.
+        
+        Parameters
+        ----------
+        x : torch.Tensor
+            Input data
+        
+        Returns
+        -------
+        torch.Tensor
+            Encoded representation (factors)
+        """
+        pass
+
+
+class BaseDecoder(nn.Module, ABC):
+    """Abstract base class for model decoders.
+    
+    Model-specific decoder base class. Decoders map latent factors
+    to observed data. This is a PyTorch module for neural decoders.
+    """
+    
+    @abstractmethod
+    def forward(self, f: torch.Tensor) -> torch.Tensor:
+        """Forward pass through decoder.
+        
+        Parameters
+        ----------
+        f : torch.Tensor
+            Latent factors
+        
+        Returns
+        -------
+        torch.Tensor
+            Reconstructed observations
+        """
+        pass

dfm_python/models/ddfm/__init__.py

@@ -0,0 +1,12 @@
+"""DDFM model components."""
+
+from .encoder import DDFMEncoder, SimpleAutoencoder, extract_decoder_params
+from .decoder import DDFMLinearDecoder, DDFMMLPDecoder
+
+__all__ = [
+    'DDFMEncoder',
+    'DDFMLinearDecoder',
+    'DDFMMLPDecoder',
+    'SimpleAutoencoder',
+    'extract_decoder_params',
+]

dfm_python/models/ddfm/ddfm.py

@@ -21,7 +21,7 @@ from ...numeric.statistic import (
     average_3d_array
 )
 from ...numeric.builder import build_ddfm_optimizer
-from ...encoder.simple_autoencoder import SimpleAutoencoder
+from .encoder import SimpleAutoencoder
 from .sampling import run_mcmc_iteration
 from ...config.schema.params import DDFMModelState
 from ...config.schema.results import DDFMResult