[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CW1SWVM0NYHVE6Q7MA3G7R":3,"skill-same:01M7CW1SWVM0NYHVE6Q7MA3G7R":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M7CW1SWVM0NYHVE6Q7MA3G7R","bio-metabolomics-msdial-preprocessing",null,"Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA\u002FDIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.","mrsonord2240\u002Fopenscience-specialists","mrsonord2240","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76487430?v=4","01M7CTEM40S43GSJZ9A3YCCXZK","Samuel Nord","01M7CTEM4K69JD1GBYNHVJ9ZP4",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-metabolomics-msdial-preprocessing\ndescription: Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA\u002FDIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.\ntool_type: mixed\nprimary_tool: msdial\n---\n\n## Version Compatibility\n\nReference examples tested with: MS-DIAL console 5.5.260820 (`MSDIALCUI.exe` -- confirmed installed and run on real data 2026-09-16), pandas 2.2+, R 4.3+\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: run `MSDIALCUI.exe` (or `MSDIALCUI` on Linux\u002FMac) with no arguments to print the current subcommand\u002Fflag list, then `MSDIALCUI.exe \u003Csubcommand> --help` for that subcommand's real options\n- R: `packageVersion('\u003Cpkg>')` then `?function_name` to verify parameters\n- Python: `pip show pandas` then `help(module.function)` to check signatures\n\nThe MS-DIAL GUI (`MSDIAL.exe`) runs only on Windows and hangs waiting for input if launched with `--help` or any unrecognized argument; the **separately-distributed** console app (`MSDIALCUI.exe`, packaged as its own `MSDIAL.console.*` release asset) is the cross-platform headless entry, and its real subcommand list -- confirmed by running it with no arguments -- is `gcms`, `lcms`, `lcimms`, `dims`, `imms`, `msn`, `eic`, `rtcorrection`, `imagegen`. GC-MS is real and working here: `gcms` is backed by its own `MsdialGcMsApi.dll` in the same release, so GC-EI does not require sourcing a separate MS-DIAL 4 build (see \"Why GC-EI Is Different\" below for what changed). If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt rather than retrying.\n\n# MS-DIAL Preprocessing\n\n**\"Process my LC-MS run with MS-DIAL and give me a feature table\"** -> Pick peaks per file, deconvolve chimeric MS\u002FMS into clean component spectra (MS2Dec), align across samples, gap-fill, then import the alignment result and filter it honestly.\n- CLI: `MSDIALCUI.exe lcms -i \u003Cin> -o \u003Cout> -m \u003Cparam.txt>` for LC-MS (DDA and DIA share this one subcommand -- see \"Run MS-DIAL Headless\" for how acquisition type is actually set); `MSDIALCUI.exe gcms -i \u003Cin> -o \u003Cout> -m \u003Cparam.txt>` for GC-MS\n- R: `read.csv(..., skip = 4, check.names = FALSE)` to parse the alignment export\n- Python: `pandas.read_csv(..., skiprows=4)` for the same export\n\n## The Single Most Important Insight -- Preprocessing Software Is Not Neutral\n\nThe same raw files through MS-DIAL versus XCMS yield different feature tables and different marker lists. Li 2018 benchmarked five tools on a 1,100-compound standard and found that while feature *detection* was broadly similar, *quantification* and the set of selected discriminating markers differed by tool. A metabolomics \"hit\" is conditional on (raw data + software + version + every parameter + fill\u002Ffilter order), not on the raw files alone. MS-DIAL's specific differentiator is **MS2Dec deconvolution**: it reconstructs clean, library-matchable MS\u002FMS spectra from chimeric DDA\u002FDIA fragment data, which is what makes wide-window DIA (SWATH) tractable at all. Report the full processing specification as part of the result, and treat a finding that survives only one pipeline as a candidate, not a result.\n\n## MS-DIAL vs XCMS\n\n| Axis | MS-DIAL | XCMS |\n|---|---|---|\n| Interface | Windows GUI + cross-platform console | R package (scriptable everywhere) |\n| Core differentiator | MS2Dec MS\u002FMS deconvolution (DDA + DIA) | centWave peak picking, full programmatic control |\n| Annotation | Built-in (library + MS-FINDER + LipidBlast) | Separate (CAMERA, downstream tools) |\n| Lipidomics | Strong (predicted-CCS \u002F EAD structural elucidation in v5) | Manual |\n| Reproducibility unit | Param file + GUI choices | Versioned R script |\n| Best when | DIA data, lipidomics, GUI workflow, built-in IDs | Scripted pipelines, custom parameters, cohort scale |\n\nUse MS-DIAL when DIA deconvolution or built-in lipid annotation is the point; use metabolomics\u002Fxcms-preprocessing for fully scripted, version-pinned cohort processing. The strongest untargeted claims replicate across both.\n\n## Decision Tree by Scenario\n\n| Situation | Do | Why |\n|---|---|---|\n| LC-MS, top-N MS\u002FMS (DDA) | `MSDIALCUI.exe lcms` (folder input, or `acquisition_type=DDA` per file in a CSV `-i`) | Cleaner per-precursor MS2, but intensity-biased, stochastic coverage |\n| LC-MS, wide-window MS\u002FMS (DIA \u002F SWATH) | `MSDIALCUI.exe lcms` (ABF input only; set `acquisition_type=DIA` per file in a CSV `-i`) | Complete MS2 coverage; chimeric spectra REQUIRE MS2Dec to be usable |\n| GC-EI run | `MSDIALCUI.exe gcms`, or AMDIS\u002FeRah | EI fragments every co-eluting compound; deconvolution IS detection (see below) |\n| Headless \u002F Linux cluster | `MSDIALCUI` (cross-platform console binary) with a `-m` param file | GUI is Windows-only; console is the reproducible batch path |\n| Lipid-focused study | MS-DIAL + LipidBlast | -> metabolomics\u002Flipidomics for lipid annotation mode |\n| Already have an alignment CSV | skip processing, parse + filter | See import + honest-filter sections below |\n\n## Why GC-EI Is Different\n\nIn GC-EI, 70 eV ionization fragments every compound reproducibly, so the trace at any retention time is a superposition of fragments from several co-eluting molecules. Naive peak picking conflates them; **deconvolution into component spectra IS the feature-detection step**, then each component is matched against EI+RI libraries (NIST, FiehnLib). Cross-run\u002Fcross-lab alignment uses **retention index** (Kovats n-alkanes, or Fiehn FAME markers giving diagnostic m\u002Fz 74\u002F87) rather than raw RT, because RT drifts with column aging. GC-MS is supported directly by the current MS-DIAL 5.x console's `gcms` subcommand (confirmed real and working on 5.5.260820, backed by its own `MsdialGcMsApi.dll`) -- a separate MS-DIAL 4 build is not required.\n\n## Run MS-DIAL Headless (console)\n\n**Goal:** Process a folder of converted spectra into an alignment table without the GUI.\n\n**Approach:** Pick the real subcommand (`lcms` or `gcms` -- there is no separate `lcmsdda`\u002F`lcmsdia` token in the current console), point `-i`\u002F`-o`\u002F`-m` at input dir, output dir, and a method (parameter) file; keep `-p` only if the project should reopen in the GUI.\n\nVerified 2026-09-16 against the real, installed `MSDIALCUI.exe` 5.5.260820: `MSDIALCUI.exe lcms -i \u003Cdir> -o \u003Cdir> -m \u003Cmethod.txt>` ran end to end on a real DDA mzML file and produced a real alignment export (see \"Import the Alignment Result\" below for its actual filename and column layout).\n\n```bash\n# LC-MS (DDA or DIA -- one subcommand covers both). Accepts netCDF\u002FmzML\u002FABF for DDA;\n# DIA\u002FSWATH accepts ABF ONLY (convert vendor raw -> ABF first; MS2Dec is the point).\nMSDIALCUI.exe lcms -i .\u002FLCMS\u002F -o .\u002FLCMS_out\u002F -m .\u002FMsdial-lcms-Param.txt\n\n# Acquisition type (DDA vs DIA) is not a console token -- it is set per file. For a\n# single-mode batch, a plain input folder is enough (every file processed the same\n# way, as above). To mix modes or set it explicitly, pass -i a CSV instead of a folder,\n# with one row per raw file and an `acquisition_type` column (DDA or DIA), per the\n# official MS-DIAL 5 console tutorial (systemsomicslab.github.io\u002Fmsdial5tutorial):\n#   file_path,file_name,file_type,class_id,acquisition_type,batch_order,analytical_order,factor\n#   LCMS\u002Fsample1.mzML,sample1,Sample,A,DDA,1,1,1\nMSDIALCUI.exe lcms -i .\u002Ffilelist.csv -o .\u002FLCMS_out\u002F -m .\u002FMsdial-lcms-Param.txt\n\n# GC-EI: retention-index alignment, quant-mass quantification. Real and working in\n# the current 5.x console (see \"Why GC-EI Is Different\" above) -- no MS-DIAL 4 needed.\nMSDIALCUI.exe gcms -i .\u002FGCMS\u002F -o .\u002FGCMS_out\u002F -m .\u002FMsdial-GCMS-Param.txt -p\n```\n\nThe parameter (`-m`) file is plain text with **`Key: Value`** pairs (colon-separated, one per line, `#` for comments) -- not `Key=Value`. The `Minimum peak height` key is the direct analog of an intensity floor and is instrument-dependent: the GUI default is tuned for a TOF and is often far too high (or its baseline assumption wrong) for an Orbitrap. Set the alignment reference to a pooled QC, never to file #1 by default.\n\n## Import the Alignment Result into R\n\n**Goal:** Split the MS-DIAL alignment export into a feature-metadata frame and an intensity matrix.\n\n**Approach:** The export carries four header rows above the real column header (sample class \u002F file type \u002F injection order \u002F batch), so skip them. Verified 2026-09-16 against a real `MSDIALCUI.exe` 5.5.260820 run: the file is **not** named `AlignResult.txt` -- the console writes `AlignResult-\u003Ctimestamp>.mdalign` (still a plain tab-separated text file, plus sibling `.mzTab` and `.qa.tsv` exports of the same run); glob for `AlignResult-*.mdalign` rather than assuming the literal name. Metadata columns precede the per-sample intensity columns, but real exports interleave extra annotation\u002FQC columns (Formula, Ontology, INCHIKEY, SMILES, matched-flag and dot-product-score columns, spectra text, ...) between the last *known* metadata column and the real sample columns -- taking \"everything after the last known metadata column\" pulls those text columns into what should be a numeric matrix. Anchor on the header block instead: MS-DIAL writes each of the 4 header rows as one row-label cell (`Class`, `File type`, `Injection order`, `Batch ID`) immediately followed by one value cell per sample, so the column right after the `Class` cell in row 1 is where the real sample columns start.\n\n```r\n# MS-DIAL alignment export: real column header is on row 5, so skip the first 4 rows.\n# Filename is timestamped -- Sys.glob() instead of a literal name.\nexport_file \u003C- Sys.glob('AlignResult-*.mdalign')[1]\nmsdial \u003C- read.csv(export_file, sep = '\\t', skip = 4, check.names = FALSE)\n\n# Metadata columns appear before the per-sample intensity columns. Common ones:\n# 'Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name', 'Adduct type',\n# 'Fill %', 'MS\u002FMS assigned', 'Reference RT', 'Formula', 'Ontology', 'INCHIKEY',\n# 'SMILES', 'Annotation tag (VS1.0)'.\nmeta_cols \u003C- c('Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name',\n               'Adduct type', 'Fill %', 'MS\u002FMS assigned', 'Annotation tag (VS1.0)')\nmeta_cols \u003C- intersect(meta_cols, colnames(msdial))\n\n# Sample columns start right after the header block's \"Class\" label cell -- NOT\n# simply \"everything after the last known metadata column\" (real exports interleave\n# unlisted annotation\u002FQC columns before the real per-sample data; see above).\nheader_row1 \u003C- as.character(read.table(export_file, sep = '\\t', header = FALSE, nrows = 1,\n                                        check.names = FALSE, colClasses = 'character',\n                                        comment.char = '')[1, ])\nclass_idx \u003C- which(header_row1 == 'Class')\nsample_cols \u003C- colnames(msdial)[(class_idx + 1):ncol(msdial)]\n\nfeature_info \u003C- msdial[, meta_cols]\nintensity \u003C- as.matrix(msdial[, sample_cols])\nrownames(intensity) \u003C- msdial[['Alignment ID']]\nstorage.mode(intensity) \u003C- 'numeric'  # confirms every detected sample col is truly numeric\n```\n\n## Import the Alignment Result into Python\n\n**Goal:** Same split, in pandas.\n\n**Approach:** `skiprows=4` to land on the real header; locate the sample columns via the same `Class`-cell anchor as the R path above, not by position after the last known metadata column.\n\n```python\nimport csv\nimport pandas as pd\nimport glob\n\nexport_file = glob.glob('AlignResult-*.mdalign')[0]  # timestamped filename, not a literal AlignResult.txt\n\nwith open(export_file, newline='') as f:\n    header_row1 = next(csv.reader(f, delimiter='\\t'))\nclass_idx = header_row1.index('Class')\n\nmsdial = pd.read_csv(export_file, sep='\\t', skiprows=4)\nmeta_cols = ['Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name', 'Adduct type', 'Fill %', 'MS\u002FMS assigned', 'Annotation tag (VS1.0)']\nmeta_cols = [c for c in meta_cols if c in msdial.columns]\nsample_cols = msdial.columns[class_idx + 1:]  # everything after the \"Class\" cell, not after the last known metadata column\n\nfeature_info = msdial[meta_cols].copy()\nintensity = msdial[sample_cols].astype(float).copy()\nintensity.index = msdial['Alignment ID']\n```\n\n## Filter the Table Honestly\n\n**Goal:** Keep features supported by real signal and known confidence, without overtrusting annotation tags.\n\n**Approach:** Filter on Fill% (cross-sample presence), require MS\u002FMS support for any feature called identified, and tie the annotation tag to a real MSI confidence level rather than treating a name as proof.\n\n```r\n# Fill% is the fraction of samples with a DETECTED (not gap-filled) peak. Low Fill% means\n# the feature exists mostly as gap-filled noise-floor integrals, which fabricate intensity\n# (an honest 'below detection' becomes a positive number). 70% is a common floor -- but\n# MS-DIAL 5.x's real \"Fill %\" column is a 0-1 FRACTION (e.g. 1.00 = 100%), not 0-100\n# (confirmed on a real MSDIALCUI.exe 5.5.260820 run, 2026-09-16), so compare to 0.70:\nkeep_fill \u003C- feature_info[['Fill %']] >= 0.70\n\n# An annotated name without MS\u002FMS is at best an MSI Level 2\u002F3 putative ID (accurate mass\n# only). Require MS\u002FMS support before trusting any identity downstream. MS-DIAL 5.x's real\n# value is title-case text (\"True\"\u002F\"False\"), not \"TRUE\"\u002F\"FALSE\" -- an exact-case comparison\n# silently keeps zero features on real output, so compare case-insensitively:\nhas_msms \u003C- tolower(trimws(feature_info[['MS\u002FMS assigned']])) == 'true'\n\n# Annotation tag confidence (do NOT treat a name as an identification). The exact tag\n# vocabulary is MS-DIAL-version-dependent, so inspect unique(feature_info[['Annotation tag (VS1.0)']])\n# and map the strings the build actually emits rather than hard-coding them:\n#   Metabolite \u002F Lipid  with MS\u002FMS  -> MSI Level 2 (spectral library match)\n#   Suggested*          mass-only   -> MSI Level 3 (putative, no MS\u002FMS)\n#   Unknown                         -> unannotated feature\nfeature_info$msi_level \u003C- ifelse(feature_info[['Annotation tag (VS1.0)']] %in% c('Metabolite', 'Lipid') & has_msms, 2,\n                          ifelse(grepl('^Suggested', feature_info[['Annotation tag (VS1.0)']]), 3, NA))\n\nfiltered \u003C- intensity[keep_fill, ]\n```\n\n**Python:** the same `MS\u002FMS assigned` check needs a different guard, not just a different case. `pandas.read_csv` auto-casts a text column of literal `True`\u002F`False` (or `TRUE`\u002F`FALSE`) to native `bool` with no warning, so the R idiom's natural Python port (`== 'True'`) silently evaluates to all-`False` -- confirmed 2026-09-16 (0\u002F94 real MS\u002FMS-supported features flagged when ported naively). Force the comparison to be dtype-safe:\n\n```python\nkeep_fill = feature_info['Fill %'] >= 0.70  # same 0-1 fraction as the R path\nhas_msms = feature_info['MS\u002FMS assigned'].astype(str).str.strip().str.lower() == 'true'\n```\n\nConfidence-level honesty and orthogonal-evidence identification belong to metabolomics\u002Fmetabolite-annotation; this skill only routes the tag to the right level. Fill% \u002F blank \u002F drift filtering interacts with normalization-qc - process blanks and pooled QCs through the SAME run, then filter the aligned table.\n\n## Per-Method Failure Modes\n\n### DIA processed as DDA (wrong acquisition type)\n- **Trigger:** Running SWATH\u002FDIA data through `lcms` without ever setting DIA acquisition type.\n- **Mechanism:** Without DIA acquisition type set (per file, via a CSV `-i` with an `acquisition_type` column -- see \"Run MS-DIAL Headless\"), MS-DIAL does not deconvolve wide-isolation chimeric MS\u002FMS, so fragments from co-isolated precursors stay mixed.\n- **Symptom:** Library matches to the wrong compound; \"clean-looking\" spectra that fail orthogonal confirmation.\n- **Fix:** Pass `-i` a CSV with `acquisition_type=DIA` for those files (ABF input only); MS2Dec deconvolution is the entire reason to run DIA in MS-DIAL.\n\n### Over-trusting the annotation tag\n- **Trigger:** Filtering on `Annotation tag != Unknown` and calling the survivors \"identified.\"\n- **Mechanism:** A `Suggested*` tag is an accurate-mass guess with no MS\u002FMS; a named hit without MS\u002FMS is MSI Level 3.\n- **Symptom:** A marker list full of confident-sounding names that do not validate against standards.\n- **Fix:** Require MS\u002FMS support for any identity claim (case-insensitive check -- MS-DIAL 5.x's real value is `True`\u002F`False`, not `TRUE`\u002F`FALSE`); map tags to MSI levels (see filtering section) and defer to metabolomics\u002Fmetabolite-annotation.\n\n### Gap-fill masquerading as measurement\n- **Trigger:** Treating low-Fill% features as quantitative.\n- **Mechanism:** Gap-filling integrates whatever signal sits in the m\u002Fz-RT box even when no peak exists, turning a true below-detection (MNAR, left-censored) value into a positive number.\n- **Symptom:** \"Significant\" features that are mostly gap-filled in one group; shrunken fold-changes for on\u002Foff markers.\n- **Fix:** Report per-feature filled fraction; gate on Fill% >= 0.70 (MS-DIAL 5.x reports it as a 0-1 fraction, not 0-100 -- see filtering section); for inferential stats prefer MNAR-aware imputation over naive fill (see metabolomics\u002Fnormalization-qc).\n\n### GC-EI run through an LC pipeline\n- **Trigger:** Treating GC-EI data like LC peak-pick-then-group, or assuming MS-DIAL 5 has no GC mode.\n- **Mechanism:** EI needs component deconvolution, not adduct-style peak picking, and RI (not RT) alignment; the current MS-DIAL 5.x console's `gcms` subcommand does handle this (confirmed real and working on 5.5.260820) if a plain LC-style `lcms` run is used instead.\n- **Symptom:** Conflated co-eluting compounds and cross-lab RT misalignment.\n- **Fix:** Use `MSDIALCUI.exe gcms` (or AMDIS\u002FeRah); align on Kovats\u002FFAME retention index.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|---|---|---|\n| Fill% >= 70% (0.70 on MS-DIAL 5.x's real 0-1 Fill % scale) | Common untargeted practice | Below this, the feature is mostly gap-filled noise-floor integrals, not measurements |\n| QC CV (RSD) \u003C 20-30% | Broadhurst 2018 | Technical reproducibility floor; drop features noisier than this in pooled QCs |\n| D-ratio (sd_QC\u002Fsd_sample) \u003C 0.5 | Broadhurst 2018 | Keeps features whose technical variance is well below biological variance |\n| Blank filter: sample mean > 3-5x blank mean | Broadhurst 2018 | Removes background\u002Fcontaminant features present in process blanks |\n| ~10x more features than compounds | Mahieu 2017 | One metabolite makes adducts\u002Fisotopes\u002Ffragments; counting features over-counts hypotheses |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| `MsdialConsoleApp lcmsdda`\u002F`lcmsdia` not found | That naming is from the older pre-5.x console; current builds ship `MSDIALCUI.exe` with one `lcms` subcommand | Run `MSDIALCUI.exe` with no args to print the real subcommand list; use `lcms` for both DDA and DIA |\n| All columns land in one field on import | Header offset wrong; tab-separated export read as CSV | `skip=4` (R) \u002F `skiprows=4` (Python), set `sep='\\t'` |\n| `Fill %` filter keeps 0 features, or keeps everything | Comparing a 0-1 fraction (MS-DIAL 5.x's real scale) against a 70-100 threshold | Compare against 0.70, not 70 |\n| `MS\u002FMS assigned` filter always evaluates False | Real value is title-case `True`\u002F`False` text (Python: pandas may also silently cast it to native `bool`), not `TRUE`\u002F`FALSE` | Compare case-insensitively: `tolower(trimws(x)) == 'true'` (R) \u002F `x.astype(str).str.strip().str.lower() == 'true'` (Python) |\n| DIA input rejects mzML | DIA mode accepts ABF only | Convert vendor raw to ABF (Reifycs ABF converter) before setting `acquisition_type=DIA` |\n| `Annotation tag` column not found | Header changes across versions (e.g. `Annotation tag (VS1.0)`) | Match by prefix \u002F inspect `colnames()`; do not hard-code the suffix |\n| Console command not found on Linux | Expecting the GUI executable | The GUI (`MSDIAL.exe`) is Windows-only and hangs on unrecognized args; run the separately-packaged `MSDIALCUI` console binary (cross-platform) |\n| Few features detected | `Minimum peak height` default too high for the instrument | Lower it toward the real baseline; defaults are TOF-tuned |\n\n## References\n\n- Tsugawa H, Cajka T, Kind T, Ma Y, Higgins B, Ikeda K, Kanazawa M, VanderGheynst J, Fiehn O, Arita M. MS-DIAL: data-independent MS\u002FMS deconvolution for comprehensive metabolome analysis. *Nat Methods.* 2015; 12(6):523-526.\n- Tsugawa H, Ikeda K, Takahashi M, et al. A lipidome atlas in MS-DIAL 4. *Nat Biotechnol.* 2020; 38(10):1159-1163.\n- Takeda H, Takahashi M, Ikeda K, et al. MS-DIAL 5 multimodal mass spectrometry data mining unveils lipidome complexities. *Nat Commun.* 2024; 15:9903.\n- Li Z, Lu Y, Guo Y, Cao H, Wang Q, Shui W. Comprehensive evaluation of untargeted metabolomics data processing software in feature detection, quantification and discriminating marker selection. *Anal Chim Acta.* 2018; 1029:50-57.\n- Mahieu NG, Patti GJ. Systems-level annotation of a metabolomics data set reduces 25,000 features to fewer than 1,000 unique metabolites. *Anal Chem.* 2017; 89(19):10397-10406.\n- Broadhurst D, Goodacre R, Reinke SN, Kuligowski J, Wilson ID, Lewis MR, Dunn WB. Guidelines and considerations for the use of system suitability and quality control samples in mass spectrometry assays applied in untargeted clinical metabolomic studies. *Metabolomics.* 2018; 14(6):72.\n- Stein SE. An integrated method for spectrum extraction and compound identification from gas chromatography\u002Fmass spectrometry data (AMDIS). *J Am Soc Mass Spectrom.* 1999; 10(8):770-781.\n\n## When NOT to Use This Skill\n\n- Need fully scripted, version-pinned R processing with custom peak-picking parameters -> metabolomics\u002Fxcms-preprocessing.\n- The data is already lipid-annotated or the question is lipid-class\u002Fspecies-level -> metabolomics\u002Flipidomics.\n- The question is about confidence-level honesty or orthogonal-evidence identification for a feature you already have -> metabolomics\u002Fmetabolite-annotation.\n- The question is drift correction, QC-CV\u002FD-ratio filtering, blank filtering, or MNAR-aware imputation on an already-aligned table -> metabolomics\u002Fnormalization-qc (this skill only routes the Fill%\u002FMS-MS\u002Fannotation-tag columns to the right level; it does not implement those filters).\n\n## Related Skills\n\n- metabolomics\u002Fxcms-preprocessing - Programmatic R preprocessing and the feature-table-as-artifact framing\n- metabolomics\u002Flipidomics - Lipid annotation mode and LipidBlast workflows\n- metabolomics\u002Fmetabolite-annotation - MSI confidence levels and orthogonal-evidence identification\n- metabolomics\u002Fnormalization-qc - Drift correction, QC\u002FCV\u002FD-ratio filtering, MNAR-aware imputation\n","## Version Compatibility\n\nReference examples tested with: MS-DIAL console 5.5.260820 (`MSDIALCUI.exe` -- confirmed installed and run on real data 2026-09-16), pandas 2.2+, R 4.3+\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: run `MSDIALCUI.exe` (or `MSDIALCUI` on Linux\u002FMac) with no arguments to print the current subcommand\u002Fflag list, then `MSDIALCUI.exe \u003Csubcommand> --help` for that subcommand's real options\n- R: `packageVersion('\u003Cpkg>')` then `?function_name` to verify parameters\n- Python: `pip show pandas` then `help(module.function)` to check signatures\n\nThe MS-DIAL GUI (`MSDIAL.exe`) runs only on Windows and hangs waiting for input if launched with `--help` or any unrecognized argument; the **separately-distributed** console app (`MSDIALCUI.exe`, packaged as its own `MSDIAL.console.*` release asset) is the cross-platform headless entry, and its real subcommand list -- confirmed by running it with no arguments -- is `gcms`, `lcms`, `lcimms`, `dims`, `imms`, `msn`, `eic`, `rtcorrection`, `imagegen`. GC-MS is real and working here: `gcms` is backed by its own `MsdialGcMsApi.dll` in the same release, so GC-EI does not require sourcing a separate MS-DIAL 4 build (see \"Why GC-EI Is Different\" below for what changed). If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt rather than retrying.\n\n# MS-DIAL Preprocessing\n\n**\"Process my LC-MS run with MS-DIAL and give me a feature table\"** -> Pick peaks per file, deconvolve chimeric MS\u002FMS into clean component spectra (MS2Dec), align across samples, gap-fill, then import the alignment result and filter it honestly.\n- CLI: `MSDIALCUI.exe lcms -i \u003Cin> -o \u003Cout> -m \u003Cparam.txt>` for LC-MS (DDA and DIA share this one subcommand -- see \"Run MS-DIAL Headless\" for how acquisition type is actually set); `MSDIALCUI.exe gcms -i \u003Cin> -o \u003Cout> -m \u003Cparam.txt>` for GC-MS\n- R: `read.csv(..., skip = 4, check.names = FALSE)` to parse the alignment export\n- Python: `pandas.read_csv(..., skiprows=4)` for the same export\n\n## The Single Most Important Insight -- Preprocessing Software Is Not Neutral\n\nThe same raw files through MS-DIAL versus XCMS yield different feature tables and different marker lists. Li 2018 benchmarked five tools on a 1,100-compound standard and found that while feature *detection* was broadly similar, *quantification* and the set of selected discriminating markers differed by tool. A metabolomics \"hit\" is conditional on (raw data + software + version + every parameter + fill\u002Ffilter order), not on the raw files alone. MS-DIAL's specific differentiator is **MS2Dec deconvolution**: it reconstructs clean, library-matchable MS\u002FMS spectra from chimeric DDA\u002FDIA fragment data, which is what makes wide-window DIA (SWATH) tractable at all. Report the full processing specification as part of the result, and treat a finding that survives only one pipeline as a candidate, not a result.\n\n## MS-DIAL vs XCMS\n\n| Axis | MS-DIAL | XCMS |\n|---|---|---|\n| Interface | Windows GUI + cross-platform console | R package (scriptable everywhere) |\n| Core differentiator | MS2Dec MS\u002FMS deconvolution (DDA + DIA) | centWave peak picking, full programmatic control |\n| Annotation | Built-in (library + MS-FINDER + LipidBlast) | Separate (CAMERA, downstream tools) |\n| Lipidomics | Strong (predicted-CCS \u002F EAD structural elucidation in v5) | Manual |\n| Reproducibility unit | Param file + GUI choices | Versioned R script |\n| Best when | DIA data, lipidomics, GUI workflow, built-in IDs | Scripted pipelines, custom parameters, cohort scale |\n\nUse MS-DIAL when DIA deconvolution or built-in lipid annotation is the point; use metabolomics\u002Fxcms-preprocessing for fully scripted, version-pinned cohort processing. The strongest untargeted claims replicate across both.\n\n## Decision Tree by Scenario\n\n| Situation | Do | Why |\n|---|---|---|\n| LC-MS, top-N MS\u002FMS (DDA) | `MSDIALCUI.exe lcms` (folder input, or `acquisition_type=DDA` per file in a CSV `-i`) | Cleaner per-precursor MS2, but intensity-biased, stochastic coverage |\n| LC-MS, wide-window MS\u002FMS (DIA \u002F SWATH) | `MSDIALCUI.exe lcms` (ABF input only; set `acquisition_type=DIA` per file in a CSV `-i`) | Complete MS2 coverage; chimeric spectra REQUIRE MS2Dec to be usable |\n| GC-EI run | `MSDIALCUI.exe gcms`, or AMDIS\u002FeRah | EI fragments every co-eluting compound; deconvolution IS detection (see below) |\n| Headless \u002F Linux cluster | `MSDIALCUI` (cross-platform console binary) with a `-m` param file | GUI is Windows-only; console is the reproducible batch path |\n| Lipid-focused study | MS-DIAL + LipidBlast | -> metabolomics\u002Flipidomics for lipid annotation mode |\n| Already have an alignment CSV | skip processing, parse + filter | See import + honest-filter sections below |\n\n## Why GC-EI Is Different\n\nIn GC-EI, 70 eV ionization fragments every compound reproducibly, so the trace at any retention time is a superposition of fragments from several co-eluting molecules. Naive peak picking conflates them; **deconvolution into component spectra IS the feature-detection step**, then each component is matched against EI+RI libraries (NIST, FiehnLib). Cross-run\u002Fcross-lab alignment uses **retention index** (Kovats n-alkanes, or Fiehn FAME markers giving diagnostic m\u002Fz 74\u002F87) rather than raw RT, because RT drifts with column aging. GC-MS is supported directly by the current MS-DIAL 5.x console's `gcms` subcommand (confirmed real and working on 5.5.260820, backed by its own `MsdialGcMsApi.dll`) -- a separate MS-DIAL 4 build is not required.\n\n## Run MS-DIAL Headless (console)\n\n**Goal:** Process a folder of converted spectra into an alignment table without the GUI.\n\n**Approach:** Pick the real subcommand (`lcms` or `gcms` -- there is no separate `lcmsdda`\u002F`lcmsdia` token in the current console), point `-i`\u002F`-o`\u002F`-m` at input dir, output dir, and a method (parameter) file; keep `-p` only if the project should reopen in the GUI.\n\nVerified 2026-09-16 against the real, installed `MSDIALCUI.exe` 5.5.260820: `MSDIALCUI.exe lcms -i \u003Cdir> -o \u003Cdir> -m \u003Cmethod.txt>` ran end to end on a real DDA mzML file and produced a real alignment export (see \"Import the Alignment Result\" below for its actual filename and column layout).\n\n```bash\n# LC-MS (DDA or DIA -- one subcommand covers both). Accepts netCDF\u002FmzML\u002FABF for DDA;\n# DIA\u002FSWATH accepts ABF ONLY (convert vendor raw -> ABF first; MS2Dec is the point).\nMSDIALCUI.exe lcms -i .\u002FLCMS\u002F -o .\u002FLCMS_out\u002F -m .\u002FMsdial-lcms-Param.txt\n\n# Acquisition type (DDA vs DIA) is not a console token -- it is set per file. For a\n# single-mode batch, a plain input folder is enough (every file processed the same\n# way, as above). To mix modes or set it explicitly, pass -i a CSV instead of a folder,\n# with one row per raw file and an `acquisition_type` column (DDA or DIA), per the\n# official MS-DIAL 5 console tutorial (systemsomicslab.github.io\u002Fmsdial5tutorial):\n#   file_path,file_name,file_type,class_id,acquisition_type,batch_order,analytical_order,factor\n#   LCMS\u002Fsample1.mzML,sample1,Sample,A,DDA,1,1,1\nMSDIALCUI.exe lcms -i .\u002Ffilelist.csv -o .\u002FLCMS_out\u002F -m .\u002FMsdial-lcms-Param.txt\n\n# GC-EI: retention-index alignment, quant-mass quantification. Real and working in\n# the current 5.x console (see \"Why GC-EI Is Different\" above) -- no MS-DIAL 4 needed.\nMSDIALCUI.exe gcms -i .\u002FGCMS\u002F -o .\u002FGCMS_out\u002F -m .\u002FMsdial-GCMS-Param.txt -p\n```\n\nThe parameter (`-m`) file is plain text with **`Key: Value`** pairs (colon-separated, one per line, `#` for comments) -- not `Key=Value`. The `Minimum peak height` key is the direct analog of an intensity floor and is instrument-dependent: the GUI default is tuned for a TOF and is often far too high (or its baseline assumption wrong) for an Orbitrap. Set the alignment reference to a pooled QC, never to file #1 by default.\n\n## Import the Alignment Result into R\n\n**Goal:** Split the MS-DIAL alignment export into a feature-metadata frame and an intensity matrix.\n\n**Approach:** The export carries four header rows above the real column header (sample class \u002F file type \u002F injection order \u002F batch), so skip them. Verified 2026-09-16 against a real `MSDIALCUI.exe` 5.5.260820 run: the file is **not** named `AlignResult.txt` -- the console writes `AlignResult-\u003Ctimestamp>.mdalign` (still a plain tab-separated text file, plus sibling `.mzTab` and `.qa.tsv` exports of the same run); glob for `AlignResult-*.mdalign` rather than assuming the literal name. Metadata columns precede the per-sample intensity columns, but real exports interleave extra annotation\u002FQC columns (Formula, Ontology, INCHIKEY, SMILES, matched-flag and dot-product-score columns, spectra text, ...) between the last *known* metadata column and the real sample columns -- taking \"everything after the last known metadata column\" pulls those text columns into what should be a numeric matrix. Anchor on the header block instead: MS-DIAL writes each of the 4 header rows as one row-label cell (`Class`, `File type`, `Injection order`, `Batch ID`) immediately followed by one value cell per sample, so the column right after the `Class` cell in row 1 is where the real sample columns start.\n\n```r\n# MS-DIAL alignment export: real column header is on row 5, so skip the first 4 rows.\n# Filename is timestamped -- Sys.glob() instead of a literal name.\nexport_file \u003C- Sys.glob('AlignResult-*.mdalign')[1]\nmsdial \u003C- read.csv(export_file, sep = '\\t', skip = 4, check.names = FALSE)\n\n# Metadata columns appear before the per-sample intensity columns. Common ones:\n# 'Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name', 'Adduct type',\n# 'Fill %', 'MS\u002FMS assigned', 'Reference RT', 'Formula', 'Ontology', 'INCHIKEY',\n# 'SMILES', 'Annotation tag (VS1.0)'.\nmeta_cols \u003C- c('Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name',\n               'Adduct type', 'Fill %', 'MS\u002FMS assigned', 'Annotation tag (VS1.0)')\nmeta_cols \u003C- intersect(meta_cols, colnames(msdial))\n\n# Sample columns start right after the header block's \"Class\" label cell -- NOT\n# simply \"everything after the last known metadata column\" (real exports interleave\n# unlisted annotation\u002FQC columns before the real per-sample data; see above).\nheader_row1 \u003C- as.character(read.table(export_file, sep = '\\t', header = FALSE, nrows = 1,\n                                        check.names = FALSE, colClasses = 'character',\n                                        comment.char = '')[1, ])\nclass_idx \u003C- which(header_row1 == 'Class')\nsample_cols \u003C- colnames(msdial)[(class_idx + 1):ncol(msdial)]\n\nfeature_info \u003C- msdial[, meta_cols]\nintensity \u003C- as.matrix(msdial[, sample_cols])\nrownames(intensity) \u003C- msdial[['Alignment ID']]\nstorage.mode(intensity) \u003C- 'numeric'  # confirms every detected sample col is truly numeric\n```\n\n## Import the Alignment Result into Python\n\n**Goal:** Same split, in pandas.\n\n**Approach:** `skiprows=4` to land on the real header; locate the sample columns via the same `Class`-cell anchor as the R path above, not by position after the last known metadata column.\n\n```python\nimport csv\nimport pandas as pd\nimport glob\n\nexport_file = glob.glob('AlignResult-*.mdalign')[0]  # timestamped filename, not a literal AlignResult.txt\n\nwith open(export_file, newline='') as f:\n    header_row1 = next(csv.reader(f, delimiter='\\t'))\nclass_idx = header_row1.index('Class')\n\nmsdial = pd.read_csv(export_file, sep='\\t', skiprows=4)\nmeta_cols = ['Alignment ID', 'Average Rt(min)', 'Average Mz', 'Metabolite name', 'Adduct type', 'Fill %', 'MS\u002FMS assigned', 'Annotation tag (VS1.0)']\nmeta_cols = [c for c in meta_cols if c in msdial.columns]\nsample_cols = msdial.columns[class_idx + 1:]  # everything after the \"Class\" cell, not after the last known metadata column\n\nfeature_info = msdial[meta_cols].copy()\nintensity = msdial[sample_cols].astype(float).copy()\nintensity.index = msdial['Alignment ID']\n```\n\n## Filter the Table Honestly\n\n**Goal:** Keep features supported by real signal and known confidence, without overtrusting annotation tags.\n\n**Approach:** Filter on Fill% (cross-sample presence), require MS\u002FMS support for any feature called identified, and tie the annotation tag to a real MSI confidence level rather than treating a name as proof.\n\n```r\n# Fill% is the fraction of samples with a DETECTED (not gap-filled) peak. Low Fill% means\n# the feature exists mostly as gap-filled noise-floor integrals, which fabricate intensity\n# (an honest 'below detection' becomes a positive number). 70% is a common floor -- but\n# MS-DIAL 5.x's real \"Fill %\" column is a 0-1 FRACTION (e.g. 1.00 = 100%), not 0-100\n# (confirmed on a real MSDIALCUI.exe 5.5.260820 run, 2026-09-16), so compare to 0.70:\nkeep_fill \u003C- feature_info[['Fill %']] >= 0.70\n\n# An annotated name without MS\u002FMS is at best an MSI Level 2\u002F3 putative ID (accurate mass\n# only). Require MS\u002FMS support before trusting any identity downstream. MS-DIAL 5.x's real\n# value is title-case text (\"True\"\u002F\"False\"), not \"TRUE\"\u002F\"FALSE\" -- an exact-case comparison\n# silently keeps zero features on real output, so compare case-insensitively:\nhas_msms \u003C- tolower(trimws(feature_info[['MS\u002FMS assigned']])) == 'true'\n\n# Annotation tag confidence (do NOT treat a name as an identification). The exact tag\n# vocabulary is MS-DIAL-version-dependent, so inspect unique(feature_info[['Annotation tag (VS1.0)']])\n# and map the strings the build actually emits rather than hard-coding them:\n#   Metabolite \u002F Lipid  with MS\u002FMS  -> MSI Level 2 (spectral library match)\n#   Suggested*          mass-only   -> MSI Level 3 (putative, no MS\u002FMS)\n#   Unknown                         -> unannotated feature\nfeature_info$msi_level \u003C- ifelse(feature_info[['Annotation tag (VS1.0)']] %in% c('Metabolite', 'Lipid') & has_msms, 2,\n                          ifelse(grepl('^Suggested', feature_info[['Annotation tag (VS1.0)']]), 3, NA))\n\nfiltered \u003C- intensity[keep_fill, ]\n```\n\n**Python:** the same `MS\u002FMS assigned` check needs a different guard, not just a different case. `pandas.read_csv` auto-casts a text column of literal `True`\u002F`False` (or `TRUE`\u002F`FALSE`) to native `bool` with no warning, so the R idiom's natural Python port (`== 'True'`) silently evaluates to all-`False` -- confirmed 2026-09-16 (0\u002F94 real MS\u002FMS-supported features flagged when ported naively). Force the comparison to be dtype-safe:\n\n```python\nkeep_fill = feature_info['Fill %'] >= 0.70  # same 0-1 fraction as the R path\nhas_msms = feature_info['MS\u002FMS assigned'].astype(str).str.strip().str.lower() == 'true'\n```\n\nConfidence-level honesty and orthogonal-evidence identification belong to metabolomics\u002Fmetabolite-annotation; this skill only routes the tag to the right level. Fill% \u002F blank \u002F drift filtering interacts with normalization-qc - process blanks and pooled QCs through the SAME run, then filter the aligned table.\n\n## Per-Method Failure Modes\n\n### DIA processed as DDA (wrong acquisition type)\n- **Trigger:** Running SWATH\u002FDIA data through `lcms` without ever setting DIA acquisition type.\n- **Mechanism:** Without DIA acquisition type set (per file, via a CSV `-i` with an `acquisition_type` column -- see \"Run MS-DIAL Headless\"), MS-DIAL does not deconvolve wide-isolation chimeric MS\u002FMS, so fragments from co-isolated precursors stay mixed.\n- **Symptom:** Library matches to the wrong compound; \"clean-looking\" spectra that fail orthogonal confirmation.\n- **Fix:** Pass `-i` a CSV with `acquisition_type=DIA` for those files (ABF input only); MS2Dec deconvolution is the entire reason to run DIA in MS-DIAL.\n\n### Over-trusting the annotation tag\n- **Trigger:** Filtering on `Annotation tag != Unknown` and calling the survivors \"identified.\"\n- **Mechanism:** A `Suggested*` tag is an accurate-mass guess with no MS\u002FMS; a named hit without MS\u002FMS is MSI Level 3.\n- **Symptom:** A marker list full of confident-sounding names that do not validate against standards.\n- **Fix:** Require MS\u002FMS support for any identity claim (case-insensitive check -- MS-DIAL 5.x's real value is `True`\u002F`False`, not `TRUE`\u002F`FALSE`); map tags to MSI levels (see filtering section) and defer to metabolomics\u002Fmetabolite-annotation.\n\n### Gap-fill masquerading as measurement\n- **Trigger:** Treating low-Fill% features as quantitative.\n- **Mechanism:** Gap-filling integrates whatever signal sits in the m\u002Fz-RT box even when no peak exists, turning a true below-detection (MNAR, left-censored) value into a positive number.\n- **Symptom:** \"Significant\" features that are mostly gap-filled in one group; shrunken fold-changes for on\u002Foff markers.\n- **Fix:** Report per-feature filled fraction; gate on Fill% >= 0.70 (MS-DIAL 5.x reports it as a 0-1 fraction, not 0-100 -- see filtering section); for inferential stats prefer MNAR-aware imputation over naive fill (see metabolomics\u002Fnormalization-qc).\n\n### GC-EI run through an LC pipeline\n- **Trigger:** Treating GC-EI data like LC peak-pick-then-group, or assuming MS-DIAL 5 has no GC mode.\n- **Mechanism:** EI needs component deconvolution, not adduct-style peak picking, and RI (not RT) alignment; the current MS-DIAL 5.x console's `gcms` subcommand does handle this (confirmed real and working on 5.5.260820) if a plain LC-style `lcms` run is used instead.\n- **Symptom:** Conflated co-eluting compounds and cross-lab RT misalignment.\n- **Fix:** Use `MSDIALCUI.exe gcms` (or AMDIS\u002FeRah); align on Kovats\u002FFAME retention index.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|---|---|---|\n| Fill% >= 70% (0.70 on MS-DIAL 5.x's real 0-1 Fill % scale) | Common untargeted practice | Below this, the feature is mostly gap-filled noise-floor integrals, not measurements |\n| QC CV (RSD) \u003C 20-30% | Broadhurst 2018 | Technical reproducibility floor; drop features noisier than this in pooled QCs |\n| D-ratio (sd_QC\u002Fsd_sample) \u003C 0.5 | Broadhurst 2018 | Keeps features whose technical variance is well below biological variance |\n| Blank filter: sample mean > 3-5x blank mean | Broadhurst 2018 | Removes background\u002Fcontaminant features present in process blanks |\n| ~10x more features than compounds | Mahieu 2017 | One metabolite makes adducts\u002Fisotopes\u002Ffragments; counting features over-counts hypotheses |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| `MsdialConsoleApp lcmsdda`\u002F`lcmsdia` not found | That naming is from the older pre-5.x console; current builds ship `MSDIALCUI.exe` with one `lcms` subcommand | Run `MSDIALCUI.exe` with no args to print the real subcommand list; use `lcms` for both DDA and DIA |\n| All columns land in one field on import | Header offset wrong; tab-separated export read as CSV | `skip=4` (R) \u002F `skiprows=4` (Python), set `sep='\\t'` |\n| `Fill %` filter keeps 0 features, or keeps everything | Comparing a 0-1 fraction (MS-DIAL 5.x's real scale) against a 70-100 threshold | Compare against 0.70, not 70 |\n| `MS\u002FMS assigned` filter always evaluates False | Real value is title-case `True`\u002F`False` text (Python: pandas may also silently cast it to native `bool`), not `TRUE`\u002F`FALSE` | Compare case-insensitively: `tolower(trimws(x)) == 'true'` (R) \u002F `x.astype(str).str.strip().str.lower() == 'true'` (Python) |\n| DIA input rejects mzML | DIA mode accepts ABF only | Convert vendor raw to ABF (Reifycs ABF converter) before setting `acquisition_type=DIA` |\n| `Annotation tag` column not found | Header changes across versions (e.g. `Annotation tag (VS1.0)`) | Match by prefix \u002F inspect `colnames()`; do not hard-code the suffix |\n| Console command not found on Linux | Expecting the GUI executable | The GUI (`MSDIAL.exe`) is Windows-only and hangs on unrecognized args; run the separately-packaged `MSDIALCUI` console binary (cross-platform) |\n| Few features detected | `Minimum peak height` default too high for the instrument | Lower it toward the real baseline; defaults are TOF-tuned |\n\n## References\n\n- Tsugawa H, Cajka T, Kind T, Ma Y, Higgins B, Ikeda K, Kanazawa M, VanderGheynst J, Fiehn O, Arita M. MS-DIAL: data-independent MS\u002FMS deconvolution for comprehensive metabolome analysis. *Nat Methods.* 2015; 12(6):523-526.\n- Tsugawa H, Ikeda K, Takahashi M, et al. A lipidome atlas in MS-DIAL 4. *Nat Biotechnol.* 2020; 38(10):1159-1163.\n- Takeda H, Takahashi M, Ikeda K, et al. MS-DIAL 5 multimodal mass spectrometry data mining unveils lipidome complexities. *Nat Commun.* 2024; 15:9903.\n- Li Z, Lu Y, Guo Y, Cao H, Wang Q, Shui W. Comprehensive evaluation of untargeted metabolomics data processing software in feature detection, quantification and discriminating marker selection. *Anal Chim Acta.* 2018; 1029:50-57.\n- Mahieu NG, Patti GJ. Systems-level annotation of a metabolomics data set reduces 25,000 features to fewer than 1,000 unique metabolites. *Anal Chem.* 2017; 89(19):10397-10406.\n- Broadhurst D, Goodacre R, Reinke SN, Kuligowski J, Wilson ID, Lewis MR, Dunn WB. Guidelines and considerations for the use of system suitability and quality control samples in mass spectrometry assays applied in untargeted clinical metabolomic studies. *Metabolomics.* 2018; 14(6):72.\n- Stein SE. An integrated method for spectrum extraction and compound identification from gas chromatography\u002Fmass spectrometry data (AMDIS). *J Am Soc Mass Spectrom.* 1999; 10(8):770-781.\n\n## When NOT to Use This Skill\n\n- Need fully scripted, version-pinned R processing with custom peak-picking parameters -> metabolomics\u002Fxcms-preprocessing.\n- The data is already lipid-annotated or the question is lipid-class\u002Fspecies-level -> metabolomics\u002Flipidomics.\n- The question is about confidence-level honesty or orthogonal-evidence identification for a feature you already have -> metabolomics\u002Fmetabolite-annotation.\n- The question is drift correction, QC-CV\u002FD-ratio filtering, blank filtering, or MNAR-aware imputation on an already-aligned table -> metabolomics\u002Fnormalization-qc (this skill only routes the Fill%\u002FMS-MS\u002Fannotation-tag columns to the right level; it does not implement those filters).\n\n## Related Skills\n\n- metabolomics\u002Fxcms-preprocessing - Programmatic R preprocessing and the feature-table-as-artifact framing\n- metabolomics\u002Flipidomics - Lipid annotation mode and LipidBlast workflows\n- metabolomics\u002Fmetabolite-annotation - MSI confidence levels and orthogonal-evidence identification\n- metabolomics\u002Fnormalization-qc - Drift correction, QC\u002FCV\u002FD-ratio filtering, MNAR-aware imputation\n",{"name":5,"tool_type":24,"description":7,"primary_tool":25},"mixed","msdial","main","e0956dc9606356ab78468936b502e55a365282e2","specialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing",0,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists","https:\u002F\u002Fgithub.com\u002Fmrsonord2240","2026-10-12 03:19:04",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-metabolomics-msdial-preprocessing",{"tool":39,"command":40},"bunx","bunx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-metabolomics-msdial-preprocessing",{"tool":42,"command":43},"pnpm","pnpm dlx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-metabolomics-msdial-preprocessing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",true,[47,53],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"examples\u002Fprocess_msdial_output.R","OTHER","其他",7504,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002Fexamples\u002Fprocess_msdial_output.R",{"path":54,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":57,"sourceHtmlUrl":58},"usage-guide.md","REFERENCE","参考文档",4589,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002Fusage-guide.md",[60,67,74,81,88,95],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7CW36A6QAGWFE2C008M1XPG","bio-workflows-metabolomics-pipeline","Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC\u002Fdrift\u002Fnormalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics\u002Fisotope-tracing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-workflows-metabolomics-pipeline\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7CW2Y18623NA2S1Y30FRQW1","bio-metabolomics-xcms-preprocessing","Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment\u002FXcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave\u002Fgrouping\u002Falignment parameters. For drift correction and QC\u002FCV filtering execution see metabolomics\u002Fnormalization-qc; for metabolite identification see metabolomics\u002Fmetabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics\u002Fmsdial-preprocessing; for downstream statistics see metabolomics\u002Fstatistical-analysis.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-xcms-preprocessing\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7CW2M364HVWPNQEKE2WP4PP","bio-metabolomics-statistical-analysis","Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA\u002FHCA for QC), permutation-validated PLS-DA\u002FOPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch\u002FMann-Whitney\u002FANOVA\u002FLMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization\u002Fdrift correction see metabolomics\u002Fnormalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning\u002Fbiomarker-discovery and machine-learning\u002Fmodel-validation; for pathway interpretation see metabolomics\u002Fpathway-mapping; for design\u002Fpower\u002Fmultiplicity regime see experimental-design\u002Fmultiple-testing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-statistical-analysis\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7CW2BCBF851WYE03Z8XPEDQ","bio-metabolomics-pathway-mapping","Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA\u002FQEA), mummichog\u002FPSEA on raw m\u002Fz peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference\u002Fbackground set. For annotation confidence levels feeding ORA see metabolomics\u002Fmetabolite-annotation; for gene-set concepts see pathway-analysis\u002Fgo-enrichment and pathway-analysis\u002Fgsea; for joint gene+metabolite pathways see multi-omics-integration\u002Fmofa-integration.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-pathway-mapping\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7CW21NSZMCPMF7D9CHJM718","bio-metabolomics-normalization-qc","Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS\u002FGC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak\u002Ffeature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics\u002Fxcms-preprocessing or metabolomics\u002Fmsdial-preprocessing; transformation\u002Fscaling for modeling defers to metabolomics\u002Fstatistical-analysis; cross-study design issues link to experimental-design\u002Fbatch-design.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-normalization-qc\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M7CW1HG6R6AWNNR0SCX6612X","bio-metabolomics-metabolite-annotation","Turns untargeted LC-MS\u002FMS features (m\u002Fz, RT, MS\u002FMS) into confidence-stratified metabolite annotations using spectral-library matching (matchms), in-silico tools (SIRIUS\u002FCSI:FingerID, MetFrag) and molecular networking, and assigns a defensible MSI\u002FSchymanski confidence level to each. Use when naming detected features, scoring MS\u002FMS against a reference library, running SIRIUS, or deciding what confidence level an evidence set actually supports. For upstream feature extraction see metabolomics\u002Fxcms-preprocessing and metabolomics\u002Fmsdial-preprocessing; for downstream enrichment that must respect these levels see metabolomics\u002Fpathway-mapping; for lipid-specific structural annotation see metabolomics\u002Flipidomics.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-metabolite-annotation\u002FSKILL.md",[],[]]