Pyteomics

---

- Changes in XML XPath implementation.
For standard XML parser classes, this only means a minor change in performance
(should be a slight improvement, most noticeable for :py:class:`TandemXML`).

- For custom classes: the implementation of xpath evaluation in :py:meth:`pyteomics.xml.XML.iterfind` has changed.
Pseudo-conditions are now not supported. Instead, an attempt is made to support full XPath.
The main difference is that the XPath is evaluated on XML elements,
whereas pseudo-conditions used to be evaluated for complete Python dictionaries.
To reproduce old behavior, you can just write an explicit `if` statement at an appropriate place.
New implementation allows actually skipping the elements that do not satisfy the XPath predicate.
When writing classes which by default iterate over elements based on a complex XPath, set
:py:attr:`_default_iter_path` instead of :py:attr:`_default_iter_tag`.

.. warning ::
Beware that if :py:attr:`_default_iter_path` differs from :py:attr:`_default_iter_tag` and you use indexing,
all elements corresponding to :py:attr:`_default_iter_tag` will be indexed.
This is a limitation of the index building procedure.
This discrepancy will lead to confusing behavior
(length checks, membership tests and other things based on index
will not correspond to items returned by iteration).
:py:meth:`map` calls will also operate on the full index.


- New keyword arguments `queue_size`, `queue_timeout` and `processes` for indexed parsers with support for :py:meth:`map`.

- New method :py:meth:`mass.Unimod.by_id`.
Also, :py:class:`mass.Unimod` now supports dict-like queries with record IDs.

- Reduce memory footprint for unit primitives (PR 35 by Joshua Klein).

- New functions :py:func:`pyteomics.auxiliary.sigma_T` and :py:func:`pyteomics.auxiliary.sigma_fdr`.

- Fix issues 44, 46, 47, 48.

-----

Bugfix: fix the standard mass value for pyrrolysine (issue 42).

-----

- Add `numpress <https://dx.doi.org/10.1074%2Fmcp.O114.037879>`_ support for mzML and mzXML files.
To read files compressed with Numpress, install `pynumpress`
(`PyPI <https://pypi.org/project/pynumpress/>`_, `GitHub <https://github.com/mobiusklein/pynumpress>`_).

- Bugfixes.

API changes
...........

- In :py:func:`ms1.read` and :py:func:`ms2.read`, the default value for `use_index` is now :py:const:`False`.
Using the indexed parsers may result in incorrect behavior if the "first" scan number in S-lines is not unique.

---

- New module :py:mod:`pyteomics.mztab` provides a parser for `mzTab files <http://www.psidev.info/mztab>`_.

- New module :py:mod:`pyteomics.ms2` provides a parser for **ms2** files.
This is in fact an alias to :py:mod:`ms1`, which handles both formats.

- Added index saving functionality for :py:class:`pyteomics.mgf.IndexedMGF`.

- New helper functions :py:func:`pyteomics.pylab_aux.plot_spectrum` and :py:func:`pyteomics.pylab_aux.annotate_spectrum`.

- The `rule` and `exception` arguments in :py:func:`pyteomics.parser.cleave` can be keys from :py:const:`expasy_rules`.

- Fixes.

-----

Fix issue `35 <hhttps://levitsky.github.io/bitbucket_backup/#!/levitsky/pyteomics/issues/35/page/1>`_
(incorrect order of deserialized offset indexes on older Python versions).

---

.. seealso::
`Pyteomics 4.0: five years of development of a Python proteomics framework
<https://pubs.acs.org/doi/10.1021/acs.jproteome.8b00717>`_


- Add parameters `semi` and `exception` in :py:func:`pyteomics.parser.cleave`.

- Add new parameter `encoding` in file writers.

- Add new parameters `write_charges` and `use_numpy` in :py:func:`pyteomics.mgf.write`.
Speed up the writing when :py:mod:`numpy` is available.

- :ref:`Indexing text parsers <indexing>`. This release introduces a family of parser classes for text files.
These parsers create byte offsets of indexed entries to allow random access by unique key or by positional index,
"rich" access by slices and, in case of MGF/mzML/mzXML, by retention time range.
All indexing parsers, text- or XML-based, now have a unified interface.

- New class :py:class:`pyteomics.mgf.IndexedMGF` is now the recommended way to parse MGF files.
It supports fast access by spectrum titles by using an index of byte offsets.
The old, sequential parser is preserved under its name, :py:class:`pyteomics.mgf.MGF`.
The function :py:func:`pyteomics.mgf.read` now returns an instance of one of the two classes,
based on the `use_index` argument and the type of `source`.
The common ancestor class, :py:class:`pyteomics.mgf.MGFBase`, can be used for type checking.

- New FASTA parsing classes:

- :py:class:`pyteomics.fasta.FASTABase` - common ancestor, suitable for type checking;

- :py:class:`pyteomics.fasta.FASTA` - text-mode, sequential parser; does
what the old :py:func:`fasta.read` was doing. Additionally, the following subclasses perform
format-specific parsing of FASTA headers:

- :py:class:`pyteomics.fasta.UniProt`;
- :py:class:`pyteomics.fasta.UniParc`;
- :py:class:`pyteomics.fasta.UniRef`;
- :py:class:`pyteomics.fasta.UniMes`;
- :py:class:`pyteomics.fasta.SPD`;
- :py:class:`pyteomics.fasta.NCBI`;

- :py:class:`pyteomics.fasta.IndexedFASTA` - binary-mode, indexing parser.
Supports direct indexing by header string;

- :py:class:`pyteomics.fasta.TwoLayerIndexedFASTA` - additionally supports
indexing by extracted header fields. Format-specific second indexes are available in
subclasses:

- :py:class:`pyteomics.fasta.IndexedUniProt`;
- :py:class:`pyteomics.fasta.IndexedUniParc`;
- :py:class:`pyteomics.fasta.IndexedUniRef`;
- :py:class:`pyteomics.fasta.IndexedUniMes`;
- :py:class:`pyteomics.fasta.IndexedSPD`;
- :py:class:`pyteomics.fasta.IndexedNCBI`.

:py:func:`pyteomics.fasta.read` now returns an instance of one of these classes,
depending on the arguments `use_index` and `flavor`.

- :py:class:`pyteomics.ms1.IndexedMS1` and :py:class:`pyteomics.ms1.MS1` are available for ms1 format.

*(In collaboration with J. Klein)*

- Multiprocessing support: all indexed XML and text file parsers now expose a :py:meth:`map` method.
This method can map a user-supplied function to each file entry in separate processes (or simply
parallelize the parsing itself).
Additionally, objects returned by :py:func:`chain` functions and :py:meth:`iterfind` methods also expose
the :py:meth:`map` interface to allow parallelizing the work over multiple files and when iterating over
non-default XML tree elements.
The order of entries is not preserved in the output.
*(In collaboration with J. Klein)*

- New module :py:mod:`pyteomics.peff` implements the :py:class:`IndexedPEFF` parser for protein databases
in the new PSI standard format, `PEFF <http://www.psidev.info/peff>`_. *(Contributed by J. Klein)*

- New module :py:mod:`pyteomics.traml` implements the :py:class:`TraML` parser for the PSI standard format
for SRM data, `TraML <http://www.psidev.info/traml>`_. *(In collaboration with J. Klein)*

- :py:class:`pyteomics.protxml.ProtXML` now also supports indexing and multiprocessing.

- Removed parameter `skip_empty_cvparam_values` in XML parsers. In cvParam elements, missing "value"
attribute is now always equivalent to the case when it is equal to an empty string. This affects
the structure of items produced by MzML and MzIdentML parsers.

- Multiple fixes and improvements.