diff --git a/doc/api.rst b/doc/api.rst index 470318cd0..685637971 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -23,6 +23,7 @@ API reference pypesto.result pypesto.sample pypesto.select + pypesto.select.postprocessors pypesto.startpoint pypesto.store pypesto.visualize diff --git a/pypesto/select/model_problem.py b/pypesto/select/model_problem.py index c1775f0b9..3718ab515 100644 --- a/pypesto/select/model_problem.py +++ b/pypesto/select/model_problem.py @@ -32,7 +32,7 @@ class ModelProblem: calibrated. minimize_options: Keyword argument options that will be passed on to - `pypesto.optimize.minimize`. + :func:`pypesto.optimize.minimize`. minimize_result: A pyPESTO result with an optimize result. model: @@ -40,13 +40,13 @@ class ModelProblem: model_id: The ID of the PEtab Select model. objective_customizer: - A method that takes a `pypesto.objective.AmiciObjective` as + A method that takes a :class:`pypesto.objective.AmiciObjective` as input, and makes changes to the objective in-place. postprocessor: - A method that takes a `ModelSelectionProblem` as input. For + A method that takes a :class:`ModelSelectionProblem` as input. For example, this can be a function that generates a waterfall plot. This postprocessor is applied at the end of the - `ModelProblem.set_result` method. + :meth:`ModelProblem.set_result` method. pypesto_problem: The pyPESTO problem for the model. valid: @@ -75,9 +75,9 @@ def __init__( Parameters ---------- autorun: - If `False`, the model parameters will not be estimated. Allows - users to manually call pypesto.minimize with custom options, - then`set_result()`. + If ``False``, the model parameters will not be estimated. Allows + users to manually call ``pypesto.minimize`` with custom options, + then :meth:`set_result()`. TODO: constraints """ diff --git a/pypesto/select/postprocessors.py b/pypesto/select/postprocessors.py index 9896f62de..4e904344c 100644 --- a/pypesto/select/postprocessors.py +++ b/pypesto/select/postprocessors.py @@ -10,6 +10,14 @@ from ..C import TYPE_POSTPROCESSOR from .model_problem import ModelProblem +__all__ = [ + 'model_id_binary_postprocessor', + 'multi_postprocessor', + 'report_postprocessor', + 'save_postprocessor', + 'waterfall_plot_postprocessor', +] + def multi_postprocessor( problem: ModelProblem, @@ -17,7 +25,7 @@ def multi_postprocessor( ): """Combine multiple postprocessors into a single postprocessor. - See `save_postprocessor` for usage hints. + See :meth:`save_postprocessor` for usage hints. Parameters ---------- @@ -25,7 +33,7 @@ def multi_postprocessor( A model selection :class:`ModelProblem` that has been optimized. postprocessors: A list of postprocessors, which will be sequentially applied to the - optimized model `problem`. + optimized model ``problem``. The location where results will be stored. """ for postprocessor in postprocessors: @@ -38,7 +46,7 @@ def waterfall_plot_postprocessor( ): """Produce a waterfall plot. - See `save_postprocessor` for usage hints and argument documentation. + See :meth:`save_postprocessor` for usage hints and argument documentation. """ visualize.waterfall(problem.minimize_result) plot_output_path = Path(output_path) / (problem.model.model_hash + ".png") @@ -53,9 +61,11 @@ def save_postprocessor( """Save the parameter estimation result. When used, first set the output folder for results, e.g. with - `functools.partial`. This is because postprocessors should take only a + :func:`functools.partial`. This is because postprocessors should take only a single parameter: an optimized model. + .. code-block:: python + from functools import partial output_path = 'results' pp = partial(save_postprocessor, output_path=output_path) @@ -71,7 +81,7 @@ def save_postprocessor( output_path: The location where output will be stored. use_model_hash: - Whether the filename should use the model hash. Defaults to `False`, + Whether the filename should use the model hash. Defaults to ``False``, in which case the model ID is used instead. """ stem = problem.model.model_id @@ -86,14 +96,14 @@ def save_postprocessor( def model_id_binary_postprocessor(problem: ModelProblem): """Change a PEtab Select model ID to a binary string. - Changes the model ID in-place to be a string like `M_ijk`, where - `i`, `j`, `k`, etc. are `1` if the parameter in that position is estimated, - or `0` if the parameter is fixed. + Changes the model ID in-place to be a string like ``M_ijk``, where + ``i``, ``j``, ``k``, etc. are ``1`` if the parameter in that position is estimated, + or ``0`` if the parameter is fixed. - To ensure that other postprocessors (e.g. `report_postprocessor`) use this - new model ID, when in use with a `multi_postprocessor`, ensure this is - before the other postprocessors in the `postprocessors` argument of - `multi_postprocessor`. + To ensure that other postprocessors (e.g. :func:`report_postprocessor`) use this + new model ID, when in use with a :func:`multi_postprocessor`, ensure this is + before the other postprocessors in the ``postprocessors`` argument of + :func:`multi_postprocessor`. Parameters ---------- diff --git a/pypesto/select/problem.py b/pypesto/select/problem.py index 969ac1307..8314ac6d0 100644 --- a/pypesto/select/problem.py +++ b/pypesto/select/problem.py @@ -12,19 +12,19 @@ class Problem: """Handles use of a model selection algorithm. Handles model selection. Usage involves initialisation with a model - specifications file, and then calling the `select()` method to perform + specifications file, and then calling the :meth:`select` method to perform model selection with a specified algorithm and criterion. Attributes ---------- calibrated_models: Storage for all calibrated models. A dictionary, where keys are - model hashes, and values are `petab_select.Model` objects. + model hashes, and values are :class:`petab_select.Model` objects. newly_calibrated_models: Storage for models that were calibrated in the previous iteration of - model selection. Same type as `calibrated_models`. + model selection. Same type as ``calibrated_models``. method_caller: - A `MethodCaller`, used to run a single iteration of a model + A :class:`MethodCaller`, used to run a single iteration of a model selection method. model_postprocessor: A method that is applied to each model after calibration. @@ -53,7 +53,7 @@ def __init__( def create_method_caller(self, **kwargs) -> MethodCaller: """Create a method caller. - `args` and `kwargs` are passed to the `MethodCaller` constructor. + ``kwargs`` are passed to the :class:`MethodCaller` constructor. Returns ------- @@ -117,7 +117,7 @@ def select( The result is the selected model for the current run, independent of previous selected models. - `kwargs` are passed to the `MethodCaller` constructor. + ``kwargs`` are passed to the :class:`MethodCaller` constructor. Returns ------- @@ -162,10 +162,10 @@ def select_to_completion( ) -> List[Model]: """Run an algorithm until an exception `StopIteration` is raised. - `kwargs` are passed to the `MethodCaller` constructor. + ``kwargs`` are passed to the :class:`MethodCaller` constructor. - An exception `StopIteration` is raised by - `pypesto.select.method.MethodCaller.__call__` when no candidate models + An exception ``StopIteration`` is raised by + :meth:`pypesto.select.method.MethodCaller.__call__` when no candidate models are found. Returns @@ -218,7 +218,7 @@ def multistart_select( (but then the same model could be repeatedly calibrated, if the calibrations start before any have stopped). - `kwargs` are passed to the `MethodCaller` constructor. + ``kwargs`` are passed to the :class:`MethodCaller` constructor. Parameters ----------