Detection Parameters
Detection Parameters
Introduction
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.
Only specify parameters you want to change from defaults:
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
For guidance on how to evaluate detection results and optimize thresholds interactively, see Detection Metrics.
Oxonium Ion Detection Parameters
MASS_ERROR (Default: 0.001 Da)
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:
- 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
Optimization: After processing, check the mass error distribution plot in the dashboard. The average peptide fragment mass error for 90% of masses is reported — use this as a guide.
Warning signs:
- Test masses detected frequently → tolerance too broad
- Known oxonium ions missing → tolerance too narrow or calibration issues
INTENSITY_THRESHOLD (Default: 0.25%)
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.
Recommended ranges:
- Conservative (complex samples): 0.5–1.0%
- Default: 0.25%
- Sensitive (rare sugars): 0.1–0.15%
This parameter sets the threshold for the scanning step. The dashboard provides additional interactive filtering on top of this value.
AMINO_ACID_MARKER (Default: False)
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.
Enable when:
- Samples may contain free sugar contamination
- Distinguishing glycopeptides from glycolipids is important
Keep disabled when:
- Running initial discovery experiments
- Maximum sensitivity is desired
CHEMSPACE_SEARCH (Default: False)
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.
docker run -p 8051:8051 -e CHEMSPACE_SEARCH=True \
-v "$(pwd)/Input:/app/Input" -v "$(pwd)/Output:/app/Output" oxonium-browser
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.
SAGE Search Parameters
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.
| 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).
Mass Calibration Parameters (Not User-Configurable)
These are internal parameters used by the recalibration module (see System Architecture for details):
- 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
Parameter Optimization Workflow
- Start with defaults — run with default parameters on your first sample
- Check mass error plots — verify calibration quality in the dashboard, adjust MASS_ERROR if needed
- Assess test mass performance — check if test masses appear in the match table; adjust thresholds using the workflow described in Detection Metrics
- Consider biological context — bacterial samples may need lower thresholds than mammalian
- Enable amino acid markers if contamination is a concern
- Enable chemspace search if you suspect rare or unusual sugars not covered by the curated database
Troubleshooting
Many test masses detected: MASS_ERROR too broad or INTENSITY_THRESHOLD too low. 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.
Expected sugars missing: Relax parameters systematically. Disable AMINO_ACID_MARKER if enabled. Check instrument performance and calibration quality.
