Ms dial version compatibility

Generate and validate MS-DIAL version-specific configuration files

Summary

Generate default TOML-formatted options files for MS-DIAL 4 or MS-DIAL 5 via the LipoCLEAN --print argument, then validate that the configuration matches the target MS-DIAL version's column schema and scaling conventions before running lipid quality filtering. This skill ensures model and configuration compatibility, since models trained on one MS-DIAL version will not work with the other.

When to use

You are preparing to run LipoCLEAN on MS-DIAL output and need to create or update a configuration file, or you have switched between MS-DIAL 4 and MS-DIAL 5 data and need to verify that your options file and trained model are compatible with the current version's column naming and scaling.

When NOT to use

• Your input MS-DIAL export was generated with a version other than the one you specify in the --print argument; regenerate the export first.
• You already have a manually edited and validated options.txt; only regenerate if you are switching MS-DIAL versions or need to reset to defaults.
• You are not using LipoCLEAN for lipid quality filtering; this skill is specific to LipoCLEAN's configuration workflow.

Inputs

• MS-DIAL version identifier (4 or 5)
• Target output directory path
• Existing options.txt file (optional, for comparison)

Outputs

• TOML-formatted options.txt configuration file
• Validated mapping between MS-DIAL version and model/column schema

How to apply

Execute LipoCLEAN --print MSD4 or LipoCLEAN --print MSD5 (via executable, Conda, or Docker) to generate a version-specific options.txt file. Open the generated file and confirm it contains TOML-formatted keys appropriate for your target MS-DIAL version. Before running inference, verify that (1) the model file specified in the options matches the version (e.g., QE_Pro_model or TOF_model), (2) all column names and scaling factors in the config match MS-DIAL's output schema for that version, and (3) the MS-DIAL export used as input was generated with the same version. If upgrading from MS-DIAL 4 to 5 or vice versa, regenerate the options file rather than reusing the old one, since column names and scaling differ between versions.

Related tools

• LipoCLEAN (Command-line tool that generates version-specific default configuration files via --print MSD4 or --print MSD5 arguments and applies machine learning-based quality filtering to MS-DIAL lipid identifications) — https://github.com/stavis1/LipoCLEAN
• MS-DIAL (Upstream mass spectrometry data analysis software whose output (alignment results exported as msp format) serves as input to LipoCLEAN; LipoCLEAN requires version-matched configuration and models)

Examples

python -m lipoCLEAN --print MSD5

Evaluation signals

• The generated options.txt file exists and is readable as valid TOML syntax with no parse errors
• All required configuration keys for the specified MS-DIAL version (MSD4 or MSD5) are present in the options file
• The model name in the options file matches the version (e.g., QE_Pro_model or TOF_model for the target instrument family)
• When used with MS-DIAL export data from the same version, LipoCLEAN runs without column-name mismatch errors or scaling warnings
• Regenerating the options file for the opposite version (e.g., MSD5 after using MSD4) produces a file with different column definitions or scaling factors, confirming version-specific content

Limitations

• Models trained on MS-DIAL 4 data will not work with MS-DIAL 5 input and vice versa; separate model and configuration files are required for each version.
• Column names and scaling factors differ between MS-DIAL versions; manually created or edited options files from a different version will cause inference errors.
• The tool supports only MS-DIAL versions 4 and 5; no option generation is available for other versions.
• The --print argument generates a template; users must still edit paths and parameters (e.g., input file location) before running inference.

Evidence

• [intro] Configuration is provided via TOML formatted text files with default options available for MS-DIAL versions 4 and 5: "all options are given to the tool in a TOML formatted text file. Default options files for MS-DIAL 4 and 5 can be obtained"
• [readme] Default options files are generated using version-specific command-line arguments: "Default options files for MS-DIAL 4 and 5 can be obtained using the --print MSD4 or --print MSD5 command line arguments, respectively. These will create an options.txt file that you can edit."
• [readme] Models and configurations are version-specific and incompatible across MS-DIAL versions: "some columns were renamed and scaled differently between the two versions so a model trained on one version's data will not work with the other. Both the options file and the model are specific to a"
• [readme] Separate default options files must be obtained for each MS-DIAL version before running inference: "We provide separate default options files for each version that can be obtained with the --print MSD4 and --print MSD5 command line arguments, respectively."
• [readme] Generated options.txt file serves as editable configuration template: "If you want a default version of the options file run LipoCLEAN.exe --print MSD4. To use the tool on other data edit the options.txt file."