CurveMole analysis bundle — Raman quick start
Application version: 1.3.1
Software RRID: RRID:SCR_029214 (https://scicrunch.org/resolver/RRID:SCR_029214)
Concept DOI (all versions): 10.5281/zenodo.22113854 (https://doi.org/10.5281/zenodo.22113854)
Spectra: 1. CSV delimiter: ','; encoding: UTF-8.

This folder contains the selected, available outputs of your analysis.
Only files included in this export are listed below.

Software citation
=================
Bibliography: cite the Zenodo DOI of the exact CurveMole version used.
Methods: Data were analysed with CurveMole version 1.3.1 (RRID:SCR_029214).
The Concept DOI is a general project reference and may resolve to a beta.
Citation guide and BibTeX: https://github.com/SebRoLENS/curvemole/blob/main/docs/citing.md

Contents of this export
=======================

Figures
File or folder                                   | What it contains
-------------------------------------------------+-------------------------------------------------------------------
figures/pdf/*.pdf (1 file)                       | Vector PDF figures for printing and sharing. One file per
                                                 | spectrum, with data, current model, components, errors and
                                                 | residuals.
figures/pdf/current_view.pdf                     | Snapshot of the visible plot when Export was pressed, redrawn with
                                                 | Matplotlib using the captured traces and view settings.
figures/png/*.png (1 file)                       | PNG images for documents and presentations. One file per spectrum,
                                                 | with data, current model, components, errors and residuals.
figures/png/current_view.png                     | Snapshot of the visible plot when Export was pressed, redrawn with
                                                 | Matplotlib using the captured traces and view settings.
figures/svg/*.svg (1 file)                       | Editable SVG vector images that stay sharp when resized. One file
                                                 | per spectrum, with data, current model, components, errors and
                                                 | residuals.
figures/svg/current_view.svg                     | Snapshot of the visible plot when Export was pressed, redrawn with
                                                 | Matplotlib using the captured traces and view settings.

Data tables
File or folder                                   | What it contains
-------------------------------------------------+-------------------------------------------------------------------
data/*_wide.csv (1 file)                         | One CSV per spectrum, with measured data, current model and
                                                 | components, residuals, errors, weights and exclusion flags in
                                                 | columns.
spectra/* (1 file)                               | Quick-export spectrum tables with data, errors, current model,
                                                 | components and residuals; source extensions and delimiters are
                                                 | retained.

Fit parameters and uncertainty
File or folder                                   | What it contains
-------------------------------------------------+-------------------------------------------------------------------
diagnostics/*_autocorrelation.csv (1 file)       | Residual autocorrelation versus lag, one CSV per spectrum covered
                                                 | by the last fit.
fit_results.csv                                  | Current parameter values, units, bounds and links, with recorded
                                                 | fit errors. One row per parameter.
fit_settings.csv                                 | Solver and loss settings recorded for the last fit.
function_parameters.csv                          | Quick-export parameter table: one row per spectrum, with function
                                                 | and parameter names in two header rows.
function_parameters_covariance/[0-9]*.csv (2     | Parameter covariance matrices from fits or selected sample
files)                                           | analyses; joint fits retain cross-spectrum relationships.
function_parameters_covariance/index.csv         | Guide to the covariance files: fitted spectra, fit or analysis
                                                 | source, method, matrix filename and sample count.
uncertainty/correlation.csv                      | Last-fit parameter correlation matrix, labeled by parameter path.
uncertainty/covariance.csv                       | Last-fit parameter covariance matrix, including relationships
                                                 | across jointly fitted spectra.
uncertainty/parameter_assessments.csv            | Recorded uncertainty estimates, methods, bounds and diagnostic
                                                 | information for parameters.

Project and Python
File or folder                                   | What it contains
-------------------------------------------------+-------------------------------------------------------------------
Raman_quick_start.fitproj                        | Open in CurveMole to resume the analysis: spectra, models,
                                                 | transformations, masks, parameter links, fit records and saved
                                                 | uncertainty samples.
index.csv                                        | Look up each spectrum's name, source, axis units and exported
                                                 | filenames using its stable ID.
models/*.fitmodel (1 file)                       | One reusable model per spectrum, including its components and
                                                 | custom-function definitions.
python/components.csv                            | Evaluated values for each enabled model component, with its
                                                 | identity and composition operator.
python/curves.csv                                | Spectrum names, sources, axis labels and units, fit state and
                                                 | applied transformations.
python/observations.csv                          | Measured points, current model, residuals, background, errors,
                                                 | weights and exclusion flags. One row per point.
python/replot.py                                 | Run this pandas/Matplotlib script to redraw each spectrum from the
                                                 | exported tables, without CurveMole.
python/results.json                              | Stored fit records, including settings, statistics, warnings and
                                                 | parameter estimates, with their scope and timestamps.

Reports and documentation
File or folder                                   | What it contains
-------------------------------------------------+-------------------------------------------------------------------
README.txt                                       | This guide to the exported files, their interpretation and use.
laboratory_notebook.txt                          | Project notes and recorded analysis history.
manifest.json                                    | Exact file inventory and export settings for software or automated
                                                 | processing.
report/full_reproducibility.html                 | Extended browser report with recorded fit settings and project
                                                 | metadata.
report/summary.pdf                               | Combined PDF report, with one page for each spectrum.
summary_report.html                              | Open in a browser to read the project, parameter and last-fit
                                                 | statistics summary.

Figure groups (*) cover per-spectrum images; current_view files are listed separately.

Using these files
-----------------
- Open Raman_quick_start.fitproj in CurveMole to resume or refit the complete analysis.
- Use figures/png for convenient image sharing; figures/svg for editable vector graphics;
  figures/pdf for individual printable figures. Each format has its own folder.
- Use index.csv to find the files belonging to a spectrum. Names include a stable ID suffix, so
  spectra with the same display name still have different files.
- manifest.json contains its exact file inventory, export settings and curve-to-file mapping.
- spectra/ contains the same tables as Quick export spectra. A vendor extension still contains a
  plain-text table; its delimiter follows the source file.
- function_parameters.csv is the Quick export function parameters table. The first two rows name the
  function and parameter/error; spectra follow project order. Parameter cells are empty unless the
  spectrum is in the Fitted state.

Current model and recorded fits
-------------------------------
- Data tables and per-spectrum figures use the CURRENT model and CURRENT transformed observations,
  even if a model is unfitted or has changed. A model curve is not proof of a converged or
  up-to-date fit. Background subtraction is not applied to the exported observations.
- fit_results.csv gives current resolved parameter values. Its error and confidence columns may
  retain recorded fit estimates; these are not uncertainties of a model changed since fitting. Check
  curve_state/state for the spectrum's fit status.
- Recorded settings, fit statistics, covariance/correlation matrices and residual autocorrelation
  describe the LAST fit. It may cover only part of the project. Stored fit records in results.json,
  when included, identify their curve IDs, scope and timestamps (fit_by_curve/global_fit_baselines).
- function_parameters_covariance/ keeps selected fit or sample-analysis covariance estimates
  separate. Its index identifies their source and scope; jointly fitted parameters keep their
  cross-spectrum terms.
- Each .fitmodel stores one spectrum's model. A complete .fitproj project snapshot is needed to
  preserve cross-spectrum relationships and resume the whole analysis.

Understanding the Python tables
-------------------------------
- observations.csv has one row per current point. Join tables using (curve_id, point_index):
  point_index starts at zero in current row order. original_row_index starts at zero in the imported
  data. X values can repeat, so never join on x alone.
- x/y are transformed measurements; model_y is the current total model; residual = y - model_y;
  background is the evaluated background. Missing model values, errors or weights are empty, not
  zero. curves.csv holds the names, sources, transformations, state and units.
- components.csv uses the same point keys plus component_id to distinguish components with the same
  name. Values are individual function evaluations: follow add/multiply/divide/convolve operators
  rather than blindly summing them.

Units, errors and excluded points
---------------------------------
- x and sigma_x use x_unit. y, model_y, residual, background, sigma_y and error_y_minus/plus use
  y_unit. Component units provide axis context; multiplication or division factors can have a
  different dimensional meaning.
- sigma_y is a standard deviation. error_y_minus/plus are confidence-interval half-widths at
  error_confidence_level in curves.csv. For weight, weights_are_inverse_variance=true means inverse
  variance; false means a direct residual multiplier.
- masked=true marks a CURRENT exclusion: masks, fit ranges or invalid observations, Y errors or
  weights. All points stay in the tables. masked is not a historical fit-inclusion flag: masks or
  solver options may have changed since fitting.
- valid checks observations, Y errors and weights; finite_xy checks only x/y; model_valid checks the
  current model evaluation. These flags describe different checks and are not interchangeable.

Parameter units
---------------
- Parameter units are listed in fit_results.csv.
- Covariance entry (i,j) has parameter-unit(i) times parameter-unit(j). Correlations are
  dimensionless; matrix labels identify the parameters.

Redraw the figures in Python
----------------------------
- Install pandas and matplotlib, then run: python python/replot.py
- The script locates its tables relative to itself and writes PNG images in python/replotted/png/
  and SVG images in python/replotted/svg/. It redraws exported values without installing CurveMole
  or rerunning a fit.
- Replotted residuals exclude currently masked points. Models using multiplication, division or
  convolution show their total without misleading raw-component overlays.
