updates to documentation

Author: AlexPatrie

bio_compose/data_model.py

@@ -13,15 +13,19 @@ def to_dict(self):
         return asdict(self)
 
 
-class Api:
-    endpoint_root: str
-    data: Dict
-    submitted_jobs: List[Dict]
+class Api(object):
+    """
+    Base class inherited by the domain-specific polymorphisms native to this package: ``verifier.Verifier``, ``composer.Composer``, and ``runner.SimulationRunner``.
+
+    Params:
+        - **endpoint_root**: `str`: default base endpoint used by this packaging.
+        - **data**: `dict`: default historical collection of data fetched by the given instance of this class.
+        - **submitted_jobs**: `list[dict]`: default list of jobs submitted by the given instance.
+    """
 
     def __init__(self):
-        """Generic base instance which is inherited by any flavor (tag group) of the BioCompose REST API.
-            Each the methods of polymorphism of this base class should pertain entirely to the tag group 
-            domain with which it is associated (e.g., 'execute-simulations', 'verification', etc.) 
+        """
+        Generic base instance which is inherited by any flavor (tag group) of the BioCompose REST API. Polymorphism of this base class should pertain entirely to the tag group domain with which it is associated (e.g., 'execute-simulations', 'verification', etc.)
         """
         self.endpoint_root = "https://biochecknet.biosimulations.org"
         self._test_root()
@@ -60,16 +64,16 @@ def _test_root(self) -> Dict:
             return {'bio-check-error': f"A connection to that endpoint could not be established: {e}"}
 
     def get_output(self, job_id: str, download_dest: str = None, filename: str = None) -> Union[Dict[str, Union[str, Dict]], RequestError]:
-        """Fetch the current state of the job referenced with `job_id`. If the job has not yet been processed, it will return a `status` of `PENDING`. If the job is being processed by
-            the service at the time of return, `status` will read `IN_PROGRESS`. If the job is complete, the job state will be returned, optionally with included result data (either JSON or downloadable file data).
+        """
+        Fetch the current state of the job referenced with `job_id`. If the job has not yet been processed, it will return a `status` of `PENDING`. If the job is being processed by the service at the time of return, `status` will read `IN_PROGRESS`. If the job is complete, the job state will be returned, optionally with included result data (either JSON or downloadable file data).
 
-            Args:
-                job_id:`str`: The id of the job submission.
-                download_dest:`Optional[str]`: Optional directory where the file will be downloaded if the output is a file. Defaults to the current directory.
-                filename:`Optional[str]`: Optional filename to save the downloaded file as if the output is a file. If not provided, the filename will be extracted from the Content-Disposition header.
+        Args:
+            - **job_id**: `str`: The id of the job submission.
+            - **download_dest**: `Optional[str]`: Optional directory where the file will be downloaded if the output is a file. Defaults to the current directory.
+            - **filename**: `Optional[str]`: Optional filename to save the downloaded file as if the output is a file. If not provided, the filename will be extracted from the Content-Disposition header.
 
-            Returns:
-                If the output is a JSON response, return the parsed JSON as a dictionary. If the output is a file, download the file and return the filepath. If an error occurs, return a RequestError.
+        Returns:
+            If the output is a JSON response, return the parsed JSON as a dictionary. If the output is a file, download the file and return the filepath. If an error occurs, return a RequestError.
         """
         piece = f'get-output/{job_id}'
         endpoint = self._format_endpoint(piece)

bio_compose/runner.py

@@ -14,20 +14,22 @@ class SimulationRunner(Api):
     submitted_jobs: List[Dict]
 
     def __init__(self):
-        """A new instance of the Verifier class. NOTE: this may clash with your record keeping in a notebook, so it is highly recommended that users treat instances of this class as quasi-singletons, although not necessary for fundamental interaction.
+        """
+        A new instance of the Verifier class. NOTE: this may clash with your record keeping in a notebook, so it is highly recommended that users treat instances of this class as quasi-singletons, although not necessary for fundamental interaction.
         """
         super().__init__()
 
-    def run_smoldyn_simulation(self, smoldyn_configuration_filepath: str, duration: int = None, dt: float = None) -> Dict[str, Any]:
-        """Run a smoldyn simulation using a standard Smoldyn configuration file. Please see https://www.smoldyn.org/SmoldynManual.pdf for more information on running simulations with Smoldyn.
+    def run_smoldyn_simulation(self, smoldyn_configuration_filepath: str, duration: int = None, dt: float = None) -> Dict:
+        """
+        Run a smoldyn simulation using a standard Smoldyn configuration file. Please see https://www.smoldyn.org/SmoldynManual.pdf for more information on running simulations with Smoldyn.
 
         Args:
-        smoldyn_configuration_filepath:`str`: The path to the Smoldyn configuration file for the given model simulation.
-        duration:`int`: The duration of the simulation. If `None` is passed, duration inference will be attempted using `time_stop` parameter within the Smoldyn configuration. Defaults to `None`.
-        dt:`float`: The timestep to use within the Smoldyn simulation. If `None` is passed, dt inference will be attempted using the `.dt` parameter of the loaded Smoldyn simulation. Defaults to `None`.
+            - **smoldyn_configuration_filepath**: `str`: The path to the Smoldyn configuration file for the given model simulation.
+            - **duration**: `int`: The duration of the simulation. If `None` is passed, duration inference will be attempted using `time_stop` parameter within the Smoldyn configuration. Defaults to `None`.
+            - **dt**: `float`: The timestep to use within the Smoldyn simulation. If `None` is passed, dt inference will be attempted using the `.dt` parameter of the loaded Smoldyn simulation. Defaults to `None`.
 
         Returns:
-        The response for the Smoldyn simulation submission request.
+            The response for the Smoldyn simulation submission request.
 
         """
         endpoint = self._format_endpoint(f'run-smoldyn')
@@ -48,18 +50,19 @@ def run_smoldyn_simulation(self, smoldyn_configuration_filepath: str, duration:
 
         return self._execute_request(endpoint=endpoint, headers=headers, multidata=multidata, query_params=query_params)
 
-    def run_utc_simulation(self, sbml_filepath: str, start: int, end: int, steps: int, simulator: str) -> Dict[str, Any]:
-        """Run a uniform time course simulation of the model specified in `sbml_filepath` with a supported simulator.
+    def run_utc_simulation(self, sbml_filepath: str, start: int, end: int, steps: int, simulator: str) -> Dict:
+        """
+        Run a uniform time course simulation of the model specified in `sbml_filepath` with a supported simulator.
 
         Args:
-        sbml_filepath:`str`: The path to a valid SBML file.
-        start:`int`: The start time of the simulation.
-        end:`int`: The end time of the simulation.
-        steps:`int`: The number of steps to record within the ODE.
-        simulator:`str`: The simulator to use. Currently, simulator choices include: `'amici'`, `'copasi'`, or `'tellurium'`.
+            - **sbml_filepath**: `str`: The path to a valid SBML file.
+            - **start**: `int`: The start time of the simulation.
+            - **end**: `int`: The end time of the simulation.
+            - **steps**: `int`: The number of steps to record within the ODE.
+            - **simulator**: `str`: The simulator to use. Currently, simulator choices include: `'amici'`, `'copasi'`, or `'tellurium'`.
 
         Returns:
-        The response for the UTC simulation submission request.
+            The response for the UTC simulation submission request.
         """
         endpoint = self._format_endpoint(f'run-utc')
 
@@ -79,16 +82,17 @@ def run_utc_simulation(self, sbml_filepath: str, start: int, end: int, steps: in
 
         return self._execute_request(endpoint=endpoint, headers=headers, multidata=multidata, query_params=query_params)
 
-    def generate_simularium_file(self, smoldyn_output_filepath: str, box_size: float, filename: str = None) -> Dict[str, Any]:
-        """Run a Smoldyn simulation and generate a Simularium trajectory from the aforementioned simulation's outputs.
+    def generate_simularium_file(self, smoldyn_output_filepath: str, box_size: float, filename: str = None) -> Dict:
+        """
+        Run a Smoldyn simulation and generate a Simularium trajectory from the aforementioned simulation's outputs.
 
         Args:
-        smoldyn_output_filepath:`str`: The path to the Smoldyn output file for the given model simulation.
-        box_size:`float`: The box size to use for the Simularium trajectory.
-        filename:`str`: The name of the Simularium file that is generated. If `None` is passed, a general `'simulation.simularium'` filename will be used. Defaults to `None`.
+            - **smoldyn_output_filepath**: `str`: The path to the Smoldyn output file for the given model simulation.
+            - **box_size**: `float`: The box size to use for the Simularium trajectory.
+            - **filename**: `str`: The name of the Simularium file that is generated. If `None` is passed, a general `'simulation.simularium'` filename will be used. Defaults to `None`.
 
         Returns:
-        The response for the Simularium submission request.
+            The response for the Simularium submission request.
         """
         endpoint = self._format_endpoint(f'generate-simularium-file')