Metabolite Metadata Column Matching

metabolite-metadata-column-matching

Summary

Validate mwTab metadata columns against standardized naming conventions and value formats using regex-based pattern matching. This skill ensures conformance of MS and NMR experimental metadata to expected column names and acceptable value ranges during file validation.

When to use

Apply this skill when validating mwTab files deposited to the Metabolomics Workbench and you need to verify that metadata columns match standard naming conventions and contain values in the expected format. Specifically, use this when collecting validation errors, warnings, and metadata column validation results as part of structured quality control reporting for MS and NMR experimental data files.

When NOT to use

• Input is already a pre-validated or curated metadata table from a trusted upstream system — re-matching is redundant.
• The mwTab file structure is malformed or unparseable — address parsing errors before attempting column-level matching.
• No schema definition is available for the experiment type — column matching requires reference rules.

Inputs

• parsed mwTab file object (MWTabFile instance)
• MS or NMR schema definition (JSON schema)
• metadata section (key-value pairs or tabular data)

Outputs

• structured metadata column validation report
• list of column name matches/mismatches
• list of column value conformance results
• categorized validation errors and warnings

How to apply

Load the parsed mwTab file's metadata sections and apply the NameMatcher.dict_match method to verify that column names match the standardized schema-defined names for the experiment type (MS or NMR). Simultaneously, apply the ValueMatcher.series_match method to each column's values, using make_list_regex to construct regex patterns that enforce acceptable value formats and ranges. The NameMatcher attributes (lists of strings or lists of lists representing name alternatives and synonyms) and ValueMatcher attributes (regex patterns as strings) encode the conformance rules. Collect all column-level matches and mismatches, categorizing them as validation results. Return structured metadata column validation outcomes that document which columns conform, which are non-standard or missing, and which contain out-of-range or malformed values.

Related tools

• mwtab (Provides MWTabFile parser and NameMatcher/ValueMatcher classes for metadata column validation) — https://github.com/MoseleyBioinformaticsLab/mwtab
• jsonschema (Defines and enforces JSON schema rules for MS and NMR metadata column structure and content)
• Python (Execution environment for mwtab library and regex-based pattern matching)

Examples

import mwtab; mwfile = mwtab.MWTabFile(open('study.mwtab')); validation_results = mwfile.validate(ms_schema, nmr_schema, verbose=True)

Evaluation signals

• All expected metadata columns from the schema are matched (present and named correctly)
• All matched column values conform to their regex patterns and value constraints
• Validation report lists zero unmatched or missing standard columns for passing files
• Validation report documents specific column names and value patterns that failed, with clear distinction between name mismatches and value format violations
• Results can be traced back to the specific NameMatcher.dict_match and ValueMatcher.series_match rules applied

Limitations

• Column matching relies on pre-defined schema rules; novel or experiment-type-specific columns not in the schema will be flagged as non-standard even if scientifically valid.
• Regex patterns for value matching are fixed at schema definition time and cannot adapt to emerging or context-dependent metadata conventions.
• No changelog is documented in the mwtab repository, so version-specific changes to NameMatcher or ValueMatcher behavior are not tracked.

Evidence

• [other] All NameMatcher attributes are lists of strings or lists of lists of strings and all are used in its only method, dict_match.: "All NameMatcher attributes are lists of strings or lists of lists of strings and all are used in its only method, dict_match."
• [other] All ValueMatcher attributes are strings and all are used in its only method, series_match.: "All ValueMatcher attributes are strings and all are used in its only method, series_match."
• [other] make_list_regex function used in creating regex patterns for validation: "There is also a function used heavily in creating these regular expressions, make_list_regex."
• [other] Collect and categorize all validation errors, warnings, and metadata column validation results: "Collect and categorize all validation errors, warnings, and metadata column validation results (via metadata_column_matching rules for standard column names and value formats)."
• [other] jsonschema used for validating mwTab files based on JSON schema: "jsonschema_ for validating functionality of mwTab files based on JSON schema."