Merge pull request #475 from Jeremi-Maciejewski/semi-specific_digestion

Semi-specific digestion

Author: cbielow

docs/source/user_guide/digestion.rst

@@ -16,6 +16,35 @@ The usual enzyme of choice for bottom-up proteomics is ``Trypsin`` (sometimes in
 We will now learn how to do digestion of protein sequences in-silico, so you can predict which
 peptides you can expect to observe in the data and even generate theoretical spectra for them.
 
+Overview of the tool
+********************
+
+Proteolytic digestion can be performed through class ``ProteaseDigestion`` and its method ``.digest``.
+This method has two variants.
+Simple variant:
+
+.. code-block:: cython
+
+    digest(protein : pyopenms.AASequence, output : list) -> int
+    #   protein - Sequence of the protein to be digested. (pyopenms.AASequence)
+    #   output - Empty list. This is where produced peptides will be stored. Warning: if the list is not empty, all its contents will be deleted! (list)
+    #
+    #   -> returns number of peptides which did not meet length restrictions and were discarded. (int)
+
+The other variant allows you to specify minimum and maximum length of peptides produced:
+
+.. code-block:: cython
+
+    digest(protein : pyopenms.AASequence, output : list, min_length : int, max_length : int) -> int
+    #   protein - Sequence of the protein to be digested. (pyopenms.AASequence)
+    #   output - Empty list. This is where produced peptides will be stored. Warning: if the list is not empty, all its contents will be deleted! (list)
+    #   min_length - Minimum length of produced peptide. Shorter products will be discarded. (int)
+    #   max_length - Maximum length of produced peptide. Longer products will be discarded. (int)
+    #
+    #   -> returns number of peptides which did not meet length restrictions and were discarded. (int)
+
+.. @todo : Overview of RNaseDigestion.digest()
+
 Proteolytic Digestion with Trypsin
 **********************************
 
@@ -63,10 +92,35 @@ We now allow up to two missed cleavages.
     for s in result:
         print(s.toString())
 
+Semi-specific Digestion
+***********************
+
+Sometimes digestion is only specific to a cleavage site on one end of resulting peptide, while the other end is cut unspecifically.
+It is possible to generate a range of peptides that could be produced as a result of such semi-specific digestion:
+
+.. code-block:: python
+
+    # Check current specificity
+    dig.getSpecificity() # 2
+    # Set specificity parameter to semi-specific
+    # dig.setSpecificity(1) is also supported (1 specific end)
+    dig.setSpecificity(oms.EnzymaticDigestion.Specificity.SPEC_SEMI)
+
+    # Short sample sequence
+    seq = oms.AASequence.fromString("MCRTLH")
+
+    dig.digest(seq, result)
+    len(result) # 10
+    # Discard single-aa results
+    dig.digest(seq, result, 2, len(seq.toString()) )
+    for pep in result:
+        print(pep.toString())
+        # MCR, TLH, CR, TL, LH, MC
+
 Proteolytic Digestion with Lys-C
 ********************************
 
-In the previous example we used Trypsin as our enzyme of choice.
+In the previous examples we used Trypsin as our enzyme of choice.
 We can of course also use different enzymes, these are defined in the ``Enzymes.xml``
 file and can be accessed using the :py:class:`~.EnzymesDB` object