Frames

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

tdfpy.Frame dataclass

Frame(
    _timsdata: TimsData,
    frame_id: int,
    time: float,
    polarity: Polarity,
    scan_mode: int,
    msms_type: int,
    tims_id: int | None,
    max_intensity: int,
    summed_intensities: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration: int,
    t1: float,
    t2: float,
    tims_calibration: int,
    property_group: int | None,
    accumulation_time: float,
    ramp_time: float,
)

Bases: _TdfData

Base class for a single timsTOF acquisition frame.

A frame represents one complete TIMS-MS acquisition cycle. All fields below are present on DDAMs1Frame and DIAMs1Frame through inheritance.

frame_id instance-attribute

frame_id: int

Unique frame ID (1-based).

time instance-attribute

time: float

Acquisition time in seconds.

polarity instance-attribute

polarity: Polarity

Ion polarity of the acquisition.

scan_mode instance-attribute

scan_mode: int

Scan mode integer from the TDF schema.

msms_type instance-attribute

msms_type: int

MS/MS type (0 = MS1, 8 = DDA MS2, 9 = DIA MS2).

tims_id instance-attribute

tims_id: int | None

TIMS device ID, if present.

max_intensity instance-attribute

max_intensity: int

Maximum peak intensity across all scans in this frame.

summed_intensities instance-attribute

summed_intensities: int

Sum of all peak intensities in this frame.

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 instance-attribute

mz_calibration: int

Reference to the m/z calibration entry.

t1 instance-attribute

t1: float

TIMS calibration coefficient T1.

t2 instance-attribute

t2: float

TIMS calibration coefficient T2.

tims_calibration instance-attribute

tims_calibration: int

Reference to the TIMS calibration entry.

property_group instance-attribute

property_group: int | None

Reference to the property group entry, 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.

peaks property

peaks: list[npt.NDArray[np.float64]]

Read raw peaks for this frame and return as list of (mz, intensity) arrays.

centroid

centroid(
    mz_tolerance: float = 8,
    mz_tolerance_type: Literal["ppm", "da"] = "ppm",
    im_tolerance: float = 0.05,
    im_tolerance_type: Literal[
        "relative", "absolute"
    ] = "relative",
    min_peaks: int = 3,
    max_peaks: int | None = None,
    noise_filter=None,
    ion_mobility_type: Literal[
        "ccs", "ook0", "voltage"
    ] = "ook0",
) -> np.ndarray

Centroid the spectrum for this frame using the specified parameters.

Source code in src/tdfpy/elems.py

def centroid(
    self,
    mz_tolerance: float = 8,
    mz_tolerance_type: Literal["ppm", "da"] = "ppm",
    im_tolerance: float = 0.05,
    im_tolerance_type: Literal["relative", "absolute"] = "relative",
    min_peaks: int = 3,
    max_peaks: int | None = None,
    noise_filter=None,
    ion_mobility_type: Literal["ccs", "ook0", "voltage"] = "ook0",
) -> np.ndarray:
    """Centroid the spectrum for this frame using the specified parameters."""
    get_spectrum = partial(
        get_centroided_spectrum,
        self.timsdata,
        frame_id=self.frame_id,
        spectrum_index=None,
        ion_mobility_type=ion_mobility_type,
        mz_tolerance=mz_tolerance,
        mz_tolerance_type=mz_tolerance_type,
        im_tolerance=im_tolerance,
        im_tolerance_type=im_tolerance_type,
        min_peaks=min_peaks,
        max_peaks=max_peaks,
        noise_filter=noise_filter,
    )

    try:
        return get_spectrum(use_numba=True)
    except Exception:
        warnings.warn(
            f"Numba centroiding failed for frame {self.frame_id}. Falling back to Python implementation.",
            UserWarning,
            stacklevel=2,
        )
        return get_spectrum(use_numba=False)

tdfpy.DDAMs1Frame dataclass

DDAMs1Frame(
    _timsdata: TimsData,
    frame_id: int,
    time: float,
    polarity: Polarity,
    scan_mode: int,
    msms_type: int,
    tims_id: int | None,
    max_intensity: int,
    summed_intensities: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration: int,
    t1: float,
    t2: float,
    tims_calibration: int,
    property_group: int | None,
    accumulation_time: float,
    ramp_time: float,
    precursors: tuple[Precursor, ...],
)

Bases: Frame

An MS1 frame from a DDA acquisition.

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

precursors instance-attribute

precursors: tuple[Precursor, ...]

All precursors detected in this MS1 frame.

tdfpy.DIAMs1Frame dataclass

DIAMs1Frame(
    _timsdata: TimsData,
    frame_id: int,
    time: float,
    polarity: Polarity,
    scan_mode: int,
    msms_type: int,
    tims_id: int | None,
    max_intensity: int,
    summed_intensities: int,
    num_scans: int,
    num_peaks: int,
    mz_calibration: int,
    t1: float,
    t2: float,
    tims_calibration: int,
    property_group: int | None,
    accumulation_time: float,
    ramp_time: float,
    dia_windows: tuple[DiaWindow, ...],
)

Bases: Frame

An MS1 frame from a DIA acquisition.

Inherits all fields from Frame. The dia_windows field lists the DIA isolation windows that were active during this frame.

dia_windows instance-attribute

dia_windows: tuple[DiaWindow, ...]

All DIA windows associated with this MS1 frame.