[frontend] improve finding, docstrings

fishbook/frontend/frontend_classes.py

@@ -4,7 +4,7 @@ import nixio as nix
 import os
 import numpy as np
 from IPython import embed
-
+from fishbook.backend.util import progress
 
 class Cell:
     def __init__(self, cell_id=None, tuple=None):
@@ -294,6 +294,9 @@ class Dataset:
 
 
 class RePro:
+    """Repro class represents an entry in the repro table. This is a run of a certain relacs "Research Protocol".
+
+    """
     def __init__(self, repro_id=None, tuple=None):
         if tuple:
             self.__tuple = tuple
@@ -349,24 +352,34 @@ class RePro:
     def stimuli(self):
         stims = Stimuli & "repro_id = '%s'" % self.id & "cell_id = '%s'" % self.cell_id
         return [Stimulus(tuple=s) for s in stims]
-
+        
     @staticmethod
-    def find(name=None, cell_id=None, cell_type=None, species=None, settings=None, quality=None):
+    def find(name=None, cell_id=None, cell_type=None, species=None, settings=[], quality=None, test=False):
-        """
+        """ Finds Repro runs in the database. When called without arguments, all RePro runs are 
-        Cell type, quality, and species are ignored, if cell_id is provided
+            found and returned.
-        :param repro_name:
+            Search can be narrowed by providing further search hints.
-        :param cell_id:
+
-        :param cell_type:
+            **Note:** Cell type, quality, and species are ignored, if cell_id is provided
-        :param species:
+            **Note:** If there are many results fetching and creating objects may take a while. Consider running as test.
-        :param settings:
+        Args:
-        :param quality:
+            name (str, optional): The RePro name, or a part of it. Defaults to None.
-        :return:
+            cell_id (str, optional): The cell_id. If given type, quality and species are ignored. Defaults to None.
+            cell_type (str, optional): type of cell. Defaults to None.
+            species (str, optional): The species name, or parts of it. Defaults to None.
+            settings (list of string, optional): List of repro settings e.g. ["contrast: 20", "am: false"]. An AND connection is assumed. Defaults to None.
+            quality (str, optional): The quality assessment. Defaults to None.
+            test (bool, optional): defines whether or not the database matches should be fetched from the database. 
+        Returns:
+            list of fishbook.RePro: list of results or empty list if test == True
+            int: number of matches
         """
+        
         repros = Repros & True
         if name:
             repros = repros & "repro_name like '%{0:s}%'".format(name)
-        if settings:
+        if len(settings) > 0:
-            repros = repros & "settings like '%{0:s}%'".format(settings)
+            settings_pattern = " AND ".join(["settings like '%{0:s}%'".format(s) for s in settings]) 
+            repros = repros & settings_pattern
         if cell_id:
             repros = repros & "cell_id = '{0:s}'".format(cell_id)
         if not cell_id and (cell_type or species or quality):
@@ -379,7 +392,15 @@ class RePro:
                 cells = cells & "quality like '{0:s}'".format(quality)
             p = cells.proj("quality", "experimenter")
             repros = repros & p
-        return [RePro(tuple=r) for r in repros]
+        
+        results = []
+        total = len(repros)
+        if not test:
+            for i, r in enumerate(repros):
+                results.append(RePro(tuple=r))
+                progress(i+1, total, "fetching %i matches" % total)
+        
+        return results, total
 
     @property
     def _tuple(self):
@@ -456,27 +477,37 @@ class Stimulus:
         return self.__tuple.copy()
 
     @staticmethod
-    def find(cell_id=None, repro_id=None, settings=None):
+    def find(cell_id=None, repro_id=None, settings=[], test=False):
         """Find stimulus presentations that match in certain properties.
         Examples:
 
         Args:
             cell_id (str, optional): [description]. Defaults to None.
             repro_id (str, optional): [description]. Defaults to None.
-            settings (str, optional): [description]. Defaults to None.
+            settings (str, optional): [description]. Defaults to []].
-
+            test (bool, optional): whether or not this is a test run. When true, results will not be fetched from the database. Defaults to False.
         Returns:
-            List: of matching Stimulus presentations
+            List: of matching Stimulus presentations, empty if test==True
+            int: count of matches 
         """
         stimuli = Stimuli & True
         if cell_id:
             stimuli = stimuli & "cell_id = '{0:s}'".format(cell_id)
         if repro_id:
             stimuli = stimuli & "repro_id = '{0:s}'".format(repro_id)
-        if settings:
+        if len(settings) > 0:
-            stimuli = stimuli & "settings like '%{0:s}%'".format(settings)
+            settings_pattern = " AND ".join(["settings like '%{0:s}%'".format(s) for s in settings]) 
-        return [Stimulus(tuple=s) for s in stimuli]
+            stimuli = stimuli & settings_pattern
-
+        
+        results = []
+        total = len(stimuli)
+        if not test:
+            for i, s in enumerate(stimuli):
+                results.append(Stimulus(tuple=s))
+                progress(i+1, total, "fetching %i matches" % total)
+        
+        return results, total
+        
 
 class Subject:
     def __init__(self, subject_id=None, tuple=None):
@@ -516,7 +547,14 @@ class Subject:
         subjs = Subjects & True
         if species:
             subjs = (Subjects & "species like '%{0:s}%'".format(species))
-        return [Subject(tuple=s) for s in subjs]
+        
+        results = []        
+        total = len(subjs)
+        for i, s in enumerate(subjs):
+            results.append(Subject(tuple=s))
+            progress(i+1, total, "fetching %i matches" % total)
+        
+        return results, total
 
     @staticmethod
     def unique_species():