Mass2Motif Module

Mass2Motif

Mass2Motif

Mass2Motif(
    frag_mz: array,
    frag_intensities: array,
    loss_mz: array,
    loss_intensities: array,
    metadata: Optional[dict] = None,
    metadata_harmonization: bool = True,
)

Container for a collection of peaks, losses and metadata.

Spectrum peaks are stored as :class:~matchms.Fragments object which can be addressed calling spectrum.peaks and contains m/z values and the respective peak intensities.

Spectrum metadata is stored as :class:~matchms.Metadata object which can be addressed by spectrum.metadata.

Code example

.. testcode::

import numpy as np
from matchms import Scores, Spectrum
from matchms.similarity import CosineGreedy

spectrum = Spectrum(mz=np.array([100, 150, 200.]),
                    intensities=np.array([0.7, 0.2, 0.1]),
                    metadata={"id": 'spectrum1',
                              "precursor_mz": 222.333,
                              "peak_comments": {200.: "the peak at 200 m/z"}})

print(spectrum)
print(spectrum.peaks.mz[0])
print(spectrum.peaks.intensities[0])
print(spectrum.get('id'))
print(spectrum.peak_comments.get(200))

Should output

.. testoutput::

Spectrum(precursor m/z=222.33, 3 fragments between 100.0 and 200.0)
100.0
0.7
spectrum1
the peak at 200 m/z

Attributes

peaks: ~matchms.Fragments.Fragments Peaks of spectrum losses: ~matchms.Fragments.Fragments or None Losses of spectrum, the difference between the precursor and all peaks.

Can be filled with

.. code-block ::

    from matchms import Fragments
    spectrum.losess = Fragments(mz=np.array([50.]), intensities=np.array([0.1]))

metadata: dict Dict of metadata with for example the scan number of precursor m/z.

Parameters

mz Array of m/z for the peaks intensities Array of intensities for the peaks metadata Dictionary with for example the scan number of precursor m/z. metadata_harmonization : bool, optional Set to False if default metadata filters should not be applied. The default is True.

Source code in MS2LDA/Mass2Motif.py

def __init__(
    self,
    frag_mz: np.array,
    frag_intensities: np.array,
    loss_mz: np.array,
    loss_intensities: np.array,
    metadata: Optional[dict] = None,
    metadata_harmonization: bool = True,
):
    """

    Parameters
    ----------
    mz
        Array of m/z for the peaks
    intensities
        Array of intensities for the peaks
    metadata
        Dictionary with for example the scan number of precursor m/z.
    metadata_harmonization : bool, optional
        Set to False if default metadata filters should not be applied.
        The default is True.
    """
    self._metadata = Metadata(metadata)
    if metadata_harmonization is True:
        self._metadata.harmonize_values()
    self.peaks = Fragments(mz=frag_mz, intensities=frag_intensities)
    self._losses = Fragments(mz=loss_mz, intensities=loss_intensities)

__hash__

__hash__()

Return a integer hash which is computed from both metadata (see .metadata_hash() method) and spectrum peaks (see .spectrum_hash() method).

Source code in MS2LDA/Mass2Motif.py

def __hash__(self):
    """Return a integer hash which is computed from both
    metadata (see .metadata_hash() method) and spectrum peaks
    (see .spectrum_hash() method)."""
    combined_hash = self.metadata_hash() + self.spectrum_hash()
    return int.from_bytes(bytearray(combined_hash, "utf-8"), "big")

clone

clone()

Return a deepcopy of the spectrum instance.

Source code in MS2LDA/Mass2Motif.py

def clone(self):
    """Return a deepcopy of the spectrum instance."""
    clone = Mass2Motif(
        frag_mz=self.peaks.mz,
        frag_intensities=self.peaks.intensities,
        loss_mz=self._losses.mz,
        loss_intensities=self._losses.intensities,
        metadata=self._metadata.data,
        metadata_harmonization=False,
    )
    return clone

get

get(key: str, default=None)

Retrieve value from :attr:metadata dict. Shorthand for

.. code-block:: python

val = self.metadata[key]

Source code in MS2LDA/Mass2Motif.py

def get(self, key: str, default=None):
    """Retrieve value from :attr:`metadata` dict. Shorthand for

    .. code-block:: python

        val = self.metadata[key]

    """
    return self._metadata.get(key, default)

metadata_dict

metadata_dict(export_style: str = 'matchms') -> dict

Convert spectrum metadata to Python dictionary.

Parameters

export_style: Converts the keys to the required export style. One of ["matchms", "massbank", "nist", "riken", "gnps"]. Default is "matchms"

Source code in MS2LDA/Mass2Motif.py

def metadata_dict(self, export_style: str = "matchms") -> dict:
    """Convert spectrum metadata to Python dictionary.

    Parameters
    ----------
    export_style:
        Converts the keys to the required export style. One of ["matchms", "massbank", "nist", "riken", "gnps"].
        Default is "matchms"
    """
    return self._metadata.to_dict(export_style)

metadata_hash

metadata_hash()

Return a (truncated) sha256-based hash which is generated based on the spectrum metadata. Spectra with same metadata results in same metadata_hash.

Source code in MS2LDA/Mass2Motif.py

def metadata_hash(self):
    """Return a (truncated) sha256-based hash which is generated
    based on the spectrum metadata.
    Spectra with same metadata results in same metadata_hash."""
    return metadata_hash(self._metadata.data)

plot

plot(figsize=(8, 6), dpi=200, **kwargs)

Plot to visually inspect a spectrum run spectrum.plot()

.. figure:: ../_static/spectrum-plot-example.png :width: 450 :alt: spectrum plotting function

Example of a spectrum plotted using ``spectrum.plot()`` ..

Source code in MS2LDA/Mass2Motif.py

def plot(self, figsize=(8, 6), dpi=200, **kwargs):
    """Plot to visually inspect a spectrum run ``spectrum.plot()``

    .. figure:: ../_static/spectrum-plot-example.png
        :width: 450
        :alt: spectrum plotting function

        Example of a spectrum plotted using ``spectrum.plot()`` ..
    """
    fig, ax = plt.subplots(1, 1, figsize=figsize, dpi=dpi)
    ax = plot_spectrum(self, ax=ax, **kwargs)
    return fig, ax

plot_against

plot_against(other_spectrum, figsize=(8, 6), dpi=200, **spectrum_kws)

Compare two spectra visually in a mirror plot.

To visually compare the peaks of two spectra run spectrum.plot_against(other_spectrum)

.. figure:: ../_static/spectrum-mirror-plot-example.png :width: 450 :alt: spectrum mirror plot function

Example of a mirror plot comparing two spectra ``spectrum.plot_against()`` ..

Source code in MS2LDA/Mass2Motif.py

def plot_against(self, other_spectrum, figsize=(8, 6), dpi=200, **spectrum_kws):
    """Compare two spectra visually in a mirror plot.

    To visually compare the peaks of two spectra run
    ``spectrum.plot_against(other_spectrum)``

    .. figure:: ../_static/spectrum-mirror-plot-example.png
        :width: 450
        :alt: spectrum mirror plot function

        Example of a mirror plot comparing two spectra ``spectrum.plot_against()`` ..
    """
    fig, ax = plt.subplots(1, 1, figsize=figsize, dpi=dpi)
    ax = plot_spectra_mirror(self, other_spectrum, ax=ax, **spectrum_kws)
    return fig, ax

set

set(key: str, value)

Set value in :attr:metadata dict. Shorthand for

.. code-block:: python

self.metadata[key] = val

Source code in MS2LDA/Mass2Motif.py

def set(self, key: str, value):
    """Set value in :attr:`metadata` dict. Shorthand for

    .. code-block:: python

        self.metadata[key] = val

    """
    self._metadata.set(key, value)
    return self

spectrum_hash

spectrum_hash()

Return a (truncated) sha256-based hash which is generated based on the spectrum peaks (mz:intensity pairs). Spectra with same peaks will results in same spectrum_hash.

Source code in MS2LDA/Mass2Motif.py

def spectrum_hash(self):
    """Return a (truncated) sha256-based hash which is generated
    based on the spectrum peaks (mz:intensity pairs).
    Spectra with same peaks will results in same spectrum_hash."""
    return spectrum_hash(self.peaks)

to_dict

to_dict(export_style: str = 'matchms') -> dict

Return a dictionary representation of a spectrum.

Parameters

export_style: Converts the keys to the required export style. One of ["matchms", "massbank", "nist", "riken", "gnps"]. Default is "matchms"

Source code in MS2LDA/Mass2Motif.py

def to_dict(self, export_style: str = "matchms") -> dict:
    """Return a dictionary representation of a spectrum.

    Parameters
    ----------
    export_style:
        Converts the keys to the required export style. One of ["matchms", "massbank", "nist", "riken", "gnps"].
        Default is "matchms"
    """
    peaks_list = np.vstack((self.peaks.mz, self.peaks.intensities)).T.tolist()
    spectrum_dict = self.metadata_dict(export_style)  # dict(self.metadata.items())
    spectrum_dict["peaks_json"] = peaks_list
    if "fingerprint" in spectrum_dict:
        spectrum_dict["fingerprint"] = spectrum_dict["fingerprint"].tolist()
    return spectrum_dict

update_peak_comments_mz_tolerance classmethod

update_peak_comments_mz_tolerance(mz_tolerance: float)

Change current peak comment m/z tolerance to mz_tolerance.

Source code in MS2LDA/Mass2Motif.py

@classmethod
def update_peak_comments_mz_tolerance(cls, mz_tolerance: float):
    """Change current peak comment m/z tolerance to mz_tolerance."""
    cls._peak_comments_mz_tolerance = mz_tolerance

Mass2MotifDocument

Mass2MotifDocument

Mass2MotifDocument(spectrum, n_decimals: int = 2)

Bases: SpectrumDocument

Create documents from spectra.

Every peak (and loss) positions (m/z value) will be converted into a string "word". The entire list of all peak words forms a spectrum document. Peak words have the form "peak@100.32" (for n_decimals=2), and losses have the format "loss@100.32". Peaks with identical resulting strings will not be merged, hence same words can exist multiple times in a document (e.g. peaks at 100.31 and 100.29 would lead to two words "peak@100.3" when using n_decimals=1).

For example:

.. testcode::

import numpy as np
from matchms import Spectrum
from spec2vec import SpectrumDocument

spectrum = Spectrum(mz=np.array([100.0, 150.0, 200.51]),
                    intensities=np.array([0.7, 0.2, 0.1]),
                    metadata={'compound_name': 'substance1'})
spectrum_document = SpectrumDocument(spectrum, n_decimals=1)

print(spectrum_document.words)
print(spectrum_document.peaks.mz)
print(spectrum_document.get("compound_name"))

Should output

.. testoutput::

['peak@100.0', 'peak@150.0', 'peak@200.5']
[100.   150.   200.51]
substance1

Parameters

spectrum: SpectrumType Input spectrum. n_decimals Peak positions are converted to strings with n_decimal decimals. The default is 2, which would convert a peak at 100.387 into the word "peak@100.39".

Source code in MS2LDA/Mass2MotifDocument.py

def __init__(self, spectrum, n_decimals: int = 2):
    """

    Parameters
    ----------
    spectrum: SpectrumType
        Input spectrum.
    n_decimals
        Peak positions are converted to strings with n_decimal decimals.
        The default is 2, which would convert a peak at 100.387 into the
        word "peak@100.39".
    """
    self.n_decimals = n_decimals
    self.weights = None
    super().__init__(spectrum, n_decimals=n_decimals)
    self._add_weights()

losses property

losses: Optional[Spikes]

Return losses of original spectrum.

metadata property

metadata

Return metadata of original spectrum.

peaks property

peaks: Spikes

Return peaks of original spectrum.

get

get(key: str, default=None)

Retrieve value from Spectrum metadata dict. Shorthand for

.. code-block:: python

val = self._obj.metadata[key]

Source code in MS2LDA/Mass2MotifDocument.py

def get(self, key: str, default=None):
    """Retrieve value from Spectrum metadata dict. Shorthand for

    .. code-block:: python

        val = self._obj.metadata[key]

    """
    assert not hasattr(
        self, key
    ), "Key cannot be attribute of SpectrumDocument class"
    return self._obj.get(key, default)