Common Scan Model

class ms_deisotope.data_source.common.Scan(data, source, peak_set=None, deconvoluted_peak_set=None, product_scans=None, annotations=None)[source]

Container for mass spectral data and associated descriptive information.

A Scan object is a generic object intended to be created by a ScanDataSource and describes a mass spectrum at each level of processing (Profile –> Peak Fitted –> Deconvoluted). The raw object provided by the source is wrapped and queried lazily when an attribute is requested, delegated through source.

To access the raw mass spectral signal, see arrays. This can be converted to a centroided peak list using pick_peaks(), populating peak_set. After picking peaks, deconvolute() can be used to deconvolute the spectrum, populating deconvoluted_peak_set.

To apply signal processing filters to the spectrum, reprofile() can create a copy of the object replacing arrays with a synthetic profile created from the fitted peaks in peak_set. Multiple spectra may be averaged together to form a new synthetic profile spectrum using average_with() (when the scans are already chosen) or average() (when selecting nearby scans automatically, MS1-only). The denoise() method can remove local unstructured noise. transform() can apply any filter from ms_peak_picker.scan_filter, returning a copy.

deconvoluted_peak_set

Deconvoluted peaks resulting from charge state deconvolution and deisotoping. Will be None if deconvolution has not been done.

Type

ms_deisotope.DeconvolutedPeakSet or None

peak_set

Picked peaks and (possibly) associated raw data points as produced by pick_peaks(). Will be None if peak picking has not been done.

Type

ms_peak_picker.PeakSet or None

product_scans

A list of Scan instances which were produced by fragmenting ions from this one. This attribute is not guaranteed to be populated depending upon how the scan is loaded.

Type

list

source

The object which produced this scan and which defines the methods for retrieving common attributes from the underlying data structures.

Type

ScanDataSource

precursor_information

Descriptive metadata for the ion which was chosen for fragmentation, and a reference to the precursor scan

Type

PrecursorInformation or None

arrays

A pair of numpy.ndarray objects corresponding to the raw m/z and intensity data points

Type

RawDataArrays

id

The unique identifier for this scan as given by the source

Type

str

title

The human-readable display string for this scan as shown in some external software

Type

str

ms_level

The degree of fragmentation performed. 1 corresponds to a MS1 or “Survey” scan, 2 corresponds to MS/MS, and so on. If ms_level > 1, the scan is considered a “tandem scan” or “MS^n” scan

Type

int

scan_time

The time the scan was acquired during data acquisition. The unit of time will always be minutes.

Type

float

drift_time

The time measured by the ion mobility spectrometer for this scan or frame. This quantity is None if the scan does not have ion mobility information associated with it, which is usually recorded in acquisition_information

Type

float or None

index

The integer number indicating how many scans were acquired prior to this scan.

Type

int

is_profile

Whether this scan’s raw data points corresponds to a profile scan or whether the raw data was pre-centroided.

Type

bool

polarity

If the scan was acquired in positive mode, the value +1. If the scan was acquired in negative mode, the value -1. May be used to indicating how to calibrate charge state determination methods.

Type

int

activation

If this scan is an MS^n scan, this attribute will contain information about the process used to produce it from its parent ion.

Type

ActivationInformation or None

instrument_configuration

The instrument configuration used to acquire this scan.

Type

InstrumentInformation

acquisition_information

Describes the type of event that produced this scan, as well as the scanning method used.

Type

ScanAcquisitionInformation or None

isolation_window

Describes the range of m/z that were isolated from a parent scan to create this scan

Type

IsolationWindow or None

annotations

A set of key-value pairs describing the scan not part of the standard interface

Type

dict

property acquisition_information: ms_deisotope.data_source.metadata.scan_traits.ScanAcquisitionInformation

Describes the type of event that produced this scan, as well as the scanning method used.

property activation: Optional[ms_deisotope.data_source.metadata.activation.ActivationInformation]

If this scan is an MS^n scan, this attribute will contain information about the process used to produce it from its parent ion.

Returns

Return type

ActivationInformation

property annotations: Dict[str, Any]

A set of key-value pairs describing the scan not part of the standard interface

property arrays: ms_deisotope.data_source.scan.base.RawDataArrays

A pair of numpy.ndarray objects corresponding to the raw m/z and intensity data points.

These arrays are wrapped in a RawDataArrays instance, which provides additional methods.

Returns

Return type

RawDataArrays

average(index_interval=None, rt_interval=None, dx=None, weight_sigma=None)[source]

Average together multiple scans’ raw data arrays to create a composite intensity profile for a common m/z axis.

Only MS1 scans will be averaged with this method

Either an absolute number of scans before and after can be specified using index_interval or a time window may be specified using rt_interval.

Parameters

  • index_interval (int, optional) – The number of scans preceding and proceding to average with.

  • rt_interval (float, optional) – The range of time (in minutes) preceding and proceding to look for other scans to average with.

  • dx (float, optional) – The distance between each point in the generated common m/z axis.

  • weight_sigma (float, optional) – When this value is not None, scans are weighted according to a gaussian distribution with a $sigma$ equal to this value

Returns

A shallow copy of this scan with its arrays attribute replaced with the averaged array

Return type

AveragedScan

average_with(scans, dx=None, weight_sigma=None, num_threads=None)[source]

Average together multiple scans’ raw data arrays to create a composite intensity profile for a common m/z axis.

Parameters

  • scans (list:) – A list of Scan objects

  • dx (float, optional) – The distance between each point in the generated common m/z axis.

  • weight_sigma (float, optional) – When this value is not None, scans are weighted according to a gaussian distribution with a $sigma$ equal to this value

  • num_threads (int, optional) – The maximum number of threads to use while averaging signal. Defaults to the number of spectra being averaged or the maximum available from the hardware, whichever is smaller.

Returns

A shallow copy of this scan with its arrays attribute replaced with the averaged array

Return type

AveragedScan

bind(source: ScanDataSource)[source]

Attach this object and its other referent members to source, letting them load information.

clear(full=False)[source]

Releases all associated in-memory data and clears the cached attributes.

The data reference attribute _data is retained and unchanged.

Parameters

full (bool) – Whether to clear more attributes to aggressively free memory.

clone(deep=True) → ms_deisotope.data_source.scan.scan.Scan[source]

Return a copy of the Scan object wrapping the same reference data, potentially a deep one

Parameters

deep (bool) –

Returns

Return type

Scan

deconvolute(*args, **kwargs)[source]

A wrapper around ms_deisotope.deconvolution.deconvolute_peaks().

The scan must have had its peaks picked before it can be deconvoluted.

Parameters

  • decon_config (dict, optional) – Parameters to use to initialize the deconvoluter instance produced by deconvoluter_type

  • charge_range (tuple of integers, optional) – The range of charge states to consider.

  • error_tolerance (float, optional) – PPM error tolerance to use to match experimental to theoretical peaks

  • priority_list (list, optional) – The set of peaks to target for deconvolution to be able to enforce external constraints on, such as selected precursors for fragmentation.

  • left_search_limit (int, optional) – The maximum number of neutron shifts to search to the left (decrease) from each query peak

  • right_search_limit (int, optional) – The maximum number of neutron shifts to search to the right (increase) from each query peak

  • left_search_limit_for_priorities (int, optional) – The maximum number of neutron shifts to search to the left (decrease) from each query peak for priority targets

  • right_search_limit_for_priorities (None, optional) – The maximum number of neutron shifts to search to the right (increase) from each query peak for priority targets

  • charge_carrier (float, optional) – The mass of the charge carrier. Defaults to PROTON

  • truncate_after (float, optional) – The percentage of the isotopic pattern to include. Defaults to TRUNCATE_AFTER

  • deconvoluter_type (type or callable, optional) – A callable returning a deconvoluter. Defaults to AveraginePeakDependenceGraphDeconvoluter

  • **kwargs – Additional keywords passed to deconvolute_peaks()

Returns

Returns self

Return type

Scan

Raises

ValueError – If peak_set is None, a ValueError will be raised indicating that a scan must be centroided before it can be deconvoluted

See also

deconvolute_peaks()

denoise(scale=5.0, window_length=2.0, region_width=10)[source]

Create a shallow copy of the scan with a noise reduction transformation applied.

This method uses the scan filter ms_peak_picker.scan_filter.FTICRBaselineRemoval which uses the MasSpike noise reduction algorithm.

Parameters

  • scale (float, optional) – The multiplier of the local noise window to remove

  • window_length (float, optional) – The width (in m/z) of each window

  • region_width (int, optional) – The width (in m/z) of each region of windows

Returns

The denoised version of this scan

Return type

Scan

has_peak(*args, **kwargs) → ms_peak_picker._c.peak_set.FittedPeak[source]

A wrapper around ms_peak_picker.PeakSet.has_peak() to query the ms_peak_picker.FittedPeak objects picked for this scan.

Parameters

  • mz (float) – The m/z to search for

  • error_tolerance (float) – The parts per million mass error tolerance to use

Returns

The peak closest to the query m/z within the error tolerance window or None if there are no peaks satisfying the requirements

Return type

ms_peak_picker.FittedPeak or None

Raises

ValueError: – If the scan has not yet had peaks picked yet

See also

Scan.pick_peaks()

property id: str

The within run unique scan identifier.

Returns

Return type

str

property index: int

The integer number indicating how many scans were acquired prior to this scan.

Returns

Return type

int

property instrument_configuration: ms_deisotope.data_source.metadata.instrument_components.InstrumentInformation

The instrument configuration used to acquire this scan.

property is_profile: bool

Whether this scan’s raw data points corresponds to a profile scan or whether the raw data was pre-centroided.

Returns

Return type

bool

property isolation_window: Optional[ms_deisotope.data_source.metadata.scan_traits.IsolationWindow]

Describes the range of m/z that were isolated from a parent scan to create this scan.

Returns

Return type

IsolationWindow

property ms_level: int

The degree of fragmentation performed. 1 corresponds to a MS1 or “Survey” scan, 2 corresponds to MS/MS, and so on. If ms_level > 1, the scan is considered a “tandem scan” or “MS^n” scan

Returns

Return type

int

pack(bind=False) → ms_deisotope.data_source.scan.scan.ProcessedScan[source]

Pack the (dispersed) representation of the data in this Scan into a packed ProcessedScan object.

Note

A reference to precursor_information is passed to the returned ProcessedScan, so both objects share it. Because the product property works by looking up the scan in source, it’s not possible to retrieve the ProcessedScan this way.

Parameters

bind (bool) – Whether or not the ProcessedScan object should also be bound to source

Returns

Return type

ProcessedScan

pick_peaks(*args, **kwargs)[source]

A wrapper around ms_peak_picker.pick_peaks() which will populate the peak_set attribute of this scan.

Parameters

  • fit_type (str, optional) – The name of the peak model to use. One of “quadratic”, “gaussian”, “lorentzian”, or “apex”

  • signal_to_noise_threshold (int, optional) – Minimum signal-to-noise measurement to accept a peak

  • intensity_threshold (int, optional) – Minimum intensity measurement to accept a peak

  • threshold_data (bool, optional) – Whether to apply thresholds to the data

  • target_envelopes (list, optional) – A sequence of (start m/z, end m/z) pairs, limiting peak picking to only those intervals

  • transforms (list, optional) – A list of scan_filter.FilterBase instances or callable that accepts (mz_array, intensity_array) and returns (mz_array, intensity_array) or str matching one of the premade names in scan_filter.filter_register

  • verbose (bool, optional) – Whether to log extra information while picking peaks

  • start_mz (float, optional) – A minimum m/z value to start picking peaks from

  • stop_mz (float, optional) – A maximum m/z value to stop picking peaks after

  • *args – Passed along to ms_peak_picker.pick_peaks()

  • **kwargs – Passed along to ms_peak_picker.pick_peaks()

Returns

Returns self

Return type

Scan

property polarity: int

If the scan was acquired in positive mode, the value +1. If the scan was acquired in negative mode, the value -1. May be used to indicating how to calibrate charge state determination methods.

Returns

Return type

int

property precursor_information: Optional[ms_deisotope.data_source.scan.base.PrecursorInformation]

Descriptive metadata for the ion which was chosen for fragmentation, and a reference to the precursor scan.

Returns

Return type

PrecursorInformation

reprofile(max_fwhm=0.2, dx=0.005, model_cls=None, override_fwhm=None)[source]

Use the picked peaks in peak_set to create a new profile mass spectrum using a peak shape model.

Parameters

  • max_fwhm (float, optional) – Maximum peak width above which peaks will be ignored

  • dx (float, optional) – The distance between each new point in m/z space in the reprofiled spectrum

  • model_cls (ms_peak_picker.peak_statistics.PeakShapeModel, optional) – The peak shape model to use to generate the profile data from the centroided peaks. Defaults a Gaussian model

Returns

A shallow copy of this scan with its arrays replaced with the new reprofiled arrays

Return type

Scan

Raises

ValueError – A scan that has not been centroided and is already in profile mode must have its peaks picked before it can be reprofiled.

property scan_id: str

The within run unique scan identifier.

Returns

Return type

str

property scan_time: float

The time the scan was acquired during data acquisition. The unit of time will always be minutes.

Returns

Return type

float

property title: str

The human-readable display string for this scan as shown in some external software.

Returns

Return type

str

transform(filters=None)[source]

Applies a series of ms_peak_picker.scan_filter.FilterBase, or strings that are recognized by ms_peak_picker.scan_filter.transform()

Parameters

filters (Iterable) – An iterable of transformations of ms_peak_picker.scan_filter.FilterBase or strings.

Returns

Return type

WrappedScan

unbind()[source]

Detattch this object and its other referent members from their currently bound source.

This may cause errors if more information is requested but is not cached, or if requesting another ScanBase be loaded.

Scan-Level Metadata

class ms_deisotope.data_source.common.PrecursorInformation(mz, intensity, charge, precursor_scan_id=None, source=None, extracted_neutral_mass=0, extracted_charge=0, extracted_intensity=0, peak=None, extracted_peak=None, defaulted=False, orphan=False, product_scan_id=None, annotations=None, coisolation=None, coisolation_index: Optional[int] = None)[source]

Store information relating a tandem MS scan to its precursor MS scan.

Note

The attributes prefixed with extracted_ refer to the quantities estimated from the data, while those unprefixed are the values read directly from the data source. These values regularly do not agree. When available, the extracted values should be more accurate.

charge

The charge reported in the source metadata

Type

int

defaulted

Whether the information in the extracted fields reflects empirical information or fell back on the vendor-reported values.

Type

bool

extracted_charge

The charge estimated from the source data

Type

int

extracted_intensity

The sum of the peak heights of the extracted isotopic pattern

Type

float

extracted_neutral_mass

The monoisotopic neutral mass estimated from the source data

Type

float

extracted_peak

The deconvoluted peak summarizing the precursor ion

Type

DeconvolutedPeak

intensity

The abundance reported in the source metadata

Type

float

mz

The m/z reported in the source metadata

Type

float

orphan

Whether there was an isotopic pattern to extract in the precursor scan. Usually paired with defaulted

Type

bool

peak

The peak nearest mz, and the starting point for estimating information about the precursor ion

Type

FittedPeak

precursor_scan_id

The id string for the precursor scan

Type

str

source

Any object implementing the ScanIterator interface to be used to look up the precursor scan with precursor_scan_id

Type

ScanIterator

bind(source: ScanDataSource) → PrecursorInformation[source]

Attach this object and its other referent members to source, letting them load information.

clone() → ms_deisotope.data_source.scan.base.PrecursorInformation[source]

Make a shallow copy of this object.

Note

This is an alias of copy()

Returns

Return type

PrecursorInformation

copy() → ms_deisotope.data_source.scan.base.PrecursorInformation[source]

Make a shallow copy of this object.

Returns

Return type

PrecursorInformation

correct_mz(error_tolerance: float = 2e-05, enforce_isolation_window: bool = False)[source]

Find the peak nearest to mz in precursor and update mz from it.

Note

The peak selected may still not be the monoisotopic peak. This requires a deconvolution procedure.

Parameters

  • error_tolerance (float, optional) – The error tolerance in PPM to use when searching for the nearest peak (the default is 2e-5).

  • enforce_isolation_window (bool, optional) – Whether or not to force the specified m/z. Defaults to False.

default(orphan: bool = False)[source]

Populate the extracted attributes of this object from the matching original attributes.

This usually reflects a failure to find an acceptable deconvolution solution, and may indicate that there was no peak at the specified location when orphan is True

Parameters

orphan (bool) – Whether or not to set orphan to True, indicating no peak was found near mz.

extract(peak: ms_deisotope._c.peak_set.DeconvolutedPeak, override_charge: Optional[int] = None)[source]

Populate the extracted attributes of this object from the attributes of a DeconvolutedPeak instance.

Parameters

  • peak (DeconvolutedPeak) – The peak to copy attributes from

  • override_charge (int, optional) – If provided, this charge will be used instead of the charge of peak

property extracted_mz: float

Recalculate the m/z of the precursor from the fitted neutral mass and charge

Returns

Return type

float

find_monoisotopic_peak(trust_charge_state: bool = True, precursor_scan: Optional[ms_deisotope.data_source.scan.base.ScanBase] = None, **kwargs) → Tuple[float, bool][source]

Find the monoisotopic peak for this precursor.

This convenience method carries out a simplified procedure for finding the precursor ion’s monoisotpic peak and charge state in the precursor scan. It follows steps similar to those found in the ScanProcessor pipeline, but is not as flexible or complete.

Note

For a full deconvolution result, please use ScanProcessor, which carries out a more complete error checking procedure.

Parameters

  • trust_charge_state (bool, optional) – Whether or not to trust the original precursor charge state, which may be based upon information not available in the examined mass spectrum.

  • precursor_scan (ScanBase, optional) – The spectrum to look for the precursor peak in. If not provided, precursor will be used.

Returns

  • float – The updated m/z of the precursor ion’s monoisotopic peak.

  • bool – Whether or not the deconvolution procedure was able to run successfully.

property neutral_mass: float

Calculate the neutral mass of the precursor from the given m/z and charge.

Returns

Return type

float

property precursor: Optional[ms_deisotope.data_source.scan.base.ScanBase]

The scan in which the precursor ion was isolated.

Returns

Return type

ScanBase

property product: Optional[ms_deisotope.data_source.scan.base.ScanBase]

The scan in which the precursor ion was fragmented and daughter ions were observed.

Returns

Return type

ScanBase

unbind()[source]

Detattch this object the currently bound source.

update_to_extracted()[source]

Override the reference values given by the source with those values that were extracted from experimental data, if they have been set.

class ms_deisotope.data_source.common.ActivationInformation(method, energy, data=None)[source]

Describes the dissociation process used to produce an MSn scan.

data

Additional metadata describing the dissociation

Type

dict

energy

The quantity of energy used

Type

float

method

The dissociation method used

Type

DissociationMethod

has_supplemental_dissociation()[source]

Determine if supplemental activation was used

Returns

Return type

bool

is_multiple_dissociation()[source]

Determine if multiple dissociation methods were used.

Returns

Return type

bool

class ms_deisotope.data_source.common.ScanAcquisitionInformation(combination, scan_list)[source]

Describes the set distinct scans along the measurable range by the instrument that were performed to produce the acquired data

ScanAcquisitionInformation objects implement the MutableSequence interface, acting as a sequence of ScanEventInformation objects.

combination

A controlled vocabulary string describing the way in which scans were combined

Type

str

scan_list

The list of scan events performed

Type

list of ScanEventInformation

copy() → ms_deisotope.data_source.metadata.scan_traits.ScanAcquisitionInformation[source]

Make a shallow copy of this object

insert(index, value)[source]

Insert an event at a given position

Parameters

  • index (int) – The position to add the new event

  • value (ScanEventInformation) – The event to insert

class ms_deisotope.data_source.common.IsolationWindow(lower, target, upper)[source]

Describes the m/z interval a precursor ion was isolated from in the precursor scan

An IsolationWindow instance is comparable, hashable, and orderable. It is based on a namedtuple, and supports the same interface and methods as a tuple.

lower

The distance from the center of the isolation window towards 0

Type

float

target

The center of the isolation window in m/z

Type

float

upper

The distance from the center of the isolation window towards \(\infty\)

Type

float

lower_bound

The m/z coordinate of the lower bound target - lower

Type

float

upper_bound

The m/z coordinate of the upper bound target + upper

Type

float

width

The sum of lower and upper, the total m/z space spanned by the window

Type

float

is_empty()[source]

Tests if the window is empty (e.g. its upper bound is equal to its lower bound)

Returns

Return type

bool

property lower_bound

The m/z coordinate of the lower bound target - lower

classmethod make_empty(point)[source]

A helper method for instantiating an empty isolation window centered at point

Parameters

point (float) – The point to center the new empty window at.

Returns

Return type

IsolationWindow

spans(x, tolerance=0.1)[source]

Test whether x is within the interval defined by this window’s bounds.

This method permits a small amount of error (controlled by tolerance) when computing the bounds.

Equivalent to: (self.lower_bound - tolerance) <= x <= (self.upper_bound + tolerance)

Parameters

  • x (float) – The number to query

  • tolerance (float, optional) – The amount of error to accept when computing the bounds (the default is 0.1)

Returns

Return type

bool

property upper_bound

The m/z coordinate of the upper bound target + upper

property width

The sum of lower and upper, the total m/z space spanned by the window

Supporting Data Structures

class ms_deisotope.data_source.common.RawDataArrays(mz, intensity, data_arrays=None)[source]

Represent the m/z and intensity arrays associated with a raw mass spectrum.

Supports scaling and summing, as well as low level m/z search.

Thin wrapper around a namedtuple, so this object supports the same interfaces as a tuple.

mz

The m/z axis of a mass spectrum

Type

np.ndarray

intensity

The intensity measured at the corresponding m/z of a mass spectrum

Type

np.ndarray

between_mz(low: float, high: float) → ms_deisotope.data_source.scan.base.RawDataArrays[source]

Returns a slice of the arrays between low and high m/z

Parameters

  • low (float) – The lower bound m/z

  • high (float) – The upper bound m/z

Returns

Return type

RawDataArrays

copy()[source]

Make a deep copy of this object.

Returns

Return type

RawDataArray

classmethod empty() → ms_deisotope.data_source.scan.base.RawDataArrays[source]

Create a new, empty instance.

Returns

Return type

RawDataArrays

find_mz(mz: float) → int[source]

Find the nearest index to the query mz

Parameters

mz (float) – The m/z value to search for

Returns

The index nearest to the query m/z

Return type

int

has_array(array_type)[source]

Check if this array set contains an array of the requested type.

This method uses the semantic lookup mechanism to test “is-a” relationships so if a more abstract term is used, a wider range of terms may be matched.

Parameters

array_type (str or Term) – The array type name to test.

Returns

Return type

bool

plot(*args, **kwargs)[source]

Draw the profile spectrum described by the contained arrays.

Parameters

  • ax (matplotlib._axes.Axes) – The figure axes onto which to draw the plot. If not provided, this will default to the current figure interactively.

  • **kwargs – All keywords are forwarded to plot() on ax.

Returns

The axes drawn on

Return type

matplotlib._axes.Axes

class ms_deisotope.data_source.common.ScanBunch(*args, **kwargs)[source]

Represents a single MS1 scan and all MSn scans derived from it, or a collection of related MSn scans.

precursor

A single MS1 scan which may have undergone MSn

Type

ScanBase

products

A list of 0 or more ScanBase objects which were derived from precursor or another element of this list derived from it.

Type

list

annotate_precursors(nperrow=4, ax=None)[source]

Plot the spectra in this group as a grid, with the full MS1 spectrum in profile in the top row, and each MSn spectrum’s precursor ion revealed in a grid panel below, with isolation window and selected ion/monoisotopic peak annotated.

Parameters

  • nperrow (int) – The number of precursors to annotate per row in the grid.

  • ax (matplotlib._axes.Axes, optional) – The axis to draw on. If not provided, a new figure will be created, along with a new axis.

Returns

Return type

matplotlib._axes.Axes

get_scan_by_id(scan_id: str) → ms_deisotope.data_source.scan.base.ScanBase[source]

Retrieve the scan object for the specified scan id from this group in memory.

Parameters

scan_id (str) – The unique scan id value to be retrieved

Returns

Return type

ScanBase

pack()[source]

Build a new ScanBunch where each scan in it is returned by calling pack()

Returns

Return type

ScanBunch

precursor_for(scan: ms_deisotope.data_source.scan.base.ScanBase) → Optional[ms_deisotope.data_source.scan.base.ScanBase][source]

Find the precursor ScanBase instance for the given scan object

Parameters

scan (ScanBase) – The MSn scan to look for the MSn-1 scan for

Returns

Return type

ScanBase