docs

README.md

@@ -5,7 +5,7 @@ A spectacularly simple package for working with peptide sequences. Now proforma2
 
 # Warnings
 
-- The fragment ion mass calculation may not be accurate. Fairly certain that the ay, by, and cy internal fragments are 
+- The internal fragment ion mass calculation may not be accurate. Fairly certain that the ay, by, and cy internal fragments are 
 correct since the y fragment is really just a smaller parent ion.
 - GNO and RESID mods are disabled for now. I will add them back in later.
 - Project is still under development. I will be adding more features and fixing bugs as I find them.

src/peptacular/__init__.py

@@ -14,16 +14,3 @@
 from .score import *
 from .util import *
 from .spans import *
-
-"""from .sequence.combinatoric import *
-from .sequence.mod_builder import *
-from .sequence.sequence_funcs import *
-
-from .proforma.proforma_parser import *
-from .proforma.proforma_dataclasses import *
-
-
-from .mods.mod_db import *
-
-
-"""

src/peptacular/chem/chem_calc.py

@@ -11,8 +11,8 @@
 from peptacular.chem.chem_util import parse_chem_formula, write_chem_formula
 from peptacular.mods.mod_db_setup import MONOSACCHARIDES_DB
 from peptacular.sequence.sequence_funcs import sequence_to_annotation
-from peptacular.constants import AA_COMPOSITIONS, AVERAGINE_RATIOS, NEUTRAL_FRAGMENT_COMPOSITION_ADJUSTMENTS, \
-    FRAGMENT_ION_COMPOSITIONS, FRAGMENT_ION_BASE_CHARGE_ADDUCTS
+from peptacular.constants import (AA_COMPOSITIONS, AVERAGINE_RATIOS, NEUTRAL_FRAGMENT_COMPOSITION_ADJUSTMENTS,
+                                  FRAGMENT_ION_BASE_CHARGE_ADDUCTS)
 from peptacular.errors import InvalidCompositionError, AmbiguousAminoAcidError, \
     UnknownAminoAcidError, DeltaMassCompositionError
 from peptacular.glycan import glycan_comp
@@ -33,7 +33,7 @@ def glycan_to_chem(glycan: Union[ChemComposition, str]) -> str:
     :return: A chemical formula string.
     :rtype: str
 
-    .. code-block:: python
+    . code-block:: python
 
             >>> glycan_to_chem({'HexNAc': 2, 'Hex': 3, 'Neu5Gc': 1})
             'C45H73N3O34'
@@ -58,7 +58,7 @@ def mod_comp(mod: ModValue) -> ChemComposition:
     :return: The composition of the modification.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         >>> mod_comp('Acetyl|INFO:newly discovered')
         {'H': 2, 'C': 2, 'O': 1}
@@ -99,7 +99,7 @@ def estimate_comp(neutral_mass: float,
     :return: The estimated composition.
     :rtype: Dict[str, int | float]
 
-    .. python::
+    . python::
 
         # Example usage
         >>> estimate_comp(1000)['C']
@@ -132,7 +132,7 @@ def _parse_glycan_comp(glycan_str: str) -> ChemComposition:
     :return: The composition of the glycan.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         #  Get Composition
         >>> _parse_glycan_comp('HexNAc2Hex3Neu1')
@@ -197,7 +197,7 @@ def _parse_mod_comp(mod: str) -> Union[ChemComposition, None]:
     :return: The parsed composition, or None if the composition cannot be parsed.
     :rtype: Dict[str, int | float] | None
 
-    .. code-block:: python
+    . code-block:: python
 
         # Calculate the mass of a peptide sequence.
         >>> _parse_mod_comp('U:2')
@@ -271,7 +271,7 @@ def _parse_mod_delta_mass(mod: str) -> Union[float, None]:
     :return: The parsed delta mass, or None if the delta mass cannot be parsed.
     :rtype: float | None
 
-    .. code-block:: python
+    . code-block:: python
 
         >>> _parse_mod_delta_mass('42.0')
         42.0
@@ -349,7 +349,7 @@ def _sequence_comp(annotation: Union[str, ProFormaAnnotation],
     :return: The composition of the sequence.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Calculate the mass of a peptide sequence.
         >>> _sequence_comp('PEPTIDE/1', 'y')
@@ -551,7 +551,7 @@ def _parse_mod_delta_mass_only(mod: Union[str, Mod]) -> Union[float, None]:
     :return: The delta mass of the modification or None if the modification is not a delta mass.
     :rtype: float | None
 
-    .. code-block:: python
+    . code-block:: python
 
         >>> _parse_mod_delta_mass_only('Acetyl|INFO:newly discovered')
 
@@ -601,7 +601,7 @@ def apply_isotope_mods_to_composition(composition: Union[ChemComposition, str],
     :return: The modified composition.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Apply isotopic modifications to a composition.
         >>> apply_isotope_mods_to_composition({'C': 6, 'H': 12, 'O': 6}, ['13C'])
@@ -656,7 +656,7 @@ def _parse_adduct_comp(adduct: str) -> ChemComposition:
     :return: The composition of the adduct.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Parse an adduct string.
         >>> _parse_adduct_comp('+Na+')
@@ -688,7 +688,7 @@ def _parse_charge_adducts_comp(adducts: ModValue) -> ChemComposition:
     :return: The composition of the charge adducts.
     :rtype: Dict[str, int | float]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Parse the charge adducts and return their mass.
         >>> _parse_charge_adducts_comp('+Na+,+H+')

src/peptacular/chem/chem_util.py

@@ -22,7 +22,7 @@ def parse_chem_formula(formula: str, sep: str = '') -> ChemComposition:
     :return: A dictionary with the element and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
         >>> parse_chem_formula('C6H12O6666')
         {'C': 6, 'H': 12, 'O': 6666}
@@ -98,7 +98,7 @@ def write_chem_formula(composition: ChemComposition, sep: str = '', hill_order:
     :return: The chemical formula.
     :rtype: str
 
-    .. code-block:: python
+    . code-block:: python
 
         # Calculate the mass of a peptide sequence.
         >>> write_chem_formula({'C': 6, 'H': 12, 'O': 6})
@@ -164,7 +164,7 @@ def chem_mass(formula: Union[ChemComposition, str],
     :return: The mass of the chemical formula.
     :rtype: float
 
-    .. code-block:: python
+    . code-block:: python
 
         # Calculate the mass of a chemical formula.
         >>> chem_mass({'C': 6, 'H': 12, 'O': 6}, precision=3)
@@ -239,7 +239,7 @@ def _split_chem_formula(formula: str) -> list[str]:
     :return: The components of the chemical formula, split by instances of the isotope notation.
     :rtype: list[str]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Split a chemical formula into its components.
         >>> _split_chem_formula('C6H12O6')
@@ -283,7 +283,7 @@ def _parse_isotope_component(formula: str) -> ChemComposition:
     :return: A dictionary with the element and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
         # Parse an isotope notation.
         >>> _parse_isotope_component('13C6')
@@ -351,7 +351,7 @@ def _parse_condensed_chem_formula(formula: str) -> ChemComposition:
     :return: A dictionary with the element and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
         # Calculate the mass of a peptide sequence.
         >>> _parse_condensed_chem_formula('C6H12O6')
@@ -433,7 +433,7 @@ def _parse_split_chem_formula(formula: str, sep: str) -> ChemComposition:
     :return: A dictionary with the element and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
         >>> _parse_split_chem_formula('C 6 H 12 O 6', ' ')
         {'C': 6, 'H': 12, 'O': 6}

src/peptacular/digestion.py

@@ -88,7 +88,7 @@ def get_left_semi_enzymatic_sequences(sequence: Union[str, ProFormaAnnotation],
     :return: The left-hand semi-enzymatic subsequences. Return type is determined by the `return_type` parameter.
     :rtype: List[str] | List[ProFormaAnnotation] | List[Span] |List[(str, Span)] | List[(ProFormaAnnotation, Span)]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Generates all left-hand semi enzymatic sequences (Returned values does not include input sequence)
         >>> get_left_semi_enzymatic_sequences('PEPTIDE')
@@ -143,7 +143,7 @@ def get_right_semi_enzymatic_sequences(sequence: Union[str, ProFormaAnnotation],
     :return: The right-hand semi-enzymatic subsequences. Return type is determined by the `return_type` parameter.
     :rtype: List[str] | List[ProFormaAnnotation] | List[Span] |List[(str, Span)] | List[(ProFormaAnnotation, Span)]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Generates all right-hand semi enzymatic sequences (Returned values does not include input sequence)
         >>> get_right_semi_enzymatic_sequences('PEPTIDE')
@@ -198,7 +198,7 @@ def get_semi_enzymatic_sequences(sequence: Union[str, ProFormaAnnotation],
     :return: Semi-enzymatic subsequences. Return type is determined by the `return_type` parameter.
     :rtype: List[str] | List[ProFormaAnnotation] | List[Span] |List[(str, Span)] | List[(ProFormaAnnotation, Span)]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Equivalent to build_left_semi_sequences + build_right_semi_sequences
         >>> res = get_left_semi_enzymatic_sequences('PEPTIDE') + get_right_semi_enzymatic_sequences('PEPTIDE')
@@ -234,7 +234,7 @@ def get_non_enzymatic_sequences(sequence: Union[str, ProFormaAnnotation],
     :return: Non-enzymatic subsequences. Return type is determined by the `return_type` parameter.
     :rtype: List[str] | List[ProFormaAnnotation] | List[Span] |List[(str, Span)] | List[(ProFormaAnnotation, Span)]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Generates non-enzymatic sequences (Returned values does not include input sequence):
         >>> get_non_enzymatic_sequences('PEP')
@@ -279,7 +279,7 @@ def get_cleavage_sites(sequence: Union[str, ProFormaAnnotation], enzyme_regex: s
     :return: List of positions where cleavage occurs in the sequence.
     :rtype: List[int]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Can use a key in PROTEASES to specify the enzyme_regex:
         >>> get_cleavage_sites(sequence='TIDERTIDEKTIDE', enzyme_regex='trypsin/P')
@@ -358,7 +358,7 @@ def digest(sequence: Union[str, ProFormaAnnotation],
     :return: List of digested peptides. Return type is determined by the `return_type` parameter.
     :rtype: List[str] | List[ProFormaAnnotation] | List[Span] |List[(str, Span)] | List[(ProFormaAnnotation, Span)]
 
-    .. code-block:: python
+    . code-block:: python
 
         # Can use a key in PROTEASES to specify the enzyme_regex:
         >>> digest(sequence='TIDERTIDEKTIDE', enzyme_regex='trypsin/P', missed_cleavages=2)

src/peptacular/fragmentation.py

@@ -311,7 +311,7 @@ def fragment(sequence: Union[str, ProFormaAnnotation],
     :return: List of Fragment objects or a list of masses or m/z values.
     :rtype: List[Fragment] | List[float]
 
-    .. code-block:: python
+    . code-block:: python
 
         # By default a frahment objectis returned
         >>> len(fragment("[1.0]-P[2.0]E[3.0]-[4.0]", 'y', 1))

src/peptacular/glycan.py

@@ -18,7 +18,7 @@ def write_glycan_formula(glycan_dict: ChemComposition, sep: str = '') -> str:
     :return: A glycan formula string.
     :rtype: str
 
-    .. code-block:: python
+    . code-block:: python
 
             # Int Counts
             >>> write_glycan_formula({'HexNAc': 2, 'Hex': 3, 'Neu': 1})
@@ -56,7 +56,7 @@ def glycan_comp(glycan: Union[ChemComposition, str]) -> ChemComposition:
     :return: A dictionary containing the glycan components and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
             # Int Counts
             >>> glycan_comp({'HexNAc': 2, 'Hex': 3, 'Neu5Gc': 1})
@@ -98,7 +98,7 @@ def parse_glycan_formula(formula: str, sep: str = '') -> ChemComposition:
     :return: A dictionary containing the glycan components and their counts.
     :rtype: ChemComposition
 
-    .. code-block:: python
+    . code-block:: python
 
             # Int Counts
             >>> parse_glycan_formula('HexNAc2Hex3Neu1')
@@ -150,7 +150,7 @@ def convert_glycan_formula_to_chem_formula(glycan: Union[ChemComposition, str])
     :return: A chemical formula string.
     :rtype: str
 
-    .. code-block:: python
+    . code-block:: python
 
             # Int Counts
             >>> convert_glycan_formula_to_chem_formula({'HexNAc': 2, 'Hex': 3, 'Neu5Gc': 1})

src/peptacular/isotope.py

@@ -37,7 +37,7 @@ def isotopic_distribution(
     :return: The isotopic distribution.
     :rtype: List[Tuple[float, float]]
 
-    .. python::
+    . code-block:: python
 
         # Example usage
         >>> formula = {'C': 12, 'H': 6, 'N': 3}
@@ -156,7 +156,7 @@ def estimate_isotopic_distribution(neutral_mass: float,
     :return: A list of tuples with (mass, abundance) representing the predicted isotopic distribution.
     :rtype: List[Tuple[float, float]]
 
-    .. python::
+    . code-block:: python
 
         # Example usage
         >>> estimate_isotopic_distribution(800, 3, 0.0, 5)
@@ -210,7 +210,7 @@ def _convolve_distributions(dist1: Dict[float, float],
     :return: A convolved isotopic distribution as a mass-to-abundance mapping.
     :rtype: Dict[float, float]
 
-    .. python::
+    . code-block:: python
 
         # Example usage
         >>> d1 = {1.0: 0.5, 2.0: 0.5}
@@ -266,7 +266,7 @@ def _calculate_elemental_distribution(element: str,
     :return: The isotopic distribution.
     :rtype: Counter[float, float]
 
-    .. python::
+    . code-block:: python
 
         # Example usage
         >>> _calculate_elemental_distribution('C', 2, False)
@@ -294,9 +294,28 @@ def _calculate_elemental_distribution(element: str,
 
 def _fix_chemical_formula(chemical_formula: Dict[str, float]) -> Dict[str, int]:
     """
+    Fix a chemical formula, by rounding the atom counts to the nearest integer and adding hydrogen atoms to reach the
+    correct molecular mass.
+
+    :param chemical_formula: The chemical formula.
+    :type chemical_formula: Dict[str, float]
+    :return: The fixed chemical formula.
+    :rtype: Dict[str, int]
+
+    . code-block:: python
+
+        # Example usage
+        >>> _fix_chemical_formula({'C': 12.0, 'H': 6.0, 'N': 3.0})
+        {'C': 12, 'H': 6, 'N': 3}
+
+        # Example usage
+        >>> _fix_chemical_formula({'C': 12.1, 'H': 6.0, 'N': 3.0})
+        {'C': 12, 'H': 7, 'N': 3}
+
+        # Example usage
+        >>> _fix_chemical_formula({'C': 12.1, 'H': 6.0, 'N': 3.9})
+        {'C': 12, 'H': 6, 'N': 4}
 
-    :param chemical_formula:
-    :return:
     """
 
     starting_mass = chem_mass(chemical_formula)