Recent changes to Detection Parameters

Detection Parameters modified by Dinko Soic

Dinko Soic — Wed, 18 Mar 2026 14:00:49 -0000

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

-For guidance on how to evaluate detection results and optimize thresholds interactively, see [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20metrics/).
+For guidance on how to evaluate detection results and optimize thresholds interactively, see [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20Metrics/).

 ## Oxonium Ion Detection Parameters

@@ -93,7 +93,7 @@


 1. **Start with defaults** — run with default parameters on your first sample
 2. **Check mass error plots** — verify calibration quality in the [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/), adjust MASS_ERROR if needed
-3. **Assess test mass performance** — check if test masses appear in the match table; adjust thresholds using the workflow described in [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20metrics/)
+3. **Assess test mass performance** — check if test masses appear in the match table; adjust thresholds using the workflow described in [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20Metrics/)
 4. **Consider biological context** — bacterial samples may need lower thresholds than mammalian
 5. **Enable amino acid markers** if contamination is a concern
 6. **Enable chemspace search** if you suspect rare or unusual sugars not covered by the curated database

Detection Parameters modified by Dinko Soic

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

--- v1
+++ v2
@@ -1,139 +1,109 @@
-# Oxonium Ion Detection Parameters
+# Detection Parameters

-## Introduction to Detection Parameters
+## Introduction

-Oxonium Browser uses three critical parameters to control the sensitivity and specificity of oxonium ion detection. Understanding how to optimize these parameters is essential for achieving reliable results while minimizing false positive detections. These parameters work together to define what constitutes a valid oxonium ion match in your MS2 spectra.
+Oxonium Browser uses several configurable parameters to control the sensitivity, specificity, and scope of oxonium ion detection. These are set as environment variables in the Docker run command. Default values work well for most high-resolution proteomics datasets; optimization may be needed for specific instruments or sample types.

-The default parameter values have been established through extensive testing on diverse shotgun proteomics datasets and provide a robust starting point for most analyses. However, optimization may be necessary depending on your specific experimental conditions, sample types, and analytical goals.
+Only specify parameters you want to change from defaults:

-## Key Detection Parameters
+```bash
+docker run -p 8051:8051 -e MASS_ERROR=0.002 -e INTENSITY_THRESHOLD=0.1 \

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

-### 1. Mass Error Tolerance
+For guidance on how to evaluate detection results and optimize thresholds interactively, see [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20metrics/).

-**Definition:** The maximum allowed mass difference (in Daltons) between the theoretical oxonium ion mass and the observed peak in the MS2 spectrum for a match to be considered valid.
+## Oxonium Ion Detection Parameters

-**Technical Implementation:**
-- Applied to both diagnostic masses (oxonium ion and water loss fragment)
-- Uses absolute mass difference: |observed_mass - theoretical_mass| ≤ tolerance
-- Both masses must be within tolerance for positive detection
-- Monitor mass error plots to verify calibration quality
+### MASS_ERROR (Default: 0.001 Da)

-**Default Settings:**
-- **Default: 0.001 Da** - Appropriate for high-resolution instruments 
-- **High Resolution: 0.0005 Da** - For instruments with sub-ppm mass accuracy
-- **Lower Resolution: 0.005-0.01 Da** - For lower-resolution instruments
+Maximum allowed mass difference between the theoretical oxonium ion mass and the observed peak for a match to be valid. Applied to both diagnostic masses — both must be within tolerance for a positive detection.

-**Instrument-Specific Recommendations:**
+**Instrument-specific recommendations:**
+- **High-resolution (sub-ppm accuracy):** 0.0005–0.001 Da
+- **Standard high-resolution:** 0.001 Da (default)
+- **Medium/lower resolution:** 0.002–0.005 Da

-**High-Resolution Instruments:**
-- 0.001 Da provides decent specificity
-- Consider 0.0005 Da for instruments with demonstrated sub-ppm accuracy
+**Optimization:** After processing, check the mass error distribution plot in the [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/). The average peptide fragment mass error for 90% of masses is reported — use this as a guide. 

-**Medium-Resolution Instruments:**
-- 0.002-0.005 Da may be more appropriate

- Pay special attention to test mass performance
-- Increase tolerance if few genuine hits are detected
+**Warning signs:**
+- Test masses detected frequently → tolerance too broad
+- Known oxonium ions missing → tolerance too narrow or calibration issues

-**Optimization Strategy:**
-1. **Start with 0.001 Da** for high-resolution data
-2. **Check mass error distribution plots** in the dashboard
-3. **Adjust based on calibration quality** - widen the mass error window based on the distribution plots
-4. **Monitor test mass detection** - high rates suggest tolerance is too broad
-5. **Consider instrument specifications** and typical mass accuracy performance
+### INTENSITY_THRESHOLD (Default: 0.25%)

-**Warning Signs:**
-- **Test masses detected frequently:** Mass tolerance may be too broad
-- **Known oxonium ions not detected:** Mass tolerance may be too narrow or calibration issues
-- **Asymmetric mass error distribution:** Systematic calibration problems
+Minimum normalized intensity for an oxonium ion to be counted as detected. Expressed as a percentage of total spectrum intensity, calculated as the average intensity of the diagnostic mass pair divided by total spectrum intensity.

-### 2. Intensity Threshold
+**Recommended ranges:**
+- **Conservative (complex samples):** 0.5–1.0%
+- **Default:** 0.25%
+- **Sensitive (rare sugars):** 0.1–0.15%

-**Definition:** The minimum normalized intensity required for an oxonium ion to be considered detected. This value represents the percentage of total spectrum intensity that the oxonium ion must contribute to qualify as a positive detection.
+This parameter sets the threshold for the scanning step. The [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/) provides additional interactive filtering on top of this value.

-**Technical Implementation:**
-- Calculated as: average intensity of the oxonium ion pair (oxonium ion and water loss fragment)/ total spectrum intensity) × 100
-- Applied after both diagnostic masses are found within mass tolerance
-- Expressed as percentage of total spectrum intensity
+### AMINO_ACID_MARKER (Default: False)

-**Default Settings:**
-- **Default: 0.25%** - Established from analysis of diverse proteomics reference samples
-- **Conservative: 0.5-1.0%** - For high-confidence detections in complex samples
-- **Sensitive: 0.1-0.15%** - For detecting low-abundant or rare sugars
+When enabled, requires the presence of at least one amino acid marker ion (147.113 or 175.119 m/z, corresponding to lysine and arginine immonium ions) alongside the oxonium ion pair. This confirms the spectrum originates from a glycopeptide rather than a free sugar or other glycoconjugate.

-**Practical Considerations:**
-- Higher thresholds reduce false positives but may miss genuine low-abundance signals
-- Lower thresholds increase sensitivity but require careful validation using test masses
-- Instrument sensitivity and spectrum quality significantly impact optimal threshold values
-- Consider your biological context - bacterial samples often require lower thresholds than mammalian samples
+**Enable when:**
+- Samples may contain free sugar contamination
+- Distinguishing glycopeptides from glycolipids is important

-### 3. Amino Acid Marker Requirement
+**Keep disabled when:**
+- Running initial discovery experiments
+- Maximum sensitivity is desired

-**Definition:** An optional validation step that requires the presence of specific amino acid fragment ions (175.11895 and 147.11280 m/z) alongside oxonium ions to confirm glycopeptide origin rather than free sugar contamination.
+### CHEMSPACE_SEARCH (Default: False)

-**Technical Implementation:**
-- Searches for either 175.11895 m/z (Arginine immonium ion) OR 147.11280 m/z (Lysine immonium ion)
-- Applied only when amino acid marker option is enabled
-- Uses the same mass tolerance as oxonium ion detection
-- Requires at least one marker mass to be present for positive detection
+When enabled, the pipeline imports a hardcoded chemical space database containing >3,300 additional monosaccharide compositions alongside the user-provided curated database. Both are scanned in a single run. The dashboard then displays a radio toggle to switch between curated, chemspace, and combined views.

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

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

-**When to Enable Amino Acid Markers:**
+When chemspace or combined view is selected in the dashboard, thresholds auto-adjust to stricter defaults (counts ≥ 25, intensity ≥ 1.0%, presence ≥ 0.025%) to manage the larger search space. For details on the chemspace database, test masses, and interpretation, see [Sugar Database](https://sourceforge.net/p/oxoniumbrowserx/wiki/Sugar%20Database/).

-**Recommended for:**
-- Samples with potential free sugar contamination
-- Complex biological matrices
-- When distinguishing glycopeptides from glycolipids or free glycans is critical
-- Validation of novel or unexpected oxonium ion detections
+## SAGE Search Parameters

-**Not Recommended for:**
-- Highly purified glycoprotein samples
-- Samples where peptide fragmentation may be limited
-- Initial discovery experiments where maximum sensitivity is desired
+These control the peptide database search used to identify and exclude unmodified peptide spectra before oxonium ion detection. For most experiments the defaults are appropriate.

-**Optimization Approach:**
-1. **Initial screening without markers** to assess overall oxonium ion landscape
-2. **Enable markers for validation** of interesting detections
-3. **Compare results** with and without markers to understand impact
-4. **Consider biological context** - contamination-prone samples benefit more from markers
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `SAGE_MIN_PEPTIDE_LENGTH` | 6 | Minimum peptide length |
+| `SAGE_MISSED_CLEAVAGES` | 2 | Maximum missed cleavages (trypsin KR/P) |
+| `SAGE_GENERATE_DECOYS` | True | Generate decoy sequences for FDR control |
+| `SAGE_PREC_TOL` | 20 | Precursor mass tolerance (ppm) |
+| `SAGE_FRAG_TOL` | 20 | Fragment mass tolerance (ppm) |
+| `SAGE_FDR` | 1 | FDR threshold (percent) |

+Static modifications: Carbamidomethylation (C). Variable modifications: Oxidation (M).

-### Parameter Optimization Workflow
+## Mass Calibration Parameters (Not User-Configurable)

-**Step 1: Establish Baseline**
-- Start with default parameters (0.25% intensity, 0.001 Da mass error, no markers)
-- Analyze test mass performance
-- Identify major oxonium ion signals
+These are internal parameters used by the recalibration module (see [System Architecture](https://sourceforge.net/p/oxoniumbrowserx/wiki/System%20Architecture/) for details):

-**Step 2: Optimize Mass Tolerance**
-- Check mass error distribution plots
-- Adjust based on instrument performance
-- Ensure test masses remain low
+- Reference peaks: 147.113, 175.119, 201.123, 215.139, 228.134, 258.145, 292.129 m/z
+- Global calibration tolerance: 20 ppm
+- Per-spectrum calibration tolerance: 10 ppm
+- Minimum reference peak matches for global calibration: 500 spectra per peak
+- Minimum reference peak matches for per-spectrum calibration: 3 peaks per spectrum

-**Step 3: Fine-tune Intensity Threshold**
-- Use test mass behavior as guide
-- Consider biological expectations
-- Balance sensitivity vs. specificity
+## Parameter Optimization Workflow

-**Step 4: Evaluate Amino Acid Markers**
-- Compare results with/without markers
-- Assess impact on known positive controls
-- Decide based on sample complexity
+1. **Start with defaults** — run with default parameters on your first sample
+2. **Check mass error plots** — verify calibration quality in the [dashboard](https://sourceforge.net/p/oxoniumbrowserx/wiki/Dashboard%20Guide/), adjust MASS_ERROR if needed
+3. **Assess test mass performance** — check if test masses appear in the match table; adjust thresholds using the workflow described in [Detection Metrics](https://sourceforge.net/p/oxoniumbrowserx/wiki/Detection%20metrics/)
+4. **Consider biological context** — bacterial samples may need lower thresholds than mammalian
+5. **Enable amino acid markers** if contamination is a concern
+6. **Enable chemspace search** if you suspect rare or unusual sugars not covered by the curated database

-**Step 5: Validation**
-- Examine retention time profiles for consistency
-- Look for co-occurring related sugars
-- Validate against biological expectations
+## Troubleshooting

-## Common Parameter Issues and Solutions
+**Many test masses detected:** MASS_ERROR too broad or INTENSITY_THRESHOLD too low. Tighten mass tolerance first, then increase intensity threshold.

-### Problem: High Test Mass Detection
-**Likely Causes:** Mass tolerance too broad, intensity threshold too low
-**Solutions:** Tighten mass tolerance first, then increase intensity threshold
+**No oxonium ions detected:** Parameters too strict, calibration issues, or sample lacks glycosylation. Check mass error plots, lower INTENSITY_THRESHOLD, verify sample preparation.

-### Problem: No Oxonium Ions Detected
-**Likely Causes:** Thresholds too stringent, calibration issues, sample lacks glycosylation
-**Solutions:** Lower intensity threshold, check mass error plots, verify sample preparation
+**Expected sugars missing:** Relax parameters systematically. Disable AMINO_ACID_MARKER if enabled. Check instrument performance and calibration quality.

-### Problem: Expected Sugars Not Detected
-**Likely Causes:** Parameters too strict, amino acid markers too restrictive, instrument issues
-**Solutions:** Systematically relax parameters, disable markers temporarily, check instrument performance
+[Back to Home](https://sourceforge.net/p/oxoniumbrowserx/wiki/Home/)

Detection parameters modified by Dinko Soic

Dinko Soic — Tue, 10 Jun 2025 06:57:39 -0000

Oxonium Ion Detection Parameters

Introduction to Detection Parameters

Oxonium Browser uses three critical parameters to control the sensitivity and specificity of oxonium ion detection. Understanding how to optimize these parameters is essential for achieving reliable results while minimizing false positive detections. These parameters work together to define what constitutes a valid oxonium ion match in your MS2 spectra.

The default parameter values have been established through extensive testing on diverse shotgun proteomics datasets and provide a robust starting point for most analyses. However, optimization may be necessary depending on your specific experimental conditions, sample types, and analytical goals.

Key Detection Parameters

1. Mass Error Tolerance

Definition: The maximum allowed mass difference (in Daltons) between the theoretical oxonium ion mass and the observed peak in the MS2 spectrum for a match to be considered valid.

Technical Implementation:
- Applied to both diagnostic masses (oxonium ion and water loss fragment)
- Uses absolute mass difference: |observed_mass - theoretical_mass| ≤ tolerance
- Both masses must be within tolerance for positive detection
- Monitor mass error plots to verify calibration quality

Default Settings:
- Default: 0.001 Da - Appropriate for high-resolution instruments
- High Resolution: 0.0005 Da - For instruments with sub-ppm mass accuracy
- Lower Resolution: 0.005-0.01 Da - For lower-resolution instruments

Instrument-Specific Recommendations:

High-Resolution Instruments:
- 0.001 Da provides decent specificity
- Consider 0.0005 Da for instruments with demonstrated sub-ppm accuracy

Medium-Resolution Instruments:
- 0.002-0.005 Da may be more appropriate
Pay special attention to test mass performance
- Increase tolerance if few genuine hits are detected

Optimization Strategy:
1. Start with 0.001 Da for high-resolution data
2. Check mass error distribution plots in the dashboard
3. Adjust based on calibration quality - widen the mass error window based on the distribution plots
4. Monitor test mass detection - high rates suggest tolerance is too broad
5. Consider instrument specifications and typical mass accuracy performance

Warning Signs:
- Test masses detected frequently: Mass tolerance may be too broad
- Known oxonium ions not detected: Mass tolerance may be too narrow or calibration issues
- Asymmetric mass error distribution: Systematic calibration problems

2. Intensity Threshold

Definition: The minimum normalized intensity required for an oxonium ion to be considered detected. This value represents the percentage of total spectrum intensity that the oxonium ion must contribute to qualify as a positive detection.

Technical Implementation:
- Calculated as: average intensity of the oxonium ion pair (oxonium ion and water loss fragment)/ total spectrum intensity) × 100
- Applied after both diagnostic masses are found within mass tolerance
- Expressed as percentage of total spectrum intensity

Default Settings:
- Default: 0.25% - Established from analysis of diverse proteomics reference samples
- Conservative: 0.5-1.0% - For high-confidence detections in complex samples
- Sensitive: 0.1-0.15% - For detecting low-abundant or rare sugars

Practical Considerations:
- Higher thresholds reduce false positives but may miss genuine low-abundance signals
- Lower thresholds increase sensitivity but require careful validation using test masses
- Instrument sensitivity and spectrum quality significantly impact optimal threshold values
- Consider your biological context - bacterial samples often require lower thresholds than mammalian samples

3. Amino Acid Marker Requirement

Definition: An optional validation step that requires the presence of specific amino acid fragment ions (175.11895 and 147.11280 m/z) alongside oxonium ions to confirm glycopeptide origin rather than free sugar contamination.

Technical Implementation:
- Searches for either 175.11895 m/z (Arginine immonium ion) OR 147.11280 m/z (Lysine immonium ion)
- Applied only when amino acid marker option is enabled
- Uses the same mass tolerance as oxonium ion detection
- Requires at least one marker mass to be present for positive detection

When to Enable Amino Acid Markers:

Recommended for:
- Samples with potential free sugar contamination
- Complex biological matrices
- When distinguishing glycopeptides from glycolipids or free glycans is critical
- Validation of novel or unexpected oxonium ion detections

Not Recommended for:
- Highly purified glycoprotein samples
- Samples where peptide fragmentation may be limited
- Initial discovery experiments where maximum sensitivity is desired

Optimization Approach:
1. Initial screening without markers to assess overall oxonium ion landscape
2. Enable markers for validation of interesting detections
3. Compare results with and without markers to understand impact
4. Consider biological context - contamination-prone samples benefit more from markers

Parameter Optimization Workflow

Step 1: Establish Baseline
- Start with default parameters (0.25% intensity, 0.001 Da mass error, no markers)
- Analyze test mass performance
- Identify major oxonium ion signals

Step 2: Optimize Mass Tolerance
- Check mass error distribution plots
- Adjust based on instrument performance
- Ensure test masses remain low

Step 3: Fine-tune Intensity Threshold
- Use test mass behavior as guide
- Consider biological expectations
- Balance sensitivity vs. specificity

Step 4: Evaluate Amino Acid Markers
- Compare results with/without markers
- Assess impact on known positive controls
- Decide based on sample complexity

Step 5: Validation
- Examine retention time profiles for consistency
- Look for co-occurring related sugars
- Validate against biological expectations

Common Parameter Issues and Solutions

Problem: High Test Mass Detection

Likely Causes: Mass tolerance too broad, intensity threshold too low
Solutions: Tighten mass tolerance first, then increase intensity threshold

Problem: No Oxonium Ions Detected

Likely Causes: Thresholds too stringent, calibration issues, sample lacks glycosylation
Solutions: Lower intensity threshold, check mass error plots, verify sample preparation

Problem: Expected Sugars Not Detected

Likely Causes: Parameters too strict, amino acid markers too restrictive, instrument issues
Solutions: Systematically relax parameters, disable markers temporarily, check instrument performance