Peak List Column Mapping

peak-list-column-mapping

Summary

Automated recognition and manual assignment of semantic meaning to columns in high-resolution mass spectrometry peak lists. This skill enables Punc'data to map raw tabular columns (m/z, intensity, formula, etc.) to their analytical significance, enabling downstream visualization and filtering workflows.

When to use

When uploading a new peak list or complex sample data file with delimiter-separated columns to Punc'data, especially when column headers are ambiguous or use non-standard naming conventions. Use this skill if you need to generate Kendrick mass plots, canvas visualizations, or comparative analyses (Matrix, Venn, PCA) that depend on correct identification of m/z values, intensity, and formula columns.

When NOT to use

• Input is already a fully parsed Punc'data session file (.json or saved state) — use session upload instead.
• Column headers are completely missing or the first row contains data rather than labels — pre-process the file to add headers.
• Data is in a non-tabular format (e.g., raw instrument output in mzML or netCDF) — convert to delimited text first.

Inputs

• Delimiter-separated peak list file (CSV, TSV, or custom delimiter)
• Column header row with semantic labels (m/z, intensity, formula, etc.)
• Previously saved Punc'data session file

Outputs

• Parsed peak list with semantically annotated columns
• Column-to-data-type mapping (m/z → numeric vector, intensity → numeric vector, formula → string vector, etc.)
• Parameters table (editable in 'parameters' tab for manual override)

How to apply

Load the input data file specifying the column delimiter (semicolon, comma, tab, or other). Punc'data will attempt automated keyword-based recognition of standard column types (m/z, intensity, formula) from the first row headers. If automated mapping fails or produces incorrect assignments, switch to the 'parameters' tab to manually edit column interpretations. Verify the mapped columns are semantically correct before proceeding to visualization or analysis tabs (Canvas, Stats, Tools, Network). The robustness of downstream analyses—especially Kendrick mass axis selection and PCA sample comparisons—depends on correct column assignment at this stage.

Related tools

• Punc'data (Primary platform for column mapping, keyword-based recognition, and manual parameter editing; supports CSV upload and provides parameters tab for correcting automated assignments) — https://github.com/WTVoe/puncdata

Evaluation signals

• Automated keyword matching correctly identifies at least 2 of 3 standard columns (m/z, intensity, formula) in test datasets with standard naming conventions.
• Manual column reassignment in the 'parameters' tab persists across visualization and analysis operations without reverting or causing downstream errors.
• Kendrick mass plot axis selector (Canvas tab) receives correct m/z values and computes Normalized Kendrick Mass (NKM) = round(m/z × base mass) − (m/z × base mass rounded) accurately when base mass is 14.0157.
• Canvas, Table, Stats, and Matrix visualizations display data consistent with the mapped column assignments (e.g., correct intensity scaling, correct m/z range).
• Example dataset 'testdata_cellulose.csv' loads without mapping errors and generates Premade Canvas plots on first attempt.

Limitations

• Keyword-based recognition depends on column headers matching expected naming patterns; non-English or highly abbreviated headers may fail automated mapping.
• No validation criteria or data quality metrics are documented; incorrect column assignments are not flagged with warnings or confidence scores.
• Manual parameter edits are stored per-session only; there is no export or schema definition to document the mapping for reproducibility across sessions.
• Delimiter detection is manual (gear icon); incorrect delimiter specification will prevent proper column parsing.

Evidence

• [readme] Punc'data recognizes column information based on keywords such as m/z value, intensity, and formula.: "Punc'data recognizes which column corresponds to which information based on keywords."
• [readme] Manual column assignment via parameters tab: "They can also be edited manually on tab "parameters"."
• [readme] Delimiter specification is required: "To vizualise data, you need to upload a file with separation (; , ...) between the columns. You can change the separator with the gear icon"
• [readme] First row must contain column headers: "The first line of any uploaded file has to be the title of each column."
• [other] Kendrick mass plot axis selection depends on correct m/z column recognition: "Punc'data recognizes m/z values from uploaded data files based on column keywords, which can be used as input parameters for generating interactive visualizations including canvas plots"