MS Peak Table Format Validation
Summary
Validates that a raw GC-MS peak table (typically CSV output from Agilent Unknowns Analysis) conforms to the required schema before downstream processing. This skill ensures input data integrity by confirming the presence and correctness of critical columns and data types needed for intelligent sorting and chemical identification.
When to use
Apply this skill immediately after loading a raw GC-MS CSV file and before executing the spreadOut() function. Use it when you have received peak table data from an instrument vendor (e.g., Agilent Unknowns Analysis) and need to confirm that column names, data types, and row counts match expectations for the uafR pipeline.
When NOT to use
- Input is already a processed list object (e.g., output from spreadOut()) — no re-validation needed
- Data has already been validated by upstream quality-control software; skip to spreadOut() directly
- CSV file is from a non-standard GC-MS instrument with different column names — requires custom schema mapping first
Inputs
- Raw GC-MS peak table CSV file from Agilent Unknowns Analysis (or compatible export)
- Expected schema specification: column names and data types
Outputs
- Boolean validation result (pass/fail)
- Data frame with validated schema if validation succeeds
- Error report listing missing columns, type mismatches, or null value counts if validation fails
How to apply
Load the CSV file into R and verify the presence of exactly six required columns: 'Component.RT', 'Base.Peak.MZ', 'Component.Area', 'Compound.Name', 'Match.Factor', and 'File.Name' in any order. Check that Component.RT and Base.Peak.MZ contain numeric values representing retention times (in minutes) and mass-to-charge ratios, Component.Area contains non-negative numeric peak intensities, Match.Factor contains values between 0 and 100 (representing spectral library match quality), and Compound.Name and File.Name contain non-empty character strings. Confirm that the total row count is consistent with the number of detected peaks expected from your sample set. If any required column is missing or contains unexpected data types or null values, reject the file and request re-export from the instrument software with correct configuration.
Related tools
- R (Programming environment for schema validation logic and data frame inspection)
- Agilent Unknowns Analysis (Source software that generates raw peak table CSV; validation confirms its output matches expected schema)
- uafR spreadOut() (Downstream function that accepts validated peak table as input; validation is prerequisite) — https://github.com/castratton/uafR
Examples
input_dat = read.csv('gcms_dataset.csv'); stopifnot(all(c('Component.RT', 'Base.Peak.MZ', 'Component.Area', 'Compound.Name', 'Match.Factor', 'File.Name') %in% names(input_dat)))
Evaluation signals
- All six required columns (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name) are present with correct casing
- Component.RT and Base.Peak.MZ are numeric; Component.Area is numeric and non-negative; Match.Factor is numeric in range [0, 100]
- No null/NA values in any required column for rows with non-zero Component.Area
- Compound.Name and File.Name contain non-empty character strings for all rows
- Row count and column count match expected dimensions from instrument output metadata
Limitations
- Validation does not check for biological plausibility or outlier retention times/masses — focus is syntax and schema only
- Does not validate uniqueness of Component.Name or File.Name; duplicates are permitted
- Cannot verify that Match.Factor values are accurate; assumes Agilent library matching was performed correctly
- No changelog available; version compatibility with different Agilent Unknowns Analysis releases is not documented
Evidence
- [readme] The input .CSV file has strict column name/input data requirements. The column names MUST include: 'Component.RT', 'Component.Area', 'Base.Peak.MZ', 'File.Name', 'Compound.Name', and 'Match.Factor' in no particular order.: "The input .CSV file has strict column name/input data requirements. The column names MUST include: 'Component.RT', 'Component.Area', 'Base.Peak.MZ', 'File.Name', 'Compound.Name', and 'Match.Factor'"
- [methods] ensure columns match expected schema (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name): "ensuring columns match expected schema (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name)"
- [methods] confirm all eight components present, verify no null matrices for samples with detected peaks: "confirm all eight components present, verify no null matrices for samples with detected peaks"
- [methods] The recommended software for generating the necessary data in the default format (i.e. with correct column names) is Unknowns Analysis: "The recommended software for generating the necessary data in the default format (i.e. with correct column names) is Unknowns Analysis"
1---2name: ms-peak-table-format-validation3description: Use when immediately after loading a raw GC-MS CSV file and before executing the spreadOut() function. Use it when you have received peak table data from an instrument vendor (e.4license: CC-BY-4.05---67# MS Peak Table Format Validation89## Summary1011Validates that a raw GC-MS peak table (typically CSV output from Agilent Unknowns Analysis) conforms to the required schema before downstream processing. This skill ensures input data integrity by confirming the presence and correctness of critical columns and data types needed for intelligent sorting and chemical identification.1213## When to use1415Apply this skill immediately after loading a raw GC-MS CSV file and before executing the spreadOut() function. Use it when you have received peak table data from an instrument vendor (e.g., Agilent Unknowns Analysis) and need to confirm that column names, data types, and row counts match expectations for the uafR pipeline.1617## When NOT to use1819- Input is already a processed list object (e.g., output from spreadOut()) — no re-validation needed20- Data has already been validated by upstream quality-control software; skip to spreadOut() directly21- CSV file is from a non-standard GC-MS instrument with different column names — requires custom schema mapping first2223## Inputs2425- Raw GC-MS peak table CSV file from Agilent Unknowns Analysis (or compatible export)26- Expected schema specification: column names and data types2728## Outputs2930- Boolean validation result (pass/fail)31- Data frame with validated schema if validation succeeds32- Error report listing missing columns, type mismatches, or null value counts if validation fails3334## How to apply3536Load the CSV file into R and verify the presence of exactly six required columns: 'Component.RT', 'Base.Peak.MZ', 'Component.Area', 'Compound.Name', 'Match.Factor', and 'File.Name' in any order. Check that Component.RT and Base.Peak.MZ contain numeric values representing retention times (in minutes) and mass-to-charge ratios, Component.Area contains non-negative numeric peak intensities, Match.Factor contains values between 0 and 100 (representing spectral library match quality), and Compound.Name and File.Name contain non-empty character strings. Confirm that the total row count is consistent with the number of detected peaks expected from your sample set. If any required column is missing or contains unexpected data types or null values, reject the file and request re-export from the instrument software with correct configuration.3738## Related tools3940- **R** (Programming environment for schema validation logic and data frame inspection)41- **Agilent Unknowns Analysis** (Source software that generates raw peak table CSV; validation confirms its output matches expected schema)42- **uafR spreadOut()** (Downstream function that accepts validated peak table as input; validation is prerequisite) — https://github.com/castratton/uafR4344## Examples4546```47input_dat = read.csv('gcms_dataset.csv'); stopifnot(all(c('Component.RT', 'Base.Peak.MZ', 'Component.Area', 'Compound.Name', 'Match.Factor', 'File.Name') %in% names(input_dat)))48```4950## Evaluation signals5152- All six required columns (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name) are present with correct casing53- Component.RT and Base.Peak.MZ are numeric; Component.Area is numeric and non-negative; Match.Factor is numeric in range [0, 100]54- No null/NA values in any required column for rows with non-zero Component.Area55- Compound.Name and File.Name contain non-empty character strings for all rows56- Row count and column count match expected dimensions from instrument output metadata5758## Limitations5960- Validation does not check for biological plausibility or outlier retention times/masses — focus is syntax and schema only61- Does not validate uniqueness of Component.Name or File.Name; duplicates are permitted62- Cannot verify that Match.Factor values are accurate; assumes Agilent library matching was performed correctly63- No changelog available; version compatibility with different Agilent Unknowns Analysis releases is not documented6465## Evidence6667- [readme] The input .CSV file has strict column name/input data requirements. The column names MUST include: 'Component.RT', 'Component.Area', 'Base.Peak.MZ', 'File.Name', 'Compound.Name', and 'Match.Factor' in no particular order.: "The input .CSV file has strict column name/input data requirements. The column names MUST include: 'Component.RT', 'Component.Area', 'Base.Peak.MZ', 'File.Name', 'Compound.Name', and 'Match.Factor'"68- [methods] ensure columns match expected schema (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name): "ensuring columns match expected schema (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name)"69- [methods] confirm all eight components present, verify no null matrices for samples with detected peaks: "confirm all eight components present, verify no null matrices for samples with detected peaks"70- [methods] The recommended software for generating the necessary data in the default format (i.e. with correct column names) is Unknowns Analysis: "The recommended software for generating the necessary data in the default format (i.e. with correct column names) is Unknowns Analysis"
HolobiomicsLab