Added docs for source test #79

src/refinegems/growth.py

@@ -757,9 +757,35 @@ def test_auxotrophies(model:cobraModel, media_list:list[medium.Medium], suppleme
 # source test
 # -----------
 
-# @TODO : set a default for substances - ideally a subset or so
+# @TODO : set new default for substances - ideally a subset or so
 # @TODO : more namespace options, currently only BiGG available
-def test_growth_with_source(model:cobra.Model, element:str, substances:None|str|list[str], medium:None|str|rg.medium.Medium=None, namespace:Literal['BiGG']='BiGG') -> rg.reports.SourceTestReport:
+# @TODO
+def test_growth_with_source(model:cobra.Model, element:str, substances:None|str|list[str]=None, medium:None|str|rg.medium.Medium=None, namespace:Literal['BiGG']='BiGG') -> rg.reports.SourceTestReport:
+    """Test the growth of a model when switching out the source of a given chemical element for
+    a set medium.
+
+    Args:
+        model (cobra.Model): The model loaded with COBRApy.
+        element (str): The chemical symbol e.g., N for nitrogen, to change the sources for.
+        substances (None | str | list[str], optional): Substances to switch out in the medium. 
+            Can be a list of substance names present in the database, a subset name to be
+            loaded from the database or None, which results in all substances in the database,
+            that contain the element being tested as a source. Option None can potentially run
+            a while.
+            Defaults to None.
+        medium (None | str | rg.medium.Medium, optional): The medium to start with. 
+            The chosen medium ideally should have all other necessary elements needed for the model
+            to grow.
+            Defaults to None.
+        namespace (Literal['BiGG'], optional): The namespace to work on. 
+            Defaults to 'BiGG'.
+
+    Raises:
+        KeyError: No growth function in model. Please add one beforehand.
+
+    Returns:
+        rg.reports.SourceTestReport: A report object with the results.
+    """
 
     # validate input
     # model is required to have a growth function

src/refinegems/reports.py

@@ -668,6 +668,13 @@ def save(self, dir:str, color_palette:str='YlGn'):
 
 
 class SourceTestReport(Report):
+    """Report for the source test (:py:func:rg.growth.test_growth_with_source).
+
+    Attributes:
+        results: A pd.DataFrame with the results (substances and growth values).
+        element: The element the test was performed for.
+        model_name: The name of the model, that was tested.
+    """
 
     def __init__(self, results:pd.DataFrame=None, element:str=None, model_name:str=None):
         # super().__init__()
@@ -676,7 +683,19 @@ def __init__(self, results:pd.DataFrame=None, element:str=None, model_name:str=N
         self.model_name = model_name
 
     # @TEST
-    def visualise(self, width:int=12, color_palette:str='YlGn'):
+    def visualise(self, width:int=12, color_palette:str='YlGn') -> tuple(matplotlib.Figure, pd.DataFrame):
+        """Visuale the results of the source test as a heatmap
+
+        Args:
+            width (int, optional): number of columns to display for the heatmap. 
+                Number of row is calculated accordingly to fit all values.
+                Defaults to 12.
+            color_palette (str, optional): Color palette (gradient) for the plot. 
+                Defaults to 'YlGn'.
+
+        Returns:
+            tuple(matplotlib.Figure, pd.DataFrame): The heatmap and the legend explaining the heatmap.
+        """
 
         # create colour gradient
         try:
@@ -732,8 +751,16 @@ def visualise(self, width:int=12, color_palette:str='YlGn'):
         return (ax.get_figure(), legend)
 
 
-    # @TEST
     def save(self, dir:str, width:int=12, color_palette:str='YlGn') -> None:
+        """Save the results of the source test.
+
+        Args:
+            dir (str): Path to a directory to save the results to.
+            width (int, optional): Number of columns for the heatmap. 
+                Defaults to 12.
+            color_palette (str, optional):Color palette (gradient) for the plot. 
+                Defaults to 'YlGn'.
+        """
 
         # make sure given directory path ends with '/'
         if not dir.endswith('/'):