Msconvert Workflow Configuration

msconvert-workflow-configuration

Summary

Configure and validate msconvert as a dependency for raw vendor mass spectrometry file conversion to mzML format, accounting for platform-specific installation paths (ProteoWizard on Windows, Docker on macOS). This skill ensures the conversion pipeline is correctly initialized before processing raw data files.

When to use

When you need to convert vendor-specific raw mass spectrometry files (.raw) to the open mzML format using imzML Writer, and msconvert is not yet installed or its location is not recognized by the system. This is a prerequisite step that must complete successfully before raw-to-mzML conversion can proceed.

When NOT to use

• Input data is already in mzML or imzML format — skip directly to mzML-to-imzML conversion or metadata annotation.
• You are working in an environment where Docker or ProteoWizard cannot be installed (e.g., restricted compute cluster without root access) — seek alternative conversion tools or pre-converted data.
• msconvert is already installed, discoverable in PATH, and has been confirmed working — this skill is redundant; proceed to raw-to-mzML conversion.

Inputs

• ProteoWizard installer (Windows) or Docker Desktop (macOS)
• System PATH environment variable (Windows) or Docker daemon (macOS)
• imzML Writer GUI or Python environment

Outputs

• Validated msconvert installation path registered in imzML Writer configuration
• Docker image (chambm/pwiz-skyline-i-agree-to-the-vendor-licenses) available and runnable (macOS)
• Confirmation that raw-to-mzML conversion can proceed

How to apply

On Windows, download and install ProteoWizard from https://proteowizard.sourceforge.io/download.html, then either add msconvert to the system PATH or manually provide its installation directory path when imzML Writer first prompts for it. On macOS, install Docker Desktop (https://www.docker.com/products/docker-desktop/), then either pre-pull the msconvert Docker image using docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses or allow imzML Writer to download it automatically on first use. Verify the configuration by launching the imzML Writer GUI and confirming that the system can locate msconvert (or confirm Docker is running and the image is accessible). The configuration is complete when msconvert is callable without manual path entry or when Docker successfully runs the pwiz-skyline image.

Related tools

• msconvert (Command-line tool that performs the actual binary-to-text conversion of vendor raw files to mzML format; invoked by imzML Writer internally) — https://proteowizard.sourceforge.io/download.html
• ProteoWizard (Windows software suite providing msconvert executable; downloaded and installed as a prerequisite on PC platforms) — https://proteowizard.sourceforge.io/download.html
• Docker (Containerization platform that runs msconvert via the pwiz-skyline image on macOS; must be installed and running for macOS users) — https://www.docker.com/products/docker-desktop/
• imzML Writer (Python package that orchestrates msconvert configuration, prompts for paths or Docker setup, and invokes msconvert via iw_utils.RAW_to_mzML() when configured) — https://github.com/VIU-Metabolomics/imzML_Writer

Examples

docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses && docker run --rm chambm/pwiz-skyline-i-agree-to-the-vendor-licenses msconvert --version

Evaluation signals

• On Windows: where msconvert or Get-Command msconvert returns a valid file path without error; imzML Writer no longer prompts for msconvert path on startup.
• On macOS: docker image ls | grep pwiz-skyline confirms the image is present; docker run --rm chambm/pwiz-skyline-i-agree-to-the-vendor-licenses msconvert --version returns version information without timeout or permission error.
• imzML Writer GUI launches without configuration dialogs or errors related to missing msconvert dependency.
• Calling iw_utils.RAW_to_mzML(raw_data_path) on a test .raw file completes without FileNotFoundError or executable-not-found exceptions.
• Generated mzML output file(s) contain valid XML structure and expected mass spectra data (verify with XML parser or mzML validator).

Limitations

• Windows users must manually install ProteoWizard; the installer is not bundled with imzML Writer and requires administrative privileges.
• macOS users must have Docker Desktop running; if Docker daemon is stopped, msconvert invocation will fail silently or timeout.
• Docker image pull on first use may take several minutes depending on network speed; pre-pulling the image is recommended for reproducibility and to avoid delays.
• msconvert invocation defaults to peakPicking settings; non-default centroid/profile modes or vendor-specific parameters cannot be configured at the workflow-configuration stage and must be set during actual raw-to-mzML conversion.
• Configuration is host-specific; moving imzML Writer to a different system or Docker container may require reconfiguration or re-pulling of the Docker image.

Evidence

• [readme] On PC, this can be installed normally from Proteowizard: https://proteowizard.sourceforge.io/download.html: "On PC, this can be installed normally from Proteowizard: https://proteowizard.sourceforge.io/download.html"
• [readme] imzML Writer will prompt you for the path to msconvert the first time you try to convert raw files (see Docs), or you can add msconvert to the system path if you'd like to run msconvert from the command line.: "imzML Writer will prompt you for the path to msconvert the first time you try to convert raw files (see Docs), or you can add msconvert to the system path"
• [readme] On Mac, you can still run msconvert via a docker image. First, install Docker: https://www.docker.com/products/docker-desktop/: "On Mac, you can still run msconvert via a docker image. First, install Docker: https://www.docker.com/products/docker-desktop/"
• [readme] Similarly, imzML Writer will prompt you to download the docker image the first time you try to call it. If you'd like to do this in advance you can open Terminal.app and run the command: docker pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses: "imzML Writer will prompt you to download the docker image the first time you try to call it. If you'd like to do this in advance you can open Terminal.app and run the command: docker pull"
• [methods] On Mac, confirm Docker is running and the pwiz-skyline Docker image is downloaded (pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses if needed).: "On Mac, confirm Docker is running and the pwiz-skyline Docker image is downloaded (pull chambm/pwiz-skyline-i-agree-to-the-vendor-licenses if needed)"
• [intro] Using imzML Writer depends on msconvert for conversion of raw vendor files to the open format mzML.: "Using imzML Writer depends on msconvert for conversion of raw vendor files to the open format mzML"