tempdisagg 0.2.2__tar.gz → 0.2.4__tar.gz

{tempdisagg-0.2.2/tempdisagg.egg-info → tempdisagg-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempdisagg
-Version: 0.2.2
+Version: 0.2.4
 Summary: Temporal disaggregation models in Python
 Author-email: Jaime Vera-Jaramillo <jaimevera1107@gmail.com>
 License-Expression: MIT

{tempdisagg-0.2.2 → tempdisagg-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tempdisagg"
-version = "0.2.2"
+version = "0.2.4"
 description = "Temporal disaggregation models in Python"
 readme = "README.md"
 authors = [
@@ -28,14 +28,14 @@ dependencies = [
     "matplotlib>=3.4"
 ]
 
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tempdisagg", "tempdisagg.*"]
+
 [project.urls]
 Homepage = "https://github.com/jaimevera1107/tempdisagg"
 
 [tool.setuptools]
-packages = ["tempdisagg"]
 
 [tool.setuptools.package-data]
 tempdisagg = ["py.typed"]
-
-[tool.setuptools.exclude-package-data]
-"*" = ["notebooks*", "example*", "tests*"]

{tempdisagg-0.2.2 → tempdisagg-0.2.4}/tempdisagg/__init__.py

@@ -26,9 +26,3 @@ __all__ = [
     "EnsemblePrediction",
     "TemporalAggregator",
 ]
-
-
-# Versioning and metadata
-__version__ = "0.2.2"
-__author__ = "Jaime Vera-Jaramillo"
-__license__ = "MIT"

tempdisagg-0.2.4/tempdisagg/core/__init__.py

@@ -0,0 +1,9 @@
+from .rho_optimizer import RhoOptimizer
+from .numeric_utils import NumericUtils
+from .temporal_aggregator import TemporalAggregator
+
+__all__ = [
+    "RhoOptimizer",
+    "NumericUtils",
+    "TemporalAggregator"
+]

tempdisagg-0.2.4/tempdisagg/core/numeric_utils.py

@@ -0,0 +1,151 @@
+import numpy as np
+from scipy.linalg import inv, pinv
+import warnings
+
+class NumericUtils:
+    """
+    Utility class for numerical operations used in temporal disaggregation models.
+    Includes methods for constructing power matrices and Q matrices with autocorrelation structure.
+    """
+
+    @staticmethod
+    def power_matrix(n):
+        """
+        Create a matrix where each element (i, j) is |i - j|.
+
+        Parameters
+        ----------
+        n : int
+            Size of the square matrix to generate.
+
+        Returns
+        -------
+        numpy.ndarray
+            A square matrix of shape (n, n) with absolute differences of indices.
+        """
+        # Validate that n is a positive integer
+        if not isinstance(n, int) or n <= 0:
+            raise ValueError("Parameter 'n' must be a positive integer.")
+
+        # Construct the power matrix using broadcasting
+        return np.abs(np.subtract.outer(np.arange(n), np.arange(n)))
+
+    @staticmethod
+    def q_matrix(rho, power_matrix, epsilon=1e-6):
+        """
+        Construct a Q matrix for Chow-Lin type models using a power matrix.
+
+        Parameters
+        ----------
+        rho : float
+            Autocorrelation parameter, expected to be between -1 and 1.
+        power_matrix : numpy.ndarray
+            Matrix of absolute differences in time indices.
+        epsilon : float, optional
+            Small constant added for numerical stability (default is 1e-6).
+
+        Returns
+        -------
+        numpy.ndarray
+            Q matrix capturing autocorrelation structure.
+        """
+        # Clip rho to avoid instability
+        rho = np.clip(rho, -0.99, 0.99)
+
+        # Validate input power matrix
+        if not isinstance(power_matrix, np.ndarray):
+            raise TypeError("Parameter 'power_matrix' must be a NumPy ndarray.")
+
+        if power_matrix.shape[0] != power_matrix.shape[1]:
+            raise ValueError("Parameter 'power_matrix' must be a square matrix.")
+
+        # Compute the Q matrix based on rho and power_matrix
+        return (1 / (1 - rho ** 2 + epsilon)) * (rho ** power_matrix)
+
+    @staticmethod
+    def q_litterman(X, rho=0):
+        """
+        Construct the Q matrix for Litterman's method.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Regressor matrix with shape (n, k).
+        rho : float, optional
+            Autocorrelation parameter (default is 0).
+
+        Returns
+        -------
+        numpy.ndarray
+            The inverted Q matrix used for GLS estimation.
+        """
+        # Validate input matrix
+        if not isinstance(X, np.ndarray):
+            raise TypeError("Parameter 'X' must be a NumPy ndarray.")
+
+        if X.ndim != 2:
+            raise ValueError("Parameter 'X' must be a 2D array.")
+
+        # Get the number of observations
+        n = X.shape[0]
+
+        # Construct H and D matrices for differencing
+        H = np.eye(n) - np.diag(np.ones(n - 1), -1) * rho
+        D = np.eye(n) - np.diag(np.ones(n - 1), -1)
+
+        # Compute Q_Litterman
+        Q_lit = D.T @ H.T @ H @ D
+
+        try:
+            # Attempt to invert Q_Lit with a small ridge for stability
+            return inv(Q_lit + np.eye(n) * 1e-8)
+        except np.linalg.LinAlgError:
+            # Fallback to pseudoinverse if singular
+            warnings.warn("Q_Lit matrix is singular. Using pseudo-inverse instead.", RuntimeWarning)
+            return pinv(Q_lit)
+
+
+    @staticmethod
+    def validate_symmetric_positive_definite(matrix, tol=1e-8):
+        """
+        Validate whether a matrix is symmetric and positive definite.
+
+        Parameters
+        ----------
+        matrix : numpy.ndarray
+            The matrix to validate.
+        tol : float
+            Tolerance for symmetry check (default is 1e-8).
+
+        Returns
+        -------
+        bool
+            True if the matrix is symmetric and positive definite.
+
+        Raises
+        ------
+        TypeError
+            If input is not a NumPy array.
+        ValueError
+            If the matrix is not square or not symmetric within tolerance.
+        np.linalg.LinAlgError
+            If the matrix is not positive definite (Cholesky fails).
+        """
+        # Ensure matrix is a NumPy array
+        if not isinstance(matrix, np.ndarray):
+            raise TypeError("Input must be a NumPy ndarray.")
+
+        # Ensure matrix is square
+        if matrix.shape[0] != matrix.shape[1]:
+            raise ValueError("Matrix must be square.")
+
+        # Check symmetry within tolerance
+        if not np.allclose(matrix, matrix.T, atol=tol):
+            raise ValueError("Matrix is not symmetric within the given tolerance.")
+
+        try:
+            # Try Cholesky decomposition to verify positive definiteness
+            _ = np.linalg.cholesky(matrix)
+            return True
+        except np.linalg.LinAlgError as e:
+            raise np.linalg.LinAlgError("Matrix is not positive definite.") from e

tempdisagg-0.2.4/tempdisagg/core/rho_optimizer.py

@@ -0,0 +1,212 @@
+import numpy as np
+import pandas as pd
+import warnings
+
+from scipy.linalg import pinv
+from scipy.optimize import minimize_scalar
+from scipy.stats import norm
+
+from tempdisagg.utils.logging_utils import VerboseLogger
+
+
+
+class RhoOptimizer:
+    """
+    Optimizes the autocorrelation parameter (rho) for temporal disaggregation models.
+
+    Supports:
+        - 'maxlog': Maximum likelihood estimation.
+        - 'minrss': Minimum residual sum of squares.
+
+    Returns full statistical outputs: rho, beta, residuals, Q matrix, variance-covariance matrix, and summary.
+    """
+
+    def __init__(self, rho_min=-0.9, rho_max=0.99, verbose=False):
+        """
+        Initialize the optimizer with bounds and verbosity.
+
+        Parameters
+        ----------
+        rho_min : float
+            Lower bound for rho (default = -0.9).
+        rho_max : float
+            Upper bound for rho (default = 0.99).
+        verbose : bool
+            Whether to enable informative logging.
+        """
+        self.rho_min = rho_min
+        self.rho_max = rho_max
+        self.verbose = verbose
+
+        # Create logger with verbosity control
+        self.logger = VerboseLogger(f"{__name__}.{id(self)}", verbose=self.verbose).get_logger()
+
+    def power_matrix(self, n):
+        """
+        Construct a power matrix of absolute differences |i - j|.
+
+        Parameters
+        ----------
+        n : int
+            Dimension of the square matrix.
+
+        Returns
+        -------
+        numpy.ndarray
+            Power matrix of shape (n, n).
+        """
+        return np.abs(np.subtract.outer(np.arange(n), np.arange(n)))
+
+    def q_matrix(self, rho, power_matrix, epsilon=1e-6):
+        """
+        Generate Q matrix using autocorrelation parameter rho.
+
+        Parameters
+        ----------
+        rho : float
+            Autocorrelation coefficient.
+        power_matrix : numpy.ndarray
+            Power matrix from self.power_matrix().
+        epsilon : float
+            Stability constant to avoid division by zero.
+
+        Returns
+        -------
+        numpy.ndarray
+            Q matrix used for GLS estimation.
+        """
+        rho = np.clip(rho, -0.99, 0.99)
+        return (1 / (1 - rho**2 + epsilon)) * (rho ** power_matrix)
+
+    def optimize(self, y_l, X, C, method="maxlog"):
+        """
+        Optimize rho and estimate model parameters.
+
+        Parameters
+        ----------
+        y_l : array-like
+            Low-frequency response variable (n_low x 1).
+        X : array-like
+            High-frequency explanatory variable (n_high x 1).
+        C : array-like
+            Conversion matrix (n_low x n_high).
+        method : str
+            Optimization method: 'maxlog' or 'minrss'.
+
+        Returns
+        -------
+        dict
+            Dictionary with rho, Q, beta, residuals, std_errors, t_stats, p_values, and summary.
+        """
+        try:
+            # Reshape and validate inputs
+            y_l = np.atleast_2d(y_l).reshape(-1, 1)
+            X = np.atleast_2d(X).reshape(-1, 1)
+            C = np.atleast_2d(C)
+
+            if C.shape[1] != X.shape[0]:
+                raise ValueError("C columns must match X rows.")
+            if C.shape[0] != y_l.shape[0]:
+                raise ValueError("C rows must match y_l rows.")
+
+            # Compute low-frequency regressor
+            X_l = C @ X
+
+            # Precompute power matrix
+            power_mat = self.power_matrix(X.shape[0])
+
+            # Store best result during optimization
+            results = {}
+
+            def objective(rho):
+                """
+                Objective function to minimize (depends on method).
+                """
+                if not (self.rho_min < rho < self.rho_max):
+                    return np.inf
+
+                try:
+                    # Compute Q matrix and covariance
+                    Q = self.q_matrix(rho, power_mat)
+                    vcov = C @ Q @ C.T + np.eye(C.shape[0]) * 1e-8
+                    inv_vcov = pinv(vcov)
+
+                    # Estimate beta
+                    XTX = X_l.T @ inv_vcov @ X_l
+                    if XTX.shape[0] != XTX.shape[1]:
+                        return np.inf
+
+                    beta = pinv(XTX) @ X_l.T @ inv_vcov @ y_l
+                    residuals = y_l - X_l @ beta
+
+                    # Evaluate objective
+                    if method == "maxlog":
+                        det = np.linalg.det(vcov)
+                        if det <= 0:
+                            return np.inf
+                        loglike = -0.5 * (np.log(det + 1e-8) + residuals.T @ inv_vcov @ residuals)
+                        value = -loglike.item()
+                    elif method == "minrss":
+                        value = (residuals.T @ inv_vcov @ residuals).item()
+                    else:
+                        raise ValueError("Invalid method: use 'maxlog' or 'minrss'.")
+
+                    # Update best result
+                    if "best_val" not in results or value < results["best_val"]:
+                        results.update({
+                            "rho": rho,
+                            "Q": Q,
+                            "vcov": vcov,
+                            "beta": beta,
+                            "residuals": residuals,
+                            "XTX": XTX,
+                            "inv_vcov": inv_vcov,
+                            "X_l": X_l,
+                            "best_val": value
+                        })
+
+                    return value
+
+                except Exception as e:
+                    warnings.warn(f"Optimization failed at rho={rho:.4f}: {e}", RuntimeWarning)
+                    return np.inf
+
+            # Minimize scalar function within bounds
+            result = minimize_scalar(objective, bounds=(self.rho_min, self.rho_max), method="bounded")
+
+            if not result.success:
+                raise RuntimeError(f"Rho optimization failed: {result.message}")
+
+            if self.verbose:
+                self.logger.info(f"Optimal rho found: {results['rho']:.6f}")
+
+            # Compute inference statistics
+            XTX_inv = pinv(results["XTX"])
+            std_errors = np.sqrt(np.diag(XTX_inv))
+            t_stats = results["beta"].flatten() / std_errors
+            p_values = 2 * (1 - norm.cdf(np.abs(t_stats)))
+            significance = ["***" if p < 0.01 else "**" if p < 0.05 else "*" if p < 0.1 else "" for p in p_values]
+
+            summary_df = pd.DataFrame({
+                "Coef.": results["beta"].flatten(),
+                "Std.Err.": std_errors,
+                "t-stat": t_stats,
+                "P>|t|": p_values,
+                "Signif.": significance
+            })
+
+            return {
+                "rho": results["rho"],
+                "Q": results["Q"],
+                "vcov": results["vcov"],
+                "beta": results["beta"],
+                "residuals": results["residuals"],
+                "std_errors": std_errors,
+                "t_stats": t_stats,
+                "p_values": p_values,
+                "significance": significance,
+                "summary": summary_df
+            }
+
+        except Exception as e:
+            raise RuntimeError(f"Optimization process failed: {e}")

tempdisagg-0.2.4/tempdisagg/core/temporal_aggregator.py

@@ -0,0 +1,82 @@
+import numpy as np
+import pandas as pd
+import logging
+from tempdisagg.utils.logging_utils import VerboseLogger
+
+class TemporalAggregator:
+    """
+    Aggregates a high-frequency time series into a low-frequency series
+    using one of four supported rules: sum, average, first, or last.
+    """
+
+    def __init__(self, conversion="sum", freq_ratio=None, grain_col="Grain", index_col="Index", verbose=False):
+        """
+        Parameters
+        ----------
+        conversion : str
+            Aggregation rule: 'sum', 'average', 'first', or 'last'.
+        freq_ratio : int
+            Number of high-frequency units per low-frequency unit.
+        grain_col : str
+            Column name for high-frequency grain.
+        index_col : str
+            Column name for low-frequency index.
+        verbose : bool
+            Enable logging messages.
+        """
+        self.conversion = conversion
+        self.freq_ratio = freq_ratio
+        self.grain_col = grain_col
+        self.index_col = index_col
+        self.verbose = verbose
+        self.logger = VerboseLogger(f"{__name__}.{id(self)}", verbose=self.verbose).get_logger()
+
+        valid = ["sum", "average", "first", "last"]
+        if self.conversion not in valid:
+            raise ValueError(f"Invalid conversion: {self.conversion}. Must be one of {valid}.")
+
+    def aggregate(self, df, value_col):
+        """
+        Aggregate the high-frequency series to low-frequency.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            Input DataFrame containing high-frequency data.
+        value_col : str
+            Name of the value column to aggregate.
+
+        Returns
+        -------
+        pd.DataFrame
+            Low-frequency aggregated series.
+        """
+        if not isinstance(df, pd.DataFrame):
+            raise TypeError("Input must be a pandas DataFrame.")
+        if value_col not in df.columns:
+            raise ValueError(f"Column '{value_col}' not found in input DataFrame.")
+
+        if self.index_col not in df.columns or self.grain_col not in df.columns:
+            raise ValueError("Both 'index_col' and 'grain_col' must exist in the DataFrame.")
+
+        df = df.copy()
+        df = df.sort_values([self.index_col, self.grain_col])
+
+        if self.verbose:
+            self.logger.info(f"Aggregating using rule: {self.conversion}")
+
+        if self.conversion == "sum":
+            agg_func = "sum"
+        elif self.conversion == "average":
+            agg_func = "mean"
+        elif self.conversion == "first":
+            agg_func = "first"
+        elif self.conversion == "last":
+            agg_func = "last"
+        else:
+            raise ValueError(f"Unsupported conversion: {self.conversion}")
+
+        result = df.groupby(self.index_col, as_index=False)[value_col].agg(agg_func)
+        result.rename(columns={value_col: f"{value_col}_agg"}, inplace=True)
+
+        return result

tempdisagg-0.2.4/tempdisagg/model/__init__.py

@@ -0,0 +1,4 @@
+from .tempdisagg_model import TempDisaggModel
+from .models_handler import ModelsHandler
+
+__all__ = ["TempDisaggModel", "ModelsHandler"]