LipidOracle Parameters Guide

All LipidOracle runs are configured via a lipidoracle.yaml file. If the file is missing, LipidOracle will generate a default configuration and exit so you can review and customise it before running.

File Structure

The YAML file has two main sections:

VERSION: x.y.z                  # Tracks configuration version

WORKFLOW:                       # Workflow switches and choices
  ...

PARAM:                          # Numeric and threshold parameters
  ...

Workflow Section

The WORKFLOW section controls which annotation engines run and how they operate.

Parameters are named after the stage that owns them. A run has three stages — s1 MS1 accurate mass, s2 MS2 fragments, s3 acyl-chain positions — and a parameter governing one of them carries that prefix, as in s2_lo_score_cutoff or s3_min_score. Names beginning ms1_ or ms2_ refer to the MS level of the data instead, not to a stage: ms2_tolerance is a tolerance on MS2 peaks, whichever stage reads them. Stages are steps; ID levels (1–4) describe how much detail a result carries. See Traceable evidence.

Library & Engine Switches

Parameter Type Default Description
lipidoracle bool True Enable the internal LipidOracle MS1/MS2 annotation engine
lipidex bool False Enable LipiDex library matching (experimental, fewer features)
lipidblast bool False Enable LipidBlast library matching (experimental, fewer features)
library_extra list [] Additional CSV-format lipid libraries (e.g., ['/path/to/custom.csv'])

Data Filtering

Parameter Type Default Description
mz_target string '' Optional m/z value list file to restrict analysis to specific features (useful for targeted runs)

Advanced Analysis

Parameter Type Choices Description
stage3 bool or string False, 'ead1', 'ead2', 'uvpd', 'oad', 'ozid' Run stage 3: localise C=C and oxygen positions along the acyl chains, reporting idlevel 3 and 4. ead1 skips oxidised species; ead2 is required for anything carrying ;O. oad currently supports unoxidised diacyl PC [M+H]+. ozid uses complete aldehyde/Criegee diagnostic pairs for its documented positive-ion profiles. Unsupported profiles fail closed. True/'v1'/'v2' are accepted aliases. See Acyl-chain analysis.
rt_check string False, 'legacy', 'liri', 'hydra' Retention-time validation engine (see RT Models for details)

PARAM Section

The PARAM section sets numeric thresholds and limits. Key parameters are listed below; the default file includes others.

Identification & Scoring

Parameter Type Default Description
rarity_max int 3 Maximum rarity index kept (lower = stricter, more conservative IDs; higher = includes rare chain compositions). Set to 0 to keep all.
rarity_penalty float 0.15 Score penalty applied to rare lipids instead of excluding them. See Lipid library.

Stage 1 — MS1 matching

Parameter Type Default Description
ms1_tolerance float 0.01 Precursor m/z tolerance in Da (tolerance used for MS1 library matching)
ms1_maxO int 0 Maximum extra oxygen atoms added during MS1 library generation (for oxidised variants)

Stage 2 — MS2 matching and spectral processing

Parameter Type Default Description
ms2_noise_abs int 10 Absolute MS2 peak intensity floor (peaks below this are removed)
ms2_maxO int 0 Maximum extra oxygen atoms added during MS2 isomer generation

Stage 3 — acyl-chain analysis (reports idlevel 3 and 4)

When stage3 is enabled, these parameters control the exhaustive C=C and oxidation position search. Every one of them is prefixed s3_, after the stage rather than the ID level it reports; the former ead_* and include_ms1_monochain spellings are still accepted as aliases, so existing configs load unchanged.

Parameter Type Default Description
s3_include_ms1_monochain bool True Also localise on idlevel 1 single-acyl species such as LPC/LPE
s3_max_unsaturated int 6 Caps unsaturation accepted for exhaustive search (higher = more candidates, slower runtime)
s3_max_oxygen int 2 Caps total oxygen positions across all chains. Used by ead2/uvpd; ead1 has no oxygen support and ignores it.
s3_max_candidates int100000 Candidates scored before stride-sampling. Raise it further for oxidised work — a single 20:4;O token enumerates ~22,300 candidates, and below that the true structure can be sampled out silently. See Acyl-chain analysis.
s3_output_max int100 Candidates written to diag/annotation_stage3.csv per feature
s3_min_score float 0.2 Absolute s3_score floor, applied after normalisation
s3_min_margin float0.0 Minimum relative gap between the two best candidates before idlevel 4 names a position (ead1, oad, and ozid). Fitted against known positions for EAD; OAD and OzID calibration remains provisional.
s3_min_matched int 3 Minimum peaks the winning candidate must have matched for that gap to count (ead1 and oad); OzID uses complete diagnostic pairs instead.
s3_intensity_scaling string 'none' Compressive transform on matched intensity (ead2 only): none, sqrt, log10, ln, log2. ead1 and oad always apply sqrt as part of their scoring models.
db_n_notation bool False Legacy switch: render double-bond positions in the idlevel-4 confidence tail as n-x. Canonical Shorthand2020 names always use Δ.
s3_null_decoys bool False Diagnostic only: also score chemically impossible (allene) placements as a null, adding a column to diag/s3_resolvability.csv. Never emitted as an annotation.
ozid_require_complete_pair bool True Require both aldehyde and Criegee products for every expected OzID double bond before accepting a localization.
ozid_min_complete_pairs int 1 Minimum number of complete OzID diagnostic pairs required for an accepted localization.
ozid_formula_mz_tolerance float 0.01 Maximum absolute precursor-mass disagreement (Da) between the library formula/adduct and observed precursor; inconsistent formulas and isotope labels fail closed.

Candidate selection (new in v1.0.173)

Which positional isomers get reported, and how confidently idlevel 4 is named. Orthogonal to stage3: either method works with any engine.

Parameter Type Default Description
s3_selection string 'posterior' posterior converts scores to a probability distribution over candidates and reports the smallest set holding the credible level. legacy (accepted as cutoff) is the original relative-score threshold. legacy names more features but is right less often.
s3_post_credible_level float 0.95 Posterior mass the reported credible set must reach
s3_post_min_mass float 0.5 Posterior mass one placement needs before its positions are written into the idlevel-4 name. Below it the chain is reported at species level and the confidence tail still lists what is known.
s3_post_temperature float 0.01 Softmax temperature turning score gaps into probabilities. Fitted against known positions, not chosen — larger flattens the posterior towards chance, smaller manufactures confidence.
s3_legacy_cutoff float 0.99 Relative score cutoff vs the top candidate. Used only when s3_selection: legacy, and weakly discriminating: against an impossible-position null, absurd structures cleared this setting for ~11% of features.

Quick-Start Defaults

For most users, the default configuration works well:

VERSION: x.y.z

WORKFLOW:
  mz_target: ''
  lipidoracle: True
  lipidex: False
  lipidblast: False
  library_extra: []
  stage3: False
  rt_check: liri

PARAM:
  rarity_max: 3
  rarity_penalty: 0.15
  ms1_tolerance: 0.01
  ms2_tolerance: 0.02
  ms2_noise_abs: 10
  ms1_maxO: 0
  ms2_maxO: 0
  s3_max_unsaturated: 6
  s3_max_oxygen: 2
  s3_max_candidates: 10000
  s3_min_score: 0.2
  s3_selection: 'posterior'
  s3_post_credible_level: 0.95
  s3_post_min_mass: 0.5
  # ... (other parameters with defaults)

When to customise