featurexml - reader for featureXML files¶
Summary¶
featureXML is a format specified in the OpenMS project. It defines a list of LC-MS features observed in an experiment.
This module provides a minimalistic way to extract information from featureXML
files. You can use the old functional interface (read()
) or the new
object-oriented interface (FeatureXML
)
to iterate over entries in <feature>
elements.
FeatureXML
also supports direct indexing with feature IDs.
Data access¶
FeatureXML
- a class representing a single featureXML file. Other data access functions use this class internally.
read()
- iterate through features in a featureXML file. Data from a single feature are converted to a human-readable dict.
chain()
- read multiple featureXML files at once.
chain.from_iterable()
- read multiple files at once, using an iterable of files.
Dependencies¶
This module requres lxml
.
- pyteomics.openms.featurexml.chain(*args, **kwargs)¶
Chain
read()
for several files. Positional arguments should be file names or file objects. Keyword arguments are passed to theread()
function.
- chain.from_iterable(files, **kwargs)¶
Chain
read()
for several files. Keyword arguments are passed to theread()
function.- Parameters:
files – Iterable of file names or file objects.
- class pyteomics.openms.featurexml.FeatureXML(source, read_schema=False, iterative=True, build_id_cache=False, use_index=None, *args, **kwargs)[source]¶
Bases:
MultiProcessingXML
Parser class for featureXML files.
- __init__(source, read_schema=False, iterative=True, build_id_cache=False, use_index=None, *args, **kwargs)¶
Create an indexed XML parser object.
- Parameters:
source (str or file) – File name or file-like object corresponding to an XML file.
read_schema (bool, optional) – Defines whether schema file referenced in the file header should be used to extract information about value conversion. Default is
False
.iterative (bool, optional) – Defines whether an
ElementTree
object should be constructed and stored on the instance or if iterative parsing should be used instead. Iterative parsing keeps the memory usage low for large XML files. Default isTrue
.use_index (bool, optional) – Defines whether an index of byte offsets needs to be created for elements listed in indexed_tags. This is useful for random access to spectra in mzML or elements of mzIdentML files, or for iterative parsing of mzIdentML with
retrieve_refs=True
. IfTrue
, build_id_cache is ignored. IfFalse
, the object acts exactly likeXML
. Default isTrue
.indexed_tags (container of bytes, optional) – If use_index is
True
, elements listed in this parameter will be indexed. Empty set by default.
- build_byte_index()¶
Build up an index of offsets for elements.
- Returns:
out
- Return type:
- build_id_cache()¶
Construct a cache for each element in the document, indexed by id attribute
- build_tree()¶
Build and store the
ElementTree
instance for the underlying file
- clear_id_cache()¶
Clear the element ID cache
- clear_tree()¶
Remove the saved
ElementTree
.
- get_by_id(elem_id, id_key=None, element_type=None, **kwargs)¶
Retrieve the requested entity by its id. If the entity is a spectrum described in the offset index, it will be retrieved by immediately seeking to the starting position of the entry, otherwise falling back to parsing from the start of the file.
- iterfind(path, **kwargs)¶
Parse the XML and yield info on elements with specified local name or by specified “XPath”.
- Parameters:
path (str) – Element name or XPath-like expression. The path is very close to full XPath syntax, but local names should be used for all elements in the path. They will be substituted with local-name() checks, up to the (first) predicate. The path can be absolute or “free”. Please don’t specify namespaces.
**kwargs (passed to
self._get_info_smart()
.)
- Returns:
out
- Return type:
iterator
- map(target=None, processes=-1, args=None, kwargs=None, **_kwargs)¶
Execute the
target
function over entries of this object across up toprocesses
processes.Results will be returned out of order.
- Parameters:
target (
Callable
, optional) – The function to execute over each entry. It will be given a single object yielded by the wrapped iterator as well as all of the values inargs
andkwargs
processes (int, optional) – The number of worker processes to use. If 0 or negative, defaults to the number of available CPUs. This parameter can also be set at reader creation.
args (
Sequence
, optional) – Additional positional arguments to be passed to the target functionkwargs (
Mapping
, optional) – Additional keyword arguments to be passed to the target function**_kwargs – Additional keyword arguments to be passed to the target function
- Yields:
object – The work item returned by the target function.
- reset()¶
Resets the iterator to its initial state.
- pyteomics.openms.featurexml.read(source, read_schema=True, iterative=True, use_index=False)[source]¶
Parse source and iterate through features.
- Parameters:
source (str or file) – A path to a target featureXML file or the file object itself.
read_schema (bool, optional) – If
True
, attempt to extract information from the XML schema mentioned in the file header (default). Otherwise, use default parameters. Disable this to avoid waiting on slow network connections or if you don’t like to get the related warnings.iterative (bool, optional) – Defines whether iterative parsing should be used. It helps reduce memory usage at almost the same parsing speed. Default is
True
.use_index (bool, optional) – Defines whether an index of byte offsets needs to be created for spectrum elements. Default is
False
.
- Returns:
out – An iterator over the dicts with feature properties.
- Return type:
iterator