Transforms Summary & Workflow Guide
====================================

This page provides a comprehensive quick-reference guide for all 11 data transforms in RheoJAX. Use the comparison matrices and workflow examples below to select and chain transforms for your rheological analysis pipelines.


Complete Transforms Comparison Matrix
--------------------------------------

The table below provides a comprehensive overview of all transforms across key characteristics for rapid transform selection.

.. list-table:: Comprehensive Transform Comparison
   :header-rows: 1
   :widths: 16 22 16 16 12 10 8
   :class: longtable

   * - Transform
     - Purpose
     - Input Data Type
     - Output Data Type
     - Computational Cost
     - Real-time Capable
     - Best For
   * - :doc:`FFT Analysis </transforms/fft>`
     - Time → frequency domain conversion, spectral analysis, PSD, peak detection
     - Time-domain (t, signal)
     - Frequency-domain (f, spectrum/PSD)
     - Low
     - Yes
     - LAOS analysis, harmonic detection, periodic signals
   * - :doc:`Mastercurve </transforms/mastercurve>`
     - Time-Temperature Superposition (TTS), WLF/Arrhenius shifting, build master curves
     - Multi-T frequency sweeps with metadata
     - Merged mastercurve + shift factors
     - Medium
     - No
     - Polymer characterization, broaden frequency range, validate WLF
   * - :doc:`Mutation Number </transforms/mutation_number>`
     - Quantify relaxation character (solid vs liquid), gel point detection
     - Relaxation data G(t)
     - Scalar Δ ∈ [0,1] (0=elastic, 1=viscous)
     - Low
     - Yes
     - Material classification, gel point, compare viscoelastic character
   * - :doc:`OWChirp </transforms/owchirp>`
     - LAOS time-frequency analysis, extract harmonics, nonlinear indicators
     - Time-domain LAOS (stress/strain vs t)
     - Frequency spectrum + time-frequency map
     - High
     - No
     - Fast rheometry, curing/gelation monitoring, LAOS harmonics
   * - :doc:`Smooth Derivative </transforms/smooth_derivative>`
     - Noise-robust numerical differentiation (Savitzky-Golay, spline, TV)
     - Any RheoData (x, y)
     - Derivative RheoData (dy/dx)
     - Low-Medium
     - Yes
     - Strain rate from strain, noisy data, multi-order derivatives
   * - :doc:`SRFS </transforms/srfs>`
     - Strain-Rate Frequency Superposition, shear banding detection
     - Multi-rate frequency sweeps with metadata
     - Merged master curve + shift factors
     - Medium
     - No
     - Soft glassy materials, thixotropic fluids, shear banding
   * - :doc:`SPP Decomposer </transforms/spp>`
     - Sequence of Physical Processes decomposition for LAOS amplitude sweeps
     - LAOS amplitude sweep (stress, strain, strain rate)
     - SPP trajectories, yield stress parameters
     - Medium-High
     - No
     - LAOS yield stress extraction, static vs dynamic yield
   * - :doc:`Prony Conversion </transforms/prony_conversion>`
     - Time ↔ frequency domain conversion via Prony series (generalized Maxwell)
     - Relaxation G(t) or oscillation G*(ω)
     - Converted domain + Prony parameters (G_i, τ_i)
     - Low
     - Yes
     - Domain interconversion, parametric representation, LVE envelope input
   * - :doc:`Spectrum Inversion </transforms/spectrum_inversion>`
     - Recover continuous relaxation spectrum H(τ) via regularized inversion
     - Oscillation G*(ω) or relaxation G(t)
     - Continuous spectrum (τ, H(τ))
     - Medium
     - No
     - Material fingerprinting, relaxation mode identification, blend analysis
   * - :doc:`LVE Envelope </transforms/lve_envelope>`
     - Linear viscoelastic startup stress envelope from Prony series
     - Prony parameters (G_i, τ_i) or RheoData with metadata
     - Stress envelope σ_LVE⁺(t)
     - Low
     - Yes
     - Nonlinearity detection, strain hardening/softening, damping function
   * - :doc:`Cox-Merz </transforms/cox_merz>`
     - Cox-Merz rule validation: |η*(ω)| vs η(γ̇) comparison
     - Two RheoData: oscillation + flow curve
     - Deviation metric + pass/fail
     - Low
     - Yes
     - Rule validation, yielding detection, material classification

**Legend:**

* **Computational Cost:** Low (<10ms), Medium (10-100ms), High (>100ms) for typical datasets
* **Real-time Capable:** Suitable for streaming/online analysis
* **Best For:** Primary use cases and applications


Transform Selection Decision Tree
----------------------------------

Follow this decision tree to identify the appropriate transform for your analysis workflow.

.. code-block:: text

   START: What do you want to achieve?
   │
   ├─ DOMAIN CONVERSION (time ↔ frequency)?
   │  │
   │  ├─ Time → Frequency (general spectral analysis)?
   │  │  └─ FFT Analysis ★★★☆☆
   │  │     • Convert time-domain signals to frequency spectra
   │  │     • Compute Power Spectral Density (PSD)
   │  │     • Detect dominant frequencies and harmonics
   │  │     • Window functions: hann, hamming, blackman, tukey
   │  │     • Use Cases: LAOS harmonic detection, periodic signal analysis
   │  │
   │  └─ LAOS-specific time-frequency analysis?
   │     └─ OWChirp ★★★★☆
   │        • Optimal Windowed Chirp Fourier Transform
   │        • Time-resolved frequency content (2D map)
   │        • Extract higher harmonics (I₃/I₁, etc.)
   │        • Nonlinearity indicators
   │        • Use Cases: Curing, gelation, fast time-resolved rheometry
   │
   ├─ TEMPERATURE EFFECTS (build master curves)?
   │  └─ Mastercurve ★★★★☆
   │     • Time-Temperature Superposition (TTS)
   │     • Shift factors: WLF or Arrhenius
   │     • Merge multi-temperature frequency sweeps
   │     • Optimize WLF parameters (C₁, C₂)
   │     • Validate temperature dependence
   │     • Use Cases: Polymer characterization, broaden ω range by 3-5 decades
   │
   ├─ MATERIAL CLASSIFICATION (solid vs liquid)?
   │  └─ Mutation Number ★★☆☆☆
   │     • Quantifies relaxation character: Δ = ∫[dG/d(ln t)] d(ln t)
   │     • Δ = 0 → Pure elastic solid
   │     • Δ = 1 → Pure viscous liquid
   │     • 0 < Δ < 1 → Viscoelastic (closer to 0.5 = balanced)
   │     • Use Cases: Gel point detection, material screening, QC
   │
   ├─ NUMERICAL DIFFERENTIATION (need derivatives)?
   │  └─ Smooth Derivative ★★★☆☆
   │     • Noise-robust differentiation
   │     • Methods: Savitzky-Golay, spline, Total Variation (TV)
   │     • Multi-order derivatives (1st, 2nd, 3rd)
   │     • Automatic unit conversion
   │     • Use Cases: Strain rate from strain, acceleration, velocity
   │
   ├─ STRAIN-RATE EFFECTS (soft glassy materials)?
   │  └─ SRFS ★★★☆☆
   │     • Strain-Rate Frequency Superposition
   │     • Master curves from multi-rate oscillatory data
   │     • Shear banding detection (non-monotonic flow curve)
   │     • Power-law shift factors → estimate SGR x parameter
   │     • Use Cases: Soft glasses, emulsions, thixotropic fluids
   │
   ├─ LAOS YIELD STRESS (nonlinear intracycle analysis)?
   │  └─ SPP Decomposer ★★★★☆
   │     • Sequence of Physical Processes (Rogers framework)
   │     • Instantaneous G'(t), G''(t) within each cycle
   │     • Cole-Cole trajectories for yielding identification
   │     • Static vs dynamic yield stress extraction
   │     • Use Cases: Yield stress fluids, LAOS characterization
   │
   ├─ PARAMETRIC DOMAIN CONVERSION (Prony series)?
   │  └─ Prony Conversion ★★★☆☆
   │     • G(t) → G'(ω), G''(ω) via analytical Prony relations
   │     • G'(ω), G''(ω) → G(t) via inverse Prony fitting
   │     • NNLS fitting ensures non-negative mode strengths
   │     • Auto mode selection or manual n_modes control
   │     • Use Cases: Domain interconversion, LVE envelope input, GMM analysis
   │
   ├─ RELAXATION SPECTRUM (continuous H(τ) recovery)?
   │  └─ Spectrum Inversion ★★★★☆
   │     • Recover H(τ) from G*(ω) or G(t) data
   │     • Methods: Tikhonov (GCV auto-λ) or Maximum Entropy
   │     • Non-negative spectrum enforcement
   │     • Dual-source: oscillation or relaxation input
   │     • Use Cases: Material fingerprinting, blend analysis, spectrum comparison
   │
   ├─ STARTUP STRESS PREDICTION (LVE envelope)?
   │  └─ LVE Envelope ★★★☆☆
   │     • σ_LVE⁺(t) = γ̇₀ [G_e·t + Σ Gᵢτᵢ(1 − exp(−t/τᵢ))]
   │     • JIT-compiled for fast multi-rate sweeps
   │     • Accepts Prony params directly or from metadata
   │     • Use Cases: Nonlinearity detection, strain hardening/softening
   │
   ├─ EMPIRICAL RULE VALIDATION (Cox-Merz)?
   │  └─ Cox-Merz ★★☆☆☆
   │     • Compare |η*(ω)| with η(γ̇) at ω = γ̇
   │     • Log-log interpolation onto common rate grid
   │     • Quantitative pass/fail with configurable tolerance
   │     • Use Cases: Rule validation, yielding detection, material screening
   │
   └─ MULTI-STEP ANALYSIS (combine transforms)?
      └─ See "Common Workflow Pipelines" section below


Transform Deep-Dive Guides
---------------------------

FFT Analysis
~~~~~~~~~~~~

**Purpose:** Convert time-domain rheological signals to frequency domain for spectral analysis, harmonic detection, and periodic signal characterization.

**Key Capabilities:**

* **FFT Transformation:** Time → Frequency using Fast Fourier Transform
* **Power Spectral Density (PSD):** Energy distribution across frequencies
* **Peak Detection:** Identify dominant frequencies and harmonics
* **Windowing:** Reduce spectral leakage (Hann, Hamming, Blackman, Tukey, Bartlett)
* **Normalization:** Optional amplitude normalization

**Input Requirements:**

* Time-domain RheoData with ``domain='time'``
* Evenly spaced time points (or interpolation applied)
* Sufficient data length for frequency resolution: Δf = 1/T_total

**Output:**

* Frequency-domain RheoData: ``(frequency, magnitude)`` or ``(frequency, PSD)``
* Peak frequencies and amplitudes via ``.detect_peaks()``

**Key Parameters:**

.. list-table:: FFT Analysis Parameters
   :header-rows: 1
   :widths: 20 15 65

   * - Parameter
     - Default
     - Description
   * - ``window``
     - ``'hann'``
     - Window function: 'hann', 'hamming', 'blackman', 'tukey', 'bartlett', None
   * - ``detrend``
     - ``True``
     - Remove linear trend before FFT
   * - ``return_psd``
     - ``False``
     - Return Power Spectral Density instead of magnitude
   * - ``normalize``
     - ``False``
     - Normalize spectrum by maximum amplitude
   * - ``n_peaks``
     - ``5``
     - Number of peaks to detect (in ``.detect_peaks()``)

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import FFTAnalysis
   import numpy as np

   # Time-domain LAOS signal
   t = np.linspace(0, 10, 1000)
   signal = np.sin(2*np.pi*1.0*t) + 0.3*np.sin(2*np.pi*3.0*t)  # Fundamental + 3rd harmonic

   data = RheoData(x=t, y=signal, domain='time')

   # FFT with Hann window
   fft_transform = FFTAnalysis(window='hann', return_psd=False)
   freq_data = fft_transform.transform(data)

   # Detect peaks
   peaks = fft_transform.detect_peaks(freq_data, n_peaks=3)
   print(f"Detected frequencies: {peaks['frequencies']} Hz")

**Best For:**

* LAOS harmonic detection (I₃/I₁ ratios)
* Identifying periodic components in stress/strain signals
* Quality control of oscillatory tests
* Frequency content analysis


Mastercurve
~~~~~~~~~~~

**Purpose:** Apply Time-Temperature Superposition (TTS) to merge multi-temperature frequency sweep data into a single master curve, extending effective frequency range by 3-5 decades.

**Key Capabilities:**

* **WLF Shifting:** Williams-Landel-Ferry equation for polymer melts/elastomers
* **Arrhenius Shifting:** Activation energy-based for Newtonian fluids/solutions
* **Shift Factor Optimization:** Automatic optimization of C₁, C₂ (WLF) or E_a (Arrhenius)
* **Vertical Shifting:** Optional modulus shifting for incompressibility corrections
* **Overlap Error:** Quantitative assessment of superposition quality

**Input Requirements:**

* List of RheoData objects (frequency sweeps at different temperatures)
* Each RheoData must have ``metadata['temperature']`` in Kelvin
* Complex modulus data: G* = [:math:`G'`, :math:`G''`] or equivalent

**Output:**

* Merged master curve RheoData at reference temperature
* Shift factors dictionary: ``{T: a_T}`` for horizontal shifts

**Shift Models:**

1. **WLF (Williams-Landel-Ferry):**

   .. math::

      \log(a_T) = -\frac{C_1(T - T_{\text{ref}})}{C_2 + (T - T_{\text{ref}})}

   * **Universal constants:** C₁ ≈ 17.44, C₂ ≈ 51.6 K (relative to T_g)
   * **Best for:** Polymer melts, elastomers, T > T_g
   * **Typical range:** T_g + 50K to T_g + 150K

2. **Arrhenius:**

   .. math::

      a_T = \exp\left[\frac{E_a}{R}\left(\frac{1}{T} - \frac{1}{T_{\text{ref}}}\right)\right]

   * **Best for:** Newtonian fluids, polymer solutions, simple liquids
   * **E_a:** Activation energy (typical: 40-100 kJ/mol)

**Key Parameters:**

.. list-table:: Mastercurve Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``reference_temp``
     - Required
     - Reference temperature (K) for master curve
   * - ``method``
     - ``'wlf'``
     - Shift method: 'wlf' or 'arrhenius'
   * - ``C1``
     - ``17.44``
     - WLF parameter C₁ (only for WLF method)
   * - ``C2``
     - ``51.6``
     - WLF parameter C₂ in Kelvin (only for WLF)
   * - ``E_a``
     - ``50e3``
     - Activation energy in J/mol (only for Arrhenius)
   * - ``vertical_shift``
     - ``False``
     - Apply vertical (modulus) shifting
   * - ``optimize_shifts``
     - ``False``
     - Automatically optimize C₁, C₂ or E_a

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import Mastercurve

   # Multi-temperature frequency sweep datasets
   datasets = [data_25C, data_50C, data_75C, data_100C]

   # Create mastercurve at 50°C with WLF shifting
   mc = Mastercurve(
       reference_temp=323.15,  # 50°C in Kelvin
       method='wlf',
       C1=17.44,
       C2=51.6,
       optimize_shifts=True  # Auto-optimize C1, C2
   )

   # Build master curve
   mastercurve, shift_factors = mc.transform(datasets)

   # Get optimized WLF parameters
   C1_opt, C2_opt = mc.get_wlf_parameters()
   print(f"Optimized WLF: C1={C1_opt:.2f}, C2={C2_opt:.2f} K")

   # Assess superposition quality
   overlap_error = mc.compute_overlap_error(datasets)
   print(f"Overlap error: {overlap_error:.4f}")

**Best For:**

* Polymer rheology (extending ω range from ~3 decades to 6-8 decades)
* Validating WLF/Arrhenius behavior
* Characterizing temperature-dependent relaxation
* Publications requiring master curves


Mutation Number
~~~~~~~~~~~~~~~

**Purpose:** Quantify the viscoelastic character of materials by computing a scalar index Δ ∈ [0, 1] from relaxation data, where Δ=0 is purely elastic and Δ=1 is purely viscous.

**Theory:**

The mutation number Δ is defined as:

.. math::

   \Delta = \frac{1}{G(0)} \int_{-\infty}^{\infty} \frac{dG}{d(\ln t)} d(\ln t)

For practical relaxation data:

.. math::

   \Delta = \frac{G(t=0) - G(t=\infty)}{G(t=0)}

**Physical Interpretation:**

.. list-table:: Mutation Number Interpretation
   :header-rows: 1
   :widths: 15 30 55

   * - Δ Value
     - Material Type
     - Physical Meaning
   * - Δ = 0
     - Pure elastic solid
     - No stress relaxation (G(t) = constant)
   * - 0 < Δ < 0.3
     - Solid-like
     - Weak relaxation, strong equilibrium modulus
   * - Δ ≈ 0.5
     - Balanced viscoelastic
     - Comparable elastic/viscous character
   * - 0.7 < Δ < 1
     - Liquid-like
     - Strong relaxation, weak/no equilibrium modulus
   * - Δ = 1
     - Pure viscous liquid
     - Complete stress relaxation (G(t→∞) = 0)

**Key Capabilities:**

* **Material Classification:** Rapid solid/liquid/gel identification
* **Gel Point Detection:** Δ ≈ 0.5-0.7 at sol-gel transition
* **Quality Control:** Consistent metric for batch comparison
* **Model Selection Aid:** Helps choose solid vs liquid models

**Input Requirements:**

* Relaxation data: G(t) vs time
* RheoData with ``test_mode='relaxation'``
* Sufficient time range to capture relaxation (ideally 4-5 decades)

**Output:**

* Scalar RheoData with Δ value in ``y`` attribute
* ``domain='scalar'`` for single-value result

**Key Parameters:**

.. list-table:: Mutation Number Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``integration_method``
     - ``'trapz'``
     - Numerical integration: 'trapz', 'simps', 'cumulative'
   * - ``extrapolate``
     - ``True``
     - Extrapolate to t→0 and t→∞
   * - ``extrapolation_model``
     - ``'power_law'``
     - Model for extrapolation: 'power_law', 'exponential'

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import MutationNumber

   # Relaxation data
   t = np.logspace(-2, 4, 100)
   G_t = 1e5 * np.exp(-t / 10.0)  # Exponential relaxation

   data = RheoData(x=t, y=G_t, domain='time', initial_test_mode='relaxation')

   # Compute mutation number
   mutation = MutationNumber(extrapolate=True)
   result = mutation.transform(data)

   delta = result.y[0]
   print(f"Mutation Number Δ = {delta:.3f}")

   # Interpret
   if delta < 0.3:
       print("Material: Solid-like")
   elif delta < 0.7:
       print("Material: Viscoelastic")
   else:
       print("Material: Liquid-like")

**Best For:**

* Rapid material screening and classification
* Gel point detection in curing studies
* Quality control metrics
* Comparing viscoelastic character across samples


OWChirp
~~~~~~~

**Purpose:** Perform time-frequency analysis of Large Amplitude Oscillatory Shear (LAOS) data using Optimal Windowed Chirp transforms, extracting harmonics and nonlinear indicators.

**Key Capabilities:**

* **Time-Frequency Maps:** 2D spectrograms showing frequency content evolution
* **Harmonic Extraction:** Separate fundamental, 3rd, 5th, 7th harmonics
* **Nonlinearity Indicators:** I₃/I₁, I₅/I₁ ratios (higher harmonics/fundamental)
* **Fast Rheometry:** Time-resolved analysis of curing, gelation, structure formation
* **LAOS Analysis:** Quantify nonlinear viscoelastic response

**Theory:**

OWChirp uses a chirp wavelet transform optimized for oscillatory rheological signals:

.. math::

   W(t, \omega) = \int_{-\infty}^{\infty} s(\tau) \psi^*(\tau - t, \omega) d\tau

where ψ is an optimal wavelet matched to oscillatory strain/stress.

**Input Requirements:**

* Time-domain LAOS data: stress(t) or strain(t)
* Imposed oscillatory strain with known frequency ω₀
* Sufficient temporal resolution (sample rate >> ω₀)

**Output:**

* Frequency spectrum RheoData (1D)
* Time-frequency map via ``.get_time_frequency_map()`` (2D array)
* Harmonic components via ``.extract_harmonics()``

**Key Parameters:**

.. list-table:: OWChirp Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``n_frequencies``
     - ``100``
     - Number of frequency points in analysis
   * - ``frequency_range``
     - ``None``
     - (f_min, f_max); auto-detect if None
   * - ``wavelet_width``
     - ``6.0``
     - Width of Morlet wavelet (cycles)
   * - ``extract_harmonics``
     - ``True``
     - Automatically extract harmonics
   * - ``max_harmonic``
     - ``7``
     - Highest harmonic to extract (1, 3, 5, 7, ...)

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import OWChirp
   import numpy as np

   # LAOS stress response (nonlinear)
   t = np.linspace(0, 10, 2000)
   omega_0 = 2 * np.pi * 1.0  # 1 Hz
   stress = (1e3 * np.sin(omega_0 * t) +
             300 * np.sin(3 * omega_0 * t) +  # 3rd harmonic
             50 * np.sin(5 * omega_0 * t))    # 5th harmonic

   data = RheoData(x=t, y=stress, domain='time')

   # OWChirp analysis
   owchirp = OWChirp(n_frequencies=200, extract_harmonics=True, max_harmonic=7)
   freq_data = owchirp.transform(data)

   # Extract harmonics
   harmonics = owchirp.extract_harmonics(freq_data, fundamental_freq=1.0)
   I1 = harmonics['I1']  # Fundamental
   I3 = harmonics['I3']  # 3rd harmonic
   I5 = harmonics['I5']  # 5th harmonic

   # Nonlinearity indicators
   print(f"I3/I1 = {I3/I1:.3f}")  # Typical: 0.01-0.3 for LAOS
   print(f"I5/I1 = {I5/I1:.3f}")

   # Time-frequency map
   tf_map = owchirp.get_time_frequency_map(data)

**Best For:**

* LAOS (Large Amplitude Oscillatory Shear) analysis
* Curing/gelation monitoring (time-resolved)
* Fast time-sweep rheometry
* Nonlinear viscoelastic characterization


Smooth Derivative
~~~~~~~~~~~~~~~~~

**Purpose:** Compute noise-robust numerical derivatives of rheological data using advanced smoothing techniques (Savitzky-Golay, spline, Total Variation).

**Key Capabilities:**

* **Noise Suppression:** Smoothing before/after differentiation
* **Multiple Methods:** Savitzky-Golay, spline, Total Variation (TV) regularization
* **Multi-Order:** 1st, 2nd, 3rd derivatives
* **Automatic Units:** Updates units for derivative quantity
* **Flexible Smoothing:** Pre-smooth, post-smooth, or both

**Methods:**

1. **Savitzky-Golay (Default):**

   * Polynomial fit over moving window
   * Preserves peak shapes
   * Best for: Smooth data with localized features
   * Parameters: ``window_length``, ``polyorder``

2. **Spline:**

   * Cubic spline interpolation + differentiation
   * Smooth continuous derivatives
   * Best for: Noisy data requiring aggressive smoothing
   * Parameters: ``smoothing_factor``

3. **Total Variation (TV):**

   * L1-norm regularization (edge-preserving)
   * Preserves discontinuities
   * Best for: Data with step changes or plateaus
   * Parameters: ``regularization_weight``

**Input Requirements:**

* Any RheoData (x, y) with sufficient data points
* Minimum points: ``window_length + 1`` for Savitzky-Golay

**Output:**

* Derivative RheoData with updated units
* Same x-axis (or slightly truncated for edge effects)

**Key Parameters:**

.. list-table:: Smooth Derivative Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``method``
     - ``'savgol'``
     - Method: 'savgol', 'spline', 'tv'
   * - ``window_length``
     - ``11``
     - Savitzky-Golay window (must be odd)
   * - ``polyorder``
     - ``3``
     - Savitzky-Golay polynomial order (<window_length)
   * - ``deriv``
     - ``1``
     - Derivative order (1, 2, 3)
   * - ``smooth_before``
     - ``True``
     - Smooth data before differentiation
   * - ``smooth_after``
     - ``False``
     - Smooth derivative after computation
   * - ``smooth_window``
     - ``5``
     - Window for post-smoothing

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import SmoothDerivative
   import numpy as np

   # Noisy strain data
   t = np.linspace(0, 10, 200)
   strain = 0.1 * t**2 + np.random.normal(0, 0.01, size=t.shape)

   data = RheoData(x=t, y=strain, domain='time', units_x='s', units_y='dimensionless')

   # Compute strain rate (dε/dt) with Savitzky-Golay
   derivative_transform = SmoothDerivative(
       method='savgol',
       window_length=15,
       polyorder=3,
       deriv=1,
       smooth_before=True
   )

   strain_rate = derivative_transform.transform(data)
   print(f"Strain rate units: {strain_rate.units_y}")  # '1/s'

   # For very noisy data, use spline or TV
   derivative_tv = SmoothDerivative(method='tv', deriv=1)
   strain_rate_tv = derivative_tv.transform(data)

**Best For:**

* Computing strain rate from strain history
* Velocity/acceleration from position
* Derivative-based features for model fitting
* Noisy experimental data


SRFS (Strain-Rate Frequency Superposition)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Purpose:** Collapse multi-rate oscillatory data onto a master curve by shifting in the strain-rate domain, analogous to time-temperature superposition (TTS) but for soft glassy materials.

**Key Capabilities:**

* **Master Curve Construction:** Merge :math:`G'(\omega)` sweeps at different :math:`\dot{\gamma}` onto one reference curve
* **Shift Factor Analysis:** Extract power-law exponent to estimate SGR noise temperature :math:`x`
* **Shear Banding Detection:** Identify non-monotonic constitutive curves from flow data
* **Thixotropy Kinetics:** Structural parameter :math:`\lambda(t)` evolution under flow

**Theory:**

For SGR-type soft glasses, moduli at different strain rates superpose via:

.. math::

   G'(\omega, \dot{\gamma}) = b(\dot{\gamma}) \, G'_{\text{master}}(a(\dot{\gamma}) \cdot \omega)

with :math:`a(\dot{\gamma}) \sim \dot{\gamma}^{-1/(x-1)}` and :math:`b(\dot{\gamma}) \sim \dot{\gamma}^{-1}` for ideal SGR materials.

**Input Requirements:**

* Multi-rate oscillatory frequency sweeps: :math:`G'(\omega)` and :math:`G''(\omega)` at 3+ strain rates
* Known strain rate for each sweep

**Output:**

* Master curve RheoData at reference strain rate
* Horizontal and vertical shift factors per rate
* Estimated :math:`x` parameter from shift factor scaling

**Key Parameters:**

.. list-table:: SRFS Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``reference_rate``
     - ``1.0``
     - Reference strain rate for the master curve
   * - ``method``
     - ``'auto'``
     - Shift factor method: 'auto', 'power_law', 'empirical'
   * - ``vertical_shift``
     - ``True``
     - Apply vertical (modulus) shifting in addition to horizontal

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import SRFS
   import numpy as np

   # Multi-rate oscillatory data
   rates = [0.01, 0.1, 1.0, 10.0]
   omega = np.logspace(-2, 2, 50)
   G_star_data = {rate: measure_modulus(omega, rate) for rate in rates}

   # Build SRFS master curve
   srfs = SRFS(reference_rate=1.0)
   master_curve, shift_factors = srfs.transform(omega, G_star_data)

   # Extract x from shift factor scaling
   # log(a) = -1/(x-1) * log(gamma_dot)
   from scipy.stats import linregress
   log_rates = np.log10(rates)
   log_a = np.log10(shift_factors['a'])
   slope, _, r_value, _, _ = linregress(log_rates, log_a)
   x_est = 1 - 1/slope
   print(f"Estimated x = {x_est:.3f} (R² = {r_value**2:.4f})")

**Best For:**

* Soft glassy materials (concentrated emulsions, colloidal gels, pastes)
* Yield stress fluids with strain-rate-dependent microstructure
* Thixotropic systems where structure evolves with deformation
* Validating SGR model predictions


SPP Decomposer
~~~~~~~~~~~~~~~

**Purpose:** Perform intracycle LAOS analysis using the Sequence of Physical Processes (SPP) framework, extracting time-resolved instantaneous moduli and yield stress from nonlinear oscillatory data.

**Key Capabilities:**

* **Instantaneous Moduli:** Time-resolved :math:`G'(t)` and :math:`G''(t)` within each oscillation cycle
* **Cole-Cole Trajectories:** Plot :math:`G'_t` vs :math:`G''_t` to visualize yielding sequences
* **Yield Stress Extraction:** Robust static/dynamic yield stress from LAOS amplitude sweeps
* **Nonlinear Fingerprinting:** Classify yielding type (abrupt vs gradual, cage vs flow yield)

**Theory:**

SPP defines instantaneous moduli from the stress response :math:`\sigma(t)` to sinusoidal
strain :math:`\gamma(t) = \gamma_0 \sin(\omega t)`:

.. math::

   G'_t = \frac{\dot{\sigma}}{\dot{\gamma}}, \quad
   G''_t \omega = \frac{d\sigma}{dt}\bigg|_{\gamma=\text{const}}

These reduce to the linear viscoelastic :math:`G', G''` at small amplitude but reveal rich
intracycle structure at large amplitudes.

**Input Requirements:**

* Time-domain LAOS data: stress :math:`\sigma(t)` and strain :math:`\gamma(t)`
* Known strain amplitude :math:`\gamma_0` and angular frequency :math:`\omega`
* Sufficient points per cycle (typically 500-1000)

**Output:**

* Instantaneous moduli arrays :math:`G'(t)`, :math:`G''(t)` over one cycle
* Cole-Cole trajectory array :math:`[G'_t, G''_t]`
* Cycle-averaged and maximum moduli, yield indicator

**Key Parameters:**

.. list-table:: SPP Decomposer Parameters
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Default
     - Description
   * - ``gamma_0``
     - Required
     - Strain amplitude for analysis
   * - ``omega``
     - Required
     - Angular frequency (rad/s)
   * - ``n_points``
     - ``1000``
     - Points per cycle for analysis
   * - ``smooth_derivatives``
     - ``True``
     - Apply Savitzky-Golay smoothing to stress derivatives
   * - ``window_length``
     - ``21``
     - Smoothing window size (must be odd)

**Example Usage:**

.. code-block:: python

   from rheojax.transforms import SPPDecomposer
   import numpy as np

   # LAOS data
   gamma_0, omega = 0.5, 1.0
   t = np.linspace(0, 2*np.pi/omega, 1000)
   gamma = gamma_0 * np.sin(omega * t)
   stress = experimental_stress(t)  # Your measured data

   spp = SPPDecomposer(gamma_0=gamma_0, omega=omega)
   result = spp.transform(t, gamma, stress)

   # Cole-Cole trajectory
   import matplotlib.pyplot as plt
   plt.plot(result.Gp_instantaneous, result.Gpp_instantaneous)
   plt.xlabel(r"$G'_t$ (Pa)")
   plt.ylabel(r"$G''_t$ (Pa)")
   plt.title("SPP Cole-Cole Trajectory")
   plt.close("all")

   # Yield stress from amplitude sweep
   yield_stress = spp.extract_yield_stress(amplitude_sweep_results)
   print(f"Yield stress: {yield_stress:.2f} Pa")

**Best For:**

* LAOS yield stress determination (more robust than Fourier methods)
* Identifying yielding mechanisms (Type I abrupt vs Type II gradual)
* Distinguishing cage yield from flow yield
* Validating constitutive models against SPP trajectories


Prony Conversion
~~~~~~~~~~~~~~~~

**Purpose:** Parametric domain conversion between time and frequency domains using the Prony (generalized Maxwell) series.

**Key Capabilities:**

* **Time → Frequency:** :math:`G(t) \to G'(\omega), G''(\omega)` via analytical Prony relations
* **Frequency → Time:** :math:`G'(\omega), G''(\omega) \to G(t)` via inverse Prony fitting
* **NNLS Fitting:** Non-negative least squares ensures thermodynamically consistent mode strengths
* **Auto Mode Selection:** Automatic number of modes based on data density

**Quick Example:**

.. code-block:: python

   from rheojax.transforms import PronyConversion

   # G(t) → G'(ω), G''(ω)
   prony = PronyConversion(n_modes=10, direction="time_to_freq")
   freq_data, info = prony.transform(relaxation_data)

   # Access Prony parameters
   result = info["prony_result"]
   print(f"Modes: {result.n_modes}, G_e: {result.G_e:.1f} Pa")

   # Reverse: G*(ω) → G(t)
   prony_inv = PronyConversion(direction="freq_to_time", n_modes=8)
   relax_data, _ = prony_inv.transform(oscillation_data)

**Best For:**

* Domain interconversion with compact parametric representation
* Obtaining Prony parameters for LVE envelope computation
* Generalized Maxwell model parameter extraction
* Round-trip validation of data consistency

Spectrum Inversion
~~~~~~~~~~~~~~~~~~

**Purpose:** Recover the continuous relaxation spectrum :math:`H(\tau)` from dynamic moduli or relaxation data via regularized inversion.

**Key Capabilities:**

* **Tikhonov Regularization:** GCV-optimized regularization parameter selection
* **Maximum Entropy:** Information-theoretic inversion preserving positivity
* **Dual-Source Input:** Works from oscillation :math:`G^*(\omega)` or relaxation :math:`G(t)` data
* **Non-Negative Enforcement:** Physical constraint :math:`H(\tau) \ge 0`

**Quick Example:**

.. code-block:: python

   from rheojax.transforms import SpectrumInversion

   # From oscillatory data
   inv = SpectrumInversion(method="tikhonov", n_tau=100)
   spectrum_data, info = inv.transform(osc_data)

   tau = spectrum_data.x      # Relaxation times
   H_tau = spectrum_data.y    # Spectrum H(τ)

   # From relaxation data
   inv_relax = SpectrumInversion(source="relaxation", method="max_entropy")
   spectrum_data, _ = inv_relax.transform(relax_data)

**Best For:**

* Material fingerprinting via relaxation time distribution
* Identifying discrete relaxation modes in blends and composites
* Comparing spectra across compositions, temperatures, or processing conditions
* Complementary to discrete Prony representation (continuous vs discrete)

LVE Envelope
~~~~~~~~~~~~~

**Purpose:** Compute the linear viscoelastic startup stress envelope from Prony series parameters.

**Key Capabilities:**

* **Analytical Prediction:** :math:`\sigma_{\text{LVE}}^+(t) = \dot{\gamma}_0 [G_e t + \sum G_i \tau_i (1 - e^{-t/\tau_i})]`
* **JIT-Compiled:** Fast evaluation for multi-rate sweeps
* **Flexible Input:** Prony parameters via constructor or from data metadata

**Quick Example:**

.. code-block:: python

   from rheojax.transforms import LVEEnvelope
   import numpy as np

   G_i = np.array([5e3, 2e3])
   tau_i = np.array([0.1, 10.0])

   lve = LVEEnvelope(shear_rate=1.0, G_i=G_i, tau_i=tau_i)
   envelope_data, info = lve.transform()

   # Compare with experimental startup data
   import matplotlib.pyplot as plt
   plt.loglog(envelope_data.x, envelope_data.y, '--', label='LVE envelope')
   plt.loglog(startup_data.x, startup_data.y, 'o', label='Experiment')
   plt.legend()
   plt.close("all")

**Best For:**

* Detecting nonlinear behavior (strain hardening/softening) in startup experiments
* Damping function extraction: :math:`h(\gamma) = \sigma_{\text{exp}} / \sigma_{\text{LVE}}`
* Multi-rate LVE families for branched polymer characterization
* Input for constitutive model validation

Cox-Merz
~~~~~~~~

**Purpose:** Validate the Cox-Merz empirical rule: :math:`|\eta^*(\omega)| = \eta(\dot{\gamma})` at :math:`\omega = \dot{\gamma}`.

**Key Capabilities:**

* **Rule Validation:** Quantitative pass/fail assessment with configurable tolerance
* **Deviation Mapping:** Point-by-point relative deviation across the overlap region
* **Log-Log Interpolation:** Onto common rate grid preserving power-law structure
* **Flexible Input:** Accepts complex :math:`G^*` or :math:`[G', G'']` and stress or viscosity

**Quick Example:**

.. code-block:: python

   from rheojax.transforms import CoxMerz

   cm = CoxMerz(tolerance=0.10)
   result_data, info = cm.transform([osc_data, flow_data])

   result = info["cox_merz_result"]
   print(f"Mean deviation: {result.mean_deviation:.1%}")
   print(f"Passes (≤10%): {result.passes}")

**Best For:**

* Validating oscillatory-to-steady-shear equivalence for flexible polymers
* Detecting yield stress behavior (Cox-Merz failure = yielding indicator)
* Material screening and classification
* Quality control of rheological measurements


Common Workflow Pipelines
--------------------------

Transform workflows combine multiple transforms in sequence to achieve complex analysis goals.

Workflow 1: Stress Relaxation → FFT → Fractional Model Fit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Convert relaxation data to frequency domain and fit a fractional model.

.. code-block:: python

   from rheojax.transforms import FFTAnalysis
   from rheojax.models import FractionalZenerSolidSolid

   # 1. Time-domain relaxation
   G_t_data = RheoData(x=t, y=G_t, domain='time', initial_test_mode='relaxation')

   # 2. FFT to frequency domain
   fft = FFTAnalysis(window='hann')
   G_star_data = fft.transform(G_t_data)

   # 3. Fit fractional model
   model = FractionalZenerSolidSolid()
   model.fit(G_star_data.x, G_star_data.y, test_mode='oscillation')

   print(f"Fitted α = {model.parameters.get_value('alpha'):.3f}")

**Why this workflow:**

* FFT converts relaxation G(t) to complex modulus G*(ω)
* Fractional models often fit better in frequency domain
* Broader frequency range from FFT than experimental oscillation


Workflow 2: Multi-Temperature Sweeps → Mastercurve → Model Fit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Build master curve from multi-T data, then fit a single model across extended frequency range.

.. code-block:: python

   from rheojax.transforms import Mastercurve
   from rheojax.models import FractionalMaxwellLiquid

   # 1. Multi-temperature datasets
   datasets = [data_25C, data_50C, data_75C, data_100C]

   # 2. Build mastercurve at 50°C
   mc = Mastercurve(reference_temp=323.15, method='wlf', optimize_shifts=True)
   mastercurve, shifts = mc.transform(datasets)

   # 3. Fit model to extended frequency range
   model = FractionalMaxwellLiquid()
   model.fit(mastercurve.x, mastercurve.y, test_mode='oscillation')

   # 4. Assess quality
   C1, C2 = mc.get_wlf_parameters()
   error = mc.compute_overlap_error(datasets)
   print(f"WLF: C1={C1:.2f}, C2={C2:.2f} K, Error={error:.4f}")

**Why this workflow:**

* Extends frequency range by 3-5 decades
* Single model fit captures temperature-invariant physics
* Validates WLF behavior


Workflow 3: Oscillation → Mutation Number → Model Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Classify material character, then select appropriate model family.

.. code-block:: python

   from rheojax.transforms import MutationNumber
   from rheojax.models import FractionalZenerSolidSolid, FractionalMaxwellLiquid

   # 1. Relaxation data
   G_t_data = RheoData(x=t, y=G_t, domain='time', initial_test_mode='relaxation')

   # 2. Compute mutation number
   mutation = MutationNumber()
   result = mutation.transform(G_t_data)
   delta = result.y[0]

   # 3. Select model based on Δ
   if delta < 0.5:
       print("Solid-like → Using Fractional Zener SS")
       model = FractionalZenerSolidSolid()
   else:
       print("Liquid-like → Using Fractional Maxwell Liquid")
       model = FractionalMaxwellLiquid()

   # 4. Fit selected model
   model.fit(t, G_t, test_mode='relaxation')

**Why this workflow:**

* Automated model selection based on physics
* Mutation number is fast and reliable classifier
* Improves convergence by using appropriate model


Workflow 4: LAOS Chirp → OWChirp FT → Extract Harmonics → Fit Nonlinear Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Analyze LAOS data for nonlinear viscoelastic response.

.. code-block:: python

   from rheojax.transforms import OWChirp

   # 1. LAOS stress response
   stress_data = RheoData(x=t, y=stress, domain='time')

   # 2. OWChirp analysis
   owchirp = OWChirp(extract_harmonics=True, max_harmonic=7)
   freq_data = owchirp.transform(stress_data)

   # 3. Extract harmonics
   harmonics = owchirp.extract_harmonics(freq_data, fundamental_freq=omega_0/(2*np.pi))
   I1, I3, I5 = harmonics['I1'], harmonics['I3'], harmonics['I5']

   # 4. Nonlinearity indicators
   print(f"Nonlinearity: I3/I1={I3/I1:.3f}, I5/I1={I5/I1:.3f}")

   # 5. Time-frequency map for curing monitoring
   tf_map = owchirp.get_time_frequency_map(stress_data)

**Why this workflow:**

* OWChirp designed for LAOS signals
* Harmonic extraction quantifies nonlinear response
* Time-frequency map reveals structural evolution


Workflow 5: Strain History → Smooth Derivative → Strain Rate → Flow Model Fit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Compute strain rate from noisy strain data, then fit flow curve model.

.. code-block:: python

   from rheojax.transforms import SmoothDerivative
   from rheojax.models import PowerLaw

   # 1. Noisy strain history
   strain_data = RheoData(x=t, y=strain, domain='time', units_x='s', units_y='dimensionless')

   # 2. Smooth derivative → strain rate
   deriv = SmoothDerivative(method='savgol', window_length=15, deriv=1)
   strain_rate = deriv.transform(strain_data)

   # 3. Combine with stress data
   stress_data = RheoData(x=t, y=stress, domain='time')

   # 4. Create flow curve (η vs γ̇)
   eta = stress_data.y / strain_rate.y
   flow_curve = RheoData(x=strain_rate.y, y=eta, domain='rotation')

   # 5. Fit Power Law
   model = PowerLaw()
   model.fit(strain_rate.y, stress_data.y, test_mode='rotation')

   K = model.parameters.get_value('K')
   n = model.parameters.get_value('n')
   print(f"Power Law: K={K:.2e}, n={n:.3f}")

**Why this workflow:**

* Smooth derivative essential for noisy strain data
* Direct computation of flow curve from time-domain data
* Enables flow model fitting from non-standard tests


Workflow 6: Relaxation → Prony Conversion → LVE Envelope → Nonlinearity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Fit Prony series to relaxation data, compute LVE startup envelope, compare with experiment.

.. code-block:: python

   from rheojax.transforms import PronyConversion, LVEEnvelope
   import numpy as np

   # Step 1: Fit Prony series to G(t) data
   prony = PronyConversion(n_modes=10, direction="time_to_freq")
   _, info = prony.transform(relaxation_data)
   result = info["prony_result"]

   # Step 2: Compute LVE envelope at experimental rate
   lve = LVEEnvelope(
       shear_rate=1.0, G_i=result.G_i,
       tau_i=result.tau_i, G_e=result.G_e
   )
   envelope_data, _ = lve.transform()

   # Step 3: Compare with experimental startup data
   import matplotlib.pyplot as plt
   plt.loglog(envelope_data.x, envelope_data.y, '--', label='LVE')
   plt.loglog(startup_data.x, startup_data.y, 'o', label='Experiment')
   plt.legend()
   plt.close("all")

**Why this workflow:**

* Prony series provides compact parametric representation for LVE envelope
* LVE envelope + experimental data reveals strain hardening/softening onset
* Multi-rate sweeps identify critical Weissenberg number

Workflow 7: Oscillation → Spectrum Inversion → Material Fingerprint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Recover continuous relaxation spectrum from frequency sweep for material identification.

.. code-block:: python

   from rheojax.transforms import SpectrumInversion
   import matplotlib.pyplot as plt

   # Recover H(τ) from oscillatory data
   inv = SpectrumInversion(method="tikhonov", n_tau=100)
   spectrum_data, info = inv.transform(osc_data)

   # Plot relaxation spectrum
   plt.semilogx(spectrum_data.x, spectrum_data.y)
   plt.xlabel(r'$\tau$ (s)')
   plt.ylabel(r'$H(\tau)$ (Pa)')
   plt.title(f"λ = {info['spectrum_result'].regularization_param:.2e}")
   plt.close("all")

**Why this workflow:**

* Continuous spectrum reveals distribution of relaxation mechanisms
* Peaks in :math:`H(\tau)` correspond to distinct molecular processes
* Fingerprint comparison across formulations, temperatures, or aging conditions

Workflow 8: Oscillation + Flow Curve → Cox-Merz Validation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Goal:** Validate Cox-Merz rule to assess whether oscillatory and steady-shear data are consistent.

.. code-block:: python

   from rheojax.transforms import CoxMerz

   cm = CoxMerz(tolerance=0.10, n_points=50)
   result_data, info = cm.transform([osc_data, flow_data])

   result = info["cox_merz_result"]
   if result.passes:
       print(f"Cox-Merz passes: mean deviation {result.mean_deviation:.1%}")
   else:
       print(f"Cox-Merz FAILS: deviation {result.mean_deviation:.1%}")
       print("Material may exhibit yielding or associating behavior")

**Why this workflow:**

* Quick validation of data consistency between oscillatory and flow measurements
* Cox-Merz failure flags yield stress behavior or structural breakdown under flow
* Useful as a quality control step before model fitting


Transform Chaining & Compatibility
-----------------------------------

Which Transforms Can Be Chained?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table:: Transform Chaining Compatibility Matrix
   :header-rows: 1
   :widths: 20 20 60

   * - Transform 1
     - Transform 2
     - Compatibility & Notes
   * - FFT
     - Mastercurve
     - ✓ FFT → frequency domain → merge multi-T → mastercurve
   * - FFT
     - OWChirp
     - ✗ Both do time→frequency (choose one based on need)
   * - FFT
     - Mutation Number
     - ✗ Mutation needs time-domain relaxation data
   * - FFT
     - Smooth Derivative
     - ✓ Smooth first → FFT (reduces spectral noise)
   * - Mastercurve
     - Smooth Derivative
     - ✓ Smooth individual sweeps before merging
   * - Mutation Number
     - Smooth Derivative
     - ✓ Smooth G(t) before computing Δ (recommended)
   * - OWChirp
     - Smooth Derivative
     - ✓ Smooth LAOS signal before OWChirp
   * - Smooth Derivative
     - Any
     - ✓ Pre-processing step for noisy data (chain first)
   * - Prony Conversion
     - LVE Envelope
     - ✓ Prony parameters feed directly into LVE envelope computation
   * - Prony Conversion
     - Spectrum Inversion
     - ✗ Both produce spectral representations (choose one)
   * - FFT
     - Prony Conversion
     - ✗ Both do time→frequency (choose based on parametric vs non-parametric need)
   * - Prony Conversion
     - Cox-Merz
     - ✓ Prony → G*(ω) → complex viscosity for Cox-Merz comparison
   * - FFT
     - Spectrum Inversion
     - ✓ FFT → G*(ω) → H(τ) spectrum recovery
   * - Spectrum Inversion
     - Any model
     - ✓ Terminal analysis (spectrum is the result); use peaks to initialize model fits
   * - Cox-Merz
     - Any
     - ✗ Terminal validation step (pass/fail metric is the result)

**General Rules:**

1. **Smooth Derivative is a pre-processor** — Apply first to reduce noise
2. **FFT and OWChirp are alternatives** — Both do time→frequency (pick based on use case)
3. **Prony Conversion and FFT are alternatives** — Parametric vs non-parametric domain conversion
4. **Prony → LVE Envelope is a natural chain** — Prony parameters feed directly into startup prediction
5. **Spectrum Inversion and Cox-Merz are terminal** — Their outputs are analysis results, not intermediate data
6. **Mastercurve is a merge operation** — Combine multiple datasets, not chainable after FFT/OWChirp


Sequential Processing Pipelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Pipeline 1: Noise Reduction → FFT → Model Fit**

.. code-block:: python

   smooth = SmoothDerivative(method='savgol', deriv=0, window_length=11)  # deriv=0 = smoothing only
   fft = FFTAnalysis(window='hann')

   smoothed_data = smooth.transform(noisy_data)
   freq_data = fft.transform(smoothed_data)
   model.fit(freq_data.x, freq_data.y)

**Pipeline 2: Multi-Temperature → Smooth → Mastercurve → Fit**

.. code-block:: python

   smooth = SmoothDerivative(method='spline', deriv=0)
   mc = Mastercurve(reference_temp=323.15, method='wlf', optimize_shifts=True)

   # Smooth each temperature dataset
   smoothed_datasets = [smooth.transform(d) for d in datasets]

   # Build mastercurve
   mastercurve, shifts = mc.transform(smoothed_datasets)

   # Fit model
   model.fit(mastercurve.x, mastercurve.y)


Quality Checkpoints Between Stages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Checkpoint 1: After Smoothing**

.. code-block:: python

   # Verify smoothing didn't over-smooth
   plt.plot(original_data.x, original_data.y, 'o', label='Original')
   plt.plot(smoothed_data.x, smoothed_data.y, '-', label='Smoothed')
   plt.legend()

**Checkpoint 2: After FFT**

.. code-block:: python

   # Check for spectral leakage
   peaks = fft.detect_peaks(freq_data, n_peaks=5)
   print(f"Detected peaks at: {peaks['frequencies']} Hz")

**Checkpoint 3: After Mastercurve**

.. code-block:: python

   # Assess superposition quality
   error = mc.compute_overlap_error(datasets)
   if error > 0.05:
       print("WARNING: Poor superposition quality")

   # Plot shift factors
   temps, shifts = mc.get_shift_factors_array()
   plt.plot(temps, np.log10(shifts), 'o-')
   plt.xlabel('Temperature (K)')
   plt.ylabel('log(a_T)')


Parameter Selection Guidelines
-------------------------------

FFT Analysis
~~~~~~~~~~~~

.. list-table:: FFT Parameter Selection Guide
   :header-rows: 1
   :widths: 25 35 40

   * - Scenario
     - Recommended Settings
     - Rationale
   * - Clean periodic signal
     - ``window=None``, ``detrend=True``
     - No window needed; remove DC offset
   * - Noisy signal
     - ``window='hann'``, ``detrend=True``
     - Hann reduces spectral leakage
   * - Sharp transients
     - ``window='blackman'``
     - Blackman has better sidelobe suppression
   * - LAOS harmonics
     - ``window='hann'``, ``normalize=True``
     - Normalize for I₃/I₁ ratios
   * - Power spectral density
     - ``return_psd=True``, ``window='hann'``
     - PSD for energy distribution

Mastercurve
~~~~~~~~~~~

.. list-table:: Mastercurve Parameter Selection Guide
   :header-rows: 1
   :widths: 25 35 40

   * - Material Type
     - Recommended Settings
     - Rationale
   * - Polymer melts
     - ``method='wlf'``, ``optimize_shifts=True``
     - WLF designed for polymers; optimize for best fit
   * - Elastomers
     - ``method='wlf'``, ``C1=17.44``, ``C2=51.6``
     - Universal WLF constants (relative to T_g)
   * - Polymer solutions
     - ``method='arrhenius'``, ``optimize_shifts=True``
     - Arrhenius for simpler temperature dependence
   * - Unknown T_g
     - ``optimize_shifts=True``
     - Let optimizer find best C₁, C₂
   * - Known activation energy
     - ``method='arrhenius'``, ``E_a=<value>``
     - Use literature E_a value

Mutation Number
~~~~~~~~~~~~~~~

.. list-table:: Mutation Number Parameter Selection
   :header-rows: 1
   :widths: 25 35 40

   * - Data Quality
     - Recommended Settings
     - Rationale
   * - Clean, wide time range
     - ``extrapolate=False``
     - Data sufficient without extrapolation
   * - Limited time range
     - ``extrapolate=True``, ``extrapolation_model='power_law'``
     - Power-law extrapolation for fractional materials
   * - Exponential decay
     - ``extrapolation_model='exponential'``
     - Match classical Maxwell/Zener behavior
   * - Noisy data
     - Pre-smooth with SmoothDerivative first
     - Reduce integration errors

OWChirp
~~~~~~~

.. list-table:: OWChirp Parameter Selection Guide
   :header-rows: 1
   :widths: 25 35 40

   * - Application
     - Recommended Settings
     - Rationale
   * - LAOS harmonics
     - ``extract_harmonics=True``, ``max_harmonic=7``
     - Capture fundamental + odd harmonics
   * - Time-resolved curing
     - ``n_frequencies=200``, ``wavelet_width=6.0``
     - High resolution for evolving spectra
   * - Fast screening
     - ``n_frequencies=50``, ``extract_harmonics=True``
     - Lower resolution for speed
   * - Known fundamental
     - Specify ``fundamental_freq`` in ``extract_harmonics()``
     - Direct harmonic extraction

Smooth Derivative
~~~~~~~~~~~~~~~~~

.. list-table:: Smooth Derivative Parameter Selection
   :header-rows: 1
   :widths: 25 35 40

   * - Data Characteristics
     - Recommended Settings
     - Rationale
   * - Low noise, smooth
     - ``method='savgol'``, ``window_length=7``, ``polyorder=3``
     - Small window preserves features
   * - High noise
     - ``method='savgol'``, ``window_length=15-21``, ``polyorder=3``
     - Larger window for aggressive smoothing
   * - Very noisy
     - ``method='spline'`` or ``method='tv'``
     - Advanced methods for heavy noise
   * - Step changes
     - ``method='tv'``
     - Total Variation preserves edges
   * - Higher derivatives
     - ``polyorder >= deriv + 2``
     - Ensure polynomial order sufficient

SRFS
~~~~

.. list-table:: SRFS Parameter Selection Guide
   :header-rows: 1
   :widths: 25 35 40

   * - Material/Scenario
     - Recommended Settings
     - Rationale
   * - Concentrated emulsions
     - ``method='power_law'``, ``vertical_shift=True``
     - SGR power-law scaling expected; modulus softening under flow
   * - Unknown soft glass
     - ``method='auto'``, ``vertical_shift=True``
     - Let optimizer determine shift model
   * - Thixotropic fluid
     - ``method='empirical'``, ``vertical_shift=True``
     - Non-ideal SGR; empirical shifts more flexible
   * - Validate SGR x
     - Fit ``slope = -1/(x-1)`` to ``log(a)`` vs ``log(γ̇)``
     - Direct physics extraction from shift factors

SPP Decomposer
~~~~~~~~~~~~~~~

.. list-table:: SPP Decomposer Parameter Selection Guide
   :header-rows: 1
   :widths: 25 35 40

   * - Application
     - Recommended Settings
     - Rationale
   * - Yield stress extraction
     - ``smooth_derivatives=True``, ``window_length=21``
     - Smoothing essential for clean :math:`G'_t` features
   * - High-resolution trajectory
     - ``n_points=2000``, ``smooth_derivatives=True``
     - More points capture subtle yielding features
   * - Noisy stress signal
     - ``window_length=31-51``, ``poly_order=3``
     - Wider window for aggressive noise removal
   * - Fast screening
     - ``n_points=500``, ``smooth_derivatives=True``
     - Fewer points for quick amplitude sweep analysis


Next Steps
----------

* **Detailed transform documentation:** :doc:`/transforms/index` for individual transform pages
* **User guide:** :doc:`/user_guide/transforms` for usage patterns and examples
* **API reference:** :doc:`/api/transforms` for complete API documentation
* **Example notebooks:** 8 transform examples in ``examples/transforms/`` directory
* **Pipeline integration:** :doc:`/user_guide/pipeline_api` for fluent transform chaining

**Need a transform not listed?** Transforms are extensible via ``BaseTransform`` - see :doc:`/developer/contributing`.