spark-spectroscopy 2.0.0__tar.gz

spark_spectroscopy-2.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: spark-spectroscopy
+Version: 2.0.0
+Summary: Professional Python suite for ultrafast transient absorption and fluorescence spectroscopy analysis.
+Author-email: Alejandro Serrano Capote <tu.correo@example.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.6.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: PyQt5>=5.15.0
+Requires-Dist: h5py>=3.0.0

spark_spectroscopy-2.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spark-spectroscopy"
+version = "2.0.0"
+description = "Professional Python suite for ultrafast transient absorption and fluorescence spectroscopy analysis."
+readme = "README.md"
+authors = [
+    { name = "Alejandro Serrano Capote", email = "tu.correo@example.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "numpy>=1.20.0",
+    "scipy>=1.6.0",
+    "matplotlib>=3.3.0",
+    "PyQt5>=5.15.0",
+    "h5py>=3.0.0"
+]
+
+[project.scripts]
+spark-gui = "spark.main:main"  
+
+[tool.setuptools.packages.find]
+include = ["spark", "spark.*"]

spark_spectroscopy-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spark_spectroscopy-2.0.0/spark/__init__.py

@@ -0,0 +1,4 @@
+
+
+
+

spark_spectroscopy-2.0.0/spark/core/__init__.py

@@ -0,0 +1,4 @@
+
+
+
+

spark_spectroscopy-2.0.0/spark/core/core_analysis.py

@@ -0,0 +1,290 @@
+# core_analysis.py
+import numpy as np
+import pandas as pd
+from scipy.interpolate import interp1d
+from scipy.optimize import curve_fit
+
+
+
+# ---------------------------------------------------------------------
+# Models and Correction Functions
+# ---------------------------------------------------------------------
+
+def eV_a_nm(E_eV):
+    """
+    Converts energy in electron-volts (eV) to wavelength in nanometers (nm).
+    
+    Args:
+        E_eV (numpy.ndarray or float): Energy in eV.
+
+    Returns:
+        numpy.ndarray or float: Corresponding wavelength in nm.
+    """
+    # Prevent division by zero by temporarily replacing 0 with 1
+    E_eV_safe = np.where(E_eV == 0, 1, E_eV)
+    return 1239.841984 / E_eV_safe
+
+
+def t0_model(w, a, b, c, d):
+    """
+    Proposed non-linear model for time-zero (t0) dispersion correction.
+    
+    Formula: t0 = a * sqrt((b*w^2 - 1) / (c*w^2 - 1)) + d
+    
+    Args:
+        w (array-like): Wavelength points.
+        a, b, c, d (float): Fitting parameters.
+
+    Returns:
+        numpy.ndarray: Computed t0 values. Returns NaN where the expression is mathematically invalid.
+    """
+    w = np.asarray(w, dtype=float)
+    num = b * w**2 - 1.0
+    den = c * w**2 - 1.0
+    
+    out = np.full_like(w, np.nan, dtype=float)
+    
+    # Suppress warnings for expected invalid operations (like negative roots or division by zero)
+    with np.errstate(divide='ignore', invalid='ignore'):
+        ratio = num / den
+        valid = (den != 0) & (ratio >= 0)
+        out[valid] = a * np.sqrt(ratio[valid]) + d
+        
+    return out
+
+
+def apply_t0_correction_poly(popt, WL, TD, data):
+    """
+    Applies a polynomial time-zero (t0) correction to the dataset.
+    
+    Args:
+        popt (array-like): Polynomial coefficients (must be of length 5, degree 4).
+        WL (numpy.ndarray): Wavelength array.
+        TD (numpy.ndarray): Time Delay array.
+        data (numpy.ndarray): 2D array of the main data matrix.
+
+    Returns:
+        tuple: A tuple containing:
+            - corrected (numpy.ndarray): The t0-corrected 2D data matrix.
+            - t0_lambda (numpy.ndarray): The calculated t0 offset for each wavelength.
+    """
+    coeffs = np.asarray(popt)
+    if coeffs.size != 5:
+        raise ValueError("Polynomial coefficients must have length 5.")
+        
+    t0_lambda = np.polyval(coeffs, WL)
+    corrected = np.zeros_like(data)
+    
+    for i, wl in enumerate(WL):
+        delay_corr = TD - t0_lambda[i]
+        
+        # SOLUTION: Strictly use 0.0 to fill out-of-bounds data to prevent extrapolation artifacts
+        f = interp1d(delay_corr, data[i, :], kind='linear', bounds_error=False, fill_value=0.0)
+        corrected[i, :] = f(TD)
+        
+    return corrected, t0_lambda
+
+
+def apply_t0_correction_nonlinear(popt, WL, TD, data):
+    """
+    Applies a non-linear time-zero (t0) correction to the dataset using `t0_model`.
+    
+    Args:
+        popt (list or array-like): Optimized parameters [a, b, c, d] for the non-linear model.
+        WL (numpy.ndarray): Wavelength array.
+        TD (numpy.ndarray): Time Delay array.
+        data (numpy.ndarray): 2D array of the main data matrix.
+
+    Returns:
+        tuple: A tuple containing:
+            - corrected (numpy.ndarray): The t0-corrected 2D data matrix.
+            - t0_lambda (numpy.ndarray): The calculated t0 offset for each wavelength.
+    """
+    t0_lambda = t0_model(WL, *popt)
+    corrected = data.copy()
+    
+    for i, t0_val in enumerate(t0_lambda):
+        if np.isfinite(t0_val):
+            delay_corr = TD - t0_val
+            
+            # SOLUTION: Strictly use 0.0 to fill out-of-bounds data to prevent extrapolation artifacts
+            f = interp1d(delay_corr, data[i, :], kind='linear', bounds_error=False, fill_value=0.0)
+            corrected[i, :] = f(TD)
+        else:
+            # If the calculated t0 is not finite, leave the data uncorrected for that wavelength
+            corrected[i, :] = data[i, :]
+            
+    return corrected, t0_lambda
+
+
+def fit_t0(w_points, t0_points, WL, TD, data, min_points_nonlinear=4, mode='auto'):
+    """
+    Fits time-zero (t0) dispersion based on user-selected points (w_points, t0_points).
+    
+    The function attempts to fit the non-linear model (`t0_model`) if there are enough points.
+    If the non-linear fit fails or lacks sufficient points, it falls back to a polynomial 
+    fit of up to degree 4.
+
+    Args:
+        w_points (array-like): Wavelengths (nm) of the chosen data points.
+        t0_points (array-like): Corresponding delays (ps) of the chosen data points.
+        WL (numpy.ndarray): Full wavelength array (from read_csv_file or load_from_paths).
+        TD (numpy.ndarray): Full time delay array.
+        data (numpy.ndarray): Full 2D data matrix.
+        min_points_nonlinear (int): Minimum number of points required to attempt the non-linear model. Defaults to 4.
+        mode (str): Fitting mode strategy. 'auto' (default), 'nonlinear' (force non-linear), or 'poly' (force polynomial).
+
+    Returns:
+        dict: A dictionary containing the fitting results:
+            - 'method': String indicating the method used ('nonlinear' or 'polyX').
+            - 'popt': The optimized coefficients/parameters.
+            - 'fit_x': High-resolution X array used for plotting the fit line.
+            - 'fit_y': High-resolution Y array representing the fit curve.
+            - 'corrected': The newly corrected 2D data matrix.
+            - 't0_lambda': The calculated t0 vector for every wavelength in WL.
+    """
+    w = np.asarray(w_points, dtype=float)
+    t0 = np.asarray(t0_points, dtype=float)
+
+    if w.size < 2:
+        raise ValueError("At least 2 points are required for fitting (ideally >= 4 for the non-linear model).")
+
+    # High-resolution array strictly for smooth plotting of the fit curve
+    fit_x = np.linspace(np.min(w), np.max(w), 400)
+
+    # =======================================================
+    # --- Forced Mode: Polynomial ---------------------------
+    # =======================================================
+    if mode == 'poly':
+        if w.size < 5:
+            deg = min(4, max(1, w.size - 1))
+        else:
+            deg = 4
+            
+        coeffs = np.polyfit(w, t0, deg)
+        
+        # Ensure coefficients array is strictly length 5 (pad with leading zeros)
+        if coeffs.size < 5:
+            coeffs = np.concatenate([np.zeros(5 - coeffs.size), coeffs])
+            
+        fit_y = np.polyval(coeffs, fit_x)
+        corrected, t0_lambda = apply_t0_correction_poly(coeffs, WL, TD, data)
+        
+        return {
+            'method': f'poly{deg}',
+            'popt': coeffs,
+            'fit_x': fit_x,
+            'fit_y': fit_y,
+            'corrected': corrected,
+            't0_lambda': t0_lambda
+        }
+
+    # =======================================================
+    # --- Forced Mode: Non-Linear ---------------------------
+    # =======================================================
+    if mode == 'nonlinear':
+        try:
+            wmin = np.min(w)
+            # Initial parameter estimates (p0)
+            a0 = (np.nanmax(t0) - np.nanmin(t0)) / 2.0 if np.isfinite(t0).any() else 0.0
+            d0 = np.nanmedian(t0)
+            min_required = 1.0 / (wmin**2) if wmin != 0 else 1e-8
+            b0 = min_required * 1.1
+            c0 = min_required * 1.2
+            
+            p0 = [a0, b0, c0, d0]
+            
+            # Bound constraints to ensure stability
+            bounds = ([-np.inf, min_required, min_required, -np.inf],
+                      [np.inf, np.inf, np.inf, np.inf])
+                      
+            popt, pcov = curve_fit(
+                t0_model, w, t0,
+                p0=p0, bounds=bounds,
+                maxfev=20000, method="trf"
+            )
+            
+            fit_y = t0_model(fit_x, *popt)
+            corrected, t0_lambda = apply_t0_correction_nonlinear(popt, WL, TD, data)
+            
+            return {
+                'method': 'nonlinear',
+                'popt': popt,
+                'fit_x': fit_x,
+                'fit_y': fit_y,
+                'corrected': corrected,
+                't0_lambda': t0_lambda
+            }
+        except Exception as e:
+            raise RuntimeError(f"Non-linear fit failed: {e}")
+
+    # =======================================================
+    # --- Auto Mode (Original Behavior) ---------------------
+    # =======================================================
+    try_nl = (w.size >= min_points_nonlinear)
+    
+    if try_nl:
+        try:
+            wmin = np.min(w)
+            # Initial parameter estimates (p0)
+            a0 = (np.nanmax(t0) - np.nanmin(t0)) / 2.0 if np.isfinite(t0).any() else 0.0
+            d0 = np.nanmedian(t0)
+            min_required = 1.0 / (wmin**2) if wmin != 0 else 1e-8
+            b0 = min_required * 1.1
+            c0 = min_required * 1.2
+            
+            p0 = [a0, b0, c0, d0]
+            
+            # Bound constraints to ensure stability
+            bounds = ([-np.inf, min_required, min_required, -np.inf],
+                      [np.inf, np.inf, np.inf, np.inf])
+                      
+            popt, pcov = curve_fit(
+                t0_model, w, t0,
+                p0=p0, bounds=bounds,
+                maxfev=20000, method="trf"
+            )
+            
+            fit_y = t0_model(fit_x, *popt)
+            
+            # Check if the curve is stable before accepting it
+            if np.all(np.isfinite(fit_y)):
+                corrected, t0_lambda = apply_t0_correction_nonlinear(popt, WL, TD, data)
+                return {
+                    'method': 'nonlinear',
+                    'popt': popt,
+                    'fit_x': fit_x,
+                    'fit_y': fit_y,
+                    'corrected': corrected,
+                    't0_lambda': t0_lambda
+                }
+        except Exception:
+            pass  # If the non-linear fit fails, proceed to polynomial fallback
+
+    # --- Polynomial Fallback ---
+    # Determine the degree based on the number of available points
+    if w.size < 5:
+        deg = min(3, max(1, w.size - 1))
+    else:
+        deg = 4
+
+    coeffs = np.polyfit(w, t0, deg)
+    
+    # Ensure coefficients array is strictly length 5
+    if coeffs.size < 5:
+        coeffs = np.concatenate([np.zeros(5 - coeffs.size), coeffs])
+        
+    fit_y = np.polyval(coeffs, fit_x)
+    corrected, t0_lambda = apply_t0_correction_poly(coeffs, WL, TD, data)
+    
+    return {
+        'method': f'poly{deg}',
+        'popt': coeffs,
+        'fit_x': fit_x,
+        'fit_y': fit_y,
+        'corrected': corrected,
+        't0_lambda': t0_lambda
+    }
+
+
+

spark_spectroscopy-2.0.0/spark/core/diagnostics.py

@@ -0,0 +1,184 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+
+def analyze(result, param_names=None):
+    """
+    Imprime un resumen profesional con los resultados del ajuste y 
+    las estadísticas del motor de optimización (SciPy).
+    """
+    print("="*50)
+    print("               SPARK FIT DIAGNOSTICS")
+    print("="*50)
+    
+    # 1. Estadísticas de convergencia
+    res = result.scipy_res
+    print("[Convergence Status]")
+    print(f" Message: {res.message}")
+    print(f" Success: {res.success}")
+    print(f" Cost (Sum of Squares): {res.cost:.4e}")
+    print(f" Function Evaluations:  {res.nfev}")
+    print("-" * 50)
+    
+    # 2. Parámetros optimizados
+    print("[Optimized Parameters]")
+    if param_names is None:
+        # Nombres por defecto si no se especifican
+        param_names = ["w (IRF FWHM)", "t0 (Time Zero)"] + [f"Tau {i+1}" for i in range(len(result.x)-2)]
+        
+    for name, val in zip(param_names, result.x):
+        print(f" {name:<15}: {val:>10.4f}")
+    print("="*50)
+
+
+def plot_spectra(dataset, target_times):
+    """
+    Dibuja los espectros a los tiempos exactos (o más cercanos) solicitados.
+    target_times: lista de tiempos en ps, ej: [0.1, 1.0, 10.0]
+    """
+    plt.figure(figsize=(8, 5))
+    
+    for t in target_times:
+        # Encontrar el índice del tiempo más cercano en el dataset
+        idx = np.abs(dataset.td - t).argmin()
+        actual_t = dataset.td[idx]
+        
+        plt.plot(dataset.wl, dataset.data[:, idx], label=f'{actual_t:.2f} ps')
+        
+    plt.axhline(0, color='black', linestyle='--', linewidth=0.8)
+    plt.xlabel("Wavelength (nm)")
+    plt.ylabel("ΔA")
+    plt.title("Transient Spectra")
+    plt.legend()
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_kinetics_fit(dataset, result, target_wavelengths, use_symlog=True):
+    """
+    Dibuja los datos experimentales (puntos) y el ajuste (línea) 
+    para las longitudes de onda solicitadas.
+    target_wavelengths: lista de wls en nm, ej: [450, 500, 600]
+    """
+    plt.figure(figsize=(8, 5))
+    
+    for w in target_wavelengths:
+        # Encontrar el índice de la longitud de onda más cercana
+        idx = np.abs(dataset.wl - w).argmin()
+        actual_w = dataset.wl[idx]
+        
+        # Puntos experimentales (scatter)
+        p = plt.plot(dataset.td, dataset.data[idx, :], 'o', markersize=4, alpha=0.6, label=f'Data {actual_w:.1f} nm')
+        color = p[0].get_color()
+        
+        # Línea del Fit
+        plt.plot(dataset.td, result.fitres[idx, :], '-', color=color, linewidth=2, label=f'Fit {actual_w:.1f} nm')
+        
+    plt.axhline(0, color='black', linestyle='--', linewidth=0.8)
+    
+    # Escala logarítmica para los tiempos (muy útil en espectroscopía)
+    if use_symlog:
+        plt.xscale('symlog', linthresh=1.0) 
+        
+    plt.xlabel("Delay Time (ps)")
+    plt.ylabel("ΔA")
+    plt.title("Kinetics & Global Fit")
+    plt.legend()
+    plt.tight_layout()
+    plt.show()
+
+def plot_associated_spectra(dataset, result, num_species=None):
+    """
+    Dibuja los espectros asociados (DAS o SAS) extraídos por el ajuste VarPro.
+    Extrae automáticamente las constantes de tiempo (taus) para la leyenda.
+    """
+    plt.figure(figsize=(8, 5))
+    
+    # Si no le pasas el número de especies, lo deduce de los parámetros
+    if num_species is None:
+        num_species = len(result.x) - 2 # Restamos w y t0
+        
+    taus = result.x[2 : 2 + num_species]
+    
+    # Dibujamos las especies cinéticas
+    for i in range(num_species):
+        plt.plot(dataset.wl, result.amplitudes[i, :], linewidth=2, 
+                 label=f'Especie {i+1} ($\\tau$ = {taus[i]:.2f} ps)')
+        
+    # Si la matriz de amplitudes tiene más filas que especies, es que hay un Artefacto Coherente
+    if result.amplitudes.shape[0] > num_species:
+        # Dibujamos el artefacto (o sus derivadas) con un estilo diferente para no confundir
+        plt.plot(dataset.wl, result.amplitudes[num_species, :], 
+                 linestyle=':', color='gray', label='Coherent Artifact')
+        
+    plt.axhline(0, color='black', linestyle='--', linewidth=0.8)
+    plt.xlabel("Wavelength (nm)")
+    plt.ylabel("Amplitud ($\\Delta$A)")
+    plt.title("Associated Spectra (DAS / SAS)")
+    plt.legend()
+    plt.tight_layout()
+    plt.show()
+    
+def plot_single_map(dataset, title="2D Map", use_symlog=True):
+    """
+    Dibuja un único mapa 2D a partir de un objeto SpectroscopyDataset.
+    Ideal para visualizar el archivo crudo o el efecto del pre-procesado.
+    """
+    plt.figure(figsize=(8, 5))
+    
+    # Centramos el colorbar en 0 para visualizar bien las absorciones/emisiones
+    max_val = np.nanmax(np.abs(dataset.data))
+    norm = mcolors.TwoSlopeNorm(vmin=-max_val, vcenter=0, vmax=max_val)
+    
+    # Usamos pcolormesh que es ideal para ejes no lineales
+    im = plt.pcolormesh(dataset.td, dataset.wl, dataset.data, 
+                        cmap='jet', norm=norm, shading='nearest')
+    
+    if use_symlog:
+        plt.gca().set_xscale('symlog', linthresh=1.0)
+        
+    plt.xlabel("Delay Time (ps)")
+    plt.ylabel("Wavelength (nm)")
+    plt.title(title)
+    plt.colorbar(im, label="Amplitud ($\\Delta$A)")
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_fit_maps(dataset, result, use_symlog=True, vmin=None, vmax=None):
+    """
+    Dibuja un panel 1x3 comparando: Datos, Ajuste Global y Matriz de Residuales.
+    """
+    fig, axes = plt.subplots(1, 3, figsize=(15, 5), sharex=True, sharey=True)
+    
+    # Si no se dan límites, calculamos la escala simétrica respecto al máximo de los datos
+    if vmin is None or vmax is None:
+        max_val = np.nanmax(np.abs(dataset.data))
+        vmin, vmax = -max_val, max_val
+        
+    norm = mcolors.TwoSlopeNorm(vmin=vmin, vcenter=0, vmax=vmax)
+    cmap = 'jet' 
+    
+    # 1. Datos experimentales
+    axes[0].pcolormesh(dataset.td, dataset.wl, dataset.data, cmap=cmap, norm=norm, shading='nearest')
+    axes[0].set_title("Processed Data")
+    
+    # 2. Superficie ajustada (Fit)
+    axes[1].pcolormesh(dataset.td, dataset.wl, result.fitres, cmap=cmap, norm=norm, shading='nearest')
+    axes[1].set_title("Global Fit")
+    
+    # 3. Residuales (Error)
+    im = axes[2].pcolormesh(dataset.td, dataset.wl, result.resid, cmap=cmap, norm=norm, shading='nearest')
+    axes[2].set_title("Residuals")
+    
+    for ax in axes:
+        if use_symlog:
+            ax.set_xscale('symlog', linthresh=1.0)
+        ax.set_xlabel("Delay Time (ps)")
+        
+    axes[0].set_ylabel("Wavelength (nm)")
+    
+    # Añadir una única barra de color compartida para todo el panel
+    fig.colorbar(im, ax=axes.ravel().tolist(), label="Amplitud ($\\Delta$A)", aspect=30, pad=0.02)
+    
+    plt.show()