Feature list format validation

Feature-List Format Validation

Summary

Validate and parse user-supplied custom feature lists (CSV/TSV/XLSX) into PFΔScreen-compatible feature objects before downstream PFAS prioritization. This skill ensures that custom feature inputs meet required schema (m/z, retention time, intensity columns) and are properly converted to internal data structures compatible with MD/C-m/C, KMD, and MS2 fragment analysis modules.

When to use

A user supplies a custom feature list from external feature-finding software (vendor tools, alternative open-source pipelines) instead of using pyOpenMS automatic detection, or wishes to augment/replace pyOpenMS results with pre-processed features. The custom list must include mandatory columns (m/z, retention time, intensity) and be provided in CSV, TSV, or XLSX format alongside the corresponding mzML raw data files.

When NOT to use

• Input is already a feature table generated by PFΔScreen's pyOpenMS module; use direct prioritization instead.
• mzML raw data files are not available; MS2 fragment data required for diagnostic fragment analysis will be missing.
• Custom feature list lacks mandatory columns (m/z, retention time, intensity) and cannot be retrofitted.

Inputs

• Custom feature list file (CSV, TSV, or XLSX format with columns: m/z, retention time, intensity)
• Corresponding mzML raw data file (data-dependent acquisition, centroided spectra)
• Optional blank control mzML file

Outputs

• Validated internal feature object table (compatible with downstream PFΔScreen modules)
• Validation report (features accepted, dropped, or flagged)
• Feature metadata in PFΔScreen format (m/z, RT, intensity, MS2 linkage status)

How to apply

Load the user-supplied custom feature file using the 'Browse SampleFeatures.xlsx' (and optionally 'Browse BlankFeatures.xlsx') buttons in the PFΔScreen GUI. Validate that the file contains required columns (m/z, retention time, intensity) with numeric values in expected ranges. Parse feature metadata and convert each row to PFΔScreen's internal feature object format. Cross-reference feature retention times and m/z values against the corresponding mzML file to ensure MS2 spectra are available for downstream fragment analysis. Document any dropped or flagged features due to missing m/z, RT, or intensity data. Only proceed to 'Run ExternalFeatureTable' preprocessing after validation passes; note that subsequent MS2 data evaluation will fail silently if mzML files are not also provided.

Related tools

• PFΔScreen (Core platform; provides GUI buttons ('Browse SampleFeatures.xlsx', 'Run ExternalFeatureTable') for loading, validating, and preprocessing custom feature lists into internal format) — https://github.com/JonZwe/PFAScreen
• pyOpenMS (Reference feature detection library; custom feature lists serve as alternative to pyOpenMS-detected features and are converted to compatible internal representation)
• MSConvert (Utility for generating vendor-independent mzML files required to accompany custom feature lists)

Evaluation signals

• All rows in the custom feature list contain non-null, numeric values for m/z, retention time, and intensity within plausible ranges for HRMS data (e.g., m/z > 0, RT > 0, intensity > 0).
• No data loss occurs during conversion: count of rows in input file equals count of validated internal feature objects (or discrepancies are logged with justification).
• Feature objects successfully link to MS2 spectra in the corresponding mzML file; 'Run ExternalFeatureTable' completes without missing-spectrum warnings.
• Validated features pass through downstream MD/C-m/C, KMD, and MS2 fragment analysis steps without schema-related errors or dropped features.
• Output Excel results table and interactive HTML plots are generated with expected columns and visualizations (MD/C-m/C plot, KMD vs. m/z, etc.), indicating successful feature integration.

Limitations

• Validation does not check for biological or chemical plausibility of feature m/z, RT, or intensity; garbage-in-garbage-out behavior is possible if the custom list contains erroneous or outlier features.
• If corresponding mzML files are not provided, the validation step cannot verify that features have associated MS2 spectra; downstream MS2 fragment analysis will fail silently without diagnostic MS2 data.
• Column name matching is case-sensitive or format-dependent; custom lists with non-standard column headers (e.g., 'mass_to_charge' instead of 'm/z') may fail validation without explicit error messages.
• Large custom feature lists (> ~10,000 features) may require adjustment of runtime parameters; the README does not specify performance thresholds or memory constraints.

Evidence

• [intro] custom feature lists can be included as alternative input pathway: "Optionally, custom feature lists can be included"
• [other] required columns for custom feature lists: "validating required columns (m/z, retention time, intensity)"
• [other] conversion to internal PFΔScreen format: "Parse feature metadata and convert to internal PFΔScreen feature object format compatible with downstream prioritization modules"
• [readme] GUI workflow for custom feature list preprocessing: "custom feature lists (see external_feature_list.xlsx) together with the respective mzML files can instead be included in PFΔScreen. This is done by the 'Browse SampleFeatures.xlsx' and 'Browse"
• [readme] MS2 data availability requirement: "Note that data evaluation only works when the corresponding mzML files are also given; otherwise MS2 data would be missing"