Precursor

tdfpy.Precursor dataclass

Precursor(
    *,
    precursor_id: int,
    largest_peak_mz: float,
    average_mz: float,
    monoisotopic_mz: float | None,
    charge: int | None,
    scan_number: float,
    intensity: float,
    parent_frame_id: int,
    pasef_frame_msms_infos: tuple[PasefFrameMsmsInfo, ...],
    rt: float,
    _timsdata: TimsData = _timsdata_field()
)

Bases: _TdfData

A detected precursor ion from a DDA acquisition.

Combines one row of the Precursors table with its PASEF MS/MS windows.

Field	Type	Description
precursor_id	int	Unique precursor ID
largest_peak_mz	float	m/z of the most intense isotope peak
average_mz	float	Intensity-weighted average m/z
monoisotopic_mz	float \| None	Monoisotopic m/z (if determined); see also precursor_mz
charge	int \| None	Charge state (if determined)
scan_number	float	Fractional mobility scan coordinate
intensity	float	Summed precursor intensity
parent_frame_id	int	MS1 frame the precursor was detected in
pasef_frame_msms_infos	tuple[PasefFrameMsmsInfo, ...]	Associated PASEF MS/MS windows
rt	float	Retention time in seconds of the parent frame

timsdata property

timsdata: TimsData

The reader's open :class:TimsData.

Raises:

Type	Description
ReaderClosedError	If the reader that built this element was closed.

precursor_mz property

precursor_mz: float

The precursor m/z: monoisotopic_mz when Bruker determined it, else largest_peak_mz.

ook0 property

ook0: float

1/K0 (V·s/cm²) at scan_number in the parent frame.

ccs property

ccs: float

CCS (Ų) at precursor_mz. Uses charge 1 when the charge is unknown.

voltage property

voltage: float

TIMS voltage (V) at scan_number in the parent frame.

scan_num_range property

scan_num_range: tuple[int, int] | None

Shared scan range of the PASEF windows, or None (with a warning) if they differ.

ook0_range property

ook0_range: tuple[float, float] | None

Shared 1/K0 range of the PASEF windows, or None (with a warning) if they differ.

ccs_range property

ccs_range: tuple[float, float] | None

Shared CCS range of the PASEF windows, or None (with a warning) if they differ.

voltage_range property

voltage_range: tuple[float, float] | None

Shared voltage range of the PASEF windows, or None (with a warning) if they differ.

isolation_mz_range property

isolation_mz_range: tuple[float, float] | None

Shared quadrupole isolation m/z range of the PASEF windows, or None (with a warning) if they differ.

collision_energy property

collision_energy: float | None

Shared collision energy (eV) of the PASEF windows, or None (with a warning) if they differ.

polarity property

polarity: Polarity | None

Shared polarity of the PASEF windows; None (with a warning) if there are none or they differ.

merged_peaks

merged_peaks() -> npt.NDArray[np.float64]

Mobility-collapsed MS/MS spectrum, one (N, 2) [m/z, intensity] array.

Sums every PASEF window of this precursor (which may span several frames), drops ion mobility, then merges peaks greedily in m/z (30 ppm). This decodes every window, so it is the most expensive accessor; call it once and keep the result. See :func:~tdfpy.get_mobility_collapsed_spectrum.

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def merged_peaks(self) -> npt.NDArray[np.float64]:
    """Mobility-collapsed MS/MS spectrum, one ``(N, 2)`` ``[m/z, intensity]`` array.

    Sums every PASEF window of this precursor (which may span several
    frames), drops ion mobility, then merges peaks greedily in m/z
    (30 ppm). This decodes every window, so it is the most expensive
    accessor; call it once and keep the result. See
    :func:`~tdfpy.get_mobility_collapsed_spectrum`.

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    return get_mobility_collapsed_spectrum(
        self.timsdata,
        [(info.frame_id, *info._window_scans()) for info in self.pasef_frame_msms_infos],
    )

pasef_merged_peaks

pasef_merged_peaks() -> list[npt.NDArray[np.float64]]

:meth:PasefFrameMsmsInfo.merged_peaks of each PASEF window, one (N_i, 2) array per window.

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def pasef_merged_peaks(self) -> list[npt.NDArray[np.float64]]:
    """:meth:`PasefFrameMsmsInfo.merged_peaks` of each PASEF window, one ``(N_i, 2)`` array per window.

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    return [pasef_info.merged_peaks() for pasef_info in self.pasef_frame_msms_infos]

tdfpy.PasefFrameMsmsInfo dataclass

PasefFrameMsmsInfo(
    *,
    frame_id: int,
    scan_num_begin: int,
    scan_num_end: int,
    isolation_mz: float,
    isolation_width: float,
    collision_energy: float,
    precursor_id: int | None,
    rt: float,
    polarity: Polarity | None,
    _timsdata: TimsData = _timsdata_field()
)

Bases: _MobilityWindow

A single PASEF MS/MS isolation window within an MS/MS frame.

One row of the PasefFrameMsMsInfo table: a contiguous range of mobility scans acquired with one isolation window and collision energy, linked to a precursor.

Field	Type	Description
frame_id	int	MS/MS frame the window was acquired in (not the parent MS1 frame)
scan_num_begin	int	First mobility scan (inclusive)
scan_num_end	int	Mobility scan range end (exclusive), so the range is [scan_num_begin, scan_num_end)
isolation_mz	float	Isolation window center m/z
isolation_width	float	Isolation window width in Th
collision_energy	float	Collision energy in eV
precursor_id	int \| None	Associated precursor ID (None when the row has no precursor)
rt	float	Retention time in seconds of that MS/MS frame
polarity	Polarity \| None	"positive" / "negative", None if unknown

timsdata property

timsdata: TimsData

The reader's open :class:TimsData.

Raises:

Type	Description
ReaderClosedError	If the reader that built this element was closed.

scan_num_range property

scan_num_range: tuple[int, int]

(scan_num_begin, scan_num_end), end exclusive.

isolation_mz_range property

isolation_mz_range: tuple[float, float]

Quadrupole isolation window (isolation_mz - width / 2, isolation_mz + width / 2), low first.

ms_level property

ms_level: int

MS level of the window's spectra: always 2 (an MS/MS isolation window).

ook0_range property

ook0_range: tuple[float, float]

(ook0_begin, ook0_end): lowest and highest 1/K0 (V·s/cm²) of the scan range, low first.

ook0_begin property

ook0_begin: float

Lowest 1/K0 (V·s/cm²) of the scan range.

ook0_end property

ook0_end: float

Highest 1/K0 (V·s/cm²) of the scan range.

ccs_range property

ccs_range: tuple[float, float]

(ccs_begin, ccs_end): CCS (Ų) range for charge 1 at isolation_mz, low first.

ccs_begin property

ccs_begin: float

Lowest CCS (Ų) of the scan range, for charge 1 at isolation_mz.

ccs_end property

ccs_end: float

Highest CCS (Ų) of the scan range, for charge 1 at isolation_mz.

voltage_range property

voltage_range: tuple[float, float]

(voltage_begin, voltage_end): TIMS voltage (V) range of the scan range, low first.

voltage_begin property

voltage_begin: float

Lowest TIMS voltage (V) of the scan range.

voltage_end property

voltage_end: float

Highest TIMS voltage (V) of the scan range.

unique_id property

unique_id: tuple[int, int | None]

(frame_id, precursor_id). Warns when precursor_id is None.

scan_peaks

scan_peaks() -> list[npt.NDArray[np.float64]]

Raw peaks, one (N_i, 2) [m/z, intensity] float64 array per mobility scan.

The list has one entry per scan in this element's scan range, in scan order; empty scans give a (0, 2) array.

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def scan_peaks(self) -> list[npt.NDArray[np.float64]]:
    """Raw peaks, one ``(N_i, 2)`` ``[m/z, intensity]`` float64 array per mobility scan.

    The list has one entry per scan in this element's scan range, in scan
    order; empty scans give a ``(0, 2)`` array.

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    td = self.timsdata
    bounds = self._scan_bounds()
    begin, end = bounds if bounds is not None else (0, td.frame_metadata(self.frame_id).num_scans)
    arrays = []
    for index_array, int_array in td.read_scans(self.frame_id, begin, end):
        mz_array = td.index_to_mz(self.frame_id, index_array)
        arrays.append(np.stack((mz_array, int_array), axis=-1).astype(np.float64))
    return arrays

raw_peaks

raw_peaks(
    *,
    exclude: ChargeStateRegion | None = None,
    smooth: Smooth | None = None,
    noise: NoiseSpec = None,
    mobility_type: MobilityType = "ook0"
) -> npt.NDArray[np.float64]

Raw peaks as one (N, 3) [m/z, intensity, ion_mobility] array.

Restricted to this element's scan range. See :func:tdfpy.get_raw_peaks for the keyword arguments.

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def raw_peaks(
    self,
    *,
    exclude: ChargeStateRegion | None = None,
    smooth: Smooth | None = None,
    noise: NoiseSpec = None,
    mobility_type: MobilityType = "ook0",
) -> npt.NDArray[np.float64]:
    """Raw peaks as one ``(N, 3)`` ``[m/z, intensity, ion_mobility]`` array.

    Restricted to this element's scan range. See :func:`tdfpy.get_raw_peaks`
    for the keyword arguments.

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    return get_raw_peaks(
        self.timsdata,
        self.frame_id,
        scan_range=self._scan_bounds(),
        exclude=exclude,
        smooth=smooth,
        noise=noise,
        mobility_type=mobility_type,
    )

centroid

centroid(
    *,
    exclude: ChargeStateRegion | None = None,
    smooth: Smooth | None = None,
    noise: NoiseSpec = None,
    mobility_type: MobilityType = "ook0",
    centroid: Centroider | None = None
) -> npt.NDArray[np.float64]

Centroided peaks as one (N, 3) [m/z, intensity, ion_mobility] array.

Restricted to this element's scan range. The raw-peak keywords are passed to :func:tdfpy.get_raw_peaks; centroider settings live on :class:~tdfpy.Centroider (default :class:~tdfpy.MergePeaksCentroider).

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def centroid(
    self,
    *,
    exclude: ChargeStateRegion | None = None,
    smooth: Smooth | None = None,
    noise: NoiseSpec = None,
    mobility_type: MobilityType = "ook0",
    centroid: Centroider | None = None,
) -> npt.NDArray[np.float64]:
    """Centroided peaks as one ``(N, 3)`` ``[m/z, intensity, ion_mobility]`` array.

    Restricted to this element's scan range. The raw-peak keywords are
    passed to :func:`tdfpy.get_raw_peaks`; centroider settings live on
    :class:`~tdfpy.Centroider` (default :class:`~tdfpy.MergePeaksCentroider`).

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    return get_centroided_spectrum(
        self.timsdata,
        self.frame_id,
        scan_range=self._scan_bounds(),
        exclude=exclude,
        smooth=smooth,
        noise=noise,
        mobility_type=mobility_type,
        centroid=centroid,
    )

merged_peaks

merged_peaks() -> npt.NDArray[np.float64]

Mobility-collapsed MS/MS spectrum, one (N, 2) [m/z, intensity] array.

Sums the window's scans (dropping ion mobility), then merges peaks greedily in m/z (30 ppm). This decodes and merges every scan, so it is the most expensive accessor; call it once and keep the result. For per-scan raw peaks use :meth:scan_peaks; for an (N, 3) spectrum that keeps ion mobility use :meth:centroid. See :func:~tdfpy.get_mobility_collapsed_spectrum.

Raises:

Type	Description
ReaderClosedError	If the reader was closed.
TdfpyError	If a window's scan range does not fit its frame (corrupt file).

Source code in src/tdfpy/elems.py

def merged_peaks(self) -> npt.NDArray[np.float64]:
    """Mobility-collapsed MS/MS spectrum, one ``(N, 2)`` ``[m/z, intensity]`` array.

    Sums the window's scans (dropping ion mobility), then merges peaks
    greedily in m/z (30 ppm). This decodes and merges every scan, so it is
    the most expensive accessor; call it once and keep the result. For
    per-scan raw peaks use :meth:`scan_peaks`; for an ``(N, 3)`` spectrum
    that keeps ion mobility use :meth:`centroid`. See
    :func:`~tdfpy.get_mobility_collapsed_spectrum`.

    Raises:
        ReaderClosedError: If the reader was closed.
        TdfpyError: If a window's scan range does not fit its frame (corrupt file).
    """
    begin, end = self._window_scans()
    return get_mobility_collapsed_spectrum(self.timsdata, [(self.frame_id, begin, end)])