Frames

Frame is the base class for all MS1 frames. DDAMs1Frame, DIAMs1Frame, and PRMMs1Frame inherit every field and method listed under Frame — only their additional fields are shown below each subclass.

tdfpy.Frame dataclass

Frame(
    *,
    frame_id: int,
    rt: float,
    polarity: Polarity | None,
    scan_mode: int,
    msms_type: MsMsType,
    tims_id: int | None,
    base_peak_intensity: int,
    total_ion_current: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration_id: int,
    t1: float,
    t2: float,
    tims_calibration_id: int,
    property_group_id: int | None,
    accumulation_time: float,
    ramp_time: float,
    _timsdata: TimsData = _timsdata_field()
)

Bases: _Spectrum

Base class for a single timsTOF MS1 frame.

A frame is one complete TIMS-MS acquisition cycle. All fields below are present on DDAMs1Frame, DIAMs1Frame and PRMMs1Frame.

timsdata property

timsdata: TimsData

The reader's open :class:TimsData.

Raises:

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

frame_id instance-attribute

frame_id: int

Unique frame ID (1-based).

rt instance-attribute

rt: float

Retention time in seconds (the Time column).

polarity instance-attribute

polarity: Polarity | None

"positive" or "negative"; None if the file stores anything else.

scan_mode instance-attribute

scan_mode: int

Scan mode integer from the TDF schema.

msms_type instance-attribute

msms_type: MsMsType

MS/MS type of the frame.

tims_id instance-attribute

tims_id: int | None

Byte offset of this frame's data block in analysis.tdf_bin (the TimsId column).

base_peak_intensity instance-attribute

base_peak_intensity: int

Most intense peak across all scans in this frame (the MaxIntensity column).

total_ion_current instance-attribute

total_ion_current: int

Sum of all peak intensities in this frame (the SummedIntensities column).

num_scans instance-attribute

num_scans: int

Number of TIMS scans (mobility bins) in this frame.

num_peaks instance-attribute

num_peaks: int

Total number of peaks across all scans in this frame.

mz_calibration_id instance-attribute

mz_calibration_id: int

ID of the row in the MzCalibration table.

t1 instance-attribute

t1: float

Temperature T1 (°C) used by the m/z calibration.

t2 instance-attribute

t2: float

Temperature T2 (°C) used by the m/z calibration.

tims_calibration_id instance-attribute

tims_calibration_id: int

ID of the row in the TimsCalibration table.

property_group_id instance-attribute

property_group_id: int | None

ID of the row in the PropertyGroups table, if present.

accumulation_time instance-attribute

accumulation_time: float

Ion accumulation time in milliseconds.

ramp_time instance-attribute

ramp_time: float

TIMS ramp time in milliseconds.

ms_level property

ms_level: int

MS level: 1 for an MS1 frame, 2 for an MS/MS frame (from msms_type).

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,
    )

tdfpy.DDAMs1Frame dataclass

DDAMs1Frame(
    *,
    frame_id: int,
    rt: float,
    polarity: Polarity | None,
    scan_mode: int,
    msms_type: MsMsType,
    tims_id: int | None,
    base_peak_intensity: int,
    total_ion_current: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration_id: int,
    t1: float,
    t2: float,
    tims_calibration_id: int,
    property_group_id: int | None,
    accumulation_time: float,
    ramp_time: float,
    _timsdata: TimsData = _timsdata_field(),
    precursors: tuple[Precursor, ...]
)

Bases: Frame

An MS1 frame from a DDA acquisition.

Inherits all fields from Frame. precursors lists every precursor detected in this frame.

precursors instance-attribute

precursors: tuple[Precursor, ...]

All precursors detected in this MS1 frame.

DIA and PRM MS1 frames

DIAMs1Frame and PRMMs1Frame add no fields to Frame; they exist so code can tell the acquisition type from the frame's type. Find the windows or transitions of a run with DIA.windows and PRM.transitions (both lookups with query() / query_range()).

tdfpy.DIAMs1Frame dataclass

DIAMs1Frame(
    *,
    frame_id: int,
    rt: float,
    polarity: Polarity | None,
    scan_mode: int,
    msms_type: MsMsType,
    tims_id: int | None,
    base_peak_intensity: int,
    total_ion_current: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration_id: int,
    t1: float,
    t2: float,
    tims_calibration_id: int,
    property_group_id: int | None,
    accumulation_time: float,
    ramp_time: float,
    _timsdata: TimsData = _timsdata_field()
)

Bases: Frame

An MS1 frame from a DIA acquisition.

Inherits all fields from Frame. DIA isolation windows belong to MS/MS frames; use the reader's windows lookup for them.

tdfpy.PRMMs1Frame dataclass

PRMMs1Frame(
    *,
    frame_id: int,
    rt: float,
    polarity: Polarity | None,
    scan_mode: int,
    msms_type: MsMsType,
    tims_id: int | None,
    base_peak_intensity: int,
    total_ion_current: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration_id: int,
    t1: float,
    t2: float,
    tims_calibration_id: int,
    property_group_id: int | None,
    accumulation_time: float,
    ramp_time: float,
    _timsdata: TimsData = _timsdata_field()
)

Bases: Frame

An MS1 frame from a PRM acquisition.

Inherits all fields from Frame. PRM transitions belong to MS/MS frames; use the reader's transitions lookup for them.