Raman Studio

Drop in a Raman spectrum (Excel, CSV, TXT, JCAMP-DX, SPC or Renishaw WDF, whatever the instrument exports) and see it immediately, cleaned up, with every peak labelled from the Raman graphene / graphene-oxide atlas. Click a label to read what the band means, get the atlas intensity ratios from your own numbers, and resolve the shoulders hidden inside broad GO bands with an atlas band fit.

Live: https://vascoesquivel.github.io/raman-studio/ · try it with no file: graphene-oxide sample, monolayer sample

Everything runs in your browser. Files are parsed locally and never uploaded. The app is static files on GitHub Pages: no server, no account, no build step.

Using it

1. Load a file: drag it onto the window, press O, or use a sample. Several files, sheets or intensity columns load as separate spectra. Switch between them from the name chip, or show them overlaid or stacked. If the app can't tell which column is the Raman shift, it shows a small column-mapping preview instead of failing.

2. Clean with the signal chain under the plot. Each module has its own switch:

   • Despike removes cosmic rays, including multi-point tracks, without touching real bands. A feature is removed only if no smooth band at least the narrowest real band wide (default 3 data points), nor two overlapping ones, can reproduce its shape within the noise. In a file with several spectra on the same axis (a map or series) the others are a second opinion: a feature they share is kept, or labelled a detector artifact when it is a single repeating pixel. Removals are marked on the plot and listed in the Data tab, where each can be kept, and any range can be zapped by hand.
   • Baseline: constant, linear or quadratic, as in PeakForge, or asymmetric least squares for curved fluorescence.
   • Smooth: optional Savitzky–Golay.
   • Normalize: to the maximum, to the G band, or to unit area.

   Raw + baseline (B) and Compare (C) show what each step did.

3. Detect. Peaks are found by prominence (a port of SciPy's find_peaks), not naive local maxima. The sensitivity slider sets the prominence threshold as a multiple of the measured noise.

4. Label. Each peak is matched to the atlas band whose window contains it, with a match score that falls off with distance from the atlas centre (1 at the centre, about 0.14 at the window edge; a distance measure, not a probability):

   • Unmatched peaks stay on the plot as unassigned. Load a reference list of your own (a JSON file, see below) from the Peaks tab and each unassigned peak lists the materials with a band within its tolerance: candidates, a coincidence of position, not an identification. The list stays in the browser session; it is not part of the app and not saved in projects.
   • Peaks in the 2850–2920 cm⁻¹ window are tagged sp³ C–H, which the atlas says is not a lattice band.
   • Pick the excitation laser (532 / 633 / 785 nm). D and 2D windows shift with it at the atlas rates (~50 and ~100 cm⁻¹/eV).

5. Deconvolve (F). This seeds PeakForge's Levenberg–Marquardt fitter with the atlas bands and fits the first- and second-order regions. In the first-order region D and G are always fitted, while D*, D″ and D′ are kept only in the band set with the lowest BIC (Bayesian information criterion), so a shoulder the data cannot support does not leave G "not significant". The Fit tab names the chosen set, lists every set tried, and shows a runner-up within ΔBIC 2 (with its ratios on the Ratios tab). Fit every band turns selection off. Bands it resolves get dashed callouts, so you can tell them apart from the solid callouts of detected maxima. The Fit tab shows residuals, fit quality against the noise floor, uncertainties and degeneracy warnings.

6. Explain.

   • Click any label to see the band's vibrational origin, scattering process, diagnostic use and references, all taken from the atlas.
   • Ratios computes the atlas ratio guide (height and area versions), with the Cançado crystallite size and Eckmann defect class. Ratios from a fit carry a ± fit-model standard uncertainty.
   • Read walks the atlas's "read your own spectrum" steps using your numbers.
   • Map appears for a Renishaw map (.wdf). It draws a band-intensity heat map: one band's height, or the ratio of two, at every map point. Click a point to open its spectrum. Compare adds a second band and gives the correlation of the two maps across the points, with a scatter plot, which replaces toggling two heat maps by eye.
   • Data shows the acquisition settings read from the file header (laser, grating, exposure, accumulations, whether the instrument's own cosmic-ray removal was on, laser power), quality warnings (saturated or clipped data), and every spike removal.

7. Export:

   • The figure as PNG (3×) or SVG, on white, with labels and legend.
   • CSV files of the peak table (with each peak's match_score), the fit parameters and the processed spectrum (raw, baseline, corrected, final and despiked columns).
   • The map values as CSV: point, stage x and y, the mapped value and the compared band.
   • Reviewer labels as JSON (see Label below), with the raw data, saved to your computer only.
   • A one-page printable report: figure, tables, ratios and interpretation.
   • A project JSON (Ctrl+S) that reopens exactly where you left off.

Calibrate the wavenumber axis from the Data tab: open a silicon reference spectrum, measure its band, and enter the nominal position with its source (the app holds no nominal value of its own). The difference is applied to every spectrum of the session as one constant offset, shown on the chain's Raw module and recorded in the report, the spectrum CSV (x_uncalibrated column) and the project.

Label spectra for a reviewed dataset, also on the Data tab: check the cosmic-ray removals and the peak labels, grade the spectrum (good / usable / reject), and Save & next moves to the next unlabelled one. Each label keeps a snapshot of the mask and the assignments you confirmed; reopening the spectrum restores your edits. Labels are saved in projects and exported as raman-studio/labels@1 JSON.

Presentation mode (P) goes fullscreen with large type and projector contrast. ← → step through the labels with a caption for each band. T switches between the dark and light themes. ? lists every shortcut.

Keyboard

Keys follow PeakForge where the action exists there.

key	action
O	open file
D	detect and label again (replays the scan)
F	deconvolve (PeakForge: auto-fit)
1 2 3	laser 532 / 633 / 785 nm
double-click plot	add a peak by hand (PeakForge: add peak)
Del	remove the selected peak (PeakForge: delete curve)
← →	nudge the selected peak (Shift = 10×)
[ ]	previous / next label
Ctrl+Z / Ctrl+Y	undo / redo
Ctrl+S	save project
wheel · drag · Shift+drag	zoom · pan · zoom to range
R	show the whole spectrum
B / C	raw + baseline / compare raw and processed
P / T	presentation mode / theme
Esc	deselect, close, leave presentation

Supported formats

format	notes
.csv .tsv .txt .dat .asc	Any delimiter (comma, semicolon, tab, pipe, spaces) and decimal commas. Header and comment lines are skipped. UTF-8, UTF-16 or Windows-1252. Handles Renishaw WiRE and Horiba LabSpec exports (descending x, #Laser headers), several intensity columns, transposed tables and long map exports (X, Y, Wave, Intensity).
.xlsx .xls	Every sheet with numeric data. Read with SheetJS 0.20.3, loaded from its CDN only when a spreadsheet is opened.
.jdx .dx	JCAMP-DX 4.24 / 5: XYDATA with AFFN or ASDF compression (SQZ, DIF, DUP), XYPOINTS, PEAK TABLE, multi-block files.
.spc	Thermo / Galactic SPC, new format. Even and XY spacing, single and multiple subfiles. Experimental.
.wdf	Renishaw WiRE native files: single spectra, series and maps, with stage coordinates and the map grid. Laser, accumulations, WiRE version and map size are shown on the Data tab; the operator name is not read. Spectral images (several rows per spectrum, as in line-focus maps) are not supported. Up to 20 000 spectra per file.

The wavenumber column is detected automatically: monotonic, roughly 50–4000 cm⁻¹, evenly spaced, and helped by header names. An index column never wins.

Adding a band library

Band data lives in data/libraries/. The app loads every file listed in data/libraries/index.json; GitHub Pages can't list folders, so the manifest is needed. To add a material:

1. Write data/libraries/<material>.json following data/libraries/schema.json. Use graphene-go.json as a worked example. Each band needs id, label, name, region (first / second), posText, posSort and a match block: range [lo, hi] in cm⁻¹, center, and dispersion.cmPerEV (0 for non-dispersive, null if unknown). The descriptive fields (origin, process, mechanism, meaning, diagnostics, use, correction, refs) fill the explanation panel.
2. Add { "file": "<material>.json" } to index.json.
3. Pick it in the Label module of the signal chain.

Ratios and the read-your-spectrum evaluation are optional (ratios, ratioMap, workflow). The automatic workflow evaluation is written for the graphene library; other libraries show their steps as text.

graphene-go.json is generated from the atlas, so don't edit it by hand:

python tools/extract_atlas.py path/to/raman-graphene-atlas/index.html --commit <sha>
python tools/verify_atlas.py            # field-by-field diff against the atlas on GitHub

Development

No build step. Serve the folder the way GitHub Pages does (under a subpath) and open it:

python tools/serve.py          # http://127.0.0.1:8765/raman-studio/

Tests run in a real browser. tests/index.html runs the unit suites (parsers, cosmic-ray filter, baselines, SciPy-checked peak detection, the fitter, atlas matching, ratios, workflow, band maps and label layout) using synthetic spectra and one small fixture per format. To run everything headless:

pip install playwright          # drives your installed Chrome or Edge
python tools/run_tests.py       # unit tests
python tools/check_app.py       # end-to-end: samples, every fixture, exports, screenshots
python tools/check_app.py --url https://vascoesquivel.github.io/raman-studio/   # same checks on the live site

Lab files for local testing go in test-data/private/, which is gitignored. python tools/lab_harness.py compares the app's fits there with the lab's own WiRE curve fits (*_curvefit.wdf) and keeps its results in the same private folder. python tools/build_reference_list.py WORKBOOK.xlsx turns a reference-peaks workbook into a reference list for the Peaks tab; it writes only inside test-data/private/. Module contracts are in docs/ARCHITECTURE.md.

Credits

• Band data: the Raman Spectroscopy of Graphene & Graphene Oxide atlas (source), its nine-band model, ratio guide, decision workflow and references, used verbatim.
• Fitting: PeakForge / Curve-gen (source), its WiRE-compatible pseudo-Voigt profile and Levenberg–Marquardt fitter with trust bounds and uncertainties.
• Peak detection follows SciPy's find_peaks. The despiking noise estimate follows Whitaker & Hayes (2018). The ALS baseline follows Eilers & Boelens (2005). The polynomial baseline follows Lieber & Mahadevan-Jansen (2003).
• SheetJS for spreadsheets. IBM Plex type via Google Fonts.

Known limitations

• Reference excitation is assumed. The atlas doesn't say which laser its positions are for. The app treats them as 532 nm and labels that as an assumption everywhere it matters.
• Only D and 2D shift with the laser. Those are the only rates the atlas gives (~50 and ~100 cm⁻¹/eV). The windows for D′, G*, D+D′ and 2D′ widen at 633/785 nm instead of shifting, so matches there are looser.
• Overlapped bands are not uniquely determined. In GO, D′ under G and D″ between D and G are often degenerate with their neighbours. The Fit tab flags them (not significant, or a near-degenerate pair) rather than hiding the problem. Seed widths are the atlas's schematic ones, each fit stops at 300 iterations, and everything runs on the main thread: with model selection the first-order region is fitted 8 times, about 1 s for a typical spectrum.
• Model selection weighs fit against parameters; it does not prove a band is there or not. BIC (Schwarz 1978) assumes independent noise, while real residuals also carry baseline and line-shape misfit, which pushes any criterion towards more bands; BIC's larger penalty was chosen partly for that. Only D*, D″ and D′ are optional, the second-order region always fits its four bands, and bands the atlas does not define (such as broad bands a lab fit may add) are never offered. The choice was checked against the lab's own WiRE curve fits (private data, not published).
• The automatic reading is a guide, not a verdict. Only numeric thresholds the atlas states are applied, such as 2D FWHM < 30 cm⁻¹ and I_2D/I_G ≥ 2. "Strong D", "little D" and "broad" have no atlas numbers, so the app shows the measured values for you to judge. It also doesn't count 2D components (to tell a monolayer from a bilayer). The evaluation is written for the graphene library only.
• A ratio's ± covers noise, not the model. It is the 1σ fit-model standard uncertainty from the fit's covariance: how much the ratio would scatter under repeated noise for the bands and line shapes that were fitted. Which bands go into the fit, their line shapes and the baseline can move a ratio further than its ± suggests, which is why a close runner-up band set is shown with its own ratios. It is not a probability. Ratios from detected peak heights have no ±.
• The match score is a distance score, not a probability. It is exp(−2(d/d_max)²) of the distance from the atlas centre within the match window, shown as a number (never a percentage) and exported as match_score.
• Most formats are tested against synthetic fixtures. WiRE SPC exports have also been checked against real instrument files (values and header); the other fixtures are modelled on WiRE, LabSpec, Excel and JCAMP-DX exports. SPC support covers the new format only. The WDF reader matches an independent reader value for value on twelve real WiRE 5.6 files (point spectra and an 88-point map); other WiRE versions have not been checked. Wavelength (nm) x-axes are not converted to Raman shift.