diff --git a/spatialpy/core/model.py b/spatialpy/core/model.py index bed35dbd..a9b3db49 100644 --- a/spatialpy/core/model.py +++ b/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): diff --git a/spatialpy/core/parameter.py b/spatialpy/core/parameter.py index 95484a36..d918663a 100644 --- a/spatialpy/core/parameter.py +++ b/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: diff --git a/spatialpy/core/reaction.py b/spatialpy/core/reaction.py index f6e7c37b..01c407e3 100644 --- a/spatialpy/core/reaction.py +++ b/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 diff --git a/spatialpy/core/result.py b/spatialpy/core/result.py index b68c499c..78737a76 100644 --- a/spatialpy/core/result.py +++ b/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() diff --git a/spatialpy/core/vtkreader.py b/spatialpy/core/vtkreader.py index d7946406..fe6e363d 100644 --- a/spatialpy/core/vtkreader.py +++ b/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: diff --git a/spatialpy/solvers/build_expression.py b/spatialpy/solvers/build_expression.py index 96a0671b..505bc79b 100644 --- a/spatialpy/solvers/build_expression.py +++ b/spatialpy/solvers/build_expression.py @@ -74,12 +74,12 @@ def __init__(self, namespace=None, blacklist=None, sanitize=False): self.invalid_names = [] self.invalid_operators = [] - def check_blacklist(self, operator): + def _check_blacklist(self, operator): """ - TODO + Helper function to check literal expression operators against blacklisted operators - :param operator: TODO - :type operator: TODO + :param operator: operator to check + :type operator: ast.BinOp.Op | ast.UnaryOp.Op """ operator = type(operator) if operator in self.blacklist: @@ -129,7 +129,7 @@ def visit_BinOp(self, node): # pylint: disable=invalid-name :returns: The original node. :rtype: ast.BinOp """ - self.check_blacklist(node.op) + self._check_blacklist(node.op) self.generic_visit(node) return node @@ -143,7 +143,7 @@ def visit_UnaryOp(self, node): # pylint: disable=invalid-name :returns: The original node. :rtype: ast.UnaryOp """ - self.check_blacklist(node.op) + self._check_blacklist(node.op) self.generic_visit(node) return node @@ -157,7 +157,7 @@ def visit_BoolOp(self, node): # pylint: disable=invalid-name :returns: The original node. :rtype: ast.BinBoolOpOp """ - self.check_blacklist(node.op) + self._check_blacklist(node.op) self.generic_visit(node) return node @@ -172,7 +172,7 @@ def visit_Compare(self, node): # pylint: disable=invalid-name :rtype: ast.Compare """ for operator in node.ops: - self.check_blacklist(operator) + self._check_blacklist(operator) self.generic_visit(node) return node @@ -186,7 +186,7 @@ def visit_Assign(self, node: "ast.Assign"): # pylint: disable=invalid-name :returns: The original node. :rtype: ast.Assign """ - self.check_blacklist(ast.Assign()) + self._check_blacklist(ast.Assign()) self.generic_visit(node) return node @@ -220,9 +220,9 @@ def __get_expr(self, converter): @classmethod def map_operator(cls, operator): """ - TODO + Map operator strings with built expressions. - :param operator: TODO + :param operator: Operator to be mapped :type operator: str | list[str] """ if isinstance(operator, list): diff --git a/spatialpy/solvers/solver.py b/spatialpy/solvers/solver.py index 24571af8..f456652e 100644 --- a/spatialpy/solvers/solver.py +++ b/spatialpy/solvers/solver.py @@ -457,7 +457,7 @@ def compile(self, debug=False, profile=False): :param profile: If True, will print additional profiling information :type profile: bool - :raises SimulationError: TODO + :raises SimulationError: Failed to compile """ if self.model.timestep_size is None: self.model.timestep_size = 1e-5 @@ -551,14 +551,14 @@ def run(self, number_of_trajectories=1, seed=None, timeout=None, :param profile: Output gprof profiling data if available :type profile: bool - :param verbose: TODO + :param verbose: If true, prints addtional data to console :type verbose: bool - :returns: TODO + :returns: A SpatialPy Result object containing spatial and time series data from simulation. :rtype: spatialpy.Result.Result | list(spatialpy.Result.Result) - :raises SimulationTimeout: TODO - :raises SimulationError: TODO + :raises SimulationTimeout: Simulation exceeded timeout. + :raises SimulationError: Simulation execution failed. """ from spatialpy.core.result import Result # pylint: disable=import-outside-toplevel if number_of_trajectories > 1: