Docs & metadata cleanup: rename project, add module READMEs, fix CITATION.cff

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

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)

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
+
+> Schultz, J. *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

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

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.

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.)

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

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)

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.

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

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:
+
+> Schultz, J. *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).

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).