The built-in MS2 library

Classes

Class	Abbreviation	Positive adducts	Negative adducts	Max level	Carbon range	Max DB	Unique species
Bis(monoacylglycero)phosphate	BMP	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS1; `[M+Na]+`: MS1	12–60	6	313
Carnitine	CAR	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1; `[M+NH4]+`: MS1	2–30	6	83
Cholesteryl ester	CE	`[M+H]+`; `[M-H2O+H]+`; `[M+Na]+`; `[M+NH4]+`	—	`[M+H]+`: MS2; `[M-H2O+H]+`: MS1; `[M+Na]+`: MS1; `[M+NH4]+`: MS2	2–34	6	93
Cardiolipin	CL	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	all: MS2	2–80	12	325
Ceramide	Cer	`[M+H]+`; `[M-H2O+H]+`; `[M+Na]+`; `[M+K]+`	`[M-H]-`	`[M+H]+`: MS2; `[M-H2O+H]+`: MS1; `[M+Na]+`: MS1; `[M+K]+`: MS1	2–60	6	133
Ceramide phosphate	CerP	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1	12–60	6	133
Diacylglycerol	DG	`[M+NH4]+`; `[M+Na]+`; `[M+H]+`; `[M+K]+`; `[M+Li]+`	—	all: MS2	2–40	12	221
Digalactosyldiacylglycerol	DGDG	`[M+NH4]+`; `[M+Na]+`	`[M+HCOO]-`; `[M-H]-`	`[M+NH4]+`: MS2; `[M+Na]+`: MS1	12–60	6	313
Fatty acid	FA	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	all: MS1	2–34	6	93
Ganglioside GD1	GD1	`[M+H]+`	`[M-H]-`	MS1	2–60	6	0
Ganglioside GD2	GD2	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Ganglioside GD3	GD3	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Ganglioside GM1	GM1	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Ganglioside GM2	GM2	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Ganglioside GM3	GM3	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Ganglioside GT1	GT1	`[M+H]+`	`[M-H]-`	MS1	12–60	6	0
Dihexosylceramide	Hex2Cer	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS2	2–60	6	133
Trihexosylceramide	Hex3Cer	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS2	12–60	6	133
Hexosylceramide	HexCer	`[M+H]+`; `[M+Na]+`; `[M+K]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS2; `[M+K]+`: MS1	12–60	6	133
Inositolphosphorylceramide	IPC	—	`[M-H]-`	—	2–60	6	0
Lysophosphatidic acid	LPA	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	3–30	6	81
Lysophosphatidylcholine	LPC	`[M+H]+`; `[M+Na]+`; `[M+Li]+`	`[M-H]-`	all: MS2	2–30, 3–30	6	83, 53, 0
Lysophosphatidylethanolamine	LPE	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1	2–30, 3–30	6	83, 53, 0
Lysophosphatidylglycerol	LPG	`[M+H]+`	`[M-H]-`	MS1	3–30	6	81
Lysophosphatidylinositol	LPI	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	3–30	6	81
Lysophosphatidylserine	LPS	`[M+H]+`	`[M-H]-`	MS1	3–30	6	81
Lactosylceramide	LacCer	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1	12–60	6	0
Monoacylglycerol	MG	`[M+NH4]+`; `[M+Na]+`; `[M+H]+`	—	`[M+NH4]+`: MS2; `[M+Na]+`: MS1; `[M+H]+`: MS2	2–30	6	83
Monogalactosyldiacylglycerol	MGDG	`[M+NH4]+`; `[M+Na]+`	`[M+HCOO]-`; `[M-H]-`	`[M+NH4]+`: MS2; `[M+Na]+`: MS1	12–60	6	264
Mannosylinositolphosphorylceramide bisphosphate	MIP2C	—	`[M-H]-`	—	12–60	6	0
Mannosylinositolphosphorylceramide	MIPC	—	`[M-H]-`	—	12–60	6	0
N-acylethanolamine	NAE	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	all: MS2	3–30	6	0
Phosphatidic acid	PA	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	`[M+H]+`: MS1; `[M+Na]+`: MS1; `[M+NH4]+`: MS2	3–60	6	337
Phosphatidylcholine	PC	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS2	2–60, 12–60	6	337, 292, 0
Phosphatidylethanolamine	PE	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1	2–60, 12–60	6	337, 292, 0
Phosphatidylglycerol	PG	`[M+H]+`	`[M-H]-`	MS1	2–60	6	337
Phosphatidylinositol	PI	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	`[M-H]-`	all: MS2	12–60	6	313
Phosphatidylinositol phosphate	PIP	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	2–60	6	337
Phosphatidylinositol bisphosphate	PIP2	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	12–60	6	313
Phosphatidylinositol trisphosphate	PIP3	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	12–60	6	313
Phosphatidylserine	PS	`[M+H]+`	`[M-H]-`	MS2	2–60	6	337
Sphingosine-1-phosphate	S1P	`[M+H]+`; `[M+Na]+`	`[M-H]-`	`[M+H]+`: MS2; `[M+Na]+`: MS1	12–30	4	5
Sphingoid base	SB	`[M+H]+`; `[M+Na]+`; `[M+NH4]+`	—	`[M+H]+`: MS2; `[M+Na]+`: MS2; `[M+NH4]+`: MS1	2–34	6	0
Sulfohexosylceramide	SHexCer	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS1	12–60	6	133
Sphingomyelin	SM	`[M+H]+`; `[M+Na]+`	`[M-H]-`	all: MS2	28–60	6	103
Sulfoquinovosyldiacylglycerol	SQDG	`[M+NH4]+`; `[M+Na]+`	`[M-H]-`	all: MS1	12–60	6	313
Sterol	ST	`[M+H]+`; `[M+H-H2O]+`; `[M+NH4]+`; `[M+Na]+`	`[M-H]-`	all: MS2	2–34	6	91
Sphingosine	Sph	`[M+H]+`; `[M-H2O+H]+`; `[M+Na]+`; `[M+K]+`	`[M-H]-`	`[M+H]+`: MS2; `[M-H2O+H]+`: MS1; `[M+Na]+`: MS1; `[M+K]+`: MS1	2–60	6	5
Triacylglycerol	TG	`[M+NH4]+`; `[M+Na]+`; `[M+H]+`; `[M+K]+`; `[M+Li]+`	—	all: MS2	14–60	12	461

Negative mode

Negative adducts for each class are listed in the Negative adducts column of the table above.

Negative-mode coverage comes from the adducts_neg entries of data/lipids_definition.json. The prior is the adduct's default weight (adducts_neg_score) and rarity is its adduct rarity (adducts_neg_rarity), shown only when non-zero. Only adducts that are also listed in PARAM.adducts are used in a run.

[M-H]- is defined for almost every class. Two exceptions: MGDG and DGDG use [M+HCOO]- as their primary channel ([M-H]- is a rarer alternative).
[M+Ac-H]-, [M+FA-H]-, and [M-2H]2- are in the default PARAM.adducts, but no class lists them under adducts_neg. Check the dashboard's **Lipid library** page for their effect in your run.
Some classes have no negative entry: FA-AMPP, SB, CE, TG, DG, and MG. They are not annotated in negative mode.
HexCer, Hex2Cer, LacCer, Hex3Cer, Cer, Sph, NAE, ST, FA, and CAR carry a reduced prior or rarity 1 for [M-H]-, so they rank below better-supported alternatives.
Ether-linked PC, PE, LPC, and LPE (O-/P-) have their own keys, with the same [M-H]- channel. LPC and LPE each cover both the sn-1 and sn-2 acyl regioisomer keys.

Oxidation

The library can generate oxidised variants of each entry. Two separate limits control how far that goes, because MS1 and MS2 libraries are built independently:

Parameter	Default	Controls
`PARAM.ms1_maxO`	`0`	Maximum additional oxygen atoms per lipid during MS1 library generation
`PARAM.ms2_maxO`	`0`	Maximum additional oxygen atoms per chain during MS2 isomer generation

Both default to 0, which means no oxidised variants are generated. Raise them if you are looking for oxidised lipids:

ms1_maxO: 1 includes mono-oxidised species in MS1 matching (one extra oxygen per lipid)
ms2_maxO: 2 allows up to two extra oxygen atoms per chain during MS2 analysis

How oxidation limits work:

MS1 generation: the limit is per lipid. A TG with ms1_maxO: 1 can have one oxygen across its three chains; setting ms1_maxO: 2 allows two total oxygens across all chains.
MS2 generation: the limit is per chain. Each acyl chain can carry up to ms2_maxO oxygens independently, subject to the class definition's oxygen limit. A lipid with two chains and ms2_maxO: 2 can have up to 2 oxygens on chain 1 and 2 on chain 2.

Total library size and runtime grow substantially with oxidation limits. The oxidation policy actually applied in a run is printed on the dashboard's Lipid Library page, so you can verify exactly which variants were considered.

Rarity

Not every formally valid lipid is equally likely to be real. LipidOracle assigns each library entry a rarity index, built as the sum of:

Rarity of the headgroup (e.g. cardiolipin is rarer than phosphatidylcholine)
Rarity of the chain lengths (very long chains, very short chains, or uneven chain pairs contribute)
Modifications present, such as hydroxyl or epoxy groups

The resulting rarity is an integer. Examples:

Rarity 0 is a common lipid: PC 34:1 or PE 36:2
Rarity 1 is uncommon: PC 40:0 or PE O-40:6
Rarity 2 or 3 marks genuinely rare lipids: CL 72:8, Cer d18:1/24:0, or unusual oxidised forms

You control rarity in two ways, and they behave very differently:

A priori filtering: PARAM.rarity_max (default 3). Entries above the configured maximum are excluded from the library before matching begins. Rare lipids are never considered at all. Setting rarity_max: 0 keeps every entry regardless of rarity; setting rarity_max: 1 removes all entries with rarity 2+ from the library. This approach is stricter and more conservative. Use it when you want to exclude unlikely lipids entirely.

A posteriori scoring: PARAM.rarity_penalty (default 0.15). Leaving rarity_max at 2 or 3 keeps rare forms in the library, but the penalty lowers their matching score. A rare lipid survives into the annotation only when its s2_score is high enough to overcome the penalty. This approach lets the data decide: the evidence is there, but weak matches on rare lipids are easier to filter out. This is usually the better choice: you keep all evidence and let score protect against noise rather than deciding in advance which lipids are worth considering.

Both parameters are independent. You can use both (keep all entries in the library with rarity_max: 0, but apply a penalty with rarity_penalty), or just one.

Additional libraries

Source	Switch	Notes
LipiDex	`WORKFLOW.lipidex`	Default `False`. Optional comparative source, fewer features.
LipidBlast	`WORKFLOW.lipidblast`	Default `False`. Optional comparative source, fewer features.
Your own CSV	`WORKFLOW.library_extra`	Default empty. One or more CSV files.

Supplying your own CSV library

A custom CSV can be a plain MS1 list or can carry MS2 fragments. Recognised columns:

Column	Meaning
`name`	Lipid name
`species`	Species identifier
`formula`	Molecular formula
`chains`	Number of acyl chains, defaults to 0 if omitted
`hg_class`	Headgroup class
`adduct`	Ion form, for example `[M+H]+`
`mod`	Modifications
`frag_mz`, `frag_w`, `frag_label`, `frag_type`	Optional MS2 fragment definition

Point at it with an absolute path inside the container:

WORKFLOW:
  library_extra: ["/input/my_library.csv"]

Questions and problems

Report issues or ask questions at github.com/zamboni-lab/lipidoracle/issues.