FeatureMap#

class pyopenms.FeatureMap#

Bases: object

A container for LC-MS features with metadata and identification information

FeatureMap is one of the core data structures in OpenMS for storing detected features from LC-MS experiments. A feature represents a detected chemical entity (peptide, protein, metabolite, etc.) with its elution profile and mass information.

Key capabilities:

Store and manage Feature objects (detected analytes)
Associate protein and peptide identifications with features
Sort features by various criteria (RT, m/z, intensity, quality)
Store experimental metadata and data processing information
Support direct iteration and indexing in Python

Example usage:

feature_map = oms.FeatureMap()
# Add a feature
feature = oms.Feature()
feature.setRT(1234.5)
feature.setMZ(445.678)
feature.setIntensity(100000.0)
feature_map.push_back(feature)
# Access features
print(f"Number of features: {feature_map.size()}")
first_feature = feature_map[0]
# Sort by RT
feature_map.sortByRT()
# Iterate over features
for feat in feature_map:
    print(f"RT: {feat.getRT()}, m/z: {feat.getMZ()}")

__init__() → None#
__init__(arg: pyopenms.FeatureMap, /) → None

Methods

`__init__`()
`append`(feature)	Add a feature to the map (alias for push_back)
`clear`([clear_meta_data])	Clears feature data and optionally metadata
`clearMetaInfo`()	Removes all meta values
`clearRanges`()	Clear all ranges
`clearUniqueId`()	Clear the unique id.
`df_columns`([columns, ...])	Returns a list of column names that to_df() would produce.
`ensureUniqueId`()	Assigns a valid unique id, but only if the present one is invalid.
`extend`(items)	Overloaded function.
`feature_view`(i)	Returns a live view of the feature at index i.
`feature_views`()	Returns a list of live views of the features (see feature_view).
`getDataProcessing`()
`getIdentifier`()	Retrieve document identifier (e.g. an LSID).
`getKeys`(keys)	Overloaded function.
`getLoadedFilePath`()	Returns the file_name which is the absolute path to the file loaded
`getLoadedFileType`()	Returns the file_type (e.g. featureXML, consensusXML, mzData, mzXML, mzML, ...) of the file loaded.
`getMaxIntensity`()	Get the maximum intensity value
`getMaxMZ`()	Get the maximum m/z value
`getMaxRT`()	Get the maximum RT value
`getMetaValue`(name)	Returns the value corresponding to a string, or DataValue::EMPTY if not found
`getMinIntensity`()	Get the minimum intensity value
`getMinMZ`()	Get the minimum m/z value
`getMinRT`()	Get the minimum RT value
`getPrimaryMSRunPath`()	Returns the file path to the first MS run
`getProteinIdentifications`()	Returns the protein identification runs stored in this map
`getUnassignedPeptideIdentifications`()	Returns peptide identifications that are not assigned to any feature
`getUniqueId`()	Returns the unique id
`get_assigned_peptide_identifications`()	Returns all PeptideIdentifications assigned to features in this map.
`get_df`(args, *kwargs)	Deprecated: use to_df() instead.
`get_df_columns`(args, *kwargs)	Deprecated: Use df_columns() instead.
`hasInvalidUniqueId`()	Returns whether the unique id is invalid.
`hasValidUniqueId`()	Returns whether the unique id is valid.
`isMetaEmpty`()	Returns if the MetaInfo is empty
`isValid`(unique_id)	Returns true if the unique_id is valid, false otherwise
`iter_feature_views`()	Yields live views of the features, one at a time (see feature_view).
`metaRegistry`()	Returns a reference to the MetaInfoRegistry
`metaValueExists`(name)	Returns whether an entry with the given name exists
`peptide_df_columns`([decode_ontology])	Returns a list of column names that to_peptide_df() would produce.
`push_back`(feature)	Add a feature to the map
`removeMetaValue`(name)	Removes the DataValue corresponding to name if it exists
`setDataProcessing`(processing_method)	Sets the description of the applied data processing
`setIdentifier`(id)	Sets document identifier (e.g. an LSID).
`setLoadedFilePath`(file_name)	Sets the file_name according to absolute path of the file loaded, preferably done whilst loading
`setLoadedFileType`(file_name)	Sets the file_type according to the type of the file loaded from, preferably done whilst loading
`setMetaValue`(name, value)	Sets the DataValue corresponding to a name
`setPrimaryMSRunPath`(s)	Overloaded function.
`setProteinIdentifications`(...)	Sets the protein identifications for this map
`setUnassignedPeptideIdentifications`(...)	Sets the unassigned peptide identifications
`setUniqueId`()	Overloaded function.
`setUniqueIds`()	Sets unique IDs on the map and all its child features
`size`()	Returns the number of features
`sortByIntensity`([reverse])	Sorts features by intensity with optional reverse order
`sortByMZ`()	Sorts features by mass-to-charge ratio (m/z) in ascending order
`sortByOverallQuality`([reverse])	Sorts features by overall quality score in ascending order
`sortByPosition`()	Sorts features by position using lexicographical comparison
`sortByRT`()	Sorts features by retention time (RT) in ascending order
`swap`(from)
`swapFeaturesOnly`(from)	Swaps the feature content (plus its range information) of this map
`to_arrow`([columns, meta_values, ...])	Returns an Apache Arrow Table with feature information.
`to_df`([columns, meta_values, ...])	Returns a pandas DataFrame with feature information.
`to_peptide_df`([decode_ontology, ...])	Returns the PeptideIdentifications assigned to features as a pandas DataFrame.
`updateRanges`()	Updates the RT, m/z, and intensity ranges based on contained features

append(feature: pyopenms.Feature) → None#: Add a feature to the map (alias for push_back)

clear(clear_meta_data: bool = True) → None#

Clears feature data and optionally metadata

Parameters:: clear_meta_data – If True, also clears all metadata; if False, keeps metadata

clearMetaInfo() → None#: Removes all meta values

clearRanges() → None#: Clear all ranges

clearUniqueId() → int#: Clear the unique id. The new unique id will be invalid. Returns 1 if the unique id was changed, 0 otherwise

df_columns(columns='default', export_peptide_identifications=True)#: Returns a list of column names that to_df() would produce.

ensureUniqueId() → int#: Assigns a valid unique id, but only if the present one is invalid. Returns 1 if the unique id was changed, 0 otherwise

extend(items: list) → None#

extend(other: pyopenms.FeatureMap) → None

Overloaded function.

extend(items: list) -> None

Add multiple features from a list

extend(other: pyopenms.FeatureMap) -> None

Add all features from another FeatureMap

feature_view(i: int) → pyopenms.Feature#: Returns a live view of the feature at index i. The view aliases this object’s storage: edits through it are visible immediately, and it stays valid only until the feature list is resized or reordered (add/set/sort operations invalidate it). The parent object is kept alive automatically. For an owned, hazard-free copy use fm[i].

feature_views()#: Returns a list of live views of the features (see feature_view).

getDataProcessing() → list[pyopenms.DataProcessing]#

getIdentifier() → str#: Retrieve document identifier (e.g. an LSID)

getKeys(keys: list) → None#

getKeys() → list

Overloaded function.

getKeys(keys: list) -> None

Fills the given list with all meta value keys

getKeys() -> list

Returns all meta value keys as a list

getLoadedFilePath() → str#: Returns the file_name which is the absolute path to the file loaded

getLoadedFileType() → pyopenms.FileTypes.FileType#: Returns the file_type (e.g. featureXML, consensusXML, mzData, mzXML, mzML, …) of the file loaded

getMaxIntensity() → float#: Get the maximum intensity value

getMaxMZ() → float#: Get the maximum m/z value

getMaxRT() → float#: Get the maximum RT value

getMetaValue(name: str) → None | int | float | str | bytes | list[str] | list[int] | list[float]#: Returns the value corresponding to a string, or DataValue::EMPTY if not found

getMinIntensity() → float#: Get the minimum intensity value

getMinMZ() → float#: Get the minimum m/z value

getMinRT() → float#: Get the minimum RT value

getPrimaryMSRunPath() → list[str]#: Returns the file path to the first MS run

getProteinIdentifications() → list[pyopenms.ProteinIdentification]#

Returns the protein identification runs stored in this map

Returns:: Protein identification data from database searches

Protein identifications contain metadata about search parameters and protein hits

getUnassignedPeptideIdentifications() → pyopenms.PeptideIdentificationList#

Returns peptide identifications that are not assigned to any feature

Returns:: Unassigned peptide identification results

These are peptide IDs that could not be matched to features, possibly due to feature detection issues or filtering

getUniqueId() → int#: Returns the unique id

get_assigned_peptide_identifications()#

Returns all PeptideIdentifications assigned to features in this map.

The identifications are returned as the features store them, feature by feature. The list holds copies, so neither the map nor its features change. To relate them to their features, use to_peptide_df(), which adds each one’s feature_id.

get_df(*args, **kwargs)#: Deprecated: use to_df() instead.

get_df_columns(*args, **kwargs)#: Deprecated: Use df_columns() instead.

hasInvalidUniqueId() → int#: Returns whether the unique id is invalid. Returns 1 if the unique id is invalid, 0 otherwise

hasValidUniqueId() → int#: Returns whether the unique id is valid. Returns 1 if the unique id is valid, 0 otherwise

isMetaEmpty() → bool#: Returns if the MetaInfo is empty

static isValid(unique_id: int) → bool#: Returns true if the unique_id is valid, false otherwise

iter_feature_views()#: Yields live views of the features, one at a time (see feature_view).

static metaRegistry() → pyopenms.MetaInfoRegistry#: Returns a reference to the MetaInfoRegistry

metaValueExists(name: str) → bool#: Returns whether an entry with the given name exists

peptide_df_columns(decode_ontology=True)#: Returns a list of column names that to_peptide_df() would produce.

push_back(feature: pyopenms.Feature) → None#: Add a feature to the map

removeMetaValue(name: str) → None#: Removes the DataValue corresponding to name if it exists

setDataProcessing(processing_method: collections.abc.Sequence[pyopenms.DataProcessing]) → None#: Sets the description of the applied data processing

setIdentifier(id: str) → None#: Sets document identifier (e.g. an LSID)

setLoadedFilePath(file_name: str) → None#: Sets the file_name according to absolute path of the file loaded, preferably done whilst loading

setLoadedFileType(file_name: str) → None#: Sets the file_type according to the type of the file loaded from, preferably done whilst loading

setMetaValue(name: str, value: None | int | float | str | bytes | list[str] | list[int] | list[float]) → None#: Sets the DataValue corresponding to a name

setPrimaryMSRunPath(s: list[str]) → None#

setPrimaryMSRunPath(s: list[str], e: pyopenms.MSExperiment) → None

Overloaded function.

setPrimaryMSRunPath(s: list[str]) -> None

Sets the file path to the primary MS run (usually the mzML file obtained after data conversion from raw files)

setPrimaryMSRunPath(s: list[str], e: pyopenms.MSExperiment) -> None

Sets the file path to the primary MS run using the mzML annotated in the MSExperiment argument e

setProteinIdentifications(protein_identifications: collections.abc.Sequence[pyopenms.ProteinIdentification]) → None#

Sets the protein identifications for this map

Parameters:: protein_identifications – Protein identification results to associate with this map

setUnassignedPeptideIdentifications(unassigned_peptide_identifications: pyopenms.PeptideIdentificationList) → None#

Sets the unassigned peptide identifications

Parameters:: unassigned_peptide_identifications – Peptide IDs not assigned to features

setUniqueId() → int#

setUniqueId(rhs: int) → None

setUniqueId(rhs: str) → None

Overloaded function.

setUniqueId() -> int

Assigns a new, valid unique id. Always returns 1

setUniqueId(rhs: int) -> None

Assigns the given unique id

setUniqueId(rhs: str) -> None

Assigns a unique id from a string (extracts UInt64 after last underscore)

setUniqueIds() → None#: Sets unique IDs on the map and all its child features

size() → int#: Returns the number of features

sortByIntensity(reverse: bool = False) → None#

Sorts features by intensity with optional reverse order

Parameters:: reverse – If True, sorts in descending order (highest to lowest intensity)

sortByMZ() → None#

Sorts features by mass-to-charge ratio (m/z) in ascending order

Useful for mass-based grouping or analysis

sortByOverallQuality(reverse: bool = False) → None#

Sorts features by overall quality score in ascending order

Higher quality scores indicate better feature detection confidence

sortByPosition() → None#

Sorts features by position using lexicographical comparison

Compares RT first, then m/z for features with the same RT

sortByRT() → None#

Sorts features by retention time (RT) in ascending order

This is useful for time-based analysis or visualization

swap(from: pyopenms.FeatureMap) → None#

swapFeaturesOnly(from: pyopenms.FeatureMap) → None#: Swaps the feature content (plus its range information) of this map

to_arrow(columns=None, meta_values=None, export_peptide_identifications=True)#: Returns an Apache Arrow Table with feature information.

to_df(columns=None, meta_values=None, export_peptide_identifications=True)#: Returns a pandas DataFrame with feature information.

to_peptide_df(decode_ontology=True, default_missing_values=None, export_unidentified=True, columns=None)#

Returns the PeptideIdentifications assigned to features as a pandas DataFrame.

One row per identification, as PeptideIdentificationList.to_df() writes the list that get_assigned_peptide_identifications() returns, preceded by a ‘feature_id’ column: the unique ID of the identification’s feature, as the unsigned 64-bit integer that also indexes to_df(). ‘P_ID’ is the identification’s position in get_assigned_peptide_identifications(). Merge the two frames with:

merged = pd.merge(fmap.to_df().reset_index(),
                  fmap.to_peptide_df(export_unidentified=False),
                  on='feature_id', suffixes=('', '_psm'))

The merge needs unique feature IDs. Features without one, such as features created in Python, have the ID 0 until FeatureMap.setUniqueIds() assigns them one. A ‘feature_id’ meta value on the hits, as 3.5.0’s get_assigned_peptide_identifications() added it, gives way to the ‘feature_id’ column.

Parameters:

decode_ontology – Decode meta value names using the PSI-MS ontology.
default_missing_values – Default values for missing data by type.
export_unidentified – Export PeptideIdentifications without PeptideHit.
columns – Columns to include after ‘feature_id’, which is always the first. If None, includes all.

Returns:

DataFrame with one row per assigned peptide identification.

updateRanges() → None#: Updates the RT, m/z, and intensity ranges based on contained features