Welcome to brainpy’s documentation!¶

Table of Contents

Welcome to brainpy’s documentation!
Indices and tables
Bibliography

brainpy is a small Python library implementing the B afflingly R ecursive A lgorithm for I sotopic Patter N generation [Dittwald2014]. It includes three implementations, a pure-Python object oriented implementation, a Cython accelerated version of the object oriented implementation, and a pure C implementation, listed in order of ascending speed. The C implementation is used by default when available.

BRAIN, implemented in brainpy.isotopic_variants(), takes an elemental composition represented by any Mapping-like Python object and uses it to compute its aggregated isotopic distribution. All isotopic variants of the same number of neutrons are collapsed into a single centroid peak, meaning it does not consider isotopic fine structure.

from brainpy import isotopic_variants

# Generate theoretical isotopic pattern
peptide = {'H': 53, 'C': 34, 'O': 15, 'N': 7}
theoretical_isotopic_cluster = isotopic_variants(peptide, npeaks=5, charge=1)
for peak in theoretical_isotopic_cluster:
    print(peak.mz, peak.intensity)

# All following code is to illustrate what brainpy just did.

# produce a theoretical profile using a gaussian peak shape
import numpy as np
mz_grid = np.arange(theoretical_isotopic_cluster[0].mz - 1,
                    theoretical_isotopic_cluster[-1].mz + 1, 0.02)
intensity = np.zeros_like(mz_grid)
sigma = 0.002
for peak in theoretical_isotopic_cluster:
    # Add gaussian peak shape centered around each theoretical peak
    intensity += peak.intensity * np.exp(-(mz_grid - peak.mz) ** 2 / (2 * sigma)
            ) / (np.sqrt(2 * np.pi) * sigma)

# Normalize profile to 0-100
intensity = (intensity / intensity.max()) * 100

# draw the profile
from matplotlib import pyplot as plt
plt.plot(mz_grid, intensity)
plt.xlabel("m/z")
plt.ylabel("Relative intensity")

(Source code, png, hires.png, pdf)

Installing ¶

brainpy has three implementations, a pure Python implementation, a Cython translation of that implementation, and a pure C implementation that releases the GIL.

To install from a package index, you will need to have a C compiler appropriate to your Python version to build these extension modules. Additionally, there are prebuilt wheels for Windows available on PyPI:

$ pip install brain-isotopic-distribution

To build from source, in addition to a C compiler you will also need to install a recent version of Cython to transpile C code.

Usage ¶

brainpy provides a single top-level function for taking a Mapping-like object defining a elemental composition and generating an isotopic pattern from it, brainpy.isotopic_variants().

Module Reference ¶

A Python Implementation of the Baffling Recursive Algorithm for Isotopic cluster distributioN

brainpy.isotopic_variants()¶

pyisotopic_variants(composition, npeaks=None, int charge=0, double charge_carrier=PROTON)

Compute a peak list representing the theoretical isotopic cluster for composition.

Parameters

composition (Mapping) – Any Mapping type where keys are element symbols and values are integers. Elements may be fixed isotopes where their isotope number is enclosed in square braces (e.g. “C[13]”). Fixed isotopes that are not recognized will throw an error.
n_peaks (int) – The number of peaks to include in the isotopic cluster, starting from the monoisotopic peak. If given a number below 1 or above the maximum number of isotopic variants, the maximum will be used. If None, a “reasonable” value is chosen by int(sqrt(max_variants(composition))).
charge (int) – The charge state of the isotopic cluster to produce. Defaults to 0, theoretical neutral mass.
charge_carrier (double) – The mass of the molecule contributing the ion’s charge

Returns

Return type

list of TheoreticalPeak

brainpy.max_variants(composition)[source]¶

Calculates the maximum number of isotopic variants that could be produced by a composition.

Parameters: composition (Mapping) – Any Mapping type where keys are element symbols and values are integers
Returns: max_n_variants
Return type: int

brainpy.calculate_mass(composition, mass_data=None)[source]¶

Calculates the monoisotopic mass of a composition

Parameters

composition (Mapping) – Any Mapping type where keys are element symbols and values are integers
mass_data (dict, optional) – A dict with the masses of the chemical elements (the default value is nist_mass).

Returns

mass

Return type

float

brainpy.parse_formula(str formula) → PyComposition ¶

Parse a chemical formula and construct a PyComposition object

The formula must be made up of zero or more pieces following the pattern (<element>[A-Z][a-z]*)(<isotope>\[\d+\])?(<count>\d+). You cannot omit the <count> digits.

Parameters: formula (str) –
Returns
Return type: PyComposition

Examples

>>> parse_formula("H2O1")
PyComposition({"H": 2, "O": 1})
>>> parse_formula("C34H53O15N7").mass()
799.35996402671
>>> parse_formula("C7H15C[13]1O6N[15]1")
PyComposition({"C": 7, "H": 15, "C[13]": 1, "O": 6, "N[15]": 1})
>>> parse_formula("C7H15C[13]1O6N[15]1").mass()
223.09032693441

Raises: ValueError – If the formula doesn’t match the expected pattern

class brainpy.PyComposition(base=None, **kwargs)¶

A mapping representing a chemical composition.

Implements arithmetic operations, +/- is defined between a PyComposition and a Mapping-like object, and * is defined between a PyComposition and an integer.

cached_mass¶

‘double’

Type: cached_mass

copy(self) → PyComposition ¶

items(self) → list ¶

keys(self) → list ¶

mass(self) → double¶

Calculate the monoisotopic mass of this chemical composition

Returns
Return type: float

pop(self, str key, default=None)¶

update(self, arg)¶

values(self) → list ¶

Supporting Objects ¶

class brainpy.Peak(mz, intensity, charge)[source]¶

Represent a single theoretical peak centroid.

Peaks are comparable, hashable, and can be copied by calling clone()

charge¶

The charge state of the peak

Type

int

intensity¶

The height of the peak. Peaks created as part of a theoretical isotopic cluster will be have an intensity between 0 and 1.

Type

float

mz¶

The mass-to-charge ratio of the peak

Type

float

class brainpy.IsotopicDistribution(composition, order=- 1)¶

aggregated_isotopic_variants(self, int charge=0, double charge_carrier=PROTON)¶

Compute the m/z (or neutral mass when charge == 0) for each aggregated isotopic peak and their intensity relative to the monoisotopic peak.

Indices and tables ¶

Bibliography ¶

Dittwald2014: Dittwald, P., & Valkenborg, D. (2014). BRAIN 2.0: time and memory complexity improvements in the algorithm for calculating the isotope distribution. Journal of the American Society for Mass Spectrometry, 25(4), 588–94. https://doi.org/10.1007/s13361-013-0796-5