SpectraStream is a Streamlit application that turns a Raman spectrum in almost any vendor format into a NeXus file, optionally with a calibrated wavenumber axis. It builds on the ramanchada2 processing library and pyambit for NeXus output.
The project is currently alpha software; results are indicative.
- Convert — upload a spectrum and download NeXus. Beyond the file you need only its x axis units and the laser wavelength; everything else is optional.
- Instruments (optional) — record an instrument and its optical paths, so their metadata enriches every export and calibrations have somewhere to live.
- Calibrate (optional) — derive a calibration from reference spectra and attach it to an optical path for reuse.
Metadata fields follow the CHARISMA/VAMAS Raman reporting template, so a spectrum described here carries the same facts as one described for a round-robin. Where a file's own header states something — many formats record the laser wavelength and integration time — those fields are prefilled and left editable.
An instrument is the box: make, model, serial. An optical path (OP) is one configuration of it — excitation wavelength, grating, objective, slit — and one instrument commonly has several. This mirrors the VAMAS template, where each Front sheet row is an OP and each measurement names the OP it used.
Calibrations belong to an optical path, never to the instrument. Change the grating and the correction changes; change the wavelength and even the reference lines are different, so a 532 nm calibration applied to a 785 nm path is not merely inaccurate but meaningless.
Calibration is pluggable. A recipe declares which reference spectra a protocol needs and which steps run over them, as YAML rather than code — see src/spectrastream/calibration/recipes/. The UI is generated from the recipe, so supporting a protocol that needs entirely different reference materials means adding a file, not changing a page. Point $SPECTRASTREAM_RECIPES at a directory to add your own.
Shipped protocols use the open ramanchada2 engine:
| Recipe | Needs | Produces |
|---|---|---|
rc2.ne_si |
Neon lamp (silicon and SRM optional) | Wavenumber axis, laser zero, relative intensity |
rc2.si_only |
Silicon wafer | Laser zero only |
rc2.y_srm |
Standard reference material | Relative intensity only |
Steps whose optional inputs are missing are skipped rather than failing the run: without a silicon spectrum you still get the neon curve.
Instrument profiles are stored in your browser, not on the server, and calibrations are stored as JSON inside them. Clearing site data removes them; export from the Instruments page to keep a copy or move to another machine. Uploaded spectra are never persisted.
Install uv, clone the repository, and install the locked environment:
git clone git@github.com:h2020charisma/spectrastream.git
cd spectrastream
uv sync --lockedStart Streamlit from the repository root:
uv run streamlit run src/streamlit_app.pyOpen http://localhost:8501.
Supported Python versions are 3.10 through 3.12; Python 3.12 is the project default.
docker build -t spectrastream:local .
docker run --rm -p 8501:8501 spectrastream:localOpen http://localhost:8501/stream. The image includes a health check at /stream/_stcore/health and runs as an unprivileged user.
Published images are available from ghcr.io/h2020charisma/spectrastream. The latest tag tracks successful builds from main; commit-addressed sha-<commit> tags support rollback. Use the image digest when deployment requires an immutable reference.
Calibrations are serialized as JSON, so importing a profile cannot execute code. Profile exports are plain .json and can be inspected before import.
See CONTRIBUTING.md for setup, testing, pull-request images, and container guidance.
SpectraStream is available under the MIT License.
🇪🇺 This project received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 952921.