updated docstrings

spatialpy/core/model.py

@@ -41,8 +41,8 @@ def export_StochSS(spatialpy_model, filename=None, return_stochss_model=False):
     :param return_stochss_model: Whether or not to return the model
     :type return_stochss_model: bool
 
-    :returns: TODO
-    :rtype: TODO
+    :returns: Filename for JSON-formatted .smdl file for use with StochSS platform.
+    :rtype: string
     """
     try:
         from spatialpy.stochss.stochss_export import export # pylint: disable=import-outside-toplevel
@@ -298,7 +298,7 @@ def add_species(self, obj):
         :param obj: The species or list of species to be added to the model object.
         :type obj: spatialpy.Model.Species | list(spatialpy.Model.Species
 
-        :returns: TODO
+        :returns: Species object which was added to the model.
         :rtype: spatialpy.Species | list(spatialpy.Species)
 
         :raises ModelError: If obj is not a spatialpy.Species
@@ -334,16 +334,16 @@ def get_all_species(self):
         """
         Returns a dictionary of all species in the model using names as keys.
 
-        :returns: TODO
+        :returns: A dictionary of all species in the form of {"species_name":Species_object}
         :rtype: dict
         """
         return self.listOfSpecies
 
     def get_num_species(self):
         """
-        Returns total number of species contained in the model.
+        Returns total number of different species contained in the model.
 
-        :returns: TODO
+        :returns: Number of different species in the model.
         :rtype: int
         """
         return len(self.listOfSpecies)
@@ -355,7 +355,7 @@ def get_species(self, sname):
         :param sname: name of species to be returned.
         :type sname: str
 
-        :returns: TODO
+        :returns: The Species objected represented by given 'sname'
         :rtype: spatialpy.Model.Species
 
         :raises ModelError: if the model does not contain the requested species
@@ -371,7 +371,7 @@ def sanitized_species_names(self):
         later on by SpatialPySolvers evaluating reaction propensity functions.
 
         :returns: the dictionary mapping user species names to their internal SpatialPy notation.
-        :rtype: TODO
+        :rtype: dict
         """
         species_name_mapping = OrderedDict([])
         for i, name in enumerate(self.listOfSpecies.keys()):
@@ -386,7 +386,7 @@ def add_parameter(self,params):
         :param params: Parameter object or list of Parameters to be added.
         :type params: spatialpy.Model.Parameter | list(spatialpy.Model.Parameter)
 
-        :returns: TODO
+        :returns: Parameter object which has been added to the model.
         :rtype: spatialpy.Parameter | list(spatialpy.Parameter)
 
         :raises ModelError: if obj is not a spatialpy.Parameter
@@ -424,22 +424,22 @@ def get_all_parameters(self):
         """
         Return a dictionary of all model parameters, indexed by name.
 
-        :returns: TODO
+        :returns: A dictionary of all model parameters in the form {'param_name':param_obj}
         :rtype: dict
         """
         return self.listOfParameters
 
     def get_parameter(self, pname):
         """
-        Remove a Parameter from model.listOfParameters.
+        Return the Parameter object from model associated with 'pname'
 
         :param pname: Name of parameter to be removed
         :type pname: spatialpy.Model.Parameter
 
-        :returns: TODO
-        :rtype: TODO
+        :returns: The Parameter object represented in the model by 'pname'
+        :rtype: Spatialpy.Model.Parameter
 
-        :raises ModelError: TODO
+        :raises ModelError: No parameter named {pname}
         """
         try:
             return self.listOfParameters[pname]
@@ -452,7 +452,7 @@ def sanitized_parameter_names(self):
         later on by SpatialPySolvers evaluating reaction propensity functions.
 
         :returns: the dictionary mapping user parameter names to their internal SpatialPy notation.
-        :rtype: TODO
+        :rtype: dict
         """
         parameter_name_mapping = OrderedDict()
         for i, name in enumerate(self.listOfParameters.keys()):
@@ -468,10 +468,10 @@ def add_reaction(self, reacs):
         :param reacs: Reaction or list of Reactions to be added.
         :type reacs: spatialpy.Model.Reaction | list(spatialpy.Model.Reaction)
 
-        :returns: TODO
-        :rtype: TODO
+        :returns: The Reaction object(s) added to the model
+        :rtype: spatialpy.Model.Reaction
 
-        :raises ModelError: TODO
+        :raises ModelError: Invalid input/reaction to add_reaction()
         """
         from spatialpy.core.reaction import Reaction # pylint: disable=import-outside-toplevel
         if isinstance(reacs, list):
@@ -504,7 +504,7 @@ def get_all_reactions(self):
         """
         Returns a dictionary of all model reactions using names as keys.
 
-        :returns: TODO
+        :returns: A dictionary of reactions in the form of {'react_name':react_obj}
         :rtype: dict
         """
         return self.listOfReactions
@@ -513,7 +513,7 @@ def get_num_reactions(self):
         """
         Returns the number of reactions in this model.
 
-        :returns: TODO
+        :returns: The total number of different reactions in the model.
         :rtype: int
         """
         return len(self.listOfReactions)
@@ -525,10 +525,10 @@ def get_reaction(self, rname):
         :param rname: name of Reaction to retrieve
         :type rname: str
 
-        :returns: TODO
+        :returns: The Reaction Object in the model represented by 'rname'
         :rtype: spatialpy.Model.Reaction
 
-        :raises ModelError: TODO
+        :raises ModelError: Could not find reaction
         """
         try:
             return self.listOfReactions[rname]
@@ -546,7 +546,8 @@ def run(self, number_of_trajectories=1, seed=None, timeout=None,
         :param seed: The random seed given to the solver.
         :type seed: int
 
-        :param timeout: TODO
+        :param timeout: Number of seconds for simulation to run.  Simulation will be
+                        killed upon reaching timeout.
         :type timeout: int
 
         :param number_of_threads: The number threads the solver will use.
@@ -555,13 +556,13 @@ def run(self, number_of_trajectories=1, seed=None, timeout=None,
         :param debug_level: Level of output from the solver: 0, 1, or 2. Default: 0.
         :type debug_level: int
 
-        :param debug: TODO
+        :param debug: Optional flag to print out additional debug info during simulation.
         :type debug: bool
 
-        :param profile: TODO
+        :param profile: Optional flag to print out addtional performance profiling for simulation.
         :type profile: bool
 
-        :returns: TODO
+        :returns: A SpatialPy Result object containing simulation data.
         :rtype: spatialpy.Result.Result
         """
         from spatialpy.solvers.solver import Solver # pylint: disable=import-outside-toplevel
@@ -589,7 +590,7 @@ def set_timesteps(self, output_interval, num_steps, timestep_size=None):
         :param timestep_size: Size of each timestep in seconds
         :type timestep_size: float
 
-        :raises ModelError: TODO
+        :raises ModelError: Incompatible combination of timestep_size and output_interval
         """
         if timestep_size is not None:
             self.timestep_size = timestep_size
@@ -620,7 +621,7 @@ def timespan(self, time_span, timestep_size=None):
         :param timestep_size: Size of each timestep in seconds
         :type timestep_size: float
 
-        :raises ModelError: TODO
+        :raises ModelError: non-uniform timespan not supported
         """
         items_diff = numpy.diff(time_span)
         items = map(lambda x: round(x, 10), items_diff)
@@ -638,7 +639,7 @@ def add_domain(self, domain):
         :param domain: The Domain object to be added to the model
         :type domain: spatialpy.Domain.Domain
 
-        :raises ModelError: TODO
+        :raises ModelError: Invalid Domain object
         """
         from spatialpy.core.domain import Domain # pylint: disable=import-outside-toplevel
         if not isinstance(domain,Domain) and type(domain).__name__ != 'Domain':
@@ -656,10 +657,10 @@ def add_data_function(self, data_function):
         :param data_function: Data function to be added.
         :type data_function: spatialpy.DataFunction
 
-        :returns: TODO
-        :rtype: spatialpy.DataFunctin | list(spatialpy.DataFunction)
+        :returns: DataFunction object(s) added tothe model.
+        :rtype: spatialpy.DataFunction | list(spatialpy.DataFunction)
 
-        :raises ModelError: TODO
+        :raises ModelError: Invalid DataFunction
         """
         from spatialpy.core.datafunction import DataFunction # pylint: disable=import-outside-toplevel
         if isinstance(data_function, list):

spatialpy/core/parameter.py

@@ -59,7 +59,7 @@ def _evaluate(self, namespace=None):
         """
         Evaluate the expression and return the (scalar) value.
 
-        :param namespace: TODO
+        :param namespace: A dictionary containing key,value pairings of expressions and evaluable executions.
         :type namespace: dict
         """
         if namespace is None:

spatialpy/core/reaction.py

@@ -47,7 +47,7 @@ class Reaction():
     :param annotation: Description of the reaction (meta)
     :type annotation: str
 
-    :param restrict_to: TODO
+    :param restrict_to: Restrict reaction execution to a type or list of types within the domain.
     :type restrict_to: int or list of ints
     """
     def __init__(self, name="", reactants=None, products=None, propensity_function=None,
@@ -215,9 +215,9 @@ def annotate(self, annotation):
 
     def initialize(self, model):
         """
-        Defered object initialization, called by model.add_reaction().
+        Deferred object initialization, called by model.add_reaction().
 
-        :param model: TODO
+        :param model: Target SpatialPy Model for annotation.
         :type model: spatialpy.Model
         """
         self.ode_propensity_function = self.propensity_function

spatialpy/core/result.py

@@ -253,10 +253,10 @@ def read_step(self, step_num, debug=False):
         :param debug: Whether or not debug information should be printed
         :type debug: bool (default False)
 
-        :returns: TODO
-        :rtype: tuble
+        :returns: A tuple containing ([points], [arrays]) from an output step of the simulation.
+        :rtype: tuple
 
-        :raises ResultError: TODO
+        :raises ResultError: Could not get result data for given step_num.
         """
         if debug:
             print(f"read_step({step_num}) ", end='')
@@ -299,7 +299,7 @@ def get_timespan(self):
         """
         Get the model time span. Returns a numpy array containing the time span of the model.
 
-        :returns: TODO
+        :returns: A numpy array of the timespan containing all output time points.
         :rtype: numpy.ndarray
         """
 
@@ -332,10 +332,11 @@ def get_species(self, species, timepoints=None, concentration=False, determinist
         :param debug: Whether or not debug information should be printed
         :type debug: bool (default False)
 
-        :returns: TODO
+        :returns: A numpy array containing population/concentration values for target species across specified
+                    timepoints.  Defaults to all timepoints.
         :rtype: numpy.ndarray
 
-        :raises ResultError: TODO
+        :raises ResultError: Unable to retrieve species data for given timepoints.
         """
         num_voxel = self.model.domain.get_num_voxels()
 
@@ -446,10 +447,10 @@ def plot_species(self, species, t_ndx=None, t_val=None, concentration=False,
         :param debug: output debugging info
         :type debug: bool
 
-        :returns: TODO
+        :returns: A dictionary containing data for a plotly figure of species output trajectory
         :rtype: dict
 
-        :raises ResultsError:
+        :raises ResultsError: unable to plot species for given time
         """
         time_index_list = self.get_timespan()
 
@@ -583,10 +584,10 @@ def get_property(self, property_name, timepoints=None):
         :param timepoints: timespan index to be returned.  Default is None
         :type timepoints: int
 
-        :returns: TODO
+        :returns: a numpy array of target property values across timepoints, defaults to all timepoints.
         :rtype: numpy.ndarray
 
-        :raises ResultsError: TODO
+        :raises ResultsError: Could not get data for given timepoints.
         """
 
         l_time = len(self.get_timespan()) - 1
@@ -677,10 +678,11 @@ def plot_property(self, property_name, t_ndx=None, t_val=None, p_ndx=0, width=No
         :param debug: output debugging info
         :type debug: bool
 
-        :returns: TODO
+        :returns: A dictionary representation of a plotly figure containing property data over given timepoints.
+                    Defaults to all timepoints.
         :rtype: dict
 
-        :raises ResultError: TODO
+        :raises ResultError: Could not get property data for given timepoints.
         """
         time_index_list = self.get_timespan()
 

spatialpy/core/vtkreader.py

@@ -84,10 +84,10 @@ class VTKReader:
     VTKReader.py: SpatialPy minimal VTK legacy file reader.
     Reference: https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf
 
-    :param filename: TODO
+    :param filename: name of SpatialPy VTK file
     :type filename: str
 
-    :param debug: TODO
+    :param debug: If true, will print debugging information.
     :type debug: bool
     """
     def __init__(self, filename=None, debug=False):
@@ -127,7 +127,7 @@ def get_array_name(self, index):
         :param index: index
         :type index: int
 
-        :returns: TODO
+        :returns: Name/Key for arraid id
         :rtype: int | None
         """
         arrayids = list(self.arrays.keys())
@@ -140,7 +140,7 @@ def get_arrays(self):
         """
         Get the dictionary of arrays.
 
-        :returns: TODO
+        :returns: dictionary of data arrays
         :rtype: dict
         """
         return self.arrays
@@ -167,7 +167,7 @@ def read_file(self):
         """
         Read VTK file.
 
-        :raises VTKReaderIOError: TODO
+        :raises VTKReaderIOError: Invalid ASCII VTK file
         """
         with open(self.filename, encoding="utf-8") as data_file:
             if self.debug: