v1.2.0

1D to 2D Map Builder (Spectroscopy / XFEL)

This standalone module is part of the Ultrafast Spectroscopy Analyzer suite.
It provides a graphical tool to reconstruct 2D spectral maps (Intensity vs. Time vs. Energy/Wavelength) starting from individual kinetic timescans (1D traces).

The main goal of this tool is to bridge the gap between raw experimental timescans and global analysis workflows, allowing users to generate clean, structured 2D datasets suitable for global fitting, SVD analysis, or further post-processing.

Originally developed for XFEL (X-Ray Free Electron Laser) and ultrafast transient absorption experiments, the module is fully general and can be adapted to any spectroscopy data stored in .npy dictionary format.

---

Scientific Motivation

In many ultrafast experiments, data is acquired as a collection of independent kinetic traces, each corresponding to a different probe energy or wavelength.
However, most global analysis methods require a 2D matrix (time × energy).

This tool reconstructs a consistent 2D map by stacking and validating multiple 1D timescans, ensuring correct alignment in both time and energy dimensions.

---

How It Works

1. Input Data

• Each kinetic scan is provided as a .npy file containing a Python dictionary.
• The dictionary must include:
  • A time-delay vector
  • Either:
    • Separate Excited State (ES) and Ground State (GS) arrays
    • or a direct signal (difference, intensity, etc.)

2. Signal Reconstruction

• If a Direct Signal Key is provided, that signal is used directly.
• Otherwise, the signal is computed internally as:

3. Matrix Assembly

• Each kinetic trace is stacked column-wise to build a 2D matrix:
  Signal = ES − GS

3. Matrix Assembly

• Each kinetic trace is stacked column-wise to build a 2D matrix:
  M(time, energy)

• NaN values in the time axis are automatically filtered.

• A consistency check ensures that the number of energy points matches the number of loaded files.

4. Visualization

• The reconstructed matrix is displayed as a 2D heatmap using matplotlib.
• Default colormap: RdBu_r, suitable for differential spectroscopy data.

5. Export

• The final dataset is saved as a .npy dictionary containing:
  • data_c: 2D intensity matrix (energy × time)
  • WL: Energy or wavelength vector
  • TD: Time-delay vector

This output format is ready for global fitting or further numerical analysis.

---

Graphical Interface Overview

Mapping & Scale Configuration

• Fully configurable dictionary keys:
  • Time
  • Excited State (ES)
  • Ground State (GS)
  • Optional Direct Signal
• A time scale factor allows on-the-fly unit conversion (e.g. fs → ps).

Energy / Wavelength Vector

• Manual input or import from .txt, .csv, or .dat files.
• Automatic validation against the number of loaded kinetic files.

Kinetic Files

• Batch loading of .npy files.
• Automatic sorting.
• Live mismatch warnings if file and energy counts differ.

Unit Auto-Detection

A statistical analysis of the time-delay vector estimates whether the data is in:

• Femtoseconds (fs)
• Picoseconds (ps)

This helps prevent silent unit mismatches before global analysis.

---

Key Features

• Flexible Data Structure
  No hardcoded variable names — compatible with any .npy dictionary layout.

• Robust Validation

  • Energy vs. file count consistency checks
  • NaN filtering
  • Explicit error messages for missing keys

• Global-Fit Ready Output
  Export format designed to integrate directly into global fitting pipelines.

---

Typical Use Case

Acquire multiple kinetic scans at different probe energies or wavelengths.

Store each scan as a .npy dictionary.

Load files and the energy vector into the GUI.

Generate and inspect the 2D spectral map.

Export the dataset for global fitting or SVD analysis.

v1.1.0 SVD Diagnosis & Advanced Global Analysis

What's New in this Release

This update introduces powerful mathematical tools and visualization features to transform your ultrafast spectroscopy workflow.

Key New Features

• SVD Analysis: Integrated Singular Value Decomposition for intelligent noise reduction and matrix rank determination (Scree Plot).
• Advanced Global Fit: Added support for both Parallel (DAS) and Sequential (SAS) models using Bateman Equations.
• 3D Surface Explorer: New interactive 3D rendering for global data trend identification.
• Enhanced UI: Interactive Trace Checker with dual Linear/Logarithmic views and real-time residual mapping.

Improvements & Fixes

• Improved data preprocessing (baseline correction, spectral/temporal binning, and cropping).
• More robust error estimation using Jacobian-based confidence intervals.