Add doctests

Author: tornikeo

pyproject.toml

@@ -77,6 +77,7 @@ addopts = "--profile=black"
 pythonpath = [
     "."
 ]
+addopts = "--doctest-modules"
 testpaths = [
     "tests",
     "integration-tests",

simms/__init__.py

@@ -1,7 +1,5 @@
 import os
-import warnings
 from contextlib import contextmanager
-from matchms.filtering.SpectrumProcessor import SpectrumProcessor
 from .__version__ import __version__
 
 

simms/similarity/CudaCosineGreedy.py

@@ -21,12 +21,14 @@ class CudaCosineGreedy(BaseSimilarity):
 
     This implementation is meant to replicate outputs of `matchms.similarity.CosineGreedy`.
 
+    For example:
+
     >>> import numpy as np
     >>> from matchms import Spectrum
     >>> from simms.similarity import CudaCosineGreedy
     >>> reference = Spectrum(mz=np.array([100, 150, 200.]), intensities=np.array([0.7, 0.2, 0.1]))
     >>> query = Spectrum(mz=np.array([100, 140, 190.]), intensities=np.array([0.4, 0.2, 0.1]))
-    >>> cosine_greedy = CudaCosineGreedy(tolerance=0.2) # Use factory to construct a similarity function
+    >>> cosine_greedy = CudaCosineGreedy(tolerance=0.2)
     >>> score = cosine_greedy.pair(reference, query)
     >>> print(f"Cosine score is {score['score']:.2f} with {score['matches']} matched peaks")
     Cosine score is 0.83 with 1 matched peaks
@@ -179,7 +181,7 @@ def _get_batches(self, references, queries):
 
     def pair(self, reference: Spectrum, query: Spectrum) -> float:
         """
-        Do not use - it is very inefficient, and used for testing purposes only.
+        Do not use, unless testing. GPUs work best with a lot of data at the same time.
         Calculates the cosine similarity score between a reference and a query spectrum.
 
         Parameters:

simms/similarity/CudaModifiedCosine.py

@@ -50,6 +50,21 @@ class CudaModifiedCosine(BaseSimilarity):
     for further details.
 
     This implementation is meant to replicate outputs of `matchms.similarity.ModifiedCosine`.
+
+    For example:
+    >>> import numpy as np
+    >>> from matchms import Spectrum
+    >>> from simms.similarity import CudaModifiedCosine
+    >>> spectrum_1 = Spectrum(mz=np.array([100, 150, 200.]),
+    ...                         intensities=np.array([0.7, 0.2, 0.1]),
+    ...                         metadata={"precursor_mz": 100.0})
+    >>> spectrum_2 = Spectrum(mz=np.array([104.9, 140, 190.]),
+    ...                         intensities=np.array([0.4, 0.2, 0.1]),
+    ...                         metadata={"precursor_mz": 105.0})
+    >>> modified_cosine = CudaModifiedCosine(tolerance=0.2)
+    >>> score = modified_cosine.pair(spectrum_1, spectrum_2)
+    >>> print(f"Modified cosine score is {score['score']:.2f} with {score['matches']} matched peaks")
+    Modified cosine score is 0.83 with 1 matched peaks
     """
 
     score_datatype = [

simms/similarity/spectrum_similarity_functions.py

@@ -89,6 +89,33 @@ def cosine_kernel(
     --------
     callable
         CUDA kernel function for calculating cosine similarity scores.
+
+    For example:
+
+    >>> from simms.similarity.spectrum_similarity_functions import cosine_kernel
+    >>> from numba import cuda
+    >>> import numpy as np
+    >>> batch_size, n_max_peaks = 2, 4
+    >>> kernel = cosine_kernel(tolerance=0.1, n_max_peaks=n_max_peaks, batch_size=batch_size)
+    >>> rspec = cuda.to_device(np.array([
+    ...    [ [1., 10., 100., 200.,],  # mz values
+    ...      [2., 20., 200., 400.,], ],
+    ...    [ [1.,  1.,   1.,   1.,], # Intensities
+    ...      [1.,  1.,   1.,   1.,], ]
+    ... ], dtype=np.float32))
+    >>> qspec = rspec # symmetric
+    >>> metadata = cuda.to_device(np.array([
+    ...   [ 4., 4., ], # lengths of reference spectra
+    ...   [ 4., 4., ], # lengths of query spectra
+    ...   [ 2., 2., ], # norms of reference spectra
+    ...   [ 2., 2., ], # norms of query spectra
+    ... ], dtype=np.float32))
+    >>> out = cuda.to_device(np.zeros((3, batch_size, batch_size), dtype=np.float32))
+    >>> kernel(rspec, qspec, metadata, out)
+    >>> scores, matches, overflows = out.copy_to_host()
+    >>> print(scores)
+    [[1.   0.25]
+     [0.25 1.  ]]
     """
 
     if is_symmetric:

simms/utils.py

@@ -122,7 +122,7 @@ def download(
     Downloads a set of sample spectra files from https://github.com/PangeAI/simms/releases/tag/samples-0.1
     Downloaded files are cached, and not re-downloaded after the initial call.
     """
-    import pooch
+    import pooch  # Import here, since we want fewer runtime dependencies - this is for development only
 
     potential_local_file = Path(f"data/{name}")
     if potential_local_file.exists():