File Format Validation

Validate .csv lipid library file format for LipidMatch integration

Summary

Verify that a user-authored .csv lipid library conforms to LipidMatch's manual format specification before integration into the matching workflow. This ensures custom lipid entries with annotated m/z fragmentation patterns are correctly recognized and registered into the active library index.

When to use

When you have authored a custom .csv lipid library and need to confirm it adheres to LipidMatch's documented schema before placing it in the designated library directory and running the library integration/loading step. Use this skill to prevent malformed entries from failing silent registration or producing incorrect candidate matches in downstream MS/MS analyses.

When NOT to use

• The library is already in LipidMatch's native in-silico format (not a user-authored .csv import).
• You are validating MS/MS peak picking output (e.g., from MZmine, XCMS, MS-DIAL) rather than a lipid library source file.
• The .csv file is intended for a different lipidomics tool (e.g., LIPID MAPS, LipidBlast) with different schema requirements.

Inputs

• .csv file with custom lipid entries
• LipidMatch manual (format specification documentation)
• Text editor or spreadsheet software for file review

Outputs

• Validated .csv lipid library file ready for integration
• Validation report (pass/fail for schema compliance)
• Reformatted .csv (if corrections were needed)

How to apply

Obtain the LipidMatch manual from the GitHub repository (GarrettLab-UF/LipidMatch) and review the documented .csv format specification. Author your test .csv lipid library to include at least 3–5 custom lipid entries, each with annotated m/z fragmentation patterns conforming to the manual's column structure and data types. Before integration, validate the .csv file structure: verify column headers match the specification, confirm all required fields are populated for each lipid entry, and check that m/z values are numeric and within physically plausible ranges for your instrument (e.g., Q-Exactive orbitrap, Q-TOF). Only after validation passes should you place the file in the LipidMatch library directory and execute the library integration step.

Related tools

• LipidMatch (Target software that consumes the validated .csv library; defines the format specification and performs library integration/registration) — https://github.com/GarrettLab-UF/LipidMatch
• Text editor or spreadsheet application (e.g., LibreOffice Calc, Excel) (Tool for authoring, viewing, and manually inspecting .csv file structure before submission to LipidMatch)

Evaluation signals

• All required columns named in the LipidMatch manual are present in the .csv header row with correct spelling and order.
• Every custom lipid entry row is complete: no missing or null fields in mandatory columns (e.g., lipid name, m/z, fragment ions).
• All m/z values are numeric, properly formatted (e.g., float with appropriate decimal precision), and within the expected mass range for the instrument(s) used in your workflow (e.g., 50–2000 m/z for Q-Exactive, 50–1700 m/z for Q-TOF).
• After LipidMatch library integration and a test matching run on a sample MS/MS dataset, at least one custom library entry appears in the output candidate list, confirming successful registration.
• No parsing errors or warnings are reported by the LipidMatch integration/loading step when the validated .csv is placed in the library directory.

Limitations

• LipidMatch does not currently support Waters instrument files, so validation of a library for Waters data will still fail at the matching stage even if the .csv format is correct.
• The manual format specification is not version-controlled in the provided context; updates to the specification may not be reflected in older GitHub releases or documentation snapshots.
• Validation of .csv syntax does not confirm biological accuracy or fragmentation chemistry; entries may pass schema validation but produce incorrect or spurious matches if m/z patterns are incorrectly annotated.

Evidence

• [other] Author a test .csv lipid library conforming to the LipidMatch manual format specification, including at least 3–5 custom lipid entries with annotated m/z fragmentation patterns.: "Author a test .csv lipid library conforming to the LipidMatch manual format specification, including at least 3–5 custom lipid entries with annotated m/z fragmentation patterns."
• [readme] LipidMatch allows for facile integration of user generated libraries for unique applications.: "LipidMatch allows for facile integration of user generated libraries for unique applications."
• [other] Place the .csv library file in the designated library directory within the LipidMatch installation.: "Place the .csv library file in the designated library directory within the LipidMatch installation."
• [other] Parse and inspect the output candidate list to confirm that at least one custom library entry appears ranked among the matching candidates.: "Parse and inspect the output candidate list to confirm that at least one custom library entry appears ranked among the matching candidates."