tdfextractor

Converts Bruker timsTOF .d folders into MS2, MGF, or mzML files that downstream search engines and de novo sequencing tools already know how to read. It's built on tdfpy for the raw PASEF data access, so you get filtering, precursor handling, and batch processing without writing any Bruker SDK code yourself.

Highlights

• Three output formats — MS2 (MS-GF+, Comet), MGF (general-purpose, Casanovo-tuned), and mzML (includes MS1 and MS2 PASEF spectra with configurable compression/encoding).
• Built-in presets — --ip2 for IP2 search engine defaults, --casanovo for de novo sequencing defaults.
• Extensive spectrum and precursor filtering — intensity, m/z, charge, retention time, CCS, and neutral mass thresholds, plus optional precursor peak removal and top-N peak trimming.
• Batch processing — point at a directory of .d folders and process them with multiple --workers.
• mzML centroiding and compression controls — choose noise filters, m/z/ion-mobility tolerances, and per-array compression (zlib, zstd, numpress-*).
• Also usable as a library — write_ms2_file, write_mgf_file, and write_mzml_file take the same typed argument dataclasses as the CLI.

Installation

pip install tdfextractor

Usage

tdfextractor provides three command-line tools for extracting spectra:

MS2 Extraction

Extract MS2 format files (compatible with MS-GF+, Comet, etc.):

ms2-extractor /path/to/sample.d

# shorthand
ms2-ex 
ms2-ex /path/to/sample.d --output custom_output.ms2 --min-intensity 100 --min-charge 2
ms2-ex /path/to/directory_with_multiple_d_folders --output /path/to/output_directory

MGF Extraction

Extract MGF format files

mgf-extractor /path/to/sample.d

#shorthand
mgf-ex
mgf-ex /path/to/sample.d --casanovo  # Optimized for Casanovo de novo sequencing
mgf-ex /path/to/directory_with_multiple_d_folders --output /path/to/output_directory

mzML Extraction

Extract mzML format files (includes both MS1 and MS2 PASEF spectra):

mzml-extractor /path/to/sample.d

# shorthand
mzml-ex /path/to/sample.d
mzml-ex /path/to/sample.d --no-ms1  # MS2 spectra only
mzml-ex /path/to/sample.d --mz-compression zstd --intensity-encoding 32
mzml-ex /path/to/directory_with_multiple_d_folders --output /path/to/output_directory

Output Options

Both extractors support flexible output options:

1. No output specified: Files are created within each .D folder with auto-generated names
2. Specific file path: Use -o filename.ms2 or -o filename.mgf for single .D folder processing
3. Output directory: Use -o /path/to/output_dir for batch processing multiple .D folders
4. Overwrite protection: Use --overwrite to replace existing output files

Batch Processing

When processing multiple .D folders, the extractors will:

• Automatically find all .D folders in the specified directory
• Create output files with names matching the .D folder names
• Skip existing files unless --overwrite is specified
• Create the output directory if it doesn't exist

Command Line Arguments

Both MS2 and MGF extractors share the same arguments, with only a few format-specific options:

Format-Specific Arguments

MS2 Extractor Only:

• --ip2: Use IP2 preset settings (sets min charge to 2, top 500 peaks)

MGF Extractor Only:

• --casanovo: Use Casanovo preset settings (enables precursor removal, top-150 peaks, min intensity 0.01, m/z range 50-2500, min charge 2)

mzML Extractor Only:

Performance Options

The --workers argument allows parallel processing of multiple .d folders:

# Process multiple .d folders with 4 worker threads
mgf-ex /path/to/directory_with_multiple_d_folders --workers 4

Note: Workers only affect processing when multiple .d folders are being processed simultaneously. Each worker processes one complete .d folder independently.

Python API

Every extractor is also importable as a function, driven by the same typed argument dataclass the CLI builds internally:

from tdfextractor import Ms2Args, write_ms2_file

args = Ms2Args(
    analysis_dir="/path/to/sample.d",
    output_file="sample.ms2",
    min_precursor_charge=2,
    top_n_peaks=500,
)
write_ms2_file(args)

MgfArgs and write_mgf_file / MzmlArgs and write_mzml_file follow the same pattern. BaseExtractorArgs documents the fields shared by all three.

License

MIT