Skip to content

Precursor & Ions

mzmlpy.spectra.Precursor dataclass 

Precursor(element: ElementTree.Element)

Bases: _DataTreeWrapper

Represents a precursor element in an mzML spectrum.

Provides access to the isolation window, selected ions, activation parameters, and reference attributes such as spectrum ref and source file ref.

ns cached property 

ns: str

Get XML namespace from the element tag.

serialize 

serialize() -> dict

return the full element content

Source code in src/mzmlpy/elems/dtree_wrapper.py 
63
64
65
66
67
68
69
70
def serialize(self) -> dict:
    """return the full element content"""
    return {
        "tag": self.element.tag,
        "attributes": self.element.attrib,
        "text": self.element.text,
        "children": [_DataTreeWrapper(child).serialize() for child in self.element],
    }

get_attribute 

get_attribute(attr_name: str) -> str | None

Get an attribute value from the element.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
72
73
74
def get_attribute(self, attr_name: str) -> str | None:
    """Get an attribute value from the element."""
    return self.element.attrib.get(attr_name)

Product

mzmlpy.spectra.Product dataclass 

Product(element: ElementTree.Element)

Bases: _ParamGroup

A product ion selection element containing an isolation window and CV parameters.

isolation_window property 

isolation_window: IsolationWindow | None

Get the isolation window for this product, if present.

ns cached property 

ns: str

Get XML namespace from the element tag.

cv_params cached property 

cv_params: list[CvParam]

Parse cvParams from the XML element.

accessions cached property 

accessions: set[str]

Get a set of all accession numbers from the cvParams.

names cached property 

names: set[str]

Get a set of all names from the cvParams.

user_params property 

user_params: list[UserParam]

Parse userParams from the XML element.

ref_params property 

ref_params: list[ReferenceableParamGroupRef]

Get a list of all referenceable parameters from the XML element.

serialize 

serialize() -> dict

return the full element content

Source code in src/mzmlpy/elems/dtree_wrapper.py 
63
64
65
66
67
68
69
70
def serialize(self) -> dict:
    """return the full element content"""
    return {
        "tag": self.element.tag,
        "attributes": self.element.attrib,
        "text": self.element.text,
        "children": [_DataTreeWrapper(child).serialize() for child in self.element],
    }

get_attribute 

get_attribute(attr_name: str) -> str | None

Get an attribute value from the element.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
72
73
74
def get_attribute(self, attr_name: str) -> str | None:
    """Get an attribute value from the element."""
    return self.element.attrib.get(attr_name)

get_cvparm 

get_cvparm(id: str) -> CvParam | None

Get a cvParam by accession or name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
100
101
102
103
104
105
def get_cvparm(self, id: str) -> CvParam | None:
    """Get a cvParam by accession or name."""
    for cv_param in self.cv_params:
        if cv_param.accession == id or cv_param.name == id:
            return cv_param
    return None

has_cvparm 

has_cvparm(id: str) -> bool

Check if a cvParam with the given accession or name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
107
108
109
def has_cvparm(self, id: str) -> bool:
    """Check if a cvParam with the given accession or name exists."""
    return any(cv_param.accession == id or cv_param.name == id for cv_param in self.cv_params)

cv_float 

cv_float(id: str) -> float | None

Return a cvParam's value as a float, or None if the term is absent or has no value.

Raises ValueError naming the term and its bad value if the value is present but not numeric — more actionable than a bare "could not convert string to float".

Source code in src/mzmlpy/elems/dtree_wrapper.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def cv_float(self, id: str) -> float | None:
    """Return a cvParam's value as a float, or None if the term is absent or has no value.

    Raises ValueError naming the term and its bad value if the value is present but not
    numeric — more actionable than a bare "could not convert string to float".
    """
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return float(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-numeric value {cv_param.value!r}"
        ) from e

cv_int 

cv_int(id: str) -> int | None

Return a cvParam's value as an int, or None if absent or valueless (see :meth:cv_float).

Source code in src/mzmlpy/elems/dtree_wrapper.py 
127
128
129
130
131
132
133
134
135
136
137
def cv_int(self, id: str) -> int | None:
    """Return a cvParam's value as an int, or None if absent or valueless (see :meth:`cv_float`)."""
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return int(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-integer value {cv_param.value!r}"
        ) from e

get_user_param 

get_user_param(name: str) -> UserParam | None

Get a userParam by name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
167
168
169
170
171
172
def get_user_param(self, name: str) -> UserParam | None:
    """Get a userParam by name."""
    for user_param in self.user_params:
        if user_param.name == name:
            return user_param
    return None

has_user_param 

has_user_param(name: str) -> bool

Check if a userParam with the given name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
174
175
176
def has_user_param(self, name: str) -> bool:
    """Check if a userParam with the given name exists."""
    return any(user_param.name == name for user_param in self.user_params)

get_ref_param 

get_ref_param(
    ref: str,
) -> ReferenceableParamGroupRef | None

Get a referenceable parameter by ref.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
187
188
189
190
191
192
def get_ref_param(self, ref: str) -> ReferenceableParamGroupRef | None:
    """Get a referenceable parameter by ref."""
    for ref_param in self.ref_params:
        if ref_param.ref == ref:
            return ref_param
    return None

has_ref_param 

has_ref_param(ref: str) -> bool

Check if a referenceable parameter with the given ref exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
194
195
196
def has_ref_param(self, ref: str) -> bool:
    """Check if a referenceable parameter with the given ref exists."""
    return any(ref_param.ref == ref for ref_param in self.ref_params)

IsolationWindow

mzmlpy.spectra.IsolationWindow dataclass 

IsolationWindow(element: ElementTree.Element)

Bases: _ParamGroup

Represents an isolation window element from a precursor or product.

Provides access to the target m/z, lower offset, and upper offset values.

target_mz property 

target_mz: float | None

Get isolation window target m/z for this precursor.

lower_offset property 

lower_offset: float | None

Get isolation window lower offset for this precursor.

upper_offset property 

upper_offset: float | None

Get isolation window upper offset for this precursor.

ns cached property 

ns: str

Get XML namespace from the element tag.

cv_params cached property 

cv_params: list[CvParam]

Parse cvParams from the XML element.

accessions cached property 

accessions: set[str]

Get a set of all accession numbers from the cvParams.

names cached property 

names: set[str]

Get a set of all names from the cvParams.

user_params property 

user_params: list[UserParam]

Parse userParams from the XML element.

ref_params property 

ref_params: list[ReferenceableParamGroupRef]

Get a list of all referenceable parameters from the XML element.

serialize 

serialize() -> dict

return the full element content

Source code in src/mzmlpy/elems/dtree_wrapper.py 
63
64
65
66
67
68
69
70
def serialize(self) -> dict:
    """return the full element content"""
    return {
        "tag": self.element.tag,
        "attributes": self.element.attrib,
        "text": self.element.text,
        "children": [_DataTreeWrapper(child).serialize() for child in self.element],
    }

get_attribute 

get_attribute(attr_name: str) -> str | None

Get an attribute value from the element.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
72
73
74
def get_attribute(self, attr_name: str) -> str | None:
    """Get an attribute value from the element."""
    return self.element.attrib.get(attr_name)

get_cvparm 

get_cvparm(id: str) -> CvParam | None

Get a cvParam by accession or name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
100
101
102
103
104
105
def get_cvparm(self, id: str) -> CvParam | None:
    """Get a cvParam by accession or name."""
    for cv_param in self.cv_params:
        if cv_param.accession == id or cv_param.name == id:
            return cv_param
    return None

has_cvparm 

has_cvparm(id: str) -> bool

Check if a cvParam with the given accession or name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
107
108
109
def has_cvparm(self, id: str) -> bool:
    """Check if a cvParam with the given accession or name exists."""
    return any(cv_param.accession == id or cv_param.name == id for cv_param in self.cv_params)

cv_float 

cv_float(id: str) -> float | None

Return a cvParam's value as a float, or None if the term is absent or has no value.

Raises ValueError naming the term and its bad value if the value is present but not numeric — more actionable than a bare "could not convert string to float".

Source code in src/mzmlpy/elems/dtree_wrapper.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def cv_float(self, id: str) -> float | None:
    """Return a cvParam's value as a float, or None if the term is absent or has no value.

    Raises ValueError naming the term and its bad value if the value is present but not
    numeric — more actionable than a bare "could not convert string to float".
    """
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return float(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-numeric value {cv_param.value!r}"
        ) from e

cv_int 

cv_int(id: str) -> int | None

Return a cvParam's value as an int, or None if absent or valueless (see :meth:cv_float).

Source code in src/mzmlpy/elems/dtree_wrapper.py 
127
128
129
130
131
132
133
134
135
136
137
def cv_int(self, id: str) -> int | None:
    """Return a cvParam's value as an int, or None if absent or valueless (see :meth:`cv_float`)."""
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return int(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-integer value {cv_param.value!r}"
        ) from e

get_user_param 

get_user_param(name: str) -> UserParam | None

Get a userParam by name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
167
168
169
170
171
172
def get_user_param(self, name: str) -> UserParam | None:
    """Get a userParam by name."""
    for user_param in self.user_params:
        if user_param.name == name:
            return user_param
    return None

has_user_param 

has_user_param(name: str) -> bool

Check if a userParam with the given name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
174
175
176
def has_user_param(self, name: str) -> bool:
    """Check if a userParam with the given name exists."""
    return any(user_param.name == name for user_param in self.user_params)

get_ref_param 

get_ref_param(
    ref: str,
) -> ReferenceableParamGroupRef | None

Get a referenceable parameter by ref.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
187
188
189
190
191
192
def get_ref_param(self, ref: str) -> ReferenceableParamGroupRef | None:
    """Get a referenceable parameter by ref."""
    for ref_param in self.ref_params:
        if ref_param.ref == ref:
            return ref_param
    return None

has_ref_param 

has_ref_param(ref: str) -> bool

Check if a referenceable parameter with the given ref exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
194
195
196
def has_ref_param(self, ref: str) -> bool:
    """Check if a referenceable parameter with the given ref exists."""
    return any(ref_param.ref == ref for ref_param in self.ref_params)

SelectedIon

mzmlpy.spectra.SelectedIon dataclass 

SelectedIon(element: ElementTree.Element)

Bases: _ParamGroup

Represents a selected ion element within a precursor.

Provides access to the selected ion m/z, peak intensity, charge state, ion mobility values, FAIMS voltages, and collisional cross section.

selected_ion_mz property 

selected_ion_mz: float | None

Get selected ion m/z for this precursor.

peak_intensity property 

peak_intensity: float | None

Get peak intensity for this precursor.

charge_state property 

charge_state: int | None

Get charge state for this precursor.

ir_im property 

ir_im: float | None

Get inversion reduced ion mobility for this precursor.

im_drift_time property 

im_drift_time: float | None

Get ion mobility drift time for this precursor.

faims_voltage_start property 

faims_voltage_start: float | None

Get FAIMS voltage start for this precursor.

faims_voltage_end property 

faims_voltage_end: float | None

Get FAIMS voltage end for this precursor.

ccs property 

ccs: float | None

Get collisional cross section for this precursor.

ns cached property 

ns: str

Get XML namespace from the element tag.

cv_params cached property 

cv_params: list[CvParam]

Parse cvParams from the XML element.

accessions cached property 

accessions: set[str]

Get a set of all accession numbers from the cvParams.

names cached property 

names: set[str]

Get a set of all names from the cvParams.

user_params property 

user_params: list[UserParam]

Parse userParams from the XML element.

ref_params property 

ref_params: list[ReferenceableParamGroupRef]

Get a list of all referenceable parameters from the XML element.

serialize 

serialize() -> dict

return the full element content

Source code in src/mzmlpy/elems/dtree_wrapper.py 
63
64
65
66
67
68
69
70
def serialize(self) -> dict:
    """return the full element content"""
    return {
        "tag": self.element.tag,
        "attributes": self.element.attrib,
        "text": self.element.text,
        "children": [_DataTreeWrapper(child).serialize() for child in self.element],
    }

get_attribute 

get_attribute(attr_name: str) -> str | None

Get an attribute value from the element.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
72
73
74
def get_attribute(self, attr_name: str) -> str | None:
    """Get an attribute value from the element."""
    return self.element.attrib.get(attr_name)

get_cvparm 

get_cvparm(id: str) -> CvParam | None

Get a cvParam by accession or name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
100
101
102
103
104
105
def get_cvparm(self, id: str) -> CvParam | None:
    """Get a cvParam by accession or name."""
    for cv_param in self.cv_params:
        if cv_param.accession == id or cv_param.name == id:
            return cv_param
    return None

has_cvparm 

has_cvparm(id: str) -> bool

Check if a cvParam with the given accession or name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
107
108
109
def has_cvparm(self, id: str) -> bool:
    """Check if a cvParam with the given accession or name exists."""
    return any(cv_param.accession == id or cv_param.name == id for cv_param in self.cv_params)

cv_float 

cv_float(id: str) -> float | None

Return a cvParam's value as a float, or None if the term is absent or has no value.

Raises ValueError naming the term and its bad value if the value is present but not numeric — more actionable than a bare "could not convert string to float".

Source code in src/mzmlpy/elems/dtree_wrapper.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def cv_float(self, id: str) -> float | None:
    """Return a cvParam's value as a float, or None if the term is absent or has no value.

    Raises ValueError naming the term and its bad value if the value is present but not
    numeric — more actionable than a bare "could not convert string to float".
    """
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return float(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-numeric value {cv_param.value!r}"
        ) from e

cv_int 

cv_int(id: str) -> int | None

Return a cvParam's value as an int, or None if absent or valueless (see :meth:cv_float).

Source code in src/mzmlpy/elems/dtree_wrapper.py 
127
128
129
130
131
132
133
134
135
136
137
def cv_int(self, id: str) -> int | None:
    """Return a cvParam's value as an int, or None if absent or valueless (see :meth:`cv_float`)."""
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return int(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-integer value {cv_param.value!r}"
        ) from e

get_user_param 

get_user_param(name: str) -> UserParam | None

Get a userParam by name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
167
168
169
170
171
172
def get_user_param(self, name: str) -> UserParam | None:
    """Get a userParam by name."""
    for user_param in self.user_params:
        if user_param.name == name:
            return user_param
    return None

has_user_param 

has_user_param(name: str) -> bool

Check if a userParam with the given name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
174
175
176
def has_user_param(self, name: str) -> bool:
    """Check if a userParam with the given name exists."""
    return any(user_param.name == name for user_param in self.user_params)

get_ref_param 

get_ref_param(
    ref: str,
) -> ReferenceableParamGroupRef | None

Get a referenceable parameter by ref.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
187
188
189
190
191
192
def get_ref_param(self, ref: str) -> ReferenceableParamGroupRef | None:
    """Get a referenceable parameter by ref."""
    for ref_param in self.ref_params:
        if ref_param.ref == ref:
            return ref_param
    return None

has_ref_param 

has_ref_param(ref: str) -> bool

Check if a referenceable parameter with the given ref exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
194
195
196
def has_ref_param(self, ref: str) -> bool:
    """Check if a referenceable parameter with the given ref exists."""
    return any(ref_param.ref == ref for ref_param in self.ref_params)

Activation

mzmlpy.spectra.Activation dataclass 

Activation(element: ElementTree.Element)

Bases: _ParamGroup

Represents an activation element within a precursor.

Provides access to the activation type, collision energy, supplemental collision energy, collision gas, and collision gas pressure.

activation_type property 

activation_type: CollisionDissociationTypeAccession | None

Get activation type for this precursor.

activation_energy property 

activation_energy: float | None

Get activation energy for this precursor.

ce property 

ce: float | None

Get collision energy for this precursor.

supplemental_ce property 

supplemental_ce: float | None

Get supplemental collision energy for this precursor.

collision_gas property 

collision_gas: str | None

Get collision gas for this precursor.

collision gas (MS:1000419) is normally a valueless flag whose identity is carried by the term name, so this returns the parameter's value when one is present and otherwise the term name — instead of returning None for the (common) valueless case.

collision_gas_pressure property 

collision_gas_pressure: float | None

Get collision gas pressure for this precursor.

ns cached property 

ns: str

Get XML namespace from the element tag.

cv_params cached property 

cv_params: list[CvParam]

Parse cvParams from the XML element.

accessions cached property 

accessions: set[str]

Get a set of all accession numbers from the cvParams.

names cached property 

names: set[str]

Get a set of all names from the cvParams.

user_params property 

user_params: list[UserParam]

Parse userParams from the XML element.

ref_params property 

ref_params: list[ReferenceableParamGroupRef]

Get a list of all referenceable parameters from the XML element.

serialize 

serialize() -> dict

return the full element content

Source code in src/mzmlpy/elems/dtree_wrapper.py 
63
64
65
66
67
68
69
70
def serialize(self) -> dict:
    """return the full element content"""
    return {
        "tag": self.element.tag,
        "attributes": self.element.attrib,
        "text": self.element.text,
        "children": [_DataTreeWrapper(child).serialize() for child in self.element],
    }

get_attribute 

get_attribute(attr_name: str) -> str | None

Get an attribute value from the element.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
72
73
74
def get_attribute(self, attr_name: str) -> str | None:
    """Get an attribute value from the element."""
    return self.element.attrib.get(attr_name)

get_cvparm 

get_cvparm(id: str) -> CvParam | None

Get a cvParam by accession or name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
100
101
102
103
104
105
def get_cvparm(self, id: str) -> CvParam | None:
    """Get a cvParam by accession or name."""
    for cv_param in self.cv_params:
        if cv_param.accession == id or cv_param.name == id:
            return cv_param
    return None

has_cvparm 

has_cvparm(id: str) -> bool

Check if a cvParam with the given accession or name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
107
108
109
def has_cvparm(self, id: str) -> bool:
    """Check if a cvParam with the given accession or name exists."""
    return any(cv_param.accession == id or cv_param.name == id for cv_param in self.cv_params)

cv_float 

cv_float(id: str) -> float | None

Return a cvParam's value as a float, or None if the term is absent or has no value.

Raises ValueError naming the term and its bad value if the value is present but not numeric — more actionable than a bare "could not convert string to float".

Source code in src/mzmlpy/elems/dtree_wrapper.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def cv_float(self, id: str) -> float | None:
    """Return a cvParam's value as a float, or None if the term is absent or has no value.

    Raises ValueError naming the term and its bad value if the value is present but not
    numeric — more actionable than a bare "could not convert string to float".
    """
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return float(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-numeric value {cv_param.value!r}"
        ) from e

cv_int 

cv_int(id: str) -> int | None

Return a cvParam's value as an int, or None if absent or valueless (see :meth:cv_float).

Source code in src/mzmlpy/elems/dtree_wrapper.py 
127
128
129
130
131
132
133
134
135
136
137
def cv_int(self, id: str) -> int | None:
    """Return a cvParam's value as an int, or None if absent or valueless (see :meth:`cv_float`)."""
    cv_param = self.get_cvparm(id)
    if cv_param is None or cv_param.value is None:
        return None
    try:
        return int(cv_param.value)
    except ValueError as e:
        raise ValueError(
            f"CV param {cv_param.name or id!r} ({id}) has a non-integer value {cv_param.value!r}"
        ) from e

get_user_param 

get_user_param(name: str) -> UserParam | None

Get a userParam by name.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
167
168
169
170
171
172
def get_user_param(self, name: str) -> UserParam | None:
    """Get a userParam by name."""
    for user_param in self.user_params:
        if user_param.name == name:
            return user_param
    return None

has_user_param 

has_user_param(name: str) -> bool

Check if a userParam with the given name exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
174
175
176
def has_user_param(self, name: str) -> bool:
    """Check if a userParam with the given name exists."""
    return any(user_param.name == name for user_param in self.user_params)

get_ref_param 

get_ref_param(
    ref: str,
) -> ReferenceableParamGroupRef | None

Get a referenceable parameter by ref.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
187
188
189
190
191
192
def get_ref_param(self, ref: str) -> ReferenceableParamGroupRef | None:
    """Get a referenceable parameter by ref."""
    for ref_param in self.ref_params:
        if ref_param.ref == ref:
            return ref_param
    return None

has_ref_param 

has_ref_param(ref: str) -> bool

Check if a referenceable parameter with the given ref exists.

Source code in src/mzmlpy/elems/dtree_wrapper.py 
194
195
196
def has_ref_param(self, ref: str) -> bool:
    """Check if a referenceable parameter with the given ref exists."""
    return any(ref_param.ref == ref for ref_param in self.ref_params)