doc: Various fixes

* Replace references to private functions
* Fix some typos and formatting

Closes #3062.

Author: dweindl

python/sdist/amici/_symbolic/de_model.py

@@ -181,7 +181,7 @@ class DEModel:
         partial derivative in the next recursion. prevents infinite recursion
 
     :ivar _simplify:
-        If not None, this function will be used to simplify symbolic
+        If not ``None``, this function will be used to simplify symbolic
         derivative expressions. Receives sympy expressions as only argument.
         To apply multiple simplifications, wrap them in a lambda expression.
 
@@ -219,8 +219,7 @@ def __init__(
             see :meth:`DEModel._simplify`
 
         :param cache_simplify:
-            Whether to cache calls to the simplify method. Can e.g. decrease
-            import times for models with events.
+            Whether to cache calls to the simplify method.
         """
         self._differential_states: list[DifferentialState] = []
         self._algebraic_states: list[AlgebraicState] = []

python/sdist/amici/importers/antimony/__init__.py

@@ -6,7 +6,13 @@
 
 from pathlib import Path
 
-__all__ = ["antimony2sbml", "antimony2amici"]
+from ..utils import MeasurementChannel
+
+__all__ = [
+    "antimony2sbml",
+    "antimony2amici",
+    "MeasurementChannel",
+]
 
 
 def antimony2sbml(ant_model: str | Path) -> str:

python/sdist/amici/importers/bngl/__init__.py

@@ -8,8 +8,12 @@
 from pysb.importers.bngl import model_from_bngl
 
 from ..pysb import pysb2amici
+from ..utils import MeasurementChannel
 
-__all__ = ["bngl2amici"]
+__all__ = [
+    "bngl2amici",
+    "MeasurementChannel",
+]
 
 
 def bngl2amici(bngl_model: str, *args, **kwargs) -> None:

python/sdist/amici/importers/petab/_petab_importer.py

@@ -582,7 +582,7 @@ def import_module(self, force_import: bool = False) -> amici.ModelModule:
             self.outdir,
         )
 
-    def create_model(self) -> amici.Model:
+    def create_model(self) -> amici.sim.sundials.Model:
         """Create a :class:`amici.Model` instance from the imported model."""
         return self.import_module().get_model()
 

python/sdist/amici/importers/pysb/__init__.py

@@ -54,6 +54,7 @@
     "pysb_model_from_path",
     "pysb2amici",
     "pysb2jax",
+    "MeasurementChannel",
 ]
 
 CL_Prototype = dict[str, dict[str, Any]]
@@ -89,11 +90,12 @@ def pysb2jax(
         simulations.
 
     :param model:
-        pysb model, :attr:`pysb.core.Model.name` will determine the name of the
-        generated module
+        PySB model, :class:`model.name <pysb.core.Model>` will determine the
+        name of the generated module.
 
     :param output_dir:
-        see :meth:`amici.de_export.ODEExporter.set_paths`
+        The directory where the generated model code is stored.
+        Will be created if it does not exist.
 
     :param observation_model:
         The different measurement channels that make up the observation
@@ -113,13 +115,15 @@ def pysb2jax(
         if set to ``True``, conservation laws are automatically computed and
         applied such that the state-jacobian of the ODE right-hand-side has
         full rank. This option should be set to ``True`` when using the Newton
-        algorithm to compute steadystates
+        algorithm to compute steady states.
 
     :param simplify:
-        see :attr:`amici.DEModel._simplify`
+        If not ``None``, this function will be used to simplify symbolic
+        derivative expressions. Receives sympy expressions as only argument.
+        To apply multiple simplifications, wrap them in a lambda expression.
 
     :param cache_simplify:
-        see :func:`amici.DEModel.__init__`
+        Whether to cache calls to the simplify method.
         Note that there are possible issues with PySB models:
         https://github.com/AMICI-dev/AMICI/pull/1672
 
@@ -190,11 +194,12 @@ def pysb2amici(
         simulations.
 
     :param model:
-        pysb model, :attr:`pysb.core.Model.name` will determine the name of the
-        generated module
+        PySB model, :class:`model.name <pysb.core.Model>` will determine the
+        name of the generated module.
 
     :param output_dir:
-        see :meth:`amici.de_export.ODEExporter.set_paths`
+        The directory where the generated model code is stored.
+        Will be created if it does not exist.
 
     :param observation_model:
         The different measurement channels that make up the observation
@@ -234,12 +239,14 @@ def pysb2amici(
         just generate the source code.
 
     :param simplify:
-        see :attr:`amici.DEModel._simplify`
+        If not ``None``, this function will be used to simplify symbolic
+        derivative expressions. Receives sympy expressions as only argument.
+        To apply multiple simplifications, wrap them in a lambda expression.
 
     :param cache_simplify:
-            see :func:`amici.DEModel.__init__`
-            Note that there are possible issues with PySB models:
-            https://github.com/AMICI-dev/AMICI/pull/1672
+        Whether to cache calls to the simplify method.
+        Note that there are possible issues with PySB models:
+        https://github.com/AMICI-dev/AMICI/pull/1672
 
     :param generate_sensitivity_code:
         if set to ``False``, code for sensitivity computation will not be
@@ -341,12 +348,14 @@ def ode_model_from_pysb_importer(
         see :func:`amici.importers.pysb.pysb2amici`
 
     :param simplify:
-            see :attr:`amici.DEModel._simplify`
+        If not ``None``, this function will be used to simplify symbolic
+        derivative expressions. Receives sympy expressions as only argument.
+        To apply multiple simplifications, wrap them in a lambda expression.
 
     :param cache_simplify:
-            see :func:`amici.DEModel.__init__`
-            Note that there are possible issues with PySB models:
-            https://github.com/AMICI-dev/AMICI/pull/1672
+        Whether to cache calls to the simplify method.
+        Note that there are possible issues with PySB models:
+        https://github.com/AMICI-dev/AMICI/pull/1672
 
     :param verbose: verbosity level for logging, True/False default to
         :attr:`logging.DEBUG`/:attr:`logging.ERROR`
@@ -1599,7 +1608,8 @@ def _get_changed_stoichiometries(
 
 
 def pysb_model_from_path(pysb_model_file: str | Path) -> pysb.Model:
-    """Load a pysb model module and return the :class:`pysb.Model` instance
+    """
+    Load a PySB model module and return the :class:`pysb.core.Model` instance.
 
     :param pysb_model_file: Full or relative path to the PySB model module
     :return: The pysb Model instance

python/sdist/amici/importers/sbml/__init__.py

@@ -349,10 +349,14 @@ def sbml2amici(
             case of stoichiometric coefficients with many significant digits.
 
         :param simplify:
-            See :attr:`amici.DEModel._simplify`.
+            If not ``None``, this function will be used to simplify symbolic
+            derivative expressions. Receives sympy expressions as only argument.
+            To apply multiple simplifications, wrap them in a lambda expression.
 
         :param cache_simplify:
-            See :meth:`amici.DEModel.__init__`.
+            Whether to cache calls to the simplify method.
+            Note that there are possible issues with PySB models:
+            https://github.com/AMICI-dev/AMICI/pull/1672
 
         :param generate_sensitivity_code:
             If ``False``, the code required for sensitivity computation will
@@ -486,10 +490,14 @@ def sbml2jax(
             case of stoichiometric coefficients with many significant digits.
 
         :param simplify:
-            see :attr:`amici.DEModel._simplify`
+            If not ``None``, this function will be used to simplify symbolic
+            derivative expressions. Receives sympy expressions as only argument.
+            To apply multiple simplifications, wrap them in a lambda expression.
 
         :param cache_simplify:
-            see :meth:`amici.DEModel.__init__`
+            Whether to cache calls to the simplify method.
+            Note that there are possible issues with PySB models:
+            https://github.com/AMICI-dev/AMICI/pull/1672
 
         :param hybridization:
             dict representation of the hybridization information in the PEtab YAML file, see

python/sdist/amici/importers/utils.py

@@ -141,6 +141,87 @@ def __init__(
         """
         Initialize a measurement channel.
 
+
+
+        The noise distributions listed in the following are supported.
+        :math:`m` denotes the measurement, :math:`y` the simulation,
+        and :math:`\\sigma` a distribution scale parameter
+        (currently, AMICI only supports a single distribution parameter).
+
+        - `'normal'`, `'lin-normal'`: A normal distribution:
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma}\\
+             exp\\left(-\\frac{(m-y)^2}{2\\sigma^2}\\right)
+
+        - `'log-normal'`: A log-normal distribution (i.e. log(m) is
+          normally distributed):
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma m}\\
+             exp\\left(-\\frac{(\\log m - \\log y)^2}{2\\sigma^2}\\right)
+
+        - `'log10-normal'`: A log10-normal distribution (i.e. log10(m) is
+          normally distributed):
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma m \\log(10)}\\
+             exp\\left(-\\frac{(\\log_{10} m - \\log_{10} y)^2}{2\\sigma^2}\\right)
+
+        - `'laplace'`, `'lin-laplace'`: A laplace distribution:
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma}
+             \\exp\\left(-\\frac{|m-y|}{\\sigma}\\right)
+
+        - `'log-laplace'`: A log-Laplace distribution (i.e. log(m) is Laplace
+          distributed):
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma m}
+             \\exp\\left(-\\frac{|\\log m - \\log y|}{\\sigma}\\right)
+
+        - `'log10-laplace'`: A log10-Laplace distribution (i.e. log10(m) is
+          Laplace distributed):
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma m \\log(10)}
+             \\exp\\left(-\\frac{|\\log_{10} m - \\log_{10} y|}{\\sigma}\\right)
+
+        - `'binomial'`, `'lin-binomial'`: A (continuation of a discrete) binomial
+          distribution, parameterized via the success probability
+          :math:`p=\\sigma`:
+
+          .. math::
+             \\pi(m|y,\\sigma) = \\operatorname{Heaviside}(y-m) \\cdot
+                    \\frac{\\Gamma(y+1)}{\\Gamma(m+1) \\Gamma(y-m+1)}
+                    \\sigma^m (1-\\sigma)^{(y-m)}
+
+        - `'negative-binomial'`, `'lin-negative-binomial'`: A (continuation of a
+          discrete) negative binomial distribution, with `mean = y`,
+          parameterized via success probability `p`:
+
+          .. math::
+
+             \\pi(m|y,\\sigma) = \\frac{\\Gamma(m+r)}{\\Gamma(m+1) \\Gamma(r)}
+                (1-\\sigma)^m \\sigma^r
+
+          where
+
+          .. math::
+             r = \\frac{1-\\sigma}{\\sigma} y
+
+        The distributions above are for a single data point.
+        For a collection :math:`D=\\{m_i\\}_i` of data points and corresponding
+        simulations :math:`Y=\\{y_i\\}_i` and noise parameters
+        :math:`\\Sigma=\\{\\sigma_i\\}_i`, AMICI assumes independence,
+        i.e. the full distributions is
+
+        .. math::
+           \\pi(D|Y,\\Sigma) = \\prod_i\\pi(m_i|y_i,\\sigma_i)
+
+        AMICI uses the logarithm :math:`\\log(\\pi(m|y,\\sigma)`.
+
         .. note::
 
             When providing expressions for (event) observables and their sigmas
@@ -167,10 +248,14 @@ def __init__(
             and parameters.
         :param noise_distribution:
             Noise distribution associated with the observable.
-            This is usually a string identifier (e.g., 'normal', 'log-normal';
-            see
-            :func:`amici.importers.utils.noise_distribution_to_cost_function`).
-            If ``None``, a normal distribution is assumed.
+            This is usually a string identifier:
+
+            {`'normal'`, `'lin-normal'`, `'log-normal'`, `'log10-normal'`,
+            `'laplace'`, `'lin-laplace'`, `'log-laplace'`, `'log10-laplace'`,
+            `'binomial'`, `'lin-binomial'`, `'negative-binomial'`,
+            `'lin-negative-binomial'`}
+
+            For the meaning of the values see above.
 
             Alternatively, a callable can be passed to account for a
             custom noise model. The callable must take a single argument

tox.ini

@@ -20,4 +20,4 @@ allowlist_externals =
     rm
 commands =
     rm -rf amici_models/ _doxyoutput_amici_cpp/ _exhale_cpp_api/ _exhale_matlab_api/ generated/ _build/
-    sphinx-build -T -E -W --keep-going -b html -d _build/doctrees-readthedocs -D language=en . _build/html
+    sphinx-build -T -E -W --keep-going -n -b html -d _build/doctrees-readthedocs -D language=en . _build/html