The complete guide to eQCX
One folder in. Two clean files out. Every time. eQCX reads spectroscopy folders of any layout, works out what is inside, and writes a tidy linked pair of tables that Excel, R, Python, and Origin can all open.
An intelligent model reads the data itself. File names and column layouts only get a converter so far. eQCX learns spectrum shape, spacing, and axis behaviour, so it can tell Raman from FTIR from mass spec in unnamed or mislabeled files. The structure starts the job; the data makes the call.
Built for confidential spectra
eQCX converts on your own machine. Spectra, metadata, and results are written to the folder you choose. Nothing is uploaded, and no account is required to convert. That makes the tool suitable for unpublished research, patient-adjacent measurements, and industry projects where data must stay inside the building. Universities and companies can verify every claim in this section with the free eQC SDK, because the records are plain files on your disk.
Welcome
What this tool is, who it is for, and how the wiki is organised. No prior knowledge is assumed.
eQCX, the Intelligent Spectroscopy Mass Data Converter, is a Windows desktop application for anyone who measures spectra: biology and chemistry students, lab technicians, professors, and industry scientists. You point it at a folder of spectral files. It produces one clean table that describes every sample, and one clean table that holds the spectra themselves. Both files open in Excel, R, Python, MATLAB, and most statistics software.
Spectroscopy instruments each export their own file style. One brand writes text files with commas, another uses semicolons, a third saves Excel sheets or binary containers. Students usually end up copying values by hand. eQCX removes that chore. It looks at the structure of every file, finds the axis and the intensity values, joins metadata it finds in neighbouring files, and writes the result in a single consistent layout called the eQC format.
It understands, it does not guess
The engine finds the axis by looking for a long, evenly spaced run of numbers. Vendor and folder names play no part in the decision, so a folder layout you have never converted before still works.
Made for non-programmers
There is no command line and no script to edit. You pick folders with the normal Windows dialog, press one button, and read plain-language progress messages while the work runs.
Every run is documented
Each conversion writes a timestamped audit trail with checksums for every output file. You can always answer the question “which file came from where, and when?”.
How to use this wiki
- New here? Read Privacy and security, then follow Quick start. That is all most people need for a first conversion.
- Looking for one setting? Press Ctrl+K and type a word such as “preview” or “quota”.
- Confused by a term? The Glossary explains every technical word in plain language.
- Something went wrong? Troubleshooting lists every error message and its fix.
Students and researchers in the life sciences. Every instruction assumes you have never used a converter before, and each button is explained the first time it appears.
Privacy and security
The full, specific answer to “is it safe to use this with my data?”. Written for universities, companies, and anyone handling unpublished measurements.
Conversion never touches the internet. Your spectra are read from your disk, transformed in the computer’s memory, and written back to your disk. No spectrum, filename, metadata value, or result is ever uploaded. The app works fully offline. A network connection is used only if you sign in to an education plan, and then only for usage counts.
What happens on your computer
- Source folders are only ever read. The engine never writes to, renames, or deletes anything inside your data folders. Cloud-synced folders (OneDrive, Dropbox) are copied to a local scratch area first so the sync client is not disturbed.
- Results are written to the destination folder you picked, as ordinary CSV files you can open, move, or delete like any other file.
- A few small helper files live in
C:\Users\<you>\.eqc_exporter\: your consent choice, your pseudonymous sign-in ID, and the window position. The exact list is in Files in the output.
What could ever travel over the network
Only two optional systems ever use the network, and neither can carry spectral data:
- Education plan sync (only if you sign in). The app sends a one-way pseudonymous ID (a salted SHA-256 hash), your email domain such as
university.edu, and usage counters such as “40 samples converted this month”. That is how your free monthly budget is tracked. Your spectra, filenames, and results are never part of this traffic. - Anonymous structure sharing (optional, off anytime). When a file fails to convert, the app can save an anonymous structural recipe of that failure: field types, decimal counts, encoding, file sizes, row counts, and how files relate in the folder. Numbers are reduced to shape and magnitude buckets. Text never leaves as text; a filename such as
S001_M1.csvbecomes the patternA999_A9.csv. The recipe contains no spectra, no filenames, no header text, and no results. It is used to teach the converter new layouts. You can turn it off in the settings at any time, and declining does not limit any feature.
Answers for institutions
Universities and teaching labs
Student data stays on student machines. No server holds spectra, so there is no central store to secure or leak. Academic accounts get the full professional feature set at education volumes, and any academic email domain is recognised automatically.
Companies and contract labs
The converter runs inside your firewall and never phones home with content. Every run produces a checksummed, timestamped record set, so quality systems can trace what was produced, when, by whom, and from which inputs.
Patient-adjacent and unpublished data
The tool has no upload path for measurements. Combined with local processing, that removes the usual concern of sending human-derived or pre-publication spectra to a third-party service. Your own institutional rules about local storage and pseudonymisation still apply.
Signed releases
Installers are code-signed by Duviloper, so Windows SmartScreen shows the verified publisher instead of an anonymous warning. If your antivirus questions an installer, ours identifies itself; see Troubleshooting.
Verification instead of trust
Statements are cheap; checksums are checkable. Every conversion writes a SHA-256 checksum for each output file into audit_log_<timestamp>.csv, plus a chain hash over all checksums. The companion eQC SDK (free, open source, MIT licence) recomputes the chain on any machine with the command python -m eqc verify. If a single byte of any output changed after the fact, verification fails. This gives labs a tamper-evident record without any server.
Everything works with networking disabled. Education sync waits and catches up when the machine next comes online, within a grace window of several days. Limits in that period come from a signed local snapshot, so the app never locks you out.
Quick start
From installation to your first converted dataset in about five minutes. No settings knowledge required; the defaults are safe.
Install and open eQCX
Get eQCX from the Microsoft Store and open it from the Start menu. Windows 10 or 11 is required. Nothing else needs installing.
Put your spectra in one folder
Copy the files you want to convert into a single folder, in any layout. Subfolders, zip archives, mixed formats, and extra non-spectral files are all fine. Leave the folder where it is; eQCX only reads it.
Add the folder and choose a destination
In the app, press Add folder and pick your data folder. Then press Browse next to “Destination folder” and pick where the results should go, for example Documents\Converted. Type your name in “Operator name” if you want it in the audit trail.
Press “Export to eQC”
One button. A progress bar shows which file is being processed, and typical folders finish in seconds to minutes. When a file has an unclear axis unit, the app asks one plain question and re-runs those files, so you never have to guess.
Open your results
The result card shows how many samples were extracted, with an Open button for the output folder and Preview spectra to see every spectrum immediately. The output contains metadata.csv, spectra.csv, and the record files described in Files in the output.
The default path changes no spectral values. Archives are extracted, split role files are joined, mismatched axis ranges become separate output groups, and the axis is written with two decimals. Each of these behaviours, and the optional ones, is explained in Conversion settings.
1. Did the destination folder exist before you pressed Export? The app asks you to set it if not. 2. Does the result card say “not converted” for some files? Double-click that tile for the per-reason breakdown. 3. Do the spectra look shifted or mirrored? Check the type chips on the result card; an ambiguous unit can be corrected with one click, see Results explained.
Install and first run
What you see the first time the app opens, and what each first-run dialog means.
Installing
- Install from the Microsoft Store. Store installs are user-local, so no administrator rights are needed on lab PCs.
- The app ships with its own conversion engine. You do not need Python, R, or any other runtime.
- First launch shows “Initializing eQCX” with a short animated bar while the engine warms up.
First-run dialog 1: anonymous structure sharing
The app explains its optional failure-reporting system and offers “Agree & continue” or “Not now”. Both choices give the full feature set. The choice is stored on your device only and can be changed later with the “Share anonymous structure” toggle in Conversion settings. See Privacy and security for exactly what is and is not included.
First-run dialog 2: activate your licence
Sign in with the email and password of your eqcx.duviloper.com account to activate your monthly plan. Have no account yet? The dialog links straight to “Get a free seat”. University (.edu-style) addresses receive a free education seat automatically. If you sign in while offline, the app falls back to a local identity and standard free limits; conversion itself never requires the network.
The dialog states clearly what syncs: the salted email hash, the account domain, and quota counts. No spectral data is ever sent. Passwords are stored only on the server as salted PBKDF2 hashes, never in the app.
Maybe: the campus seat cap
When many students from one university signed up this month, the app shows a friendly notice. Your free budget continues unchanged, and a ready-written email asks the lab manager for a campus plan with higher shared quotas. Continuing with the free budget is one click.
The window
After the dialogs you land in the main window. A footer at the bottom shows the status dot (grey idle, yellow working, green done, red failed), your remaining quota as a chip once signed in, and the app version. The layout is explained in The main window.
What eQCX produces
The eQC format: two ordinary CSV files that always travel together and always have the same shape, whatever went in.
File 1: metadata.csv, the sample table
One row per sample, one column per property. Every cell is stored as text, so identifiers like 007 keep their leading zero. The first columns are always the same:
sample_id— the link key, numberedsample_00000,sample_00001, and so on.data_type— the spectroscopy type detected from the spectrum itself: Raman, FTIR, NIR, SERS, UVRR, UV-Vis, or MALDI-TOF MS.source_fileandoriginal_sample_id— which file the sample came from and its real name in that file, so nothing is hidden behind the numbering.measurement_idandvariant— when a folder holds both a raw and a processed copy of the same measurement (tokens likeraw,processed,baselinein the filename), both rows carry the same measurement ID and each is tagged with its variant. Nothing is thrown away, and the pair can be compared later.- Enrichment columns — properties such as species, antibiotics, cohort, city, instrument, DOI, and operator, recovered from label sheets, JSON notes, comment headers, and readme-style text files.
- Report-only structure columns —
wn_min,wn_max,peak_count,dominant_peak_cm1,entropy_bits,zero_crossingsand similar. They describe each spectrum in a few numbers so you can spot outliers at a glance in Excel.
File 2: spectra.csv, the spectrum table
This table is transposed: each row is one point on the axis, and each column is one sample. The first column is the axis, named after the detected type:
| Axis column | Used for | Meaning |
|---|---|---|
| wavenumber_cm_minus_1 | Raman, FTIR, SERS, UVRR | Vibrational spectra in inverse centimetres |
| wavelength_nm | NIR, UV-Vis | Optical spectra in nanometres |
| m_z | MALDI-TOF MS, mass spectrometry | Mass-to-charge ratio |
Column headers after the axis repeat the sample_id values, which is what links a spectrum to its metadata row. Values are written with four decimals. The table contains no invented points inside the measured range: the axis follows the data itself, and the few cells outside a sample’s own measured range are written as 0.0 so the file stays rectangular.
Why two files instead of one giant table?
Spectra are big; metadata is small. Keeping them apart means Excel stays responsive when you filter samples, and statistics software can load thousands of spectra without touching the labels. Very large groups are split into shards named spectra_01.csv, spectra_02.csv and so on, all with the same header, so no single file becomes unopenable.
Groups: one folder per spectroscopy type
A mixed folder is never blended. Raman stays with Raman, MALDI stays with MALDI. Each detected type becomes its own output group folder with its own pair of files. Wavenumbers, nanometres, and mass units are physically different quantities and are never merged onto one axis.
Spectroscopy types
The data types eQCX recognises, how it tells them apart, and what each looks like in the output.
Type detection starts from the spectrum shape and the container, never from the file name. A trained shape model, header unit declarations, and axis ranges each contribute evidence, and the decision plus its evidence source are recorded per file in the audit trail. Sub-types such as SERS or UVRR are labelled when the folder or headers name them. Hover over a card below to see its typical shape drawn.
Raman
Sharp peaks over a flat baseline. Recognised across Renishaw, Bruker, Horiba, and generic text exports.
FTIR
Broad absorption bands over the classic mid-IR window. The preview displays FTIR from 4000 down to 400 cm⁻¹ by convention.
NIR
Smooth, overlapping humps in the near-infrared. Kept on its own nanometre axis; never merged into wavenumbers.
SERS
Very strong, sharp Raman peaks from surface-enhanced samples. Labelled from folder or header naming.
UVRR
Ultraviolet resonance Raman: Raman-like peaks measured with UV excitation.
MALDI-TOF MS
Stick-like mass peaks. Mass XML files and m/z-shaped data are routed here, on a separate mass axis.
UV-Vis
Broad absorption whose range tops out below 400 nm is labelled UV-Vis instead of NIR.
A numeric axis between 200 and 2600 could be nanometres or inverse centimetres. When headers and file names give no hint, the app converts as Raman and shows a one-click question on the result card: “Treat as UV-Vis/NIR (nm) and re-run”. Your answer is recorded in the audit trail. Folders where most files are confidently nanometre data can flip the remaining ambiguous files automatically.
Supported file formats
What can go into the folder. Mixed formats in one folder are fine; each file is examined on its own.
Fully supported
| Format | Extensions | Notes |
|---|---|---|
| Text spectra, two-column | .txt .csv .tsv .tab .dpt .asc | One spectrum per file. Delimiter detected automatically: comma, semicolon, tab, or space. Comment lines at the top are read as metadata. |
| Wide text tables | .txt .csv .xlsx | Axis in the first row or in the header, one column per sample. The common export style of instrument software. |
| JCAMP-DX | .jdx .dx | The industry standard used by Bruker, PerkinElmer, Agilent, Thermo, JASCO, and Shimadzu. Simple and compressed numeric forms are supported; micrometre axes are converted. |
| Mass spectrometry XML | .mzml .mzxml | Standard open mass-spec formats, routed to the m/z group. |
| NumPy arrays | .npz .npy | Arrays are found by shape and structure, so non-standard key names still work. Label vectors stored beside the spectra become metadata columns. |
| Excel workbooks | .xlsx | All sheets are scanned for the numeric spectral block; descriptive text columns are kept as metadata. |
| R data files | .rds .rda | Flat tables directly; nested lists via a companion cache file when present. |
| Python pickles | .pkl | Common layouts including long-format tables (CoreID / xAxis / RawSpectra). |
| MATLAB files | .mat | Standard and v7.3 (HDF5) files, including PLS_Toolbox table objects. |
| Thermo Galactic SPC | .spc | Standard SPC, Renishaw/Andor HoloGRAMS variants, and companion-cache recovery. |
| Archives | .zip .tar .tar.gz .tgz .gz .7z | Extracted to a scratch area and converted; archives above 250 MB are skipped with a log entry. |
| Metadata sidecars | .csv .xlsx .json .txt .md .ini … | Not spectra themselves. They are mined for sample labels and study facts and joined onto the samples. |
Not directly readable (skipped with a clear reason)
A few vendor binary formats have no reliable public documentation, so converting them would risk inventing data. These files are skipped and listed in the report: Bruker OPUS (extension .0), Omnic .spa, Renishaw .wdf, and PerkinElmer .sp. The result card names them and suggests the fix: re-export from the instrument software as CSV, Excel, or JCAMP-DX, then convert again.
Open INDEX_<timestamp>.csv in the output folder. Every skipped file is listed with a short reason: duplicate_of (a byte-identical copy was already converted), non_spectral (no spectrum structure found), container_unsupported (the vendor formats above), or a parse error. The result card offers the same breakdown by file type; see Results explained.
Special layouts handled automatically
- Bundles. Some datasets are split by role into separate files: one holds the axis, one the intensities, one the labels. When file names follow this pattern, the parts are joined back together by position.
- Duplicates. Files with identical content (even renamed copies) are converted once; copies are reported as duplicates.
- Axis-less MALDI arrays. A spectrum array stored without an axis receives the standard 2000 to 20000 Da MALDI range, and the audit trail states this openly so you can verify it.
The main window
A guided walk through every region of the app, from left to right.
Left column: settings
Operator name, the source folder list, destination picker, and the collapsible “Conversion settings” form. Settings stay where you left them between runs.
Right panel: results
Cumulative totals (folders, files, samples, processing time), the history list, and the live progress of the running conversion with one card per queued folder.
Footer: status
A colour dot (grey idle, yellow working, green done, red failed), a status line, your quota chip when signed in, and the version badge.
Resizing and layout
Drag the divider between the columns to give either side more room; the position is remembered. Double-click the divider to reset it. On narrow windows the two columns stack vertically.
The page intro
The text at the top of the settings column summarises the deal: folders in any format, unified into linked metadata.csv plus spectra.csv, with a tamper-evident audit trail aligned with FDA 21 CFR Part 11 record-keeping practice. It is worth one read.
Convert a folder
The everyday workflow in detail, including the small dialogs you may meet on the way.
Step by step
- Press Add folder. The picker title reminds you that Ctrl+click, Shift+click, and Ctrl+A select several folders at once; double-click enters a folder instead of selecting it.
- Queued folders appear in the source list with their full path. Remove one with its × button, or press Remove all to clear the list.
- Set the destination with Browse. If it is missing, Export gently pulses the field and asks you to choose one.
- Press Export to eQC. Each folder gets a card with “Folder i of N”, a progress bar, the current file name, and Processed/Total counters. Stages have plain names: scanning, writing, resampling, enriching metadata.
- When a folder finishes, its card turns into the result view described in Results explained, and the folder leaves the source list. A failed folder stays in the list marked red so you can fix and retry.
While a conversion runs
You can keep adding folders; they queue as “Waiting…” and start when the current work ends. Starting a second run at the same time is not possible, and the status line says so. Cancel stops the converter; history and totals reset, and the source list survives so nothing is lost.
“This folder has already been converted”
If a queued folder was converted earlier in the same session, a dialog offers Ignore, Ignore All, Continue, or Continue All. Re-running is safe (the output is a new timestamped copy, never an overwrite), so this guard only protects against accidental duplicate work.
Where results go
Inside the destination you chose, each conversion writes one output folder per data-type group. Every file name carries the run timestamp, so converting the same source twice produces two complete side-by-side snapshots instead of overwriting. The layout is documented in Files in the output.
Batch and groups
Convert many folders in one sitting, or fuse them into a single dataset with one click.
Batch: many folders, one after another
Every folder added to the source list is one batch item. Press Export once and the app works through the queue, producing one result card per folder. Progress never resets between folders, and the overall bar fills as folders complete.
Group: many folders, one dataset
When two or more folders are queued, the Convert as group button appears. Give the group a name (a suggestion like grp_20260914 is filled in for you) and press Export group. The queued folders become one dataset:
- Sample numbering continues across folders with no gaps or collisions.
- Metadata columns from all sources are merged. Columns present in only some folders stay, with blank cells elsewhere.
- Same-type samples combine onto one axis; different types still split into separate groups, and a toast tells you how many groups were produced.
- Everything lands in one output folder named after the group, with one INDEX row per source folder.
A course splits a spectra set across three lab PCs. Each student exports their folder; the instructor queues all three and exports them as one group named after the class. The combined output is ready for the shared analysis exercise.
Mixed types in one group
If a group contains, say, Raman and MALDI files, the app warns with a toast, converts everything, and delivers one output group per type inside the group folder. Types are never blended onto one axis.
Conversion settings
Every control in the settings form, grouped the same way the app groups them, with plain-language effects and safety notes.
The form lives under Conversion settings. Three labelled sections mirror how regulated labs think about data: what only records facts, what only reads, and what derives new values.
Record keeping FDA-aligned
| Control | What it does |
|---|---|
| Operator name (for audit trail) | Your name goes into every record file so runs are attributable. Prefilled from your Windows user name or signed-in email. |
| Source folders (batch) | The queue described in Convert a folder. |
| Destination folder | Where output folders are written. Source folders are never modified. |
Discovery no data altered
| Control | Default | What it does |
|---|---|---|
| Extract archives | On | Zip, tar, gz, and 7z archives inside the folder are unpacked to a scratch area and converted. Off skips archives entirely. |
| Join bundles | On | Role-split file sets (axis file + intensity file + label file) are joined back into whole samples. |
| Separate mismatched ranges | On | Samples whose axis ranges differ become separate output groups, each on its own axis. Turning this off merges different ranges onto one grid, which requires interpolation of values. |
| Wavenumber decimals | 2 | Axis values are rounded to this many decimals before samples with near-identical axes are grouped. Raising it groups more strictly; lowering it groups more loosely. |
| Share anonymous structure | On (consented) | The failure-reporting system described in Privacy and security. Off means nothing is captured, ever. |
| Limits PRO unlocks unlimited | 50 / 50 / 5 | A read-only display of your current caps: files per run, samples per run, figure exports per day. Unlimited on Pro, Enterprise, and development builds; education budgets come from the server. |
Wavenumber unification derived · alters data · logged PRO
Off by default, and the section is shown greyed with a PRO tag on Free plans. When enabled, every sample of a type is resampled onto one shared axis so that columns line up perfectly for statistics. Because this computes new values, it is treated as a derived method and documented per sample in the records.
| Control | Options | Plain-language meaning |
|---|---|---|
| Mode | Keep separate / Unify per modality | Keep separate is the safe default. Unify builds one common axis per spectroscopy type. |
| Target grid | Majority / Finest / Canonical | Majority picks the axis most samples already share, so most spectra need no maths at all. Finest adopts the densest axis. Canonical uses your own min, max, and step, with input boxes that appear only for this choice. |
| Interpolator | Linear / PCHIP / Lanczos | How new points are estimated between measured ones. Linear is the safest. PCHIP preserves peak shapes well, a good fit for Raman. Lanczos is band-limited and suits Fourier-transform instruments. |
| Peak alignment | Off by default | Shifts each spectrum by up to ±4 cm⁻¹ to line its peaks up with the group median, in the style of the icoshift method. The applied shift per sample is recorded in the shift_cm1 column. |
When the target axis is coarser than the source, the engine first block-averages source points into each target bin before interpolating. Peaks stay honest instead of being clipped away. After every resample, an automatic fidelity check compares each output spectrum to its source and writes warnings into the audit trail if a peak moved too far, the overall texture changed by more than 5%, or the noise pattern changed by more than 25%.
Discovery options change which files are read and how samples are grouped, but spectral values are written as measured. Unification, and only unification, computes new values, which is why it is yellow-tagged and fully logged. The compliance file records the distinction; see Compliance.
Results explained
How to read the result card, including every stat, notice, and button.
The stats tiles
TOTAL FILES
How many candidate files were found, before duplicates were removed.
SAMPLES EXTRACTED
Samples written out, with the percentage of files that produced samples.
NOT CONVERTED
Files skipped, with the percentage of the total. Yellow when above zero. Double-click the tile for the breakdown by file type and reason.
A stacked bar under the tiles shows converted versus skipped at a glance. Coloured chips name each detected data type: green for the Raman family, yellow for FTIR, orange for mass spec, purple for NIR and UV.
Notices you might see on the card
| Notice | Meaning |
|---|---|
| “N converted file(s) produced no sample (spill_dropped)” | Under very heavy memory load, accumulated work is written to disk to protect your machine; if a file could not survive that spill, it is counted here openly and in the audit trail. Nothing fails silently. |
| “N unique physical measurements — M file-samples kept and tagged” | The folder contained raw and processed copies of the same measurement. Both are kept, joined by measurement_id and labelled with variant. |
| “N file(s) have an ambiguous axis unit … converted as Raman”, with a re-run button | The unit question from Spectroscopy types. One click re-runs the affected files as nanometre data, with your choice recorded in the audit trail. |
| “Derived output — data-altering methods applied” | Unification was on. The compliance file lists exactly which methods touched values. |
| “N anonymous structural formulation(s) captured” | Failure reports were saved locally while structure sharing was on. See Privacy and security. |
Buttons and logs on the card
- Preview spectra opens the full-screen viewer described in Spectrum preview.
- Open shows the output folder in Explorer.
- Request format review appears when files were skipped or an error occurred. It builds an anonymous, content-free description of the folder and sends it (or saves it locally) so the converter can learn the layout. Voluntary, and structure-only, exactly like the consent system.
- Audit trail (tamper-evident) shows the run’s record inside the app. The full log is a Pro feature; free plans see the first lines. Conversion log is always complete.
- On failure, Why it failed (bridge log tail) shows the last lines of the engine log, which support asks for when you report a problem.
Spectrum preview
A full-screen viewer for exploring, comparing, and annotating the spectra of any output folder. Everything here is display-only; your CSV files are never modified. The frame below is the real viewer layout, shown with one live spectrum and one frozen comparison layer.
Opening and layout
Every result card, history row, and imported folder offers Preview spectra. The viewer opens with three areas: the sample list on the left, the plot in the middle, and a layers and peaks panel on the right. A metadata strip below the plot shows the selected sample’s properties. Both side panels drag to resize. The sample list is virtualized, so folders with thousands of spectra scroll smoothly.
Choosing and navigating samples
- The group selector switches between data-type groups in the output; the counter shows “3 / 214”.
- ↑↓ or ←→ step through samples; Home and End jump to the ends; Esc closes. Neighbouring spectra are preloaded so stepping feels instant.
- Filter chips narrow the list by any metadata column: press + add filter…, pick a column, then a value. Filters combine (AND), and a second filter on the same column is declined with a toast.
- The name composer builds display names from metadata parts, for example “species-batch”, with a separator you can change. Handy when the raw IDs are opaque codes.
Display options per spectroscopy type
Each data type gets the display its field expects:
| Type | X axis | Y axis and extras |
|---|---|---|
| FTIR | Wavenumber, descending 4000 → 400 cm⁻¹ | Transmittance (%) by default with a true A = −log₁₀T absorbance mode; automatic dip markers; optional stacked waterfall layout. |
| Raman, SERS, UVRR | Raman shift, ascending | Intensity (a.u.), with noise-aware peak suggestions. |
| NIR / UV-Vis | Wavelength (nm) | Intensity, standard optical view. |
| MALDI / MS | m/z | Base-peak percentage normalisation available. |
The normalisation menu offers Raw (as stored), Min–max 0–1, SNV, Vector, and, for mass spec, Base peak %. These reshape the drawing only. FTIR additionally offers rubber-band baseline and smoothing for on-screen reading, also display-only.
Freeze, compare, annotate
- Freeze (F or the ❄ button) pins the current spectrum as a coloured overlay layer. Freeze more spectra to build a comparison; each layer keeps its own colour, peaks, and name.
- Peaks: click the plot to drop a marker on the target layer (the highlighted one); click a marker to remove it; double-click a peak label to rename it, for example “amide I”. For FTIR the panel is titled Dips and suggests absorption bands automatically.
- Range slider: zooms the x axis, with fine min/max boxes; the FTIR slider runs right-to-left to match the reversed axis.
- Labels stay anchored to their peak line even when you zoom or reverse the axis, and the strip along the top edge drags to make room for them.
- The metadata panel under the plot expands to a full column and value list of the selected sample.
Waterfall for FTIR
The ⇅ Stacked button separates spectra into lanes, the classic waterfall layout used for comparing many IR spectra. ⇅ Overlaid returns to a shared scale. Together with per-spectrum normalisation, this makes small differences between spectra visible without touching data.
Session memory (.eqcs)
The viewer saves its state (chosen group, filters, frozen layers, peak names, zoom) beside the output as a .eqcs file and restores it when you reopen the same folder. If the host cannot save sessions, a toast says so and everything else still works.
Preview reads from a compact sidecar index written during conversion, so opening a 5,000-sample output takes seconds and browsing stays fluid. The sidecar files are listed in Files in the output and are safe to delete.
Figure export
Turn the current preview view into a publication-ready PNG with a white background and full typographic control.
Starting an export
Freeze at least one spectrum (F), then press ⬇ Export. The export prints the frozen layers with their peak markers, honouring the current zoom range. Without a frozen layer, a toast explains what to do first.
What you can set
| Group | Options |
|---|---|
| Style | Modern, Classic, or Minimal preset; typeface (Helvetica/Arial, Segoe UI, Georgia, Times New Roman); text size. |
| Titles | Figure label (“Figure 1.”), title, caption with alignment, legend position on a nine-point grid, legend size and offset, optional legend overlap. |
| Numbers | Compact K/M thousands, decimal places, automatic avoidance of overlapping peak labels. |
| FTIR layout | Overlaid or stacked waterfall, stack offset multiplier, headroom above the curves. |
| Paper | A4 landscape or portrait, Letter, A5, journal single and double column, 16:9 slide, or any custom width and height in millimetres; 150, 300 (print), or 600 DPI. |
| Seal | Optional QR code embedding the SHA-256 content hash of the exported curves, or the product website, or off. |
A live preview on white shows the result as you type. ⬇ Save PNG… opens the normal Windows save dialog. Free and education plans include five exports per day; Pro is unlimited. The footer quota chip updates after each export.
History panel
Every run of this session in one list, with grouping, renaming, and re-opening.
Rows and badges
Each row names the source folder, its data types, and sample count, with badges: IMPORT for imported outputs, GROUP for group runs, and coloured type chips. Expand a row to see its full result card again, including preview and open buttons. Groups expand to show their child folders.
Selection and grouping
Click to select, Ctrl+click to add, Shift+click or drag for a range. Right-click offers “Group selected” for two or more rows, which folds them under one violet group entry. Double-click a group title to rename it. Group rows can be previewed as a whole: the viewer merges the child folders so you can flip between all their spectra in one session.
Editing type labels
Double-click a type badge to correct it. Choose from Raman, FTIR, SERS, UVRR, NIR, UV-Vis, MALDI-TOF MS, Mass spectrometry, or type a custom label up to 24 characters. Useful when you know the ground truth better than the detector, for example a Raman folder someone saved under “misc”.
Keeping and importing
- Free plans keep the session’s runs while the app is open; the panel states this plainly. Pro and education plans keep the recent-run list between sessions (the in-app list holds the last 20 runs).
- Import converted folder (top of the settings column) loads an existing eQC output that was made earlier, on this or another machine, into history as read-only. No re-conversion happens and no file changes. Re-importing the same output updates the existing entry instead of duplicating it.
Import an output
Bring existing results back into the app for previewing, checking, or sharing with a colleague.
What counts as an eQC output
A folder containing timestamped metadata_*.csv and spectra_*.csv files. That includes outputs made by eQCX, outputs from the command-line engine, and outputs from the eQC SDK pipeline. Anything else is declined with a toast that names the missing files.
How to import
- Press Import converted folder.
- In the picker, select one or many output folders (multi-select works as everywhere else).
- Each valid folder becomes a read-only history entry with its groups, sample counts, preview, and open-folder buttons. The status line reports how many folders and samples were imported.
Grouped outputs import as one entry with all child folders. The entry notes “Imported from existing eQC output — no files were changed”, which matters when you need to demonstrate that a shared dataset was only read.
Files in the output
Every file eQCX writes, what it contains, and why it is there.
Folder layout of one run
The timestamp YYYY-MM-DD_HH-MM-SS is identical on every file of one run. Re-running never overwrites: the second run sits beside the first as a separate snapshot, which is exactly what you want for lab notebooks.
The record files
| File | Contents |
|---|---|
| INDEX_*.csv | One row per event of the run: which folders were sources, one summary per group (type, samples, axis points, grid range), every skipped file with its reason, and converter statistics. |
| audit_log_*.csv | The decision log in four columns (section, item, value, detail): operator and machine, inputs, options used, per-group results, the SHA-256 of every output file, the self-check results, and the integrity chain hashes. Plain CSV, readable in any editor. |
| compliance_*.csv | The ALCOA+/Part 11 style assessment: which record-keeping properties hold (attributable, legible, original, accurate, integrity), and a separate section listing any data-altering method that ran. See Compliance. |
| alteration_report_*.csv | When unification ran: for every sample whose values were computed, the original range and step, the target range and step, the applied shift, and the fidelity warnings. Header only when the default pipeline ran, which is itself a useful fact. |
Files on your computer (outside the output)
| Location | Contains |
|---|---|
| C:\Users\<you>\.eqc_exporter\consent.json | Your anonymous-structure choice for this device. |
| C:\Users\<you>\.eqc_exporter\student.json | Your pseudonymous sign-in ID and email domain. Deleting this file erases the stored identity; that is also the erasure path support uses on request. |
| C:\Users\<you>\.eqc_exporter\telemetry_corpus\ | Locally saved structural failure recipes, when structure sharing is on. |
| C:\Users\<you>\.eqc_exporter\window.json | Window size and position. |
| Beside the app: eqc_bridge.log, eqc_exporter.log | Engine and app logs for diagnosing problems. |
Audit trail
What “tamper-evident” means concretely, and how to verify a result set months later.
Every run records its own history as it happens. The audit log names the operator, the machine, the exact software version, the start and end time, every input option, and each output file with its SHA-256 checksum and byte size. Two special rows close the loop:
output_chain_hash— a hash over all output checksums. Change any output file and the chain no longer matches.audit_body_hash— a hash over the log body itself, so the log cannot be edited without detection.
Verifying with the eQC SDK
The free, open-source eQC SDK reads the newest record set in an output folder and recomputes every checksum and the chain:
A self-check also runs inside every conversion: six structural checks on each emitted group (sample_id first, data_type second, text metadata, correct axis column, spectra columns match sample ids, NaN fraction under 0.5), and the PASS or FAIL result is written into the log. The summary row states whether all groups passed.
Records are described as “aligned with FDA 21 CFR Part 11 — aligned, not compliant”. Alignment means the record-keeping practices (attribution, timestamps, integrity, derivation logging) follow the regulation’s expectations. Formal compliance is a decision only your own quality or validation process can make, and the files are written to support that process.
Compliance
How the output separates facts from derived values, and what that means for regulated work.
The compliance file has two clearly separated sections. The first records the FDA-aligned facts of the run: who ran it (operator and machine), when (timestamps), that originals were preserved (sources untouched), that results are checkable (self-check plus checksum chain), and which capability tier produced them. The second section lists derived methods, and only those actually applied:
- Default run: the derived section states plainly that no data-altering transform was applied. The spectra you received are the spectra that were read.
- With unification or peak alignment: each applied method is listed with
alters_data = yes, and the per-sample provenance lives in the alteration report. - Report-only columns (peak counts, entropy, and similar) are marked as measurements of the data,
alters_data = no.
This separation mirrors how instrument data is treated in regulated labs: raw files stay raw, and derived results declare how they were derived. Because everything is CSV with checksums, your LIMS or ELN can ingest the records directly, and an auditor can verify integrity without the app.
Plans and limits
What each plan includes. Locked features are always visible in the app with a PRO tag, never hidden.
| Capability | Free | Education | Pro | Enterprise |
|---|---|---|---|---|
| Full conversion engine, all formats | ✓ | ✓ | ✓ | ✓ |
| Compliance sheet, alteration report, self-check | ✓ | ✓ | ✓ | ✓ |
| Structure report columns (peaks, entropy…) | ✓ | ✓ | ✓ | ✓ |
| Spectrum preview and navigation | ✓ | ✓ | ✓ | ✓ |
| Files / samples per run | 50 / 50 | server budget | Unlimited | Unlimited |
| Figure exports per day | 5 | server budget | Unlimited | Unlimited |
| Wavenumber unification (all grids, PCHIP, Lanczos) | — | ✓ | ✓ | ✓ |
| Peak alignment (±4 cm⁻¹) | — | ✓ | ✓ | ✓ |
| Full audit log in the app | first lines | ✓ | ✓ | ✓ |
| Persistent history between sessions | session only | ✓ | ✓ | ✓ |
| Offline licence tokens, custom deployments | — | — | — | ✓ |
How the tiers work
- Free is the built-in plan. No sign-up needed; convert and export right away within the per-run caps.
- Education unlocks every professional feature. Verified academic accounts keep it permanently; verified non-academic accounts get a 10-day full-feature trial. Volumes come from your monthly server budget (see Education program).
- Pro raises all caps to unlimited and adds the derived-method toolkit and full in-app records, for industry and heavy research use.
- Enterprise adds offline licence tokens and deployment support for locked-down environments, including air-gapped installers.
Signed-in users see their remaining budget as a chip in the footer, refreshed after each run. Hard safety ceilings apply to every server-granted number, so a misconfigured server can never set an absurd limit on your machine.
Education program
Free professional features for students, professors, and university courses.
Getting a seat
- Create a free account at eqcx.duviloper.com/#education with your academic email. Recognised academic domains register automatically with 20 seats per month; if your university’s seats are taken, you join a waitlist and the app suggests asking your lab manager for a campus plan.
- Sign in once in the app (first-run dialog) or later. Your licence page lives at eqcx.duviloper.com/profile with your plan, live remaining credits, and downloads.
- The footer chip shows your remaining samples and figure exports. Monthly budgets reset at the start of each month by the server’s clock.
Campus plans
A campus plan raises every student’s personal quota and adds a shared monthly pool for the whole lab, sized for courses (the invite template mentions 2,000 samples per student plus a 50,000-sample pool). When your university hits its seat cap, the app offers a ready-written email to the lab manager; your own free budget is never blocked in the meantime.
For course instructors
- Students need no installation beyond the installer, and no data leaves lab PCs, which keeps IT happy.
- Group conversion is designed for class datasets: everyone’s folder becomes one dataset with continuous sample IDs.
- The audit trail makes it easy to check who converted what, which helps when grading data-handling steps.
Offline and quotas
What happens without internet, and how usage counting behaves.
Conversion is always offline
Converting folders never requires the network. The licence sync is a background convenience: if the server cannot be reached, the app continues on its last known budget, reduced by what you already used, for a grace period of several days. Past the grace window (or a distant hard expiry), limits fall back to the built-in plan values. The app never locks and never destroys work because of a network problem.
How counting works
- Converted samples and figure exports are counted on your machine and reported after each run. Reports travel in small clamped batches, so a glitch cannot inflate your usage.
- When your remaining budget reaches zero, the app says “quota exhausted” and points at the reset date or the campus plan. It never silently truncates a conversion to fit.
- Monthly boundaries are decided by the server clock, so changing your PC’s date cannot extend a budget.
Install while online once, then run the course offline. Free-plan caps still apply offline, which is enough for typical course folders of a few dozen samples. Campus plans sync the moment any machine comes back online.
FAQ
The questions students and lab heads actually ask, answered without hedging.
+Does any of my data leave my computer?
No. Spectra, metadata, and results are processed and stored locally. The only network traffic in the whole product is (a) optional education-plan usage counts tied to a pseudonymous ID and (b) optional anonymous failure reports containing file structure only. Both are explained in Privacy and security, and both can be switched off.
+Do I need an account to use it?
Not for converting. The free plan works without sign-up within its per-run caps. An account only adds education or professional volumes and features.
+What exactly is the “eQC format”?
A pair of ordinary CSV files that always travel together: metadata.csv with one row per sample, and spectra.csv with one row per axis point and one column per sample. They link through the sample_id column. Because it is plain CSV with a fixed shape, any software that opens text files can read it. See What eQCX produces.
+How do I open the results in Excel, R, or Python?
Excel: double-click the CSVs; for the transposed spectra table use Data > From Text if your region formats numbers differently. Python: pandas.read_csv("spectra.csv"); the first column is the axis, the rest are samples. R: read.csv("spectra.csv"). Each spectra shard (01, 02, …) has the same header and can be joined by the axis column.
+My folder is messy: subfolders, zips, Excel sheets, a readme. Is that okay?
That is the normal case. Subfolders are walked, archives are unpacked, non-spectral files are ignored or mined for metadata. The result card tells you what was used, what was skipped, and why.
+Some files were “not converted”. Did I lose data?
Nothing is lost or modified; the originals are untouched. Double-click the NOT CONVERTED tile for the breakdown. Common reasons: the file is a byte-identical duplicate of one already converted, the file contains no spectrum structure, or it is one of the four vendor binary formats listed in Supported file formats that must first be re-exported from the instrument software.
+My folder has both raw and processed versions of the same spectra. What happens?
Both are converted. They share a measurement_id, and each row is labelled with its variant (raw, processed, baseline-corrected, and so on). The result card reports how many unique physical measurements versus tagged file-samples were written, so you can filter either set later.
+Should I turn on “Unify per modality”?
Only if your analysis software needs every spectrum on exactly the same axis, for example a principal component analysis over the whole set. The default keeps measured values untouched, which is the right choice for archiving and for most plotting. Unification computes new values, which is why it is tagged, logged, and paired with the alteration report and fidelity checks.
+Is eQCX FDA compliant?
The records are aligned with FDA 21 CFR Part 11 expectations, and the tool itself says “aligned, not compliant”. Compliance is decided by your quality system validating how you use the tool. The record files are designed so that such a validation has everything it needs: attribution, timestamps, integrity hashes, and explicit derived-method declarations.
+Why do output file names have such long timestamps?
So a re-run never overwrites your previous results. Each run is a complete snapshot, and the stamp tells you when it was made. The SDK always picks the newest set automatically when verifying or reading.
+Can I use it with patient-derived or unpublished industry spectra?
The design goal is exactly that: local processing, no upload path for content, no account requirement, and verifiable records. Your institutional rules on local storage still apply, and the audit trail helps you demonstrate where each result came from.
+Does it work behind a corporate firewall or fully offline?
Yes. Conversion and preview never call out. Licence sync resumes when connectivity returns, within the grace window described in Offline and quotas. Enterprise deployments add fully offline licence tokens.
+How do I report a file that will not convert?
On the result card, press “Request format review”. It packages an anonymous, content-free description of the folder (shapes and formatting, no spectra, no names) and sends it for engineering review, or saves it locally for you to attach. If structure sharing is on, failures were already captured the same anonymous way.
+Which version produced my files, and how do I pin it?
The audit log’s header section records the exact engine version (for example eQC-X v1.0.0) with machine and operator. Cite that row when a methods section or a validation needs a pinned version. This wiki documents version 1.0.0 of the engine and version 1.0 of the eQC format.
Troubleshooting
Every common message, what causes it, and the fix. Messages are quoted as the app shows them.
| What you see | Why | Fix |
|---|---|---|
| “Destination folder is not set up.” | No destination chosen. | Press Browse next to the destination field and pick a folder, then Export again. |
| “container_unsupported” for .0 / .spa / .wdf / .sp files | Those vendor binary formats have no reliable public reader. | Re-export from the instrument software as CSV, Excel, or JCAMP-DX (.jdx), then convert again. The skipped list names every affected file. |
| Ambiguous unit question on the result card | The axis values fit both nm and cm⁻¹, and no header gave a hint. | Check one spectrum’s expected range, then press “Treat as UV-Vis/NIR (nm) and re-run” if it is optical data. Your choice is recorded in the audit trail. |
| “Output files are locked” | The output CSVs are open in Excel or another program. | Close the files there, then press Retry in the dialog. |
| “QUOTA exhausted” | The monthly budget of your plan is used up. | Wait for the month to reset, or move to a campus or Pro plan. Nothing was truncated; the run stopped instead. |
| “CAPABILITY denied <feature>” | The run asked for a feature your plan does not grant (for example unification on Free). | Use the default pipeline, or activate Education or Pro. Locked controls show the PRO tag in the app. |
| “LICENSE revoked” | The account was revoked by its administrator. | Contact support if this is unexpected. Revocation survives reinstalls because it is tied to the account ID. |
| “No spectra found in that output folder.” in preview | The folder is not an eQC output. | Import the parent output folder, or convert the source first. Valid outputs contain metadata_*.csv and spectra_*.csv. |
| “Session save unavailable …” toast in preview | The session (.eqcs) store is unavailable in this environment. | Previewing still works fully; only the remember-state feature is off. Restarting the app re-enables it. |
| “Daily PNG export limit reached (N/day).” | Free or education daily figure cap used. | Pro is unlimited; education budgets refresh daily and monthly. The footer chip shows what is left. |
| Windows SmartScreen warned about the installer | New releases take time to build reputation. | Choose “More info” then “Run anyway”. The installer is code-signed by Duviloper, and the publisher name is shown on that dialog. |
| Antivirus flagged a component | Some heuristics dislike packaged engines. | Check the publisher signature, and report false positives to support, who ship fixed builds. The app performs no network activity beyond the optional syncs described in Privacy and security. |
| Conversion seems stuck at “Scanning folder…” | Very large folders (tens of thousands of files) take a while to index. | Wait; the counter line updates as files are seen. Cloud folders are copied locally first, which adds time once. |
| “spill_dropped” appeared in the stats | System memory was heavily loaded and some accumulated work had to be spilled. | Re-run with fewer folders in the batch, or close memory-heavy apps. The audit trail lists exactly which files were affected. |
Open the result card’s “Why it failed (bridge log tail)” and copy the last lines, plus the audit_log_*.csv of the run. These contain no spectra; they contain the decisions and errors, which is what support needs.
Keyboard shortcuts
Every shortcut in the app, grouped by where it works.
Spectrum preview
- ↑ ↓ / ← →
- Previous / next sample
- Home / End
- First / last sample
- F
- Freeze the current spectrum as an overlay layer
- Esc
- Close the preview
Preview widgets
- Drag the top edge of the plot
- Make more room for peak labels
- Mouse wheel over a number box
- Nudge the value (Shift gives bigger steps)
- Double-click a layer name, group title, or peak label
- Rename it
- Click near an existing peak marker
- Remove that marker
Everywhere
- Ctrl K or /
- Search this wiki
- Ctrl+click / Shift+click / Ctrl+A
- Multi-select in every folder picker and in the history list
- Enter / Esc
- Commit / cancel any inline rename
- Double-click the NOT CONVERTED tile
- Open the skip breakdown
- Double-click the settings divider
- Reset the column widths
Glossary
Every technical term used in this wiki and the app, in one plain-language list.
| Term | Plain-language meaning |
|---|---|
| Spectrum | A measurement of intensity across an axis, for example how strongly a sample scatters light at each wavenumber. |
| Wavenumber (cm⁻¹) | The axis unit of Raman and infrared spectra. Higher values correspond to faster molecular vibrations. |
| Raman shift | Wavenumber difference from the laser line; the x axis of a Raman spectrum. |
| Wavelength (nm) | The axis unit of optical spectra such as NIR and UV-Vis. |
| m/z | Mass-to-charge ratio, the axis of mass spectra such as MALDI-TOF. |
| Transmittance / Absorbance | Two ways to show infrared intensity: how much light passes through, or how much is absorbed. The preview can switch between them. |
| Metadata | Descriptive information about samples: species, treatment, operator, date, and so on. |
| Sample | One measured spectrum plus its metadata row in the output. |
| Measurement / variant | One physical measurement may exist as raw and processed files. They share a measurement ID and are tagged with their variant. |
| Baseline | The slowly varying background under the peaks, often from fluorescence or drift. |
| SNV | Standard normal variate: rescaling each spectrum to zero mean and unit spread so shapes can be compared fairly. |
| Despiking | Removing single wild points (cosmic-ray spikes) from Raman spectra. |
| Resampling / interpolation | Estimating intensity values on a new axis. Used only when you enable unification. |
| Grid | The list of axis points a group is written on. |
| Unification | Resampling every spectrum of a type onto one shared grid. A derived, logged operation. |
| Archive | A compressed container such as .zip or .7z. eQCX unpacks these automatically. |
| Bundle | A dataset split into role files (axis, intensities, labels) that belong together. |
| Checksum (SHA-256) | A fingerprint of a file. Change one byte and the fingerprint changes, which is how the audit trail proves files were not altered. |
| Audit trail | The timestamped log of a conversion: inputs, options, outputs, and checksums. |
| Tier / plan | Your capability level: Free, Education, Pro, or Enterprise. |
| Quota | Your monthly allowance of converted samples and figure exports on server-backed plans. |
| Shard | One piece of a very large spectra table (spectra_01.csv, spectra_02.csv, …), all with the same header. |