***************************************************************************************************************************************** ***********************User manual for Raman Substrate Analysis GUI v1.3 (filename:RamanSubstrateAnalysisGUI_v1_3)********************** ***************************************************************************************************************************************** 1. Purpose of the script This script is intended for Raman substrate evaluation in two different workflows: A. Control-only mode (COM) Used for direct assessment of substrate-intrinsic background by comparing each substrate spectrum against a baseline spectrum. B. Paired signal-to-parasite ratio mode (SPR mode) Used for practical sample-on-substrate measurements, where each dataset contains a matched baseline, control, and sample spectrum. In this mode, the script calculates residual components and the Signal-to-Parasite Ratio (SPR). 2. General workflow After the script is launched, the user pastes a table of spectral data into the upper text field labeled “Paste your table here:”. The program then detects the input format automatically, performs the appropriate analysis after pressing Analyze, shows a text summary in the lower “Results / report preview:” field, and enables export of the numerical results as TSV and the report as TXT. 3. Input requirements common to both modes The script expects a plain text table pasted into the GUI. It can interpret columns separated by tab, comma, semicolon, vertical bar, or whitespace. At least two rows must be present, and at least three numeric rows are required for successful analysis. Non-numeric rows that do not match the expected table structure are ignored during parsing. Decimal commas are accepted and internally converted to decimal points. The first column must always contain the Raman shift axis (x). The remaining columns depend on the selected mode, which is determined automatically from the column headers. If the first row contains headers with suffixes such as __baseline, __control, or __sample, the script switches to paired mode; otherwise it uses control-only mode. 4. Control-only mode (COM) 4.1 When to use this mode Use control-only mode when the goal is to quantify intrinsic substrate background or parasitic signal without an analyte-containing sample. In this workflow, one baseline spectrum is compared against one or more substrate spectra. 4.2 Required input format Paste a table in the following layout: x baseline substrate1 substrate2 substrate3 ... A header row is optional. If present, the first column should be the Raman shift axis, the second column should be the baseline spectrum, and all following columns should be substrate spectra. If no valid headers are present, the program assigns default names such as Substrate_1, Substrate_2, etc. The script accepts up to 20 substrate columns in this mode. 4.3 Step-by-step procedure • Launch the script. • Copy the spectral table from Excel, a spreadsheet, or a text editor. • Paste the table into the upper input field. • Check that the first column contains Raman shift values, the second column contains the baseline spectrum, and the remaining columns contain substrate spectra. • Click Analyze. • Inspect the report shown in the lower preview field. • To save the numerical residual spectra, click Export TSV. • To save the text summary, click Save Report (TXT). • To start a new analysis, click Clear. 4.4 What the script computes in COM For each substrate spectrum, the script fits the model: s ≈ α·b + β·1 + γ·x where b is the baseline spectrum and x is the Raman shift axis. It then calculates the residual spectrum d = s − (α·b + β + γ·x), estimates the baseline/reference noise using MAD-based robust statistics, and reports the following metrics: • α, β, γ • σ_b • σ_ref • RMS_d • RMS_d / σ_ref • L1_d • PI • classification as CLEAN, MINOR PARASITICS, or INTRINSIC SIGNAL PRESENT 4.5 Output files in COM In control-only mode, Export TSV produces a file named by default control_residuals.tsv. The first column is x, and each following column contains one residual spectrum labeled as residual_. The text report can be saved as control_report.txt. 5. Paired Signal-to-Parasite Ratio mode (SPR mode) 5.1 When to use this mode Use SPR mode when each analyte measurement is accompanied by a matched baseline and control measurement. This is the appropriate mode for practical sample-on-substrate comparisons where the goal is to separate useful Raman signal from smooth background and substrate-derived parasitic contributions. 5.2 Required input format Paired mode requires a header row with named triplets. The format is: x PairA__baseline PairA__control PairA__sample PairB__baseline PairB__control PairB__sample ... Each triplet must share the same prefix, such as PairA, and must contain exactly the suffixes __baseline, __control, and __sample. The program groups columns by this prefix and analyzes each complete triplet as one pair. If no valid triplets are found, the script returns a parse error. 5.3 Step-by-step procedure • Launch the script. • Prepare a table with a header row. • Put the Raman shift axis in the first column (x). • For each matched dataset, create three columns named PairName__baseline, PairName__control, and PairName__sample. • Paste the full table into the upper input field. • Click Analyze. • Read the paired-analysis report in the lower preview field. • Click Export TSV to save the numerical residual components. • Click Save Report (TXT) to save the textual summary. • Click Clear before starting a new dataset. 5.4 What the script computes in SPR mode For each pair, the control and sample spectra are first baseline-projected separately using the same underlying fitting routine as in control-only mode. The paired residual is then defined as: Δ = d_sample − d_control This paired residual is decomposed into: a smooth background term obtained by moving-average filtering a peak-rich term defined as Δ − smooth_bg From these components, the script reports: • α_control • α_sample • control classification • Useful RMS • Background RMS • Substrate RMS • Parasite RSS • SPR • Useful L1 The built-in paired-mode summary explicitly states that: useful Raman signal is quantified as RMS(peaks) parasitic contribution is quantified as RSS(RMS(background), RMS(control residual)) SPR = Useful RMS / Parasite RSS larger SPR values indicate stronger dominance of structured sample signal over smooth background and substrate-induced parasitics 5.5 Output files in SPR mode In paired mode, Export TSV produces a file named by default paired_analysis.tsv. For each pair, the output includes five columns: PairName__d_control PairName__d_sample PairName__delta PairName__smooth_bg PairName__peaks The text report can be saved as paired_report.txt. 6. Practical notes for preparing input tables 6.1 Copying from Excel The most reliable workflow is to prepare the data in Excel or another spreadsheet program and copy the relevant columns directly into the script. Tab-delimited clipboard data is handled naturally by the parser. 6.2 Consistent x-axis All spectra within one pasted table must correspond row-by-row to the same Raman shift axis in the first column. The script does not perform interpolation or axis matching internally; it assumes that the input rows are already aligned. This follows from the fact that the code directly reads all numeric rows into one array and uses the first column as a common x axis for all subsequent calculations. 6.3 Header naming in paired mode The paired mode is sensitive to the exact naming pattern. The suffixes must be written as: __baseline __control __sample The detection is case-insensitive for these suffixes, but the double underscore structure is required. 7. Troubleshooting 7.1 “Please paste your table first.” This message appears when Analyze is pressed with an empty input field. Paste the dataset before running the analysis. 7.2 “Please paste at least two rows.” This error indicates that the pasted content is too short to be interpreted as a table. Add the full dataset, including multiple numeric rows. 7.3 “Not enough numeric rows found.” This means the parser could not extract enough valid numeric rows for control-only mode. Check whether the pasted table contains text in numeric areas, missing values, or incompatible formatting. 7.4 “Not enough numeric rows found for paired mode.” This means the paired table was detected, but too few valid numeric rows could be read. Verify that the body of the table contains properly formatted numbers. 7.5 “No valid paired triplets found.” This occurs when the headers do not contain complete prefix__baseline, prefix__control, prefix__sample triplets. Check spelling, double underscores, and whether all three columns are present for each pair. 7.6 Buttons for export remain inactive The Export TSV and Save Report (TXT) buttons are enabled only after a successful analysis. If they remain disabled, the analysis did not complete successfully. 8. Minimal input examples Example A: control-only mode x baseline Glass Quartz CaF2 324 12.1 12.8 12.4 12.0 325 11.9 12.7 12.5 12.1 326 12.0 12.6 12.4 12.0 ... Example B: paired SPR mode x S1__baseline S1__control S1__sample S2__baseline S2__control S2__sample 324 10.2 12.1 18.4 11.0 13.2 16.8 325 10.1 12.0 18.1 10.9 13.0 16.5 326 10.3 12.2 18.6 11.1 13.1 16.7 ... These examples follow exactly the formats described in the script header and parsing logic. 9. Short summary The script provides two complementary evaluation modes in one interface. Control-only mode quantifies substrate-intrinsic residual background after projection against a baseline spectrum, whereas paired mode compares matched control and sample spectra to estimate useful Raman signal, parasitic background, and the resulting Signal-to-Parasite Ratio (SPR). The program accepts pasted tabular input, automatically detects the mode from column headers, displays a text summary, and exports the processed residual data for further inspection.