updates to docs

biosimulators · Sep 9, 2024 · cb3e168 · cb3e168
1 parent a78f9b3
commit cb3e168
Show file tree

Hide file tree

Showing 9 changed files with 121 additions and 59 deletions.
diff --git a/bio_compose/__init__.py b/bio_compose/__init__.py
@@ -1,6 +1,10 @@
 import os
 import time
 
+from bio_compose.processing_tools import get_job_signature
+from bio_compose.runner import SimulationRunner, SimulationResult
+from bio_compose.verifier import Verifier, VerificationResult
+
 
 current_dir = os.path.dirname(__file__)
 version_file_path = os.path.join(current_dir, '_VERSION')
@@ -10,20 +14,19 @@
     __version__ = f.read().strip()
 
 
-def run_simulation(*args, **kwargs):
+def run_simulation(*args, **kwargs) -> SimulationResult:
     """
     Run a simulation with BioCompose
 
     Args:
-        - args: Positional arguments
-            - 1 argument(**smoldyn simulation only**): smoldyn simulation configuration in which time parameters (dt, duration) are already defined.
-            - 3 arguments(**smoldyn simulation only**): smoldyn configuration file, smoldyn simulation duration, smoldyn simulation dt
-            - 5 arguments(**sbml simulation only**): sbml filepath, simulation start, simulation end, simulation steps, simulator
+        - **args**: Positional arguments:
+            1 argument(**smoldyn simulation only**): smoldyn simulation configuration in which time parameters (dt, duration) are already defined.
+            3 arguments(**smoldyn simulation only**): smoldyn configuration file, smoldyn simulation duration, smoldyn simulation dt
+            5 arguments(**sbml simulation only**): sbml filepath, simulation start, simulation end, simulation steps, simulator.
 
+    Returns:
+        `SimulationResult` instance of simulation results.
     """
-    from bio_compose.processing_tools import get_job_signature
-    from bio_compose.runner import SimulationRunner, SimulationResult
-
     # set up submission
     runner = SimulationRunner()
     in_file = args[0]
@@ -77,19 +80,16 @@ def verify(*args, **kwargs):
     Verify and compare the outputs of simulators for a given entrypoint file of either sbml or omex.
 
     Args:
-        - **args**: positional arguments passed to the verification.
-            - 1 argument(`str`): submit an sbml or omex verification with no time params.
-            - 2 arguments(`str`, `list[str]`): omex filepath, simulators to include in the verification.
-            - 4 arguments(`str`, `int`, `int`, `int`): sbml filepath, start, stop, steps.
-            - 5 arguments(`str`, `int`, `int`, `int`, `list[str]`): sbml filepath, start, stop, steps, simulators.
-        - **kwargs**: keyword arguments passed to the verification.
+        **args**: positional arguments passed to the verification.
+            1 argument(`str`): submit an sbml or omex verification with no time params.
+            2 arguments(`str`, `list[str]`): omex filepath, simulators to include in the verification.
+            4 arguments(`str`, `int`, `int`, `int`): sbml filepath, start, stop, steps.
+            5 arguments(`str`, `int`, `int`, `int`, `list[str]`): sbml filepath, start, stop, steps, simulators.
+        **kwargs**: keyword arguments passed to the verification.
 
     Returns:
         Verification result instance. See documentation for more details.
     """
-    from bio_compose.processing_tools import get_job_signature
-    from bio_compose.verifier import Verifier, VerificationResult
-
     verifier = Verifier()
     simulators = kwargs.get('simulators')
     run_sbml = False

diff --git a/bio_compose/runner.py b/bio_compose/runner.py
@@ -115,15 +115,19 @@ def generate_simularium_file(self, smoldyn_output_filepath: str, box_size: float
     def visualize_observables(self, job_id: str, hspace: float = 0.25, use_grid: bool = False, save_dest: str = None):
         """
         Visualize simulation output (observables) data.
+
         Args:
             - **job_id**: `str`: job id for the simulation observables output you wish to visualize.
             - **hspace**: `float`: horizontal spacing between subplots. Defaults to 0.25.
             - **use_grid**: `bool`: whether to use a grid for each subplot. Defaults to False.
             - **save_dest**: `str`: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.
+
          Returns:
             `Tuple[matplotlib.Figure, Dict]` of matplotlib Figure and simulation observables.
+
         Raises:
             `IOError`: If `job_id` does not contain a 'results' field.
+
         """
         import matplotlib.pyplot as plt 
         import seaborn as sns
@@ -152,4 +156,19 @@ def __init__(self, data: dict):
         self.runner = SimulationRunner()
 
     def visualize(self, **kwargs):
+        """
+        Visualize simulation output (observables) data.
+
+        Args:
+            **kwargs**: Visualization kwargs are as follows:
+                job_id: `str`: job id for the simulation observables output you wish to visualize.
+                hspace: `float`: horizontal spacing between subplots. Defaults to 0.25.
+                use_grid: `bool`: whether to use a grid for each subplot. Defaults to False.
+                save_dest: `str`: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.
+
+         Returns:
+            `Tuple[matplotlib.Figure, Dict]` of matplotlib Figure and simulation observables.
+        Raises:
+            `IOError`: If `job_id` does not contain a 'results' field.
+                """
         return self.runner.visualize_observables(job_id=self.job_id, **kwargs)
diff --git a/documentation/build/doctrees/bio_compose.doctree b/documentation/build/doctrees/bio_compose.doctree
diff --git a/documentation/build/doctrees/environment.pickle b/documentation/build/doctrees/environment.pickle
diff --git a/documentation/build/html/_modules/bio_compose.html b/documentation/build/html/_modules/bio_compose.html
@@ -75,6 +75,10 @@ <h1>Source code for bio_compose</h1><div class="highlight"><pre>
 <span></span><span class="kn">import</span> <span class="nn">os</span>
 <span class="kn">import</span> <span class="nn">time</span>
 
+<span class="kn">from</span> <span class="nn">bio_compose.processing_tools</span> <span class="kn">import</span> <span class="n">get_job_signature</span>
+<span class="kn">from</span> <span class="nn">bio_compose.runner</span> <span class="kn">import</span> <span class="n">SimulationRunner</span><span class="p">,</span> <span class="n">SimulationResult</span>
+<span class="kn">from</span> <span class="nn">bio_compose.verifier</span> <span class="kn">import</span> <span class="n">Verifier</span><span class="p">,</span> <span class="n">VerificationResult</span>
+
 
 <span class="n">current_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">)</span>
 <span class="n">version_file_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">current_dir</span><span class="p">,</span> <span class="s1">&#39;_VERSION&#39;</span><span class="p">)</span>
@@ -86,20 +90,19 @@ <h1>Source code for bio_compose</h1><div class="highlight"><pre>
 
 <div class="viewcode-block" id="run_simulation">
 <a class="viewcode-back" href="../bio_compose.html#bio_compose.run_simulation">[docs]</a>
-<span class="k">def</span> <span class="nf">run_simulation</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
+<span class="k">def</span> <span class="nf">run_simulation</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">SimulationResult</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Run a simulation with BioCompose</span>
 
 <span class="sd">    Args:</span>
-<span class="sd">        - args: Positional arguments</span>
-<span class="sd">            - 1 argument(**smoldyn simulation only**): smoldyn simulation configuration in which time parameters (dt, duration) are already defined.</span>
-<span class="sd">            - 3 arguments(**smoldyn simulation only**): smoldyn configuration file, smoldyn simulation duration, smoldyn simulation dt</span>
-<span class="sd">            - 5 arguments(**sbml simulation only**): sbml filepath, simulation start, simulation end, simulation steps, simulator</span>
+<span class="sd">        - **args**: Positional arguments:</span>
+<span class="sd">            1 argument(**smoldyn simulation only**): smoldyn simulation configuration in which time parameters (dt, duration) are already defined.</span>
+<span class="sd">            3 arguments(**smoldyn simulation only**): smoldyn configuration file, smoldyn simulation duration, smoldyn simulation dt</span>
+<span class="sd">            5 arguments(**sbml simulation only**): sbml filepath, simulation start, simulation end, simulation steps, simulator.</span>
 
+<span class="sd">    Returns:</span>
+<span class="sd">        `SimulationResult` instance of simulation results.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="kn">from</span> <span class="nn">bio_compose.processing_tools</span> <span class="kn">import</span> <span class="n">get_job_signature</span>
-    <span class="kn">from</span> <span class="nn">bio_compose.runner</span> <span class="kn">import</span> <span class="n">SimulationRunner</span><span class="p">,</span> <span class="n">SimulationResult</span>
-
     <span class="c1"># set up submission</span>
     <span class="n">runner</span> <span class="o">=</span> <span class="n">SimulationRunner</span><span class="p">()</span>
     <span class="n">in_file</span> <span class="o">=</span> <span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
@@ -156,19 +159,16 @@ <h1>Source code for bio_compose</h1><div class="highlight"><pre>
 <span class="sd">    Verify and compare the outputs of simulators for a given entrypoint file of either sbml or omex.</span>
 
 <span class="sd">    Args:</span>
-<span class="sd">        - **args**: positional arguments passed to the verification.</span>
-<span class="sd">            - 1 argument(`str`): submit an sbml or omex verification with no time params.</span>
-<span class="sd">            - 2 arguments(`str`, `list[str]`): omex filepath, simulators to include in the verification.</span>
-<span class="sd">            - 4 arguments(`str`, `int`, `int`, `int`): sbml filepath, start, stop, steps.</span>
-<span class="sd">            - 5 arguments(`str`, `int`, `int`, `int`, `list[str]`): sbml filepath, start, stop, steps, simulators.</span>
-<span class="sd">        - **kwargs**: keyword arguments passed to the verification.</span>
+<span class="sd">        **args**: positional arguments passed to the verification.</span>
+<span class="sd">            1 argument(`str`): submit an sbml or omex verification with no time params.</span>
+<span class="sd">            2 arguments(`str`, `list[str]`): omex filepath, simulators to include in the verification.</span>
+<span class="sd">            4 arguments(`str`, `int`, `int`, `int`): sbml filepath, start, stop, steps.</span>
+<span class="sd">            5 arguments(`str`, `int`, `int`, `int`, `list[str]`): sbml filepath, start, stop, steps, simulators.</span>
+<span class="sd">        **kwargs**: keyword arguments passed to the verification.</span>
 
 <span class="sd">    Returns:</span>
 <span class="sd">        Verification result instance. See documentation for more details.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="kn">from</span> <span class="nn">bio_compose.processing_tools</span> <span class="kn">import</span> <span class="n">get_job_signature</span>
-    <span class="kn">from</span> <span class="nn">bio_compose.verifier</span> <span class="kn">import</span> <span class="n">Verifier</span><span class="p">,</span> <span class="n">VerificationResult</span>
-
     <span class="n">verifier</span> <span class="o">=</span> <span class="n">Verifier</span><span class="p">()</span>
     <span class="n">simulators</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;simulators&#39;</span><span class="p">)</span>
     <span class="n">run_sbml</span> <span class="o">=</span> <span class="kc">False</span>

diff --git a/documentation/build/html/_modules/bio_compose/runner.html b/documentation/build/html/_modules/bio_compose/runner.html
@@ -203,15 +203,19 @@ <h1>Source code for bio_compose.runner</h1><div class="highlight"><pre>
     <span class="k">def</span> <span class="nf">visualize_observables</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">job_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">hspace</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.25</span><span class="p">,</span> <span class="n">use_grid</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">save_dest</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Visualize simulation output (observables) data.</span>
+
 <span class="sd">        Args:</span>
 <span class="sd">            - **job_id**: `str`: job id for the simulation observables output you wish to visualize.</span>
 <span class="sd">            - **hspace**: `float`: horizontal spacing between subplots. Defaults to 0.25.</span>
 <span class="sd">            - **use_grid**: `bool`: whether to use a grid for each subplot. Defaults to False.</span>
 <span class="sd">            - **save_dest**: `str`: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.</span>
+
 <span class="sd">         Returns:</span>
 <span class="sd">            `Tuple[matplotlib.Figure, Dict]` of matplotlib Figure and simulation observables.</span>
+
 <span class="sd">        Raises:</span>
 <span class="sd">            `IOError`: If `job_id` does not contain a &#39;results&#39; field.</span>
+
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="nn">plt</span> 
         <span class="kn">import</span> <span class="nn">seaborn</span> <span class="k">as</span> <span class="nn">sns</span>
@@ -246,6 +250,21 @@ <h1>Source code for bio_compose.runner</h1><div class="highlight"><pre>
 <div class="viewcode-block" id="SimulationResult.visualize">
 <a class="viewcode-back" href="../../bio_compose.html#bio_compose.runner.SimulationResult.visualize">[docs]</a>
     <span class="k">def</span> <span class="nf">visualize</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Visualize simulation output (observables) data.</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            **kwargs**: Visualization kwargs are as follows:</span>
+<span class="sd">                job_id: `str`: job id for the simulation observables output you wish to visualize.</span>
+<span class="sd">                hspace: `float`: horizontal spacing between subplots. Defaults to 0.25.</span>
+<span class="sd">                use_grid: `bool`: whether to use a grid for each subplot. Defaults to False.</span>
+<span class="sd">                save_dest: `str`: path to save the figure. If this value is passed, the figure will be saved in pdf format to this location.</span>
+
+<span class="sd">         Returns:</span>
+<span class="sd">            `Tuple[matplotlib.Figure, Dict]` of matplotlib Figure and simulation observables.</span>
+<span class="sd">        Raises:</span>
+<span class="sd">            `IOError`: If `job_id` does not contain a &#39;results&#39; field.</span>
+<span class="sd">                &quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">runner</span><span class="o">.</span><span class="n">visualize_observables</span><span class="p">(</span><span class="n">job_id</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">job_id</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></div>
 </div>