Recent changes to Sugar Database

Sugar Database modified by glycolab

glycolab — Mon, 25 May 2026 20:33:46 -0000

--- v2
+++ v3
@@ -63,51 +63,30 @@

 Test masses are generated as random values within the sugar oxonium ion mass range (100–400 Da): a random integer base with a fractional part of 0–0.2 Da (or 0–0.25 Da above 250 Da). Each candidate is checked against all real sugar masses at 0.0075 Da tolerance to avoid accidental overlap. The water loss mass is computed as ox_mass1 − 18.011 Da. The number of test masses is approximately equal to the number of real sugar entries (1:1 ratio).

-### Curated vs. Chemspace Test Masses
+### Curated vs. Chemspace ("extensive") Test Masses

-The curated database and chemspace database each have their own independent set of test masses, tagged separately (`curated_test` and `chemspace_test`). When switching between views in the [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/), each view shows only its corresponding test masses, ensuring a fair comparison at each scale.
+The curated database (small set of empirical sugar masses) and chemspace ("extensive" chemical sugar space) database each have their own independent set of test masses, tagged separately (`curated_test` and `chemspace_test`).  Test masses should not be removed from the provided database.

-Test masses should not be removed from the curated database.
-
-## Chemspace Database (Optional)
+## Chemspace Database (Optional use)

 ### What It Contains

-The chemspace database is a hardcoded Python module (`chemspace_database.py`) containing 3,332 chemically plausible monosaccharide compositions systematically enumerated within a defined elemental space (C, H, O, N, S) and mass range (~83–382 Da). Each entry is identified by its molecular formula (e.g. C5H8O2, C8H15N1O6) and follows the same diagnostic mass pair structure as the curated list. The database also includes 3,332 fixed random test masses as negative controls.
+The Chemspace database contains 3,332 chemically plausible monosaccharide compositions systematically enumerated within a defined elemental space (C, H, O, N, S) and mass range (~83–382 Da). Each entry is represented by its molecular formula (e.g. C5H8O2, C8H15NO6) and follows the same diagnostic mass-pair structure as the curated database. The database also includes 3,332 fixed random test masses used as negative controls. These entries are included together with the empirical sugars in the provided OX_DB_COMBINED_v03.xlsx reference file. Empirical sugars are labelled as "curated" in the list column, whereas theoretical Chemspace entries are labelled as "extensive".

-### How to Enable
+### How to Use

-Set the `CHEMSPACE_SEARCH` environment variable:
+The pipeline automatically searches both the curated and Chemspace databases.

-```bash
-docker run -p 8051:8051 -e CHEMSPACE_SEARCH=True \

-  -v "$(pwd)/Input:/app/Input" -v "$(pwd)/Output:/app/Output" oxonium-browser
-```
+### How to see Chemspace enhanced output in the Dashboard

-When disabled (default), the pipeline behaves exactly as in curated-only mode. For the full parameter reference, see [Detection Parameters](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20Parameters/).
-
-### How It Works
-
-When enabled:
-
-1. The pipeline reads the user's curated Excel file as normal
-2. It imports the hardcoded chemspace database
-3. Curated and chemspace entries are merged, with automatic deduplication — if a chemspace mass overlaps with a curated entry (within 0.001 Da), the curated version is kept, preserving names like "Hex" instead of "C6H12O6"
-4. The scanner runs once on the full merged list (~6,600 ions)
-5. The [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/) provides a radio toggle to switch between curated, chemspace, and combined views
-
-### Dashboard Behavior
-
-When chemspace search is active, switching to chemspace or combined view automatically sets stricter default thresholds (counts ≥ 25, intensity ≥ 1.0%, presence ≥ 0.025%) to manage the larger search space. Switching back to curated restores the original defaults.
+Switching to the combined view displays both curated matches and additional Chemspace matches. This automatically applies stricter default thresholds (counts ≥ 25, intensity ≥ 1.5%, presence ≥ 0.025%) to account for the larger search space. Switching back to curated view restores the original thresholds.

 ### Interpreting Chemspace Results

 Genuine sugar signals stand out even with >3,000 candidates. Key indicators:
-

 - **High counts and intensity** — well above the test mass metrics
 - **Water loss partners** — the match table groups related masses; a group containing both the intact ion and its water loss is stronger evidence
 - **Co-occurrence** — genuine fragments from the same glycan should cluster together in the co-occurrence plot
-
 Some molecular formulas may consistently appear across different organisms as top hits without being sugars — these likely represent dipeptide fragments or other non-glycan contaminants.

 ### From Formula to Sugar Identity
@@ -117,9 +96,9 @@
 ### When to Use Chemspace Search

 **Recommended for:**
-- Organisms with poorly characterized glycosylation 
+- Organisms with not or only poorly characterized metabolism and glycosylation 

 - Discovery experiments looking for unexpected sugar modifications
-- Comparing curated results against the broader chemical space
+- Comparing curated results against the broader chemical space to ensure complete coverage

 ## Database Comparison

Sugar Database modified by Dinko Soic

Dinko Soic — Wed, 18 Mar 2026 14:01:27 -0000

--- v1
+++ v2
@@ -57,7 +57,7 @@

 ### Purpose

-The database includes entries named `Ox_test_1`, `Ox_test_2`, etc. These are random masses serving as built-in negative controls for empirical false discovery assessment. Any detections of test masses represent random chance matches, providing a direct estimate of the false positive rate at the current threshold settings. For guidance on using test masses to optimize thresholds, see [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20metrics/).
+The database includes entries named `Ox_test_1`, `Ox_test_2`, etc. These are random masses serving as built-in negative controls for empirical false discovery assessment. Any detections of test masses represent random chance matches, providing a direct estimate of the false positive rate at the current threshold settings. For guidance on using test masses to optimize thresholds, see [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20Metrics/).

 ### How Test Masses Are Generated

@@ -84,7 +84,7 @@
   -v "$(pwd)/Input:/app/Input" -v "$(pwd)/Output:/app/Output" oxonium-browser
 ```

-When disabled (default), the pipeline behaves exactly as in curated-only mode. For the full parameter reference, see [Detection Parameters](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20parameters/).
+When disabled (default), the pipeline behaves exactly as in curated-only mode. For the full parameter reference, see [Detection Parameters](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20Parameters/).

 ### How It Works

Sugar Database modified by Dinko Soic

Dinko Soic — Wed, 18 Mar 2026 13:56:53 -0000

Sugar Database

Overview

Oxonium Browser uses a sugar oxonium ion database to define which masses to search for in MS2 spectra. Each entry specifies a diagnostic mass pair: the intact oxonium ion ([M+H−H₂O]⁺) and its water loss fragment ([M+H−2H₂O]⁺). Both masses must be present within the mass error tolerance for a positive detection.

Two databases are available:

Curated database — user-provided Excel file with named sugars and test masses
Chemspace database — optional hardcoded comprehensive chemical space of >3,300 monosaccharide compositions

Curated Database

File Format

The curated database is an Excel file (.xlsx) placed in the Input directory. The current version ships as OX_DB_CURATED_v03.xlsx.

Required Columns

Column	Description	Example
`Oxonium`	Unique name for the sugar	HexNAc
`ox_mass1`	Primary diagnostic mass (oxonium ion)	204.0867
`ox_mass2`	Secondary diagnostic mass (water loss)	186.0761

Additional columns (Example sugar, Name, Monoisotopic Mass, M+H+) may be present for reference but are not required by the software.

Included Sugars

The curated database covers common, rare, and derivative monosaccharides compiled from CSDB, KEGG, and published glycan literature, including pentoses, hexoses, heptoses, ulosonic acids, deoxy sugars, amino sugars, acetylated and methylated derivatives, and others.

Diagnostic Mass Pairs

Each sugar is defined by two diagnostic masses rather than a single mass. Requiring both the intact ion and its water loss product significantly reduces false positive detections compared to single-mass matching.

For most sugars, the pair consists of:

ox_mass1 = [M+H−H₂O]⁺ (one water loss from the protonated sugar)
ox_mass2 = [M+H−2H₂O]⁺ (two water losses)

For some sugars (e.g. uronic acids), ox_mass2 may represent a carboxylic acid loss fragment instead.

Adding Custom Sugars

To add a new sugar to the curated database:

Determine the exact monoisotopic mass of your sugar
Calculate the two diagnostic masses:
ox_mass1 = [M+H]⁺ − H₂O = monoisotopic mass + 1.00728 − 18.01056
ox_mass2 = ox_mass1 − 18.01056
Add a new row to the Excel file with a unique name in the Oxonium column
Enter the diagnostic masses in ox_mass1 and ox_mass2
Save the file maintaining the same format

The tool will automatically include all entries during the next analysis run. Consider testing with a known positive control sample first.

Test Masses (Negative Controls)

Purpose

The database includes entries named Ox_test_1, Ox_test_2, etc. These are random masses serving as built-in negative controls for empirical false discovery assessment. Any detections of test masses represent random chance matches, providing a direct estimate of the false positive rate at the current threshold settings. For guidance on using test masses to optimize thresholds, see Detection Metrics.

How Test Masses Are Generated

Test masses are generated as random values within the sugar oxonium ion mass range (100–400 Da): a random integer base with a fractional part of 0–0.2 Da (or 0–0.25 Da above 250 Da). Each candidate is checked against all real sugar masses at 0.0075 Da tolerance to avoid accidental overlap. The water loss mass is computed as ox_mass1 − 18.011 Da. The number of test masses is approximately equal to the number of real sugar entries (1:1 ratio).

Curated vs. Chemspace Test Masses

The curated database and chemspace database each have their own independent set of test masses, tagged separately (curated_test and chemspace_test). When switching between views in the dashboard, each view shows only its corresponding test masses, ensuring a fair comparison at each scale.

Test masses should not be removed from the curated database.

Chemspace Database (Optional)

What It Contains

The chemspace database is a hardcoded Python module (chemspace_database.py) containing 3,332 chemically plausible monosaccharide compositions systematically enumerated within a defined elemental space (C, H, O, N, S) and mass range (~83–382 Da). Each entry is identified by its molecular formula (e.g. C5H8O2, C8H15N1O6) and follows the same diagnostic mass pair structure as the curated list. The database also includes 3,332 fixed random test masses as negative controls.

How to Enable

Set the CHEMSPACE_SEARCH environment variable:

docker run -p 8051:8051 -e CHEMSPACE_SEARCH=True \
  -v "$(pwd)/Input:/app/Input" -v "$(pwd)/Output:/app/Output" oxonium-browser

When disabled (default), the pipeline behaves exactly as in curated-only mode. For the full parameter reference, see Detection Parameters.

How It Works

When enabled:

The pipeline reads the user's curated Excel file as normal
It imports the hardcoded chemspace database
Curated and chemspace entries are merged, with automatic deduplication — if a chemspace mass overlaps with a curated entry (within 0.001 Da), the curated version is kept, preserving names like "Hex" instead of "C6H12O6"
The scanner runs once on the full merged list (~6,600 ions)
The dashboard provides a radio toggle to switch between curated, chemspace, and combined views

Dashboard Behavior

When chemspace search is active, switching to chemspace or combined view automatically sets stricter default thresholds (counts ≥ 25, intensity ≥ 1.0%, presence ≥ 0.025%) to manage the larger search space. Switching back to curated restores the original defaults.

Interpreting Chemspace Results

Genuine sugar signals stand out even with >3,000 candidates. Key indicators:

High counts and intensity — well above the test mass metrics
Water loss partners — the match table groups related masses; a group containing both the intact ion and its water loss is stronger evidence
Co-occurrence — genuine fragments from the same glycan should cluster together in the co-occurrence plot

Some molecular formulas may consistently appear across different organisms as top hits without being sugars — these likely represent dipeptide fragments or other non-glycan contaminants.

From Formula to Sugar Identity

Chemspace hits are identified by molecular formula only (e.g. C8H15N1O6). To determine the actual sugar identity, cross-reference the formula with sugar databases (CSDB, KEGG, GlyTouCan), check whether the mass matches known sugar derivatives for the organism, and validate with complementary experiments.

When to Use Chemspace Search

Recommended for:

Organisms with poorly characterized glycosylation
Discovery experiments looking for unexpected sugar modifications
Comparing curated results against the broader chemical space

Database Comparison

Property	Curated	Chemspace
Size	~35 sugars + ~35 test masses	~3,300 sugars + ~3,300 test masses
Names	Descriptive (Hex, HexNAc, dHex)	Molecular formulas (C6H12O6, C8H15NO6)
Source	Literature, CSDB, KEGG	Systematic generation of compositions
Customizable	Yes (edit Excel file)	No (hardcoded)
Test masses	In Excel file, user-editable	Hardcoded, fixed across all runs
Always active	Yes	Only with `CHEMSPACE_SEARCH=True`

Back to Home