Add opt-in support for chimeric ProForma parsing

doc/source/api/proforma.rst

@@ -43,6 +43,16 @@ Data Access
 
 :py:func:`to_proforma` - Format a sequence and set of properties as ProForma text.
 
+Chimeric spectra are parsed by opting in with ``chimeric=True``. In that mode,
+top-level ``+`` separates peptidoform components and shared fixed modification
+rules and isotope labels are applied to each component:
+
+.. code-block:: python
+
+    >>> components = parse("<[Carbamidomethyl]@C>AC+CC", chimeric=True)
+    >>> len(components)
+    2
+
 
 Classes
 -------
@@ -140,7 +150,7 @@ These features are independent from each other:
 6. Spectral Support
 
     - [x] Charge state and adducts
-    - [ ] Chimeric spectra are special cases.
+    - [x] Chimeric spectra are special cases.
     - [x] Global modifications (e.g., every C is C13).
 
 

doc/source/proforma.rst

@@ -25,3 +25,31 @@ To instantiate a :py:class:`ProForma` object, use the class method :py:meth:`Pro
 
         >>> seq.composition()
         Composition({'H': 86, 'C': 51, 'O': 30, 'N': 12, 'S': 1, 'P': 2})
+
+Chimeric spectra
+~~~~~~~~~~~~~~~~
+
+Top-level ``+`` in ProForma is treated as a chimeric separator only when
+``chimeric=True`` is passed. The return value is then a list of parsed
+components:
+
+.. code-block:: python
+
+    >>> forms = ProForma.parse("<[Carbamidomethyl]@C>AC+CC", chimeric=True)
+    >>> len(forms)
+    2
+    >>> [str(form) for form in forms]
+    ['<[Carbamidomethyl]@C>AC', '<[Carbamidomethyl]@C>CC']
+
+Fixed modification rules, isotope labels, and peptidoform names are shared
+across all chimeric components.
+
+Other APIs such as mass calculation, fragment series generation, and spectrum
+annotation operate on one peptidoform at a time. Use the parsed components
+individually:
+
+.. code-block:: python
+
+    >>> from pyteomics import mass
+    >>> masses = [mass.calculate_mass(proforma=str(form)) for form in forms]
+    >>> fragments = [mass.fragment_series(str(form)) for form in forms]