---
name: feature-list-format-validation
description: Use when 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3763
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_0625
  tools:
  - Python
  - pyOpenMS
  - PFΔScreen
  - MSConvert
derived_from:
- doi: 10.1007/s00216-023-05070-2
  title: pfdeltascreen
evidence_spans:
- PFΔScreen is an open-source Python based non-target screening software tool
- pyOpenMS (Python interface to the C++ OpenMS library) is used for feature detection in MS raw data
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_pfdeltascreen
    doi: 10.1007/s00216-023-05070-2
    title: pfdeltascreen
  dedup_kept_from: coll_pfdeltascreen
schema_version: 0.2.0
---

# 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"