dftmodels 1.0.0__py3-none-any.whl

dftmodels/__init__.py

@@ -0,0 +1,42 @@
+from importlib.metadata import version
+from .stats import cramer_rao_bound
+
+__version__ = version("dftmodels")
+from .dft import (
+    DFTConfig,
+    NormType,
+    DFTRange,
+    WindowType,
+    DFTCorrection,
+    DFTCorrectionMode,
+    SignalSeries,
+    FourierSeries,
+)
+from .models import (
+    FourierModelBase,
+    Sinusoid,
+    SineFourier,
+    CompositeModel,
+    ModelBase,
+)
+
+__all__ = [
+    "__version__",
+    # Stats
+    "cramer_rao_bound",
+    # DFT
+    "DFTConfig",
+    "NormType",
+    "DFTRange",
+    "WindowType",
+    "DFTCorrection",
+    "DFTCorrectionMode",
+    "SignalSeries",
+    "FourierSeries",
+    # Models
+    "FourierModelBase",
+    "ModelBase",
+    "Sinusoid",
+    "SineFourier",
+    "CompositeModel",
+]

dftmodels/dft/__init__.py

@@ -0,0 +1,15 @@
+from .config import DFTConfig, NormType, DFTRange, WindowType, get_window_array
+from .correction import DFTCorrection, DFTCorrectionMode
+from .series import SignalSeries, FourierSeries
+
+__all__ = [
+    "DFTConfig",
+    "NormType",
+    "DFTRange",
+    "WindowType",
+    "get_window_array",
+    "DFTCorrection",
+    "DFTCorrectionMode",
+    "SignalSeries",
+    "FourierSeries",
+]

dftmodels/dft/config.py

@@ -0,0 +1,170 @@
+from dataclasses import dataclass, replace, field
+from enum import Enum
+from functools import cached_property
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class WindowType(str, Enum):
+    # Cosine-sum windows
+    RECTANGULAR      = "rectangular"
+    HAMMING          = "hamming"
+    HANN             = "hann"
+    DIRICHLET        = "rectangular"  # alias for RECTANGULAR
+    BLACKMAN         = "blackman"
+    NUTTAL           = "nuttal"
+    BLACKMAN_NUTTAL  = "blackman-nuttal"
+    BLACKMAN_HARRIS  = "blackman-harris"
+    FLAT_TOP         = "flat-top"
+
+    # For Debug Only
+    # COS4N            = "cos-4n"
+    # COS6N            = "cos-6n"
+    # COS8N            = "cos-8n"
+
+    # Other
+    EXPONENTIAL_ASYM = "exponential-asymmetric"
+    BARTLETT         = "bartlett"
+
+
+
+def get_window_array(window: WindowType, n: int, **params) -> NDArray[np.floating]:
+    match window:
+        case WindowType.RECTANGULAR:
+            return np.ones(n)
+        case WindowType.HAMMING:
+            return 25/46 - 21/46 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.HANN:
+            return 0.5 - 0.5 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.BLACKMAN:
+            return (7938 
+                - 9240 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 1430 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+            ) / 18608
+        case WindowType.NUTTAL:
+            return (355_768 \
+                - 487_396 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 144_232 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -  12_604 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+            ) / 1_000_000
+        case WindowType.BLACKMAN_NUTTAL:
+            return (3_635_819 \
+                - 4_891_775 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 1_365_995 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -   106_411 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+            ) / 10_000_000
+        case WindowType.BLACKMAN_HARRIS:
+            return (4_243_801 \
+                - 4_973_406 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 782_793 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+            ) / 10_000_000
+        case WindowType.FLAT_TOP:
+            return (215_578_950 \
+                - 416_631_580 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 277_263_158 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -  83_578_947 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+                +   6_947_368 * np.cos(8 * np.pi * np.arange(n) / (n - 1))
+            ) / 1_000_000_000
+        case WindowType.BARTLETT:
+            return np.bartlett(n)
+        # case WindowType.COS6N:
+        #     return .5 - .5 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+        # case WindowType.COS8N:
+        #     return .5 - .5 * np.cos(8 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.EXPONENTIAL_ASYM:
+            return np.exp(-np.arange(n) * params.get("alpha", 1.0) / (n - 1))
+        case _:
+            raise ValueError(f"Unsupported window type: {window}")
+
+
+class NormType(str, Enum):
+    CFT     = "continuous_fourier_transform"
+    ASD     = "amplitude_spectral_density"
+    ASD_ABS = "amplitude_spectral_density_absolute"
+    PSD     = "power_spectral_density"
+
+
+class DFTRange(str, Enum):
+    DOUBLE_SIDED = "double_sided"
+    SINGLE_SIDED = "single_sided"
+
+
+@dataclass(frozen=True)
+class DFTConfig:
+    number_of_samples: int
+    sample_rate: float
+    pad: float = 1.0
+    window: WindowType = WindowType.RECTANGULAR
+    window_params: dict = field(default_factory=dict)  # <--- NEW
+    norm_type: NormType = NormType.ASD
+    dft_range: DFTRange = DFTRange.DOUBLE_SIDED
+
+    def __post_init__(self):
+        if self.number_of_samples <= 0:
+            raise ValueError("number_of_samples must be a positive integer")
+        if self.sample_rate <= 0:
+            raise ValueError("sample_rate must be positive")
+        if self.pad < 1.0:
+            raise ValueError("pad cannot be less than 1.0")
+        if self.window not in WindowType:
+            raise ValueError(f"Unsupported window type: {self.window}")
+        if self.norm_type not in NormType:
+            raise ValueError(f"Unsupported norm type: {self.norm_type}")
+        if self.dft_range not in DFTRange:
+            raise ValueError(f"Unsupported DFT range: {self.dft_range}")
+
+    @cached_property
+    def number_of_samples_fft(self) -> int:
+        return round(self.number_of_samples * self.pad)
+
+    @cached_property
+    def window_array(self) -> NDArray[np.floating]:
+        return get_window_array(self.window, self.number_of_samples, **self.window_params)
+
+    @cached_property
+    def norm_factor(self) -> float:
+        if self.norm_type in (NormType.ASD, NormType.ASD_ABS):
+            return self._asd_norm()
+        elif self.norm_type == NormType.PSD:
+            return self._asd_norm() ** 2
+        elif self.norm_type == NormType.CFT:
+            return self._cft_norm()
+        raise ValueError(f"Unsupported norm type: {self.norm_type}")
+
+    def _cft_norm(self) -> float:
+        wa = self.window_array
+        if wa[0] == 0.0:
+            raise ValueError('Zero-valued window is incompatible with CFT normalization')
+        factor = 2.0 if self.dft_range == DFTRange.SINGLE_SIDED else 1.0
+        return factor / self.sample_rate / wa[0]
+
+    def _asd_norm(self) -> float:
+        wa = self.window_array
+        n = self.number_of_samples
+        window_rms = np.sqrt(np.sum(wa ** 2) / n)
+        factor = np.sqrt(2.0) if self.dft_range == DFTRange.SINGLE_SIDED else 1.0
+        return factor / np.sqrt(self.sample_rate * n) / window_rms
+
+    @cached_property
+    def frequency_step(self) -> float:
+        return self.sample_rate / self.number_of_samples_fft
+
+    @cached_property
+    def frequency_min(self) -> float:
+        if self.dft_range == DFTRange.SINGLE_SIDED:
+            return 0.0
+        n = self.number_of_samples_fft
+        df = self.frequency_step
+        return -(self.sample_rate + df) / 2 if n % 2 == 0 else -self.sample_rate / 2
+
+    @cached_property
+    def frequency_max(self) -> float:
+        if self.dft_range == DFTRange.SINGLE_SIDED:
+            return self.sample_rate / 2
+        n = self.number_of_samples_fft
+        df = self.frequency_step
+        return (self.sample_rate - df) / 2 if n % 2 == 0 else self.sample_rate / 2
+
+    def copy(self) -> 'DFTConfig':
+        return replace(self)

dftmodels/dft/correction.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from enum import IntFlag, auto
+
+
+class DFTCorrectionMode(IntFlag):
+    NONE          = 0
+    BASELINE_ONLY = auto()
+    SAMPLING_ONLY = auto()
+    WINDOW_ONLY   = auto()
+
+    WINDOW        = WINDOW_ONLY
+    BASELINE      = WINDOW_ONLY | BASELINE_ONLY
+    ALL           = WINDOW_ONLY | BASELINE_ONLY | SAMPLING_ONLY
+
+
+@dataclass(frozen=True)
+class DFTCorrection:
+    mode: DFTCorrectionMode
+    order: int = 10

dftmodels/dft/series.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import numpy as np
+from numpy.typing import NDArray
+
+from .config import DFTConfig, DFTRange, NormType, WindowType
+
+@dataclass
+class DataSeries:
+    x: NDArray[np.floating]
+    y: NDArray
+
+@dataclass
+class SignalSeries(DataSeries):
+    def __post_init__(self):
+        x = np.asarray(self.x)
+        if np.iscomplexobj(x):
+            raise ValueError("x must be real-valued")
+        self.x = x.astype(float)
+        self.y = np.asarray(self.y)
+
+        if self.x.ndim != 1:
+            raise ValueError("x must be 1-dimensional")
+        if len(self.x) != len(self.y):
+            raise ValueError("x and y must have the same length")
+
+    def __len__(self) -> int:
+        return len(self.x)
+
+    @property
+    def sample_rate(self) -> float:
+        if len(self.x) < 2:
+            raise ValueError("Need at least 2 samples to determine sample rate")
+        return 1.0 / (self.x[1] - self.x[0])
+
+    def copy(self) -> SignalSeries:
+        return SignalSeries(
+            x=self.x.copy(),
+            y=self.y.copy(),
+        )
+
+    def calculate_rms(self) -> float:
+        return float(np.sqrt(np.mean(np.abs(self.y) ** 2)))
+
+    def calculate_dft(
+        self,
+        pad: float = 1.0,
+        norm: NormType = NormType.CFT,
+        window: WindowType = WindowType.RECTANGULAR,
+        window_params: None | dict = None,
+        dft_range: DFTRange = DFTRange.DOUBLE_SIDED,
+    ) -> FourierSeries:
+        if len(self) == 0:
+            raise ValueError("Signal is empty")
+
+        if dft_range == DFTRange.SINGLE_SIDED and np.iscomplexobj(self.y):
+            raise ValueError("Single-sided DFT requires a real-valued signal")
+
+        n = len(self)
+        sr = self.sample_rate
+
+        if window_params is None:
+            window_params = dict()
+
+        dft_config = DFTConfig(
+            number_of_samples=n,
+            sample_rate=sr,
+            pad=pad,
+            window=window,
+            window_params=window_params,
+            norm_type=norm,
+            dft_range=dft_range,
+        )
+
+        windowed = self.y * dft_config.window_array
+        n_fft = dft_config.number_of_samples_fft
+        t_step = 1.0 / sr
+
+        if dft_range == DFTRange.DOUBLE_SIDED:
+            amplitude = np.fft.fftshift(np.fft.fft(windowed, n=n_fft))
+            frequency = np.fft.fftshift(np.fft.fftfreq(n_fft, t_step))
+        else:
+            amplitude = np.fft.rfft(windowed, n=n_fft)
+            frequency = np.fft.rfftfreq(n_fft, t_step)
+
+        if norm == NormType.PSD:
+            amplitude = np.abs(amplitude) ** 2
+        elif norm == NormType.ASD_ABS:
+            amplitude = np.abs(amplitude)
+
+        amplitude = amplitude * dft_config.norm_factor
+
+        return FourierSeries(
+            x=frequency,
+            y=amplitude,
+            dft_config=dft_config,
+        )
+
+
+@dataclass
+class FourierSeries(DataSeries):
+    dft_config: DFTConfig
+
+    def __post_init__(self):
+        self.x = np.asarray(self.x, dtype=float)
+        self.y = np.asarray(self.y)
+
+        if len(self.x) != len(self.y):
+            raise ValueError("x and y must have the same length")
+
+    def __len__(self) -> int:
+        return len(self.x)
+
+    def copy(self) -> FourierSeries:
+        return FourierSeries(
+            x=self.x.copy(),
+            y=self.y.copy(),
+            dft_config=self.dft_config.copy(),
+        )
+
+    @property
+    def real(self) -> FourierSeries:
+        result = self.copy()
+        result.y = np.real(self.y).copy()
+        return result
+
+    @property
+    def imag(self) -> FourierSeries:
+        result = self.copy()
+        result.y = np.imag(self.y).copy()
+        return result
+
+    @property
+    def abs(self) -> FourierSeries:
+        result = self.copy()
+        result.y = np.abs(self.y).copy()
+        return result
+
+    def calculate_integral(
+        self,
+        f_min: float | None = None,
+        f_max: float | None = None,
+    ):
+        """Integrate the spectrum using the rectangular (midpoint) rule.
+
+        The rectangular rule is exact for DFT spectra: Parseval's theorem
+        holds precisely as ``df * sum(PSD) == signal_power``.
+
+        When f_min/f_max are given, boundary bins are weighted by their
+        fractional overlap with the integration window rather than included
+        or excluded wholesale.
+        """
+        x, y = self.x, self.y
+
+        if len(x) == 0:
+            return 0.0
+        if len(x) == 1:
+            return y[0]
+
+        df = x[1] - x[0]
+
+        if f_min is None and f_max is None and self.dft_config.dft_range == DFTRange.SINGLE_SIDED:
+            lo = x[0]
+            hi = x[-1]
+        else:
+            lo = f_min if f_min is not None else x[0] - df / 2
+            hi = f_max if f_max is not None else x[-1] + df / 2
+
+        bin_starts = x - df / 2
+        bin_ends = x + df / 2
+
+        overlap = np.maximum(0.0, np.minimum(bin_ends, hi) - np.maximum(bin_starts, lo))
+        proportions = overlap / df
+
+        return df * np.sum(proportions * y)
+
+    def calculate_idft(self, remove_padding: bool = True, remove_window: bool = True) -> SignalSeries:
+        cfg = self.dft_config
+        n_fft = cfg.number_of_samples_fft
+        n = cfg.number_of_samples
+
+        window_array = cfg.window_array
+        if np.any(window_array == 0.0):
+            raise ValueError("Zero-valued window is incompatible with IDFT")
+
+        if cfg.norm_type in (NormType.ASD_ABS, NormType.PSD):
+            raise ValueError("Cannot compute IDFT of ASD_ABS or PSD data")
+
+        expected_len = n_fft if cfg.dft_range == DFTRange.DOUBLE_SIDED else n_fft // 2 + 1
+        if len(self) != expected_len:
+            raise ValueError(
+                f"Expected {expected_len} frequency bins for IDFT, got {len(self)}"
+            )
+
+        amplitude = self.y / cfg.norm_factor
+
+        if cfg.dft_range == DFTRange.DOUBLE_SIDED:
+            value = np.fft.ifft(np.fft.ifftshift(amplitude), n=n_fft)
+        else:
+            value = np.fft.irfft(amplitude, n=n_fft)
+
+        if remove_padding:
+            value = value[:n]
+
+        if remove_window:
+            value[:n] = value[:n] / window_array
+
+        sr = cfg.sample_rate
+        n_out = n if remove_padding else n_fft
+        time = np.linspace(0, n_out / sr, n_out, endpoint=False)
+
+        return SignalSeries(x=time, y=value)
+
+    def convert_to_psd(self) -> FourierSeries:
+        if self.dft_config.norm_type not in (NormType.ASD, NormType.ASD_ABS):
+            raise ValueError("convert_to_psd requires ASD or ASD_ABS normalization")
+
+        cfg = DFTConfig(
+            number_of_samples=self.dft_config.number_of_samples,
+            sample_rate=self.dft_config.sample_rate,
+            pad=self.dft_config.pad,
+            window=self.dft_config.window,
+            window_params=self.dft_config.window_params,
+            norm_type=NormType.PSD,
+            dft_range=self.dft_config.dft_range,
+        )
+        
+        return FourierSeries(
+            x=self.x.copy(),
+            y=np.abs(self.y) ** 2,
+            dft_config=cfg,           
+        )
+
+    def convert_to_asd(self) -> FourierSeries:
+        if self.dft_config.norm_type != NormType.PSD:
+            raise ValueError("convert_to_asd requires PSD normalization")
+
+        cfg = DFTConfig(
+            number_of_samples=self.dft_config.number_of_samples,
+            sample_rate=self.dft_config.sample_rate,
+            pad=self.dft_config.pad,
+            window=self.dft_config.window,
+            window_params=self.dft_config.window_params,
+            norm_type=NormType.ASD_ABS,
+            dft_range=self.dft_config.dft_range,
+        )
+        return FourierSeries(
+            x=self.x.copy(),
+            y=np.sqrt(np.abs(self.y)),
+            dft_config=cfg,
+        )

dftmodels/models/__init__.py

@@ -0,0 +1,11 @@
+from .base import FourierModelBase, ModelBase
+from .sinusoid import Sinusoid, SineFourier
+from .composite import CompositeModel
+
+__all__ = [
+    "FourierModelBase",
+    "Sinusoid",
+    "SineFourier",
+    "ModelBase",
+    "CompositeModel",
+]