timsconvert package

Submodules

timsconvert.arguments module

timsconvert.arguments.args_check(args)

Check relevant arguments to ensure user input values are valid.

Parameters:

args (dict) – Arguments obtained from timsconvert.arguments.get_args().

timsconvert.arguments.get_args(server=False)

Parse command line parameters, including required, optional, and system parameters.

Parameters:

server (bool) – If enabled, allows the user to specify a custom url using the “–url” parameter, defaults to False

Returns:

Arguments with default or user specified values.

Return type:

dict

timsconvert.classes module

class timsconvert.classes.TimsconvertBafData(bruker_d_folder_name: str, baf2sql, raw_calibration=False, all_variables=True)

Bases: BafData

Child class of pyBaf2Sql.classes.BafData containing metadata from BAF files and methods from Baf2sql library to work with BAF format data.

Parameters:

  • bruker_d_folder_name (str) – Path to Bruker .d directory containing analysis.baf and analysis.sqlite.

  • baf2sql (ctypes.CDLL) – Library initialized by pyBaf2Sql.init_baf2sql.init_baf2sql_api().

  • raw_calibration (bool) – Whether to use recalibrated data (False) or not (True), defaults to False.

  • all_variables (bool) – Whether to load all variables from analysis.sqlite database, defaults to True.

subset_ms1_frames()

Subset timsconvert.classes.BafData.frames table (Spectra table from analysis.sqlite) to only include MS1 rows. Used during the subsetting process during data parsing/writing for memory efficiency. The subset pandas.DataFrame is stored in timsconvert.classes.TimsconvertBafData.ms1_frames.

class timsconvert.classes.TimsconvertTdfData(bruker_d_folder_name: str, tdf_sdk, use_recalibrated_state=True, pressure_compensation_strategy=PressureCompensationStrategy.NoPressureCompensation)

Bases: TdfData

Child class of pyTDFSDK.classes.TdfData containing metadata from TDF files and methods from TDF-SDK library to work with TDF format data.

Parameters:

  • bruker_d_folder_name (str) – Path to a Bruker .d directory containing analysis.tdf.

  • tdf_sdk (ctypes.CDLL) – Library initialized by pyTDFSDK.init_tdf_sdk.init_tdf_sdk_api().

  • use_recalibrated_state (bool) – Whether to use recalibrated data (True) or not (False), defaults to True.

  • pressure_compensation_strategy (enum.Enum) – Pressure compensation when opening TDF data (pyTDFSDK.ctypes_data_structures.PressureCompensationStrategy.NoPressureCompensation = None, pyTDFSDK.ctypes_data_structures.PressureCompensationStrategy.AnalyisGlobalPressureCompensation = analysis global pressure compensation, pyTDFSDK.ctypes_data_structures.PressureCompensationStrategy.PerFramePressureCompensation = per frame pressure compensation), defaults to No Pressure Compensation.

subset_ms1_frames()

Subset timsconvert.classes.TdfData.frames table (Frames table from analysis.tdf) to only include MS1 rows. Used during the subsetting process during data parsing/writing for memory efficiency. The subset pandas.DataFrame is stored in timsconvert.classes.TimsconvertTdfData.ms1_frames.

class timsconvert.classes.TimsconvertTsfData(bruker_d_folder_name: str, tdf_sdk, use_recalibrated_state=True)

Bases: TsfData

Child class of pyTDFSDK.classes.TsfData containing metadata from TSF files and methods from TDF-SDK library to work with TSF format data.

Parameters:

  • bruker_d_folder_name (str) – Path to a Bruker .d directory containing analysis.tsf.

  • tdf_sdk (ctypes.CDLL) – Library initialized by pyTDFSDK.init_tdf_sdk.init_tdf_sdk_api().

  • use_recalibrated_state (bool) – Whether to use recalibrated data (True) or not (False), defaults to True.

subset_ms1_frames()

Subset timsconvert.classes.TsfData.frames table (Frames table from analysis.tsf) to only include MS1 rows. Used during the subsetting process during data parsing/writing for memory efficiency. The subset pandas.DataFrame is stored in timsconvert.classes.TimsconvertTsfData.ms1_frames.

timsconvert.constants module

timsconvert.data_input module

timsconvert.data_input.check_for_multiple_analysis(bruker_dot_d_file)

Check to ensure that only a single .baf/.tsf/.tdf and associated .tsf_bin/.tdf_bin exists within the .d directory.

Parameters:

bruker_dot_d_file – Path to the .d directory of interest.

Type:

str

timsconvert.data_input.dot_d_detection(input_directory)

Search the input directory and any subdirectories for .d directory paths.

Parameters:

input_directory – Path to the directory to be searched.

Type:

str

Returns:

List of absolute paths for each .d directory found.

Return type:

list

timsconvert.data_input.schema_detection(bruker_dot_d_file)

Detect the schema used by the raw data in the Bruker .d directory.

Parameters:

bruker_dot_d_file – Path to the .d directory of interest.

Type:

str

Returns:

Capitalized schema extension (TDF, TSF, or BAF).

Return type:

str

timsconvert.parse module

timsconvert.parse.parse_lcms_baf(baf_data, frame_start, frame_stop, mode, ms2_only, profile_bins, encoding)

Parse group of frames from LC-MS(/MS) data from Bruker BAF files acquired in MS1 only, Auto MS/MS, MRM MS/MS, isCID MS/MS, or bbCID MS/MS mode in otofControl.

Parameters:

  • baf_data (timsconvert.classes.TimsconvertBafData) – baf_data object containing metadata from analysis.sqlite database.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

Returns:

Tuple of (list of dictionaries containing MS1 spectrum data, list of dictionaries containing MS/MS spectrum data).

Return type:

tuple[list[pyBaf2Sql.classes.BafSpectrum]]

timsconvert.parse.parse_lcms_tdf(tdf_data, frame_start, frame_stop, mode, ms2_only, exclude_mobility, profile_bins, encoding)

Parse group of frames from LC-MS(/MS) data from Bruker TDF files acquired in MS1 only, ddaPASEF MS/MS, diaPASEF MS/MS, bbCID MS/MS, MRM MS/MS, or prmPASEF MS/MS mode in timsControl.

Parameters:

  • tdf_data (timsconvert.classes.TimsconvertTdfData) – tdf_data object containing metadata from analysis.tdf database.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • exclude_mobility (bool | None) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

Returns:

Tuple of (list of dictionaries containing MS1 spectrum data, list of dictionaries containing MS/MS spectrum data).

Return type:

tuple[list[pyTDFSDK.classes.TdfSpectrum]]

timsconvert.parse.parse_lcms_tsf(tsf_data, frame_start, frame_stop, mode, ms2_only, profile_bins, encoding)

Parse group of frames from LC-MS(/MS) data from Bruker TSF files acquired in Auto MS/MS mode MS1 only, Auto MS/MS, MRM MS/MS, or bbCID MS/MS mode in timsControl.

Parameters:

  • tsf_data (timsconvert.classes.TimsconvertTsfData) – tsf_data object containing metadata from analysis.tsf database.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

Returns:

Tuple of (list of dictionaries containing MS1 spectrum data, list of dictionaries containing MS/MS spectrum data).

Return type:

tuple[list[pyTDFSDK.classes.TsfSpectrum]]

timsconvert.parse.parse_maldi_plate_map(plate_map_filename)

Parse a MALDI plate map from a CSV file without a column header or row index.

Parameters:

plate_map_filename (str) – Path to the MALDI plate map in CSV format.

Returns:

Dictionary containing standard MTP spot names as the key and spot label/category/condition as the value.

Return type:

dict

timsconvert.parse.parse_maldi_tdf(tdf_data, frame_start, frame_stop, mode, ms2_only, exclude_mobility, profile_bins, encoding)

Parse group of frames from MALDI-MS(/MS) data from Bruker TDF files acquired in MS1 only, MS/MS, or bbCID MS/MS mode in timsControl.

Parameters:

  • tdf_data (timsconvert.classes.TimsconvertTdfData) – tdf_data object containing metadata from analysis.tdf database.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • exclude_mobility (bool | None) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

Returns:

List of dictionaries containing spectrum data.

Return type:

list[pyTDFSDK.classes.TdfSpectrum]

timsconvert.parse.parse_maldi_tsf(tsf_data, frame_start, frame_stop, mode, ms2_only, profile_bins, encoding)

Parse group of frames from MALDI-MS(/MS) data from Bruker TSF files acquired in MS1 only, MS/MS, or bbCID MS/MS mode in timsControl.

Parameters:

  • tsf_data (timsconvert.classes.TimsconvertTsfData) – tsf_data object containing metadata from analysis.tsf database.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

Returns:

List of dictionaries containing spectrum data.

Return type:

list[pyTDFSDK.classes.TsfSpectrum]

timsconvert.timestamp module

timsconvert.timestamp.get_iso8601_timestamp()

Get timestamp in ISO 8601 format.

Returns:

ISO 8601 format timestamp.

Return type:

str

timsconvert.timestamp.get_timestamp()

Get timestamp in non-standard format that is compatible with Windows file system.

Returns:

Timestamp.

Return type:

str

timsconvert.write module

timsconvert.write.get_spectra_count(data)

Calculate the predicted number of spectra to be written.

Parameters:

data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

Returns:

Number of expected spectra.

Return type:

int

timsconvert.write.update_spectra_count(outdir, outfile, num_of_spectra, scan_count)

Calculate the actual number of spectra that were written to the output mzML file. Update is needed to prevent counting emtpy spectra that were omitted from the output. Performs this by iterating over tmp mzML file that was written and replacing the tmp file with a final mzML file with a true spectra count.

Parameters:

  • outdir (str) – Output directory path that was specified from the command line parameters or the original input file path if no output directory was specified.

  • outfile (str) – Output filename that was specified from the command line parameters or the original input filename if no output filename was specified.

  • num_of_spectra (int) – Number of spectra that was calculated for the current file being converted using timsconvert.write.get_spectra_count().

  • scan_count (int) – Final true count for the number of spectra from the current file being converted.

timsconvert.write.write_lcms_chunk_to_mzml(data, writer, frame_start, frame_stop, scan_count, mode, ms2_only, exclude_mobility, profile_bins, encoding, compression)

Parse and write out a group of spectra to an mzML file from an LC-MS(/MS) dataset using psims.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

  • writer (psims.mzml.MzMLWriter) – Instance of psims.mzml.MzMLWriter for output file.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • scan_count (int) – Current count for the number of spectra from the current file that have been converted.

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • exclude_mobility (bool) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

Returns:

Updated count for the number of spectra from the current file that have been converted.

Return type:

int

timsconvert.write.write_lcms_mzml(data, infile, outdir, outfile, mode, ms2_only, exclude_mobility, profile_bins, encoding, compression, barebones_metadata, chunk_size)

Parse and write out spectra to an mzML file from an LC-MS(/MS) dataset using psims.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

  • infile (str) – Input file path to be used for source file metadata.

  • outdir (str) – Output directory path that was specified from the command line parameters or the original input file path if no output directory was specified.

  • outfile (str) – Output filename that was specified from the command line parameters or the original input filename if no output filename was specified.

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • exclude_mobility (bool) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

  • barebones_metadata (bool) – If True, omit software and data processing metadata in the resulting mzML files. Used for compatibility with downstream analysis software that does not have support for newer CV params or UserParams.

  • chunk_size (int) – Number of MS1 spectra that to be used when subsetting dataset into smaller groups to pass onto timsconvert.write.write_lcms_chunk_to_mzml() for memory efficiency; larger chunk_size requires more memory during conversion.

timsconvert.write.write_maldi_dd_mzml(data, infile, outdir, outfile, mode, ms2_only, exclude_mobility, profile_bins, encoding, compression, maldi_output_file, plate_map, barebones_metadata)

Parse and write out spectra to an mzML file from a MALDI-MS(/MS) dried droplet dataset using psims.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData) – Object containing raw data information from TDF or TSF file.

  • infile (str) – Input file path to be used for source file metadata.

  • outdir (str) – Output directory path that was specified from the command line parameters or the original input file path if no output directory was specified.

  • outfile (str) – Output filename that was specified from the command line parameters or the original input filename if no output filename was specified.

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • exclude_mobility (bool) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

  • maldi_output_file (str) – Determines whether all spectra from a given .d dataset are written to a single mzML file (“combined”), written to individual mzML files (“individual”, i.e. one spectrum per file), or grouped to have one mzML file per annotation/label/condition (“sample”, requires CSV plate_map to be specified).

  • plate_map (str) – Path to the MALDI plate map in CSV format.

  • barebones_metadata (bool) – If True, omit software and data processing metadata in the resulting mzML files. Used for compatibility with downstream analysis software that does not have support for newer CV params or UserParams.

timsconvert.write.write_maldi_ims_chunk_to_imzml(data, imzml_file, frame_start, frame_stop, mode, exclude_mobility, profile_bins, encoding)

Parse and write out a group of spectra to an imzML file from a MALDI-MS(/MS) MSI dataset using pyimzML.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData) – Object containing raw data information from TDF or TSF file.

  • imzml_file (pyimzml.ImzMLWriter.ImzMLWriter) – Instance of pyimzml.ImzMLWriter.ImzMLWriter for output file.

  • frame_start (int) – Beginning frame number.

  • frame_stop (int) – Ending frame number (non-inclusive).

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • exclude_mobility (bool) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

timsconvert.write.write_maldi_ims_imzml(data, outdir, outfile, mode, exclude_mobility, profile_bins, imzml_mode, encoding, compression, chunk_size)

Parse and write out spectra to an imzML file from a MALDI-MS(/MS) MSI dataset using pyimzML.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData) – Object containing raw data information from TDF or TSF file.

  • outdir (str) – Output directory path that was specified from the command line parameters or the original input file path if no output directory was specified.

  • outfile (str) – Output filename that was specified from the command line parameters or the original input filename if no output filename was specified.

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • exclude_mobility (bool) – Whether to include mobility data in the output files, defaults to None.

  • profile_bins (int) – Number of bins to bin spectrum to.

  • imzml_mode (str) – Whether to export spectra in “processed” (individual m/z and intensity arrays per pixel) or “continuous” mode (single m/z array for the entire dataset, individual intensity arrays per pixel).

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

  • chunk_size (int) – Number of MS1 spectra that to be used when subsetting dataset into smaller groups to pass onto timsconvert.write.write_lcms_chunk_to_mzml() for memory efficiency; larger chunk_size requires more memory during conversion.

timsconvert.write.write_ms1_spectrum(writer, data, scan, encoding, compression, title=None)

Write an MS1 spectrum to an mzML file using psims.

Parameters:

  • writer (psims.mzml.MzMLWriter) – Instance of psims.mzml.MzMLWriter for output file.

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

  • scan (pyBaf2Sql.classes.BafSpectrum | pyTDFSDK.classes.TsfSpectrum | pyTDFSDK.classes.TdfSpectrum) – Object containing spectrum metadata and data arrays.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

  • title (str | None) – Spectrum title to be used for MALDI data, defaults to None.

timsconvert.write.write_ms2_spectrum(writer, data, scan, encoding, compression, parent_scan=None, title=None)

Write an MS/MS spectrum to an mzML file using psims.

Parameters:

  • writer (psims.mzml.MzMLWriter) – Instance of psims.mzml.MzMLWriter for output file.

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

  • scan (pyBaf2Sql.classes.BafSpectrum | pyTDFSDK.classes.TsfSpectrum | pyTDFSDK.classes.TdfSpectrum) – Object containing spectrum metadata and data arrays.

  • encoding (int) – Encoding command line parameter, either “64” or “32”.

  • compression (str) – Compression command line parameter, either “zlib” or “none”.

  • parent_scan (pyBaf2Sql.classes.BafSpectrum | pyTDFSDK.classes.TsfSpectrum | pyTDFSDK.classes.TdfSpectrum) – Object containing standard spectrum data for parent scan used to link MS/MS spectrum with an MS1 spectrum.

  • title (str | None) – Spectrum title to be used for MALDI data, defaults to None.

timsconvert.write.write_mzml_metadata(data, writer, infile, mode, ms2_only, barebones_metadata)

Write metadata to mzML file using psims. Includes spectral metadata, source files, software list, instrument configuration, and data processing. Note that TIMSCONVERT is not included as a data processing step due to a lack CV param and compatibility with downstream data analysis software.

Parameters:

  • data (timsconvert.classes.TimsconvertTdfData | timsconvert.classes.TimsconvertTsfData | timsconvert.classes.TimsconvertBafData) – Object containing raw data information from TDF, TSF, or BAF file.

  • writer (psims.mzml.MzMLWriter) – Instance of psims.mzml.MzMLWriter for output file.

  • infile (str) – Input file path to be used for source file metadata.

  • mode (str) – Mode command line parameter, either “profile”, “centroid”, or “raw”.

  • ms2_only (bool) – Whether to include MS1 data in the output files.

  • barebones_metadata (bool) – If True, omit software and data processing metadata in the resulting mzML files. Used for compatibility with downstream analysis software that does not have support for newer CV params or UserParams.

Module contents