diff --git a/Backend/Convenience/README.md b/Backend/Convenience/README.md new file mode 100644 index 0000000..a1a280a --- /dev/null +++ b/Backend/Convenience/README.md @@ -0,0 +1,28 @@ +# Backend/Convenience + +General-purpose utility functions used throughout the toolkit. + +## Versioning Convention + +Higher version numbers indicate more current implementations. Where both a versioned and an unversioned copy of a function exist, prefer the versioned one. + +## Functions + +- `MDSEASRead.m` — reads MDS/EAS data files into MATLAB structures +- `Probe_slice_normalization.m` — normalizes probe axis slices of 2D spectral data +- `buttonchoice.m` — UI button choice dialog helper for interactive scripts +- `findind.m` — find index utility (legacy version; prefer `findind_v2.m`) +- `findind_v2.m` — find index utility (current version) +- `findinds.m` — find multiple indices matching a set of values +- `frobnorm_v2.m` — Frobenius normalization utility; **note:** `frobnormv2l.m` in `Backend/FFT/` is the canonical version used in the FFT pipeline +- `getopts.m` — options parsing utility for handling function argument key/value pairs +- `pumpslices.m` — extracts pump frequency slices from 2D spectral data +- `savearray.m` — array save utility (legacy version; prefer `savearray_v2.m`) +- `savearray_v2.m` — array save utility (current version) +- `savestruct.m` — struct save utility (legacy version; prefer `savestruct_v2.m`) +- `savestruct_v2.m` — struct save utility (current version) +- `scanave_t2.m` — scan averaging over the t2 (waiting time) dimension +- `timeshift_v1.m` — shifts the time axis by a specified offset +- `trim2d.m` — trims a 2D array to a specified frequency or index range +- `unpackOAS.m` — unpacks OAS result structs into component arrays +- `unpackStruct.m` — generic utility to unpack fields of any struct into the caller workspace diff --git a/Backend/FFT/README.md b/Backend/FFT/README.md new file mode 100644 index 0000000..4dd11e6 --- /dev/null +++ b/Backend/FFT/README.md @@ -0,0 +1,9 @@ +# Backend/FFT + +Fourier transform routines for 2D spectroscopy data processing. + +## Functions + +- `complexFFT_v2.m` — performs a complex Fourier transform along the coherence time axis of 2D spectroscopy data +- `real_FFT_v1.m` — performs a real-valued FFT; used when only the real part of the spectrum is needed +- `frobnormv2l.m` — Frobenius normalization variant used in the FFT pipeline; this is the **canonical** frobnorm implementation (also see `frobnorm_v2.m` in `Backend/Convenience/` for a related version) diff --git a/Backend/Fitting/OAS/README.md b/Backend/Fitting/OAS/README.md index 9932c26..8bdeb90 100644 --- a/Backend/Fitting/OAS/README.md +++ b/Backend/Fitting/OAS/README.md @@ -1,3 +1,21 @@ -# Oscillation Associated Spectra +# Oscillation Associated Spectra (OAS) -Data processing scripts and functions used in Phonon-induced plasmon-exciton coupling changes probed via oscillation-associated spectra (https://doi.org/10.1063/1.5116836). Data fitting script leads an individual through all of the relevant steps to calculate the oscillation associated spectra for a given data set. +This directory contains the implementation of the Oscillation-Associated Spectra (OAS) method. OAS analysis decomposes 2D spectroscopic data into frequency-resolved maps by fitting oscillatory components at each pixel, revealing how specific vibrational or electronic modes contribute across the 2D spectrum. + +## Publication + +> Kirschner, M. S. *et al.* "Phonon-induced plasmon-exciton coupling changes probed via oscillation-associated spectra." *J. Chem. Phys.* (2019). https://doi.org/10.1063/1.5116836 + +## Files + +- `OscillationAssociatedSpectrum.m` — main OAS computation function; orchestrates the full OAS pipeline for a given dataset +- `DataFittingScript_test.m` — **development artifact / internal test script; not intended for end-user use** +- `DetermineIndices.m` — determines the frequency and time indices relevant to the analysis window +- `PhaseMean.m` — computes the mean phase across ensemble or repetitions +- `ReferencePhase.m` — establishes a reference phase used to align oscillatory components +- `SingleFrequencyFT.m` — performs a single-frequency Fourier transform at a specified frequency +- `itcmp.m` — iterative component fitting routine; fits multiple oscillatory components simultaneously +- `itcmpEval.m` — evaluation function called during iterative fitting to assess residuals +- `itcmpFilterOscillations.m` — filters oscillatory components within the iterative fitting loop +- `itcmpParamConversion.m` — converts fitted parameters between internal units and physical units +- `svdecon.m` — SVD decomposition helper used to reduce dimensionality before fitting diff --git a/Backend/Fitting/README.md b/Backend/Fitting/README.md new file mode 100644 index 0000000..e37964f --- /dev/null +++ b/Backend/Fitting/README.md @@ -0,0 +1,25 @@ +# Backend/Fitting + +Functions for population dynamics fitting, LPSVD analysis, and oscillation-associated spectra. See the [`OAS/`](OAS/) subdirectory for the self-contained oscillation-associated spectra module. + +## Functions + +- `MDSDimRed.m` — dimensionality reduction for MDS data prior to fitting +- `OAS.m` — entry point for oscillation-associated spectra analysis (delegates to the `OAS/` subdirectory for full implementation) +- `casepoptsubt.m` — case-based population subtraction dispatcher +- `complexbeatproc.m` — complex beat signal processing for oscillatory components +- `cutresQB.m` — cuts residuals for quantum beat analysis +- `cuttimes.m` — trims data to a specified time range +- `lpsvd_range.m` — runs LPSVD fitting over a defined frequency or time range +- `lpsvd_runStruct.m` — runs LPSVD using a parameter struct for batch processing +- `lpsvd_zoom.m` — LPSVD fitting with zoom windowing for targeted frequency regions +- `lpsvdrun.m` — core LPSVD runner; called by the higher-level LPSVD wrappers +- `pop_fit_v2.m` — population dynamics fitting (current version) +- `popsubt_v1.m` — population subtraction (current version) +- `popsubtsigs_v1.m` — population subtraction applied to multiple signals simultaneously +- `subtlog.m` — logs subtraction operations for reproducibility +- `subtpred.m` — generates subtraction predictions for comparison with data + +## Subdirectory + +- [`OAS/`](OAS/) — self-contained module for oscillation-associated spectra analysis diff --git a/Backend/Inpaint_nans/README.md b/Backend/Inpaint_nans/README.md new file mode 100644 index 0000000..73220c2 --- /dev/null +++ b/Backend/Inpaint_nans/README.md @@ -0,0 +1,13 @@ +# Backend/Inpaint_nans + +This directory contains the third-party `inpaint_nans` toolbox by John D'Errico, used for NaN interpolation in 2D spectral data. + +## Attribution + +**Author:** John D'Errico +**Source:** MATLAB File Exchange — https://www.mathworks.com/matlabcentral/fileexchange/4551 +**License:** See [`license.txt`](license.txt) for the original BSD-style license terms. + +## Contents + +The toolbox is included unmodified from its original distribution. The double-nested folder structure (`Inpaint_nans/Inpaint_nans/`) is a known artifact of the original toolbox package. The `demo/`, `doc/`, and `test/` subdirectories, as well as the demo images (`garden50.jpg`, `monet_adresse.jpg`), are part of the original distribution and are included as-is. diff --git a/Backend/Loading/README.md b/Backend/Loading/README.md new file mode 100644 index 0000000..7fad8e0 --- /dev/null +++ b/Backend/Loading/README.md @@ -0,0 +1,10 @@ +# Backend/Loading + +Functions for loading and configuring Phasetech QuickControl data. + +> **Note:** The `data` and `dataworkup` directory paths in `AnalysisHub.mlx` must be updated to match the locations on your local machine before use. + +## Functions + +- `MDSload.m` — main data loading function; reads Phasetech QuickControl output files and organizes the results into MATLAB structs for downstream processing +- `mdsparams.m` — defines and returns parameter structs that configure the MDS data loading process (scan parameters, frequency axes, etc.) diff --git a/Backend/Plotting/README.md b/Backend/Plotting/README.md new file mode 100644 index 0000000..ed2e582 --- /dev/null +++ b/Backend/Plotting/README.md @@ -0,0 +1,41 @@ +# Backend/Plotting + +Functions for visualizing 2D spectral data, frequency maps, beat signals, and related diagnostics. + +## Core 2D Plotting + +- `MDplot.m` — basic 2D spectral plot (legacy version; prefer `MDplot_v2.m`) +- `MDplot_v2.m` — 2D spectral plot with improved display options (current version) +- `MDplotmv.m` — multi-view 2D spectral plot for comparing multiple spectra side-by-side +- `MDfreqplot.m` — frequency-domain 2D plot +- `plot2Dt.m` — 2D plot in the time domain +- `plot2Dw.m` — 2D plot in the frequency domain; the most feature-rich 2D plotting function + +## Beat / Oscillation Visualization + +- `beatcontours_exp.m` — plots beat signal contours extracted from experimental data +- `qbexam.m` — quantum beat examination plot for inspecting oscillatory residuals + +## Normalization + +- `norm2DES.m` — normalizes 2DES spectra for display +- `norm2DESfreq.m` — normalizes 2DES spectra in the frequency domain +- `normdim.m` — normalizes an array along a specified dimension + +## Smoothing + +- `smooth_2D_v3.m` — 2D smoothing (legacy version; prefer `smooth_2D_v4.m`) +- `smooth_2D_v4.m` — 2D smoothing (current version) +- `smoothcase.m` — case-based smoothing dispatcher for time-domain data +- `smoothfreqcase.m` — frequency-domain smoothing dispatcher (legacy version; prefer `smoothfreqcase_v2.m`) +- `smoothfreqcase_v2.m` — frequency-domain smoothing dispatcher (current version) + +## Utilities + +- `NanReplace.m` — replaces NaN values with a fill value to avoid display artifacts +- `ButtonDownFcn2DES_live.m` — interactive mouse click callback for live 2DES plots in `AnalysisHub.mlx` +- `mouseMove.m` — mouse movement callback used in interactive spectral plots +- `cmap2d.m` — 2D colormap utility for diverging spectral color scales +- `plot_areaerrorbar.m` — plots area-style shaded error bars around a trace +- `progressbar.m` — progress bar display utility for long-running loops +- `genericplot.m` — minimal generic plot wrapper for quick visualization diff --git a/Backend/SignalGeneration/README.md b/Backend/SignalGeneration/README.md new file mode 100644 index 0000000..dfb12b6 --- /dev/null +++ b/Backend/SignalGeneration/README.md @@ -0,0 +1,10 @@ +# Backend/SignalGeneration + +Functions for computing 2D spectroscopic signals from raw experimental data. + +## Functions + +- `abs4framev1.m` — generates absorbance signals using the 4-frame phase-cycling scheme +- `absprocv1.m` — processes absorbance signals (background correction, normalization steps) +- `gendeltaA.m` — generates differential absorbance (ΔA) signals from raw frames +- `rnr4framev4.m` — computes rephasing and non-rephasing 2D signals using the 4-frame phase-cycling approach (current version) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d6387e9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +### Changed +- Documentation and organization cleanup: rewrote root `README.md`, fixed `CITATION.cff` metadata, added per-module READMEs throughout `Backend/`, added `CHANGELOG.md` and `THIRD_PARTY_LICENSES.md`, and removed empty `OASlog.txt`. + +## [v1.0] — 2022-06-27 + +### Added +- Initial public release of CMDS-Experiment-Toolkit. +- `AnalysisHub.mlx` — main MATLAB Live Script analysis hub. +- `Backend/` — full set of supporting modules: `Convenience`, `FFT`, `Fitting` (including OAS), `Inpaint_nans`, `Loading`, `Plotting`, and `SignalGeneration`. +- `CITATION.cff` — citation metadata. diff --git a/CITATION.cff b/CITATION.cff index 1e314ed..b79e3a8 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,7 +1,10 @@ -cff-version: 1.1.0 +cff-version: 1.2.0 message: "If you use this software, please cite it as below." -authors: Jonathan Schultz -orcid: https://orcid.org/0000-0002-3386-5460 -title: jonathanschultzNU/MDS_EXP: v1.0 +authors: + - family-names: Schultz + given-names: Jonathan + orcid: https://orcid.org/0000-0002-3386-5460 +title: "CMDS-Experiment-Toolkit" version: v1.0 date-released: 2022-06-27 +repository-code: https://github.com/jonathanschultzNU/CMDS-Experiment-Toolkit diff --git a/OASlog.txt b/OASlog.txt deleted file mode 100644 index e69de29..0000000 diff --git a/README.md b/README.md index 1f7a986..458ce7b 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,59 @@ -# MDS_EXP +# CMDS-Experiment-Toolkit -MDS_EXP is a software package designed to process 1D and 2D data from Phasetech's -QuickControl outputs (phasetechspectroscopy.com/products/quickcontrol/) +CMDS-Experiment-Toolkit is a MATLAB software package for processing 1D and 2D spectroscopy data from [Phasetech QuickControl](https://phasetechspectroscopy.com/products/quickcontrol/) outputs. -The main code is AnalysisHub.mlx, which is written such that the user can navigate the hub -section-by-section (rather than running the entire code from start to finish). +## Prerequisites -The package comes with sample 2DES data that are loaded by default in the MDS code if the -user does not change any of the user controls. However, the location of the data and -dataworkup directories must be updated since they are specific to the user's computer. +- **MATLAB** — the main entry point (`AnalysisHub.mlx`) is a MATLAB Live Script (`.mlx` format) +- **Signal Processing Toolbox** — required for FFT and filtering operations used throughout the toolkit -Disclaimer: The MDS code has checkpoints where data can be saved for reloading at a -later time (it takes a long time to load data that hasn't been processed before). If -the sample data are processed without any changes to the controls, the total analysis -will take up approximately 2 GB of memory. +## Setup + +1. Add the `Backend/` folder tree to the MATLAB path (use *Set Path* or `addpath(genpath('Backend'))` from the repository root). +2. Open `AnalysisHub.mlx` in MATLAB. +3. Update the `data` and `dataworkup` directory paths near the top of `AnalysisHub.mlx` to match the locations on your local machine. + +## Usage + +`AnalysisHub.mlx` is organized into self-contained sections that can be run individually rather than executing the entire script from start to finish. The typical analysis workflow proceeds as follows: + +1. **Loading** — reads Phasetech QuickControl output files into MATLAB structs via `MDSload` +2. **Signal Generation** — computes rephasing/non-rephasing and absorbance signals +3. **FFT** — applies complex or real FFT along the coherence time axis +4. **Plotting** — visualizes 2D spectra, frequency-domain maps, and beat signals +5. **Fitting** — population subtraction, LPSVD fitting, and oscillation-associated spectra (OAS) analysis + +> **Checkpoints:** The toolkit includes checkpoint saves so that processed data can be reloaded in a later session without re-running expensive steps from scratch. + +> **Memory:** Processing the full sample dataset requires approximately **2 GB** of memory. + +## Directory Structure + +``` +CMDS-Experiment-Toolkit/ +├── AnalysisHub.mlx # Main analysis entry point (MATLAB Live Script) +├── CITATION.cff # Citation metadata +├── CHANGELOG.md # Version history +├── THIRD_PARTY_LICENSES.md # Third-party attributions +└── Backend/ + ├── Convenience/ # General-purpose utility functions + ├── FFT/ # Fourier transform routines + ├── Fitting/ # Population fitting, LPSVD, and OAS analysis + │ └── OAS/ # Oscillation-Associated Spectra module + ├── Inpaint_nans/ # Third-party NaN interpolation toolbox + ├── Loading/ # Data loading and parameter configuration + ├── Plotting/ # 2D spectral plotting and visualization + └── SignalGeneration/ # Signal computation routines +``` + +See the `README.md` in each `Backend/` subdirectory for per-function documentation. + +## Associated Publication (OAS) + +The oscillation-associated spectra (OAS) module is described in: + +> Kirschner, M. S. *et al.* "Phonon-induced plasmon-exciton coupling changes probed via oscillation-associated spectra." *J. Chem. Phys.* (2019). https://doi.org/10.1063/1.5116836 + +## Citing This Work + +If you use this toolkit, please cite it using the metadata in [`CITATION.cff`](CITATION.cff). diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md new file mode 100644 index 0000000..10aa65b --- /dev/null +++ b/THIRD_PARTY_LICENSES.md @@ -0,0 +1,15 @@ +# Third-Party Licenses + +This project includes the following third-party software. + +--- + +## inpaint_nans + +**Author:** John D'Errico +**Source:** MATLAB File Exchange — https://www.mathworks.com/matlabcentral/fileexchange/4551 +**Location in this repository:** `Backend/Inpaint_nans/` + +`inpaint_nans` is used for NaN interpolation in 2D spectral data. It is included here unmodified from its original distribution. + +The license for this toolbox can be found at [`Backend/Inpaint_nans/license.txt`](Backend/Inpaint_nans/license.txt).