Doc: fix formatting / missing type annotations (#292)

dweindl · dilpath · web-flow · commit 4360836e5125 · 2024-06-29T20:17:11.000+02:00
Document, fix formatting, fix missing type annotations

---------

Co-authored-by: Dilan Pathirana &lt;59329744+dilpath@users.noreply.github.com&gt;
diff --git a/doc/modules.rst b/doc/modules.rst
@@ -1,14 +1,13 @@
 API Reference
 =============
 
-.. automodule:: petab
-
 .. rubric:: Modules
 
 .. autosummary::
    :toctree: build/_autosummary
    :recursive:
 
+   petab
    petab.v1
    petab.v1.C
    petab.v1.calculate
diff --git a/petab/C.py b/petab/C.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.C instead."""
 from petab import _deprecated_import_v1
 from petab.v1.C import *  # noqa: F403, F401, E402
 
diff --git a/petab/__init__.py b/petab/__init__.py
@@ -2,6 +2,11 @@
 PEtab global
 ============
 
+.. warning::
+
+    All functions in here are deprecated. Use the respective functions from
+    :mod:`petab.v1` instead.
+
 Attributes:
     ENV_NUM_THREADS:
         Name of environment variable to set number of threads or processes
diff --git a/petab/calculate.py b/petab/calculate.py
@@ -1,3 +1,6 @@
+"""Deprecated module for calculating residuals and log-likelihoods.
+
+Use petab.v1.calculate instead."""
 from petab import _deprecated_import_v1
 from petab.v1.calculate import *  # noqa: F403, F401, E402
 
diff --git a/petab/composite_problem.py b/petab/composite_problem.py
@@ -1,3 +1,6 @@
+"""Deprecated module for composite problems.
+
+Use petab.v1.composite_problem instead."""
 from petab import _deprecated_import_v1
 from petab.v1.composite_problem import *  # noqa: F403, F401, E402
 
diff --git a/petab/conditions.py b/petab/conditions.py
@@ -1,3 +1,7 @@
+"""Deprecated module for condition tables.
+
+Use petab.v1.conditions instead.
+"""
 from petab import _deprecated_import_v1
 from petab.v1.conditions import *  # noqa: F403, F401, E402
 
diff --git a/petab/core.py b/petab/core.py
@@ -1,3 +1,6 @@
+"""Deprecated module for PEtab core classes and functions.
+
+Use petab.v1.core instead."""
 from petab import _deprecated_import_v1
 from petab.v1.core import *  # noqa: F403, F401, E402
 
diff --git a/petab/lint.py b/petab/lint.py
@@ -1,3 +1,8 @@
+"""Deprecated module for linting PEtab files.
+
+Use petab.v1.lint instead.
+"""
+
 from petab import _deprecated_import_v1
 from petab.v1.lint import *  # noqa: F403, F401, E402
 
diff --git a/petab/mapping.py b/petab/mapping.py
@@ -1,3 +1,6 @@
+"""Deprecated module for mapping tables.
+
+Use petab.v1.mapping instead."""
 from petab import _deprecated_import_v1
 from petab.v1.mapping import *  # noqa: F403, F401, E402
 
diff --git a/petab/math/__init__.py b/petab/math/__init__.py
@@ -1,3 +1,6 @@
+"""Deprecated module for math handling.
+
+Use petab.v1.math instead."""
 from petab import _deprecated_import_v1
 from petab.v1.math import *  # noqa: F403, F401, E402
 
diff --git a/petab/math/sympify.py b/petab/math/sympify.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.math.sympify instead."""
 from petab import _deprecated_import_v1
 from petab.v1.math.sympify import *  # noqa: F403, F401, E402
 
diff --git a/petab/measurements.py b/petab/measurements.py
@@ -1,3 +1,6 @@
+"""Deprecated module for measurement tables.
+
+Use petab.v1.measurements instead."""
 from petab import _deprecated_import_v1
 from petab.v1.measurements import *  # noqa: F403, F401, E402
 
diff --git a/petab/models/__init__.py b/petab/models/__init__.py
@@ -1,3 +1,6 @@
+"""Deprecated module for PEtab models.
+
+Use petab.v1.models instead"""
 from petab import _deprecated_import_v1
 from petab.v1.models import *  # noqa: F403, F401, E402
 
diff --git a/petab/models/model.py b/petab/models/model.py
@@ -1,3 +1,6 @@
+"""Deprecated module for PEtab models.
+
+Use petab.v1.models instead."""
 from petab import _deprecated_import_v1
 from petab.v1.models.model import *  # noqa: F403, F401, E402
 
diff --git a/petab/models/pysb_model.py b/petab/models/pysb_model.py
@@ -1,3 +1,6 @@
+"""Deprecated module for PySB models.
+
+Use petab.v1.models.pysb_model instead."""
 from petab import _deprecated_import_v1
 from petab.v1.models.pysb_model import *  # noqa: F403, F401, E402
 
diff --git a/petab/models/sbml_model.py b/petab/models/sbml_model.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.models.sbml_model instead."""
 from petab import _deprecated_import_v1
 from petab.v1.models.sbml_model import *  # noqa: F403, F401, E402
 
diff --git a/petab/observables.py b/petab/observables.py
@@ -1,3 +1,7 @@
+"""Deprecated module for observable tables.
+
+Use petab.v1.observables instead.
+"""
 from petab import _deprecated_import_v1
 from petab.v1.observables import *  # noqa: F403, F401, E402
 
diff --git a/petab/parameter_mapping.py b/petab/parameter_mapping.py
@@ -1,3 +1,6 @@
+"""Deprecated module for parameter mapping.
+
+Use petab.v1.parameter_mapping instead."""
 from petab import _deprecated_import_v1
 from petab.v1.parameter_mapping import *  # noqa: F403, F401, E402
 
diff --git a/petab/parameters.py b/petab/parameters.py
@@ -1,3 +1,6 @@
+"""Deprecated module for parameter table handling.
+
+Use petab.v1.parameters instead."""
 from petab import _deprecated_import_v1
 from petab.v1.parameters import *  # noqa: F403, F401, E402
 
diff --git a/petab/simplify.py b/petab/simplify.py
@@ -1,3 +1,6 @@
+"""Deprecated module for simplifying PEtab problems.
+
+Use petab.simplify instead."""
 from petab import _deprecated_import_v1
 from petab.v1.simplify import *  # noqa: F403, F401, E402
 
diff --git a/petab/simulate.py b/petab/simulate.py
@@ -1,3 +1,7 @@
+"""Deprecated module for simulating PEtab models.
+
+Use petab.v1.simulate instead."""
+
 from petab import _deprecated_import_v1
 from petab.v1.simulate import *  # noqa: F403, F401, E402
 
diff --git a/petab/v1/__init__.py b/petab/v1/__init__.py
@@ -3,7 +3,6 @@
 Contains all functionality related to handling PEtab 1.0 problems.
 """
 
-
 from ..version import __version__  # noqa: F401, E402
 from .C import *  # noqa: F403, F401, E402
 from .calculate import *  # noqa: F403, F401, E402
diff --git a/petab/v1/models/__init__.py b/petab/v1/models/__init__.py
@@ -1,4 +1,7 @@
+"""Handling of different model types supported by PEtab."""
+#: SBML model type as used in a PEtab v2 yaml file as `language`.
 MODEL_TYPE_SBML = "sbml"
+#: PySB model type as used in a PEtab v2 yaml file as `language`.
 MODEL_TYPE_PYSB = "pysb"
 
 known_model_types = {
diff --git a/petab/v1/problem.py b/petab/v1/problem.py
@@ -629,23 +629,23 @@ def error(name: str) -> ValueError:
                 mapping_files=mapping_file,
             )
 
-    def get_optimization_parameters(self):
+    def get_optimization_parameters(self) -> list[str]:
         """
         Return list of optimization parameter IDs.
 
         See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameters(self.parameter_df)
 
-    def get_optimization_parameter_scales(self):
+    def get_optimization_parameter_scales(self) -> dict[str, str]:
         """
         Return list of optimization parameter scaling strings.
 
         See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameter_scaling(self.parameter_df)
 
-    def get_model_parameters(self):
+    def get_model_parameters(self) -> list[str] | dict[str, float]:
         """See :py:func:`petab.sbml.get_model_parameters`"""
         warn(
             "petab.Problem.get_model_parameters is deprecated and will be "
@@ -656,7 +656,7 @@ def get_model_parameters(self):
 
         return sbml.get_model_parameters(self.sbml_model)
 
-    def get_observable_ids(self):
+    def get_observable_ids(self) -> list[str]:
         """
         Returns dictionary of observable ids.
         """
diff --git a/petab/v2/lint.py b/petab/v2/lint.py
@@ -152,8 +152,9 @@ def lint_problem(problem: Problem | str | Path) -> ValidationResultList:
     """Validate a PEtab problem.
 
     Arguments:
-        problem: PEtab problem to check. Instance of :class:`Problem` or path
-        to a PEtab problem yaml file.
+        problem:
+            PEtab problem to check. Instance of :class:`Problem` or path
+            to a PEtab problem yaml file.
     Returns:
         A list of validation results. Empty if no issues were found.
     """
diff --git a/petab/v2/problem.py b/petab/v2/problem.py
@@ -1,3 +1,4 @@
+"""PEtab v2 problems."""
 from __future__ import annotations
 
 import logging
@@ -297,7 +298,7 @@ def from_combine(filename: Path | str) -> Problem:
         return problem
 
     @staticmethod
-    def get_problem(problem: str | Path | Problem):
+    def get_problem(problem: str | Path | Problem) -> Problem:
         """Get a PEtab problem from a file or a problem object.
 
         Arguments:
@@ -317,23 +318,23 @@ def get_problem(problem: str | Path | Problem):
             "or a PEtab problem object."
         )
 
-    def get_optimization_parameters(self):
+    def get_optimization_parameters(self) -> list[str]:
         """
         Return list of optimization parameter IDs.
 
         See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameters(self.parameter_df)
 
-    def get_optimization_parameter_scales(self):
+    def get_optimization_parameter_scales(self) -> dict[str, str]:
         """
         Return list of optimization parameter scaling strings.
 
         See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameter_scaling(self.parameter_df)
 
-    def get_observable_ids(self):
+    def get_observable_ids(self) -> list[str]:
         """
         Returns dictionary of observable ids.
         """
@@ -548,8 +549,8 @@ def x_fixed_indices(self) -> list[int]:
         estimated = list(self.parameter_df[ESTIMATE])
         return [j for j, val in enumerate(estimated) if val == 0]
 
-    def get_simulation_conditions_from_measurement_df(self):
-        """See petab.get_simulation_conditions"""
+    def get_simulation_conditions_from_measurement_df(self) -> pd.DataFrame:
+        """See :func:`petab.get_simulation_conditions`."""
         return measurements.get_simulation_conditions(self.measurement_df)
 
     def get_optimization_to_simulation_parameter_mapping(self, **kwargs):
@@ -569,7 +570,7 @@ def get_optimization_to_simulation_parameter_mapping(self, **kwargs):
             )
         )
 
-    def create_parameter_df(self, **kwargs):
+    def create_parameter_df(self, **kwargs) -> pd.DataFrame:
         """Create a new PEtab parameter table
 
         See :py:func:`create_parameter_df`.
@@ -683,7 +684,7 @@ def validate(
 
         Arguments:
             validation_tasks: List of validation tasks to run. If ``None``
-             or empty, :attr:Problem.validation_tasks` are used.
+             or empty, :attr:`Problem.validation_tasks` are used.
         Returns:
             A list of validation results.
         """
diff --git a/petab/visualize/__init__.py b/petab/visualize/__init__.py
@@ -1,3 +1,7 @@
+"""Deprecated module for visualization of PEtab problems.
+
+Use petab.v1.visualize instead."""
+
 from petab import _deprecated_import_v1
 from petab.v1.visualize import *  # noqa: F403, F401, E402
 
diff --git a/petab/visualize/data_overview.py b/petab/visualize/data_overview.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.visualize.data_overview instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.data_overview import *  # noqa: F403, F401, E402
 
diff --git a/petab/visualize/lint.py b/petab/visualize/lint.py
@@ -1,3 +1,6 @@
+"""Deprecated module for linting PEtab visualization files.
+
+Use petab.v1.visualize.lint instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.lint import *  # noqa: F403, F401, E402
 
diff --git a/petab/visualize/plot_data_and_simulation.py b/petab/visualize/plot_data_and_simulation.py
@@ -1,3 +1,6 @@
+"""Deprecated module.
+
+Use petab.v1.visualize.plot_data_and_simulation instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.plot_data_and_simulation import *  # noqa: F403, F401, E402
 
diff --git a/petab/visualize/plot_residuals.py b/petab/visualize/plot_residuals.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.visualize.plot_residuals instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.plot_residuals import *  # noqa: F403, F401, E402
 
diff --git a/petab/visualize/plotter.py b/petab/visualize/plotter.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.visualize.plotter instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.plotter import *  # noqa: F403, F401, E402
 from petab.v1.visualize.plotter import (  # noqa: F401
diff --git a/petab/visualize/plotting.py b/petab/visualize/plotting.py
@@ -1,3 +1,4 @@
+"""Deprecated module. Use petab.v1.visualize.plotting instead."""
 from petab import _deprecated_import_v1
 from petab.v1.visualize.plotting import *  # noqa: F403, F401, E402
 from petab.v1.visualize.plotting import DEFAULT_FIGSIZE  # noqa: F401
diff --git a/petab/yaml.py b/petab/yaml.py
@@ -1,3 +1,6 @@
+"""Deprecated module for reading and writing PEtab YAML files.
+
+Use petab.v1.yaml instead."""
 from petab import _deprecated_import_v1
 from petab.v1.yaml import *  # noqa: F403, F401, E402
 
diff --git a/tests/v1/math/__init__.py b/tests/v1/math/__init__.py
@@ -0,0 +1 @@
+"""PEtab math handling functionality."""

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Deprecated module. Use petab.v1.C instead."""`
`1`	`2`	`from petab import _deprecated_import_v1`
`2`	`3`	`from petab.v1.C import * # noqa: F403, F401, E402`
`3`	`4`