Local Usage

The command line interface version of TIMSCONVERT supports conversion of all experimental types specified above. Please note that certain versions of Linux may not be compatible with the Baf2Sql API used to convert BAF files. See this issue for more details.

Basic Example

Only the input parameter is required to run TIMSCONVERT. By default, the output file(s) can be found in the same directory as the input data using the same filenames as the original .d file(s). Please note that any previously converted mzML/imzML files in the output directory with the same filename will be overwritten. If no other parameters are specified, their default values will be used.

timsconvert --input [path to data]

Depending on the size of your data and the number of files being converted, TIMSCONVERT may take some time to finish conversion.

For a full list of parameters, use the --help flag.

timsconvert --help

See below for a full list of descriptions for each parameter.

Parameters

Parameter	Description
input	Filepath for Bruker .d file containing TSF or TDF file or directory containing multiple Bruker .d files.
outdir	Path to folder in which to write output file(s). Default = none
outfile	User defined filename for output if converting a single file, otherwise files will have same filename and overwrite each other. Default is none.
mode	Choose whether export to spectra in “raw” or “centroid” formats. Defaults to “centroid”.
compression	Choose between ZLIB compression (“zlib”) or no compression (“none”). Defaults to “zlib”.
ms2_only	Boolean flag that specifies only MS2 spectra should be converted.
exclude_mobility	Boolean flag used to exclude trapped ion mobility spectrometry data from exported data. Precursor ion mobility information is still exported.
encoding	Choose encoding for binary arrays: 32-bit (“32”) or 64-bit (“64”). Defaults to 64-bit.
profile_bins	Number of bins used to bin data when converting in profile mode. A value of 0 indicates no binning is performed. Defaults to 0.
barebones_metadata	Only use basic mzML metadata. Use if downstream data analysis tools throw errors with descriptive CV terms.
maldi_output_file	For MALDI dried droplet data, whether individual scans should be placed in individual files (“individual”), combined into a single file (“combined”), or combined by sample label (“sample”). Defaults to “combined”.
maldi_plate_map	Plate map to be used for parsing spots if –maldi_output_file == “individual” or –maldi_output_file == “sample”. Should be a .csv file with no header/index.
imzml_mode	Whether .imzML files should be written in “processed” or “continuous” mode. Defaults to “processed”.
chunk_size	Relative size of chunks of spectral data that are parsed and subsequently written at once. Increasing parses and write more spectra at once but increases RAM usage. Default = 10.
verbose	Boolean flag to determine whether to print logging output.
url	URL for server to run TIMSCONVERT (if submitting job through API). Default = localhost:5000

Notes on mode Parameter

There are 3 options for exporting spectra: raw, centroid, and profile mode. This section describes what each mode means for different types of raw data.

For TSF and BAF files, raw and centroid modes are equivalent and will export data in centroid mode. Note that for raw mode, all spectra will be labeled as centroided. For these file types, profile mode is also as described and will export spectra in profile mode.

For TDF files in which the data is exported without writing out the ion mobility binary arrays, raw mode exports centroided spectra using the tims_read_scans_v2 function from Bruker’s TDF-SDK. Note that as mentioned above, all spectra will be labeled as centroided. centroid mode exports centroided spectra using a different function, tims_extract_centroided_spectrum_for_frame_v2 function from TDF-SDK. This results in minor differences in the resulting line spectra, but most major peaks should be equivalent. For profile mode TDF files, the tims_extract_profile_for_frame function is used to extract a quasi-profile spectrum from the raw data.

For TDF files in which the data is exported with the ion mobiilty arrays (resulting in 3 binary data arrays for m/z, intensity, and ion mobility, only raw mode is available due to conversion speed and the resulting data size if centroid or profile mode are used. Again, all spectra are labeled as centroided.

Notes on barebones_metadata Parameter

If the --barebones_metadata flag is used when running TIMSCONVERT, the following metadata is not written to the resulting mzML file: 1) software list including acquistion and data conversion software, 2) data processing list including data conversion software, and 3) instrument name. This is done to allow for compatibility with older software predating the timsTOF, TDF-SDK, psims, etc. that cannot recognize those CVParams. Additionally, TIMSCONVERT is written out as a UserParam, and although it is technically correct, the presence of that UserParam is not always compatible with these software.

Testing

To test TIMSCONVERT locally:

• Download test data.

  cd [path to timsconvert]/test
  make download_test
  

• Test Python CLI workflow

  cd [path to timsconvert]/test
  make run_test
  make run_test_mobility
  

• Test Nextflow workflow

  cd [path to timsconvert]/test
  make run_nextflow_mobility