tsqn-python 0.1.0__py3-none-any.whl

tsqn/__init__.py

@@ -0,0 +1,37 @@
+"""tsqn: Robust time-series estimators based on the Qn scale."""
+
+from .gph import GPHResult, GPH_estimate, gph_estimate
+from .periodogram import PerQn, PerioMrob, per_qn, perio_mrob
+from .robacf import RobACFResult, plot_robacf, robacf
+from .robust_cov import (
+    corMatQn,
+    corQn,
+    cor_mat_qn,
+    cor_qn,
+    covMatQn,
+    covQn,
+    cov_mat_qn,
+    cov_qn,
+)
+
+__all__ = [
+    "GPHResult",
+    "GPH_estimate",
+    "gph_estimate",
+    "PerQn",
+    "PerioMrob",
+    "per_qn",
+    "perio_mrob",
+    "RobACFResult",
+    "plot_robacf",
+    "robacf",
+    "corMatQn",
+    "corQn",
+    "cor_mat_qn",
+    "cor_qn",
+    "covMatQn",
+    "covQn",
+    "cov_mat_qn",
+    "cov_qn",
+]
+

tsqn/_qn.py

@@ -0,0 +1,19 @@
+"""Qn robust scale wrapper utilities."""
+
+from __future__ import annotations
+
+import numpy as np
+from statsmodels.robust.scale import qn_scale as _sm_qn_scale
+
+
+def qn_scale(x: np.ndarray | list[float]) -> float:
+    """Compute the robust Qn scale for a one-dimensional sample."""
+    arr = np.asarray(x, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError("Input must be one-dimensional.")
+    if arr.size < 2:
+        raise ValueError("At least two observations are required.")
+    if np.isnan(arr).any():
+        raise ValueError("Input contains NaN values.")
+    # Delegate to statsmodels to match the robustbase-style Qn constant.
+    return float(_sm_qn_scale(arr))

tsqn/_validation.py

@@ -0,0 +1,62 @@
+"""Shared validation helpers used across the tsqn package."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def as_1d_float_array(
+    values: np.ndarray | list[float],
+    *,
+    name: str,
+    min_size: int = 1,
+    allow_nan: bool = False,
+) -> np.ndarray:
+    """Convert input to a validated 1D float NumPy array.
+
+    Args:
+        values: Input values expected to represent one numeric series.
+        name: Argument name used in error messages.
+        min_size: Minimum required number of elements.
+        allow_nan: Whether NaN values are allowed.
+
+    Returns:
+        A one-dimensional float array.
+    """
+    arr = np.asarray(values, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional.")
+    if arr.size < min_size:
+        raise ValueError(f"{name} must have at least {min_size} observations.")
+    if not allow_nan and np.isnan(arr).any():
+        raise ValueError(f"{name} contains NaN values.")
+    return arr
+
+
+def as_2d_float_array(
+    values: np.ndarray | list[list[float]],
+    *,
+    name: str,
+    min_rows: int = 1,
+    allow_nan: bool = False,
+) -> np.ndarray:
+    """Convert input to a validated 2D float NumPy array.
+
+    Args:
+        values: Input values expected to represent a matrix.
+        name: Argument name used in error messages.
+        min_rows: Minimum required number of rows.
+        allow_nan: Whether NaN values are allowed.
+
+    Returns:
+        A two-dimensional float array.
+    """
+    arr = np.asarray(values, dtype=float)
+    if arr.ndim != 2:
+        raise ValueError(f"{name} must be a 2D matrix.")
+    if arr.shape[0] < min_rows:
+        raise ValueError(f"{name} must have at least {min_rows} rows.")
+    if not allow_nan and np.isnan(arr).any():
+        raise ValueError(f"{name} contains NaN values.")
+    return arr
+

tsqn/correlation.py

@@ -0,0 +1,44 @@
+"""Robust correlation estimator based on the Qn robust scale."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._qn import qn_scale
+from ._validation import as_1d_float_array
+
+
+def cor_qn(x: np.ndarray | list[float], y: np.ndarray | list[float]) -> float:
+    """Compute the Ma-Genton robust correlation estimator using Qn.
+
+    Args:
+        x: First numeric series.
+        y: Second numeric series.
+
+    Returns:
+        Robust correlation estimate between ``x`` and ``y``.
+    """
+    x_arr = as_1d_float_array(x, name="x", min_size=2)
+    y_arr = as_1d_float_array(y, name="y", min_size=2)
+    if x_arr.size != y_arr.size:
+        raise ValueError("x and y are unequal sizes")
+
+    # The robust self-correlation of a series is exactly one.
+    if np.array_equal(x_arr, y_arr):
+        return 1.0
+
+    alpha_qn = qn_scale(x_arr)
+    beta_qn = qn_scale(y_arr)
+    if alpha_qn == 0.0 or beta_qn == 0.0:
+        raise ValueError("Qn scale is zero for one of the input series.")
+
+    x_alpha = x_arr / alpha_qn
+    y_beta = y_arr / beta_qn
+    qn1 = qn_scale(x_alpha + y_beta)
+    qn2 = qn_scale(x_alpha - y_beta)
+    den = (qn1 * qn1) + (qn2 * qn2)
+    if den == 0.0:
+        raise ValueError("Unable to compute robust correlation due to zero denominator.")
+    cor_qn_val = ((qn1 * qn1) - (qn2 * qn2)) / den
+    return float(cor_qn_val)
+

tsqn/covariance.py

@@ -0,0 +1,42 @@
+"""Robust covariance estimator based on the Qn robust scale."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._qn import qn_scale
+from ._validation import as_1d_float_array
+
+
+def cov_qn(x: np.ndarray | list[float], y: np.ndarray | list[float]) -> float:
+    """Compute the Ma-Genton robust covariance estimator using Qn.
+
+    Args:
+        x: First numeric series.
+        y: Second numeric series.
+
+    Returns:
+        Robust covariance estimate between ``x`` and ``y``.
+    """
+    x_arr = as_1d_float_array(x, name="x", min_size=2)
+    y_arr = as_1d_float_array(y, name="y", min_size=2)
+    if x_arr.size != y_arr.size:
+        raise ValueError("x and y are unequal sizes")
+
+    alpha_qn = qn_scale(x_arr)
+    beta_qn = qn_scale(y_arr)
+
+    # The robust variance is the squared robust scale when both series are identical.
+    if np.array_equal(x_arr, y_arr):
+        return float(alpha_qn * alpha_qn)
+
+    if alpha_qn == 0.0 or beta_qn == 0.0:
+        raise ValueError("Qn scale is zero for one of the input series.")
+
+    x_alpha = x_arr / alpha_qn
+    y_beta = y_arr / beta_qn
+    qn1 = qn_scale(x_alpha + y_beta)
+    qn2 = qn_scale(x_alpha - y_beta)
+    cov_qn_val = ((alpha_qn * beta_qn) / 4.0) * ((qn1 * qn1) - (qn2 * qn2))
+    return float(cov_qn_val)
+