Deconvolution Pipeline¶

The deconvolution process can be pipelined from start to finish using the ScanProcessor class. This includes precursor recalculation and coisolation detection. ScanProcessor is intended to be used either as a replacement for ScanIterator when deconvolution is desired, or that it’s ScanProcessor.process() method will be used to handle individual ScanBunch objects/pairs of precursor Scan objects and a list of product Scan objects.

The free-function process() is a convenience wrapper around ScanProcessor, with fewer configurable parameters.

from ms_deisotope import ScanProcessor, glycopeptide, peptide
from ms_deisotope.scoring import PenalizedMSDeconVFitter, MSDeconVFitter
from ms_deisotope.test.common import datafile

# Locate example dataset
example_file = datafile("20150710_3um_AGP_001_29_30.mzML.gz")

proc = processor.ScanProcessor(example_file, ms1_deconvolution_args={
    "averagine": glycopeptide,
    "scorer": PenalizedMSDeconVFitter(20., 2.),
    "truncate_after": 0.95
}, msn_deconvolution_args={
    "averagine": peptide,
    "scorer": MSDeconVFitter(10.),
    "truncate_after": 0.8
})

bunch = next(proc)
print(bunch)
print(bunch.precursor.deconvoluted_peak_set)

class ms_deisotope.processor.ScanProcessor(data_source, ms1_peak_picking_args=None, msn_peak_picking_args=None, ms1_deconvolution_args=None, msn_deconvolution_args=None, pick_only_tandem_envelopes=False, default_precursor_ion_selection_window=1.5, trust_charge_hint=True, loader_type=None, envelope_selector=None, terminate_on_error=True, ms1_averaging=0, respect_isolation_window=False, too_many_peaks_threshold=7000)[source]¶

Orchestrates the deconvolution of a ScanIterator scan by scan. This process will apply different rules for MS1 scans and MSn scans. This type itself mimics a ScanIterator, consuming (raw) mass spectral data and producing deisotoped and charge deconvolved spectra.

The algorithms used for each task are independent and can be specified in the appropriate attribute dictionary, however there is information sharing between each MS1 scan and its MSn scans as the precursor monoisotopic mass is recalibrated according to the MS1 processing arguments, and the selected charge state is used to limit the charge range used in the matching MSn scan. These are described by PriorityTarget objects.

If an averagine-based deconvoluter is used, the averagine cache will be pre-populated.

At the moment, MSn assumes only MS2. Until MS3 data become available for testing, this limit will remain.

data_source¶

Any valid object to be passed to the loader_type callable to produce a ScanIterator instance. A path to a mass spectrometry data file, a file-like object, or an instance of ScanIterator. Used to populate reader

Type: str, ScanIterator or file-like

loader_type¶

A callable, which when passed data_source returns an instance of ScanIterator. By default, this is MSFileLoader(). Used to populate reader

Type: callable

reader¶

Any object implementing the ScanIterator interface, produced by calling loader_type on data_source.

Type: ScanIterator

ms1_deconvolution_args¶

The arguments passed to deconvolute_peaks() for MS1 scans. This dictionary’s keys should match the arguments of deconvolute_peaks(), all other arguments are passed through to configure the deconvoluter or will be ignored.

Type: dict

ms1_peak_picking_args¶

The arguments passed to ms_peak_picker.pick_peaks() for MS1 scans.

Type: dict

msn_deconvolution_args¶

The arguments passed to deconvolute_peaks() for MSn scans. This dictionary’s keys should match the arguments of deconvolute_peaks(), all other arguments are passed through to configure the deconvoluter or will be ignored.

Type: dict

msn_peak_picking_args¶

The arguments passed to ms_peak_picker.pick_peaks() for MSn scans.

Type: dict

pick_only_tandem_envelopes¶

Whether or not to process whole MS1 scans or just the regions around those peaks chosen for MSn

Type: bool

default_precursor_ion_selection_window¶

Size of the selection window to use when pick_only_tandem_envelopes is True and the information is not available in the scan.

Type: float

trust_charge_hint¶

Whether or not to trust the charge provided by the data source when determining the charge state of precursor isotopic patterns. Defaults to True

Type: bool

respect_isolation_window¶

Whether to use the bounds of the isolation window to reject a monoisotopic peak solution

Type: bool

terminate_on_error¶

Whether or not to stop processing on an error. Defaults to True

Type: bool

ms1_averaging¶

The number of adjacent MS1 scans to average prior to picking peaks.

Type: int

deconvolute_precursor_scan(precursor_scan: ms_deisotope.data_source.scan.scan.Scan, priorities: Optional[List[ms_deisotope.processor.PriorityTarget]] = None, product_scans: Optional[List[ms_deisotope.data_source.scan.scan.Scan]] = None) → Tuple[ms_deisotope._c.peak_set.DeconvolutedPeakSetIndexed, ms_deisotope.utils.TargetedDeconvolutionResultBase][source]¶

Deconvolute the given precursor scan, giving priority to its product ions, correcting the precursor_information attributes of priority targets, as well as calculating the degree of precursor purity and coisolating ions.

Parameters

precursor_scan (Scan) – The precursor scan to deconvolute
priorities (list of PriorityTarget, optional) – The priority targets for the product ions derived from precursor_scan
product_scans (list of Scan) – The product ion scans of precursor_scan.

Returns

DeconvolutedPeakSet – The deconvoluted peaks of precursor_scan
list of PriorityTarget – The precursor ions selected, with updated mass and charge information

Raises

Exception – Any errors which are thrown during the deconvolution process may be thrown if terminate_on_error is True.

deconvolute_product_scan(product_scan: ms_deisotope.data_source.scan.scan.Scan) → ms_deisotope._c.peak_set.DeconvolutedPeakSetIndexed[source]¶

Deconvolute the peaks of product_scan.

This method will override the upper limit “charge_range” of msn_deconvolution_args to the charge information of the precursor ion.

This method sets the deconvoluted_peak_set of product_scan.

Parameters: product_scan (Scan) – The scan to deconvolute.
Returns
Return type: DeconvolutedPeakSet
Raises: Exception – Any errors which are thrown during the deconvolution process may be thrown if terminate_on_error is True.

next() → ms_deisotope.data_source.scan.base.ScanBunch[source]¶

Fetches the next bunch of scans from reader and invokes process() on them, picking peaks and deconvoluting them.

Returns
Return type: ScanBunch

pick_precursor_scan_peaks(precursor_scan: ms_deisotope.data_source.scan.scan.Scan) → Union[ms_peak_picker._c.peak_index.PeakIndex, ms_peak_picker._c.peak_set.PeakSetIndexed][source]¶

Picks peaks for the given precursor_scan using the appropriate strategy.

If ms1_averaging > 0, then the signal averaging strategy is used, otherwise peaks are picked directly.

Parameters: precursor_scan (Scan) –
Returns
Return type: PeakSet

pick_product_scan_peaks(product_scan: ms_deisotope.data_source.scan.scan.Scan) → Union[ms_peak_picker._c.peak_index.PeakIndex, ms_peak_picker._c.peak_set.PeakSetIndexed][source]¶

Pick the peaks of product scan

Parameters: product_scan (Scan) – The scan to pick peaks from.
Returns
Return type: PeakSet

process(precursor: ms_deisotope.data_source.scan.scan.Scan, products: List[ms_deisotope.data_source.scan.scan.Scan]) → ms_deisotope.data_source.scan.base.ScanBunch[source]¶

Fully preprocesses the precursor and products scans, performing any necessary information sharing.

This method may be used to process scans from other sources not from the wrapped ScanIterator.

Parameters

precursor (Scan) – An MS1 Scan
products (list of Scan) – A list of MSn Scans related to precursor

Returns

The fully processed version of precursor and products

Return type

ScanBunch

process_scan_group(precursor_scan: ms_deisotope.data_source.scan.scan.Scan, product_scans: List[ms_deisotope.data_source.scan.scan.Scan]) → Tuple[ms_deisotope.data_source.scan.scan.Scan, List[ms_deisotope.processor.PriorityTarget], List[ms_deisotope.data_source.scan.scan.Scan]][source]¶

Performs the initial extraction of information relating precursor_scan to product_scans and picks peaks for precursor_scan. Called by process(). May be used separately if doing the process step by step.

Parameters

precursor_scan (Scan) – An MS1 Scan
product_scans (list of Scan) – A list of MSn Scans related to precursor_scan

Returns

precursor_scan (Scan) – As Parameter
prioritiies (list of PriorityTarget) – list of the peak target windows in precursor_scan which are related to product_scans
product_scans (list of Scan) – As Parameter

start_from_scan(*args, **kwargs) → ms_deisotope.processor.ScanProcessor[source]¶

A wrapper around start_from_scan() provided by reader, if available.

Returns
Return type: self

Supporting Types¶

When an ion has been selected with a known m/z and charge, it may be wrapped in an instance of PriorityTarget.

class ms_deisotope.processor.PriorityTarget(peak, info, trust_charge_hint=True, precursor_scan_id=None, product_scan_id=None, isolation_window=None)[source]¶

Represent a targeted envelope deconvolution’s parameters and constraints.

This class is used to tell ms_deisotope.deconvolution.deconvolute_peaks() that the solution produced by this peak should be preferentially extracted.

info¶

The associated precursor information block which contains the charge state hint.

Type

PrecursorInformation

peak¶

The peak from which to start the deconvolution

Type

FittedPeak

trust_charge_hint¶

Whether or not to force the deconvoluter to only consider the charge specified in the hint.

Type

bool

mz¶

The m/z of peak

Type

float

charge¶

The charge state hint from info

Type

int

isolation_window¶

The isolation window for this precursor ion. May be None

Type

IsolationWindow

charge_range_hint(charge_range)[source]¶

Create an updated charge range for a Deconvoluter to search.

At the moment, this only amounts to either returning the charge range unchanged or returning a charge range that only contains the hinted charge state, depending upon whether trust_charge_hint is False or not.

Parameters

charge_range (tuple) – The charge range to update

Returns

The updated charge range

Return type

tuple