trajmod 0.1.0__py3-none-any.whl

trajmod/__init__.py

@@ -0,0 +1,21 @@
+"""trajmod: Simple GNSS trajectory modeling.
+
+A Python library for modeling GNSS displacement time series with support for
+earthquakes, slow slip events, and advanced multi-tier postseismic filtering.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Giuseppe Costantino"
+__license__ = "MIT"
+
+# Import main classes for convenient access
+from trajmod.model.model import TrajectoryModel
+from trajmod.config.modelconfig import ModelConfig
+from trajmod.model.results import ModelResults
+
+__all__ = [
+    "TrajectoryModel",
+    "ModelConfig",
+    "ModelResults",
+    "__version__",
+]

trajmod/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration module for trajmod."""
+
+from trajmod.config.modelconfig import ModelConfig
+
+__all__ = ["ModelConfig"]

trajmod/config/modelconfig.py

@@ -0,0 +1,79 @@
+"""Configuration management for GNSS trajectory modeling."""
+from dataclasses import dataclass, field
+from typing import List, Optional, Any
+
+import numpy as np
+
+
+@dataclass
+class ModelConfig:
+    """Configuration for TrajectoryModel parameters.
+
+    Attributes:
+        d_param: Empirical scaling parameter in radius law
+        include_seasonal: Whether to include annual & semi-annual terms
+        use_envelope_basis: Whether to use envelope basis functions
+        postseismic_mag_threshold: Minimum magnitude for post-seismic template
+        tau_grid: Candidate tau values (days) for post-seismic decay
+        merge_close_sse: Whether to merge close SSE templates
+        merge_earthquakes_same_day: Whether to merge earthquakes on same day
+        acceleration_term: Whether to include acceleration term
+        envelope_periods: Periods (days) for envelope basis functions
+        gap_merge_threshold: Threshold (days) for merging close events
+        bspline_knots: Number of knots for B-spline basis
+        bspline_degree: Degree of B-spline basis
+    """
+    d_param: Optional[float] = 1.0
+    include_seasonal: bool = True
+    use_envelope_basis: bool = False
+    postseismic_mag_threshold: float = 6.5
+    tau_grid: List[int] = field(default_factory=lambda: [7, 14, 30, 60, 90, 180, 1800])
+
+
+    fit_postseismic_decay: bool = True
+    postseismic_selection_criterion: str = 'aic'  # 'aic', 'bic', 'ftest', 'always'
+    postseismic_selection_threshold: float = -2  # ΔAIC/ΔBIC < -2 or p < 0.05
+    fit_best_postseismic_tau: bool = True
+    enforce_postseismic_sign_consistency: bool = True
+    postseismic_min_step_amplitude: float = 5.0  # mm
+
+
+    merge_close_sse: bool = False
+    merge_earthquakes_same_day: bool = False
+    acceleration_term: bool = True
+
+    # envelope periods (60-365 days, not 1-6 years!)
+    envelope_periods: np.ndarray = field(
+        default_factory=lambda: np.array([
+            365.25 / 6,  # ~60.875 days (2 months)
+            365.25 / 5,  # ~73.05 days
+            365.25 / 4,  # ~91.3125 days (3 months)
+            365.25 / 3,  # ~121.75 days (4 months)
+            365.25 / 2,  # ~182.625 days (6 months)
+            365.25  # 365.25 days (1 year)
+        ])
+    )
+
+    gap_merge_threshold: int = 5
+    bspline_knots: int = 20
+    bspline_degree: int = 3
+
+
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if self.d_param is not None and self.d_param <= 0:
+            raise ValueError(f"d_param must be positive, got {self.d_param}")
+
+        if self.postseismic_mag_threshold < 0:
+            raise ValueError("postseismic_mag_threshold must be non-negative")
+
+        # NEW: Validate min step amplitude
+        if self.postseismic_min_step_amplitude < 0:
+            raise ValueError("postseismic_min_step_amplitude must be non-negative")
+
+        if any(tau <= 0 for tau in self.tau_grid):
+            raise ValueError("All tau_grid values must be positive")
+
+        valid_criteria = ['aic', 'bic', 'ftest', 'always']
+        if self.postseismic_selection_criterion not in valid_criteria:
+            raise ValueError(f"postseismic_selection_criterion must be one of {valid_criteria}")

trajmod/design/__init__.py

@@ -0,0 +1,2 @@
+from trajmod.design.matrix import DesignMatrixBuilder
+__all__ = ["DesignMatrixBuilder"]

trajmod/design/matrix.py

@@ -0,0 +1,99 @@
+"""Design matrix construction for trajectory models."""
+import numpy as np
+from typing import List, Dict, Tuple
+import logging
+
+from trajmod.config.modelconfig import ModelConfig
+from trajmod.templates.templates import TemplateFunctions
+
+logger = logging.getLogger(__name__)
+
+
+class DesignMatrixBuilder:
+    """Builder for design matrix G."""
+
+    def __init__(self, templates: TemplateFunctions, config: ModelConfig):
+        self.templates = templates
+        self.config = config
+        self.template_names: List[str] = []
+
+    def build(self, selected_sse: List[Dict], selected_eq: List[Dict]) -> Tuple[np.ndarray, List[str]]:
+        """Build complete design matrix."""
+        self.template_names = []
+        columns = []
+
+        columns.extend(self._build_base_model())
+
+        if self.config.include_seasonal:
+            columns.extend(self._build_seasonal())
+
+        columns.extend(self._build_sse_templates(selected_sse))
+        columns.extend(self._build_earthquake_templates(selected_eq))
+
+        G = np.column_stack(columns) if columns else np.empty((len(self.templates.t_days), 0))
+
+        logger.info(f"Design matrix: {G.shape[0]} x {G.shape[1]}")
+        return G, self.template_names
+
+    def _build_base_model(self) -> List[np.ndarray]:
+        columns = []
+        columns.append(self.templates.offset())
+        self.template_names.append('offset')
+        columns.append(self.templates.trend())
+        self.template_names.append('trend')
+
+        if self.config.acceleration_term:
+            columns.append(self.templates.acceleration())
+            self.template_names.append('acceleration')
+
+        return columns
+
+    def _build_seasonal(self) -> List[np.ndarray]:
+        columns = []
+        columns.append(self.templates.seasonal_sin(365.25))
+        self.template_names.append('annual_sin')
+        columns.append(self.templates.seasonal_cos(365.25))
+        self.template_names.append('annual_cos')
+        columns.append(self.templates.seasonal_sin(365.25 / 2))
+        self.template_names.append('semiannual_sin')
+        columns.append(self.templates.seasonal_cos(365.25 / 2))
+        self.template_names.append('semiannual_cos')
+
+        '''if self.config.use_envelope_basis:
+            for T in self.config.envelope_periods:
+                columns.append(self.templates.seasonal_sin(T))
+                self.template_names.append(f'envelope_sin_{int(T / 365.25)}yr')
+                columns.append(self.templates.seasonal_cos(T))
+                self.template_names.append(f'envelope_cos_{int(T / 365.25)}yr')'''
+
+        if self.config.use_envelope_basis:
+            for T in self.config.envelope_periods:
+                columns.append(self.templates.seasonal_sin(T))
+                self.template_names.append(f'envelope_sin_{int(T)}d')
+                columns.append(self.templates.seasonal_cos(T))
+                self.template_names.append(f'envelope_cos_{int(T)}d')
+
+        return columns
+
+    def _build_sse_templates(self, selected_sse: List[Dict]) -> List[np.ndarray]:
+        columns = []
+        for i, event in enumerate(selected_sse):
+            rc = self.templates.raised_cosine(event['start_day'], event['end_day'])
+            columns.append(rc)
+            start_str = event['start_day'].strftime('%Y-%m-%d')
+            end_str = event['end_day'].strftime('%Y-%m-%d')
+            self.template_names.append(f'SSE_{i}_{start_str}_to_{end_str}')
+        return columns
+
+    def _build_earthquake_templates(self, selected_eq: List[Dict]) -> List[np.ndarray]:
+        columns = []
+        for i, eq in enumerate(selected_eq):
+            eq_date = eq['eq_day']
+
+            step = self.templates.step(eq_date)
+            columns.append(step)
+            eq_str = eq_date.strftime('%Y-%m-%d')
+            self.template_names.append(f'EQ_{i}_{eq_str}_step')
+
+        return columns
+

trajmod/events/__init__.py

@@ -0,0 +1,15 @@
+"""Event catalog and selection module."""
+
+from trajmod.events.events import EventCatalog
+from trajmod.events.event_selection import (
+    EventSelector,
+    KneeEventSelector,
+    LassoEventSelector,
+)
+
+__all__ = [
+    "EventCatalog",
+    "EventSelector",
+    "KneeEventSelector",
+    "LassoEventSelector",
+]

trajmod/events/amplitude_threshold_selector.py

@@ -0,0 +1,149 @@
+"""Amplitude-based event selection."""
+import logging
+from typing import List, Dict, Optional
+
+import numpy as np
+
+from .event_selection import EventSelector
+
+logger = logging.getLogger(__name__)
+
+
+class AmplitudeThresholdSelector(EventSelector):
+    """Select events based on fitted amplitude threshold.
+
+    Fits all events and keeps only those with amplitude above threshold.
+    """
+
+    def __init__(self, threshold: float = 2.0, mode: str = 'absolute'):
+        """Initialize amplitude threshold selector.
+
+        Args:
+            threshold: Threshold value
+            mode: Threshold mode:
+                - 'absolute': Keep events with |amplitude| > threshold (mm)
+                - 'relative': Keep events with |amplitude| > threshold × RMS(data)
+                - 'snr': Keep events with |amplitude|/σ > threshold
+        """
+        if mode not in ['absolute', 'relative', 'snr']:
+            raise ValueError(f"mode must be 'absolute', 'relative', or 'snr', got {mode}")
+
+        self.threshold = threshold
+        self.mode = mode
+        self.last_amplitudes = None
+        self.last_threshold_value = None
+
+    def select(self, y: np.ndarray, G_baseline: np.ndarray,
+               event_templates: List[Dict], valid_mask: np.ndarray) -> List[int]:
+        """Select events with amplitude above threshold."""
+
+        if len(event_templates) == 0:
+            return []
+
+        # Fit full model to get event amplitudes
+        event_matrix = np.column_stack([ev['template'] for ev in event_templates])
+        G_full = np.hstack([G_baseline, event_matrix])
+
+        Gsub = G_full[valid_mask, :]
+        ysub = y[valid_mask]
+
+        try:
+            coeffs_full, _, _, _ = np.linalg.lstsq(Gsub, ysub, rcond=None)
+        except np.linalg.LinAlgError:
+            logger.warning("Singular matrix in amplitude selection, returning empty")
+            return []
+
+        # Extract event coefficients
+        n_baseline = G_baseline.shape[1]
+        event_coeffs = coeffs_full[n_baseline:]
+
+        # Store for debugging
+        self.last_amplitudes = event_coeffs
+
+        # Compute threshold based on mode
+        if self.mode == 'absolute':
+            threshold_value = self.threshold
+        elif self.mode == 'relative':
+            # Threshold relative to data RMS
+            data_rms = np.sqrt(np.mean(y[valid_mask] ** 2))
+            threshold_value = self.threshold * data_rms
+        else:  # snr
+            # Estimate noise level using MAD
+            from src.trajmod.model.model_selection import ModelSelector
+            # Compute residuals from full fit
+            fitted = G_full @ coeffs_full
+            residuals = y - fitted
+            sigma = ModelSelector.mad_sigma(residuals[valid_mask])
+            # SNR = |amplitude| / sigma > threshold
+            # So amplitude threshold = threshold * sigma
+            threshold_value = self.threshold * sigma
+
+        self.last_threshold_value = threshold_value
+
+        # Select events above threshold
+        selected_mask = np.abs(event_coeffs) >= threshold_value
+        selected_indices = np.where(selected_mask)[0].tolist()
+
+        logger.info(f"Amplitude selector ({self.mode}, threshold={self.threshold}) "
+                    f"selected {len(selected_indices)}/{len(event_templates)} events "
+                    f"(effective threshold={threshold_value:.2f} mm)")
+
+        return selected_indices
+
+    def plot_amplitudes(self, event_names: Optional[List[str]] = None,
+                        figsize=(10, 6), save_path: Optional[str] = None):
+        """Plot event amplitudes with threshold line.
+
+        Args:
+            event_names: Optional list of event names for x-axis labels
+            figsize: Figure size
+            save_path: Path to save plot
+        """
+        if self.last_amplitudes is None:
+            raise ValueError("Must call select() before plotting")
+
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        n_events = len(self.last_amplitudes)
+        x = np.arange(n_events)
+        amplitudes = self.last_amplitudes
+
+        # Sort by amplitude for better visualization
+        sorted_idx = np.argsort(-np.abs(amplitudes))
+        amplitudes_sorted = amplitudes[sorted_idx]
+
+        # Plot bars
+        colors = ['steelblue' if abs(a) >= self.last_threshold_value else 'lightgray'
+                  for a in amplitudes_sorted]
+        bars = ax.bar(x, amplitudes_sorted, color=colors, alpha=0.7, edgecolor='black')
+
+        # Add threshold lines
+        ax.axhline(self.last_threshold_value, color='red', linestyle='--',
+                   linewidth=2, label=f'Threshold (+{self.last_threshold_value:.2f} mm)')
+        ax.axhline(-self.last_threshold_value, color='red', linestyle='--',
+                   linewidth=2, label=f'Threshold (−{self.last_threshold_value:.2f} mm)')
+        ax.axhline(0, color='black', linewidth=0.8)
+
+        ax.set_xlabel('Event Index (sorted by amplitude)', fontsize=12)
+        ax.set_ylabel('Amplitude (mm)', fontsize=12)
+        ax.set_title(f'Event Amplitudes - {self.mode.capitalize()} Threshold',
+                     fontsize=14, fontweight='bold')
+        ax.legend(fontsize=11)
+        ax.grid(True, alpha=0.3, axis='y')
+
+        # Add text showing selection
+        n_selected = np.sum(np.abs(amplitudes) >= self.last_threshold_value)
+        ax.text(0.98, 0.98, f'{n_selected}/{n_events} events selected',
+                transform=ax.transAxes, ha='right', va='top',
+                bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.8),
+                fontsize=11)
+
+        plt.tight_layout()
+
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            logger.info(f"Saved amplitude plot to {save_path}")
+
+        return fig, ax