Set __all__ (#72)

1. Avoids littering the namespace on star imports more than necessary

2. Simplifies cross-references to documentation, e.g., in addition to `petab_select.problem.Problem`, we can also now reference `petab_select.Problem`. This wasn't possible before.

3. Now also https://petab-select--72.org.readthedocs.build/en/72/generated/petab_select.html is populated. (To be decided whether we want to have only the top-level imports or only the individual modules.)

petab_select/__init__.py

@@ -1,5 +1,7 @@
 """Model selection extension for PEtab."""
 
+import sys
+
 from .candidate_space import *
 from .constants import *
 from .criteria import *
@@ -9,3 +11,9 @@
 from .model_subspace import *
 from .problem import *
 from .ui import *
+
+__all__ = [
+    x
+    for x in dir(sys.modules[__name__])
+    if not x.startswith('_') and x != 'sys'
+]

petab_select/candidate_space.py

@@ -28,6 +28,15 @@
 from .handlers import TYPE_LIMIT, LimitHandler
 from .model import Model, default_compare
 
+__all__ = [
+    'BackwardCandidateSpace',
+    'BruteForceCandidateSpace',
+    'CandidateSpace',
+    'FamosCandidateSpace',
+    'ForwardCandidateSpace',
+    'LateralCandidateSpace',
+]
+
 
 class CandidateSpace(abc.ABC):
     """A base class for collecting candidate models.

petab_select/constants.py

@@ -1,4 +1,5 @@
 """Constants for the PEtab Select package."""
+import sys
 from enum import Enum
 from pathlib import Path
 from typing import Dict, List, Literal, Union
@@ -118,36 +119,48 @@
 class Method(str, Enum):
     """String literals for model selection methods."""
 
+    #: The backward stepwise method.
     BACKWARD = 'backward'
     BIDIRECTIONAL = 'bidirectional'
+    #: The brute-force method.
     BRUTE_FORCE = 'brute_force'
+    #: The FAMoS method.
     FAMOS = 'famos'
+    #: The forward stepwise method.
     FORWARD = 'forward'
     FORWARD_AND_BACKWARD = 'forward_and_backward'
+    #: The lateral, or swap, method.
     LATERAL = 'lateral'
+    #: The jump-to-most-distant-model method.
     MOST_DISTANT = 'most_distant'
 
 
 class Criterion(str, Enum):
     """String literals for model selection criteria."""
 
+    #: The Akaike information criterion.
     AIC = 'AIC'
+    #: The corrected Akaike information criterion.
     AICC = 'AICc'
+    #: The Bayesian information criterion.
     BIC = 'BIC'
+    #: The likelihood.
     LH = 'LH'
+    #: The log-likelihood.
     LLH = 'LLH'
+    #: The negative log-likelihood.
     NLLH = 'NLLH'
 
 
-# Methods that move through model space by taking steps away from some model.
+#: Methods that move through model space by taking steps away from some model.
 STEPWISE_METHODS = [
     Method.BACKWARD,
     Method.BIDIRECTIONAL,
     Method.FORWARD,
     Method.FORWARD_AND_BACKWARD,
     Method.LATERAL,
 ]
-# Methods that require an initial model.
+#: Methods that require an initial model.
 INITIAL_MODEL_METHODS = [
     Method.BACKWARD,
     Method.BIDIRECTIONAL,
@@ -156,11 +169,20 @@ class Criterion(str, Enum):
     Method.LATERAL,
 ]
 
-# Virtual initial models can be used to initialize some initial model methods.
+#: Virtual initial models can be used to initialize some initial model methods.
 VIRTUAL_INITIAL_MODEL = 'virtual_initial_model'
+#: Methods that are compatible with a virtual initial model.
 VIRTUAL_INITIAL_MODEL_METHODS = [
     Method.BACKWARD,
     Method.BIDIRECTIONAL,
     Method.FORWARD,
     Method.FORWARD_AND_BACKWARD,
 ]
+
+
+__all__ = [
+    x
+    for x in dir(sys.modules[__name__])
+    if not x.startswith('_')
+    and x not in ('sys', "Enum", "Path", "Dict", "List", "Literal", "Union")
+]

petab_select/criteria.py

@@ -9,7 +9,12 @@
 
 from .constants import PETAB_PROBLEM, Criterion  # LH,; LLH,; NLLH,
 
-# from .model import Model
+__all__ = [
+    'calculate_aic',
+    'calculate_aicc',
+    'calculate_bic',
+    'CriterionComputer',
+]
 
 
 # use as attribute e.g. `Model.criterion_computer`?

petab_select/misc.py

@@ -9,6 +9,10 @@
     TYPE_PARAMETER_OPTIONS,
 )
 
+__all__ = [
+    'parameter_string_to_value',
+]
+
 
 def hashify(x: Any) -> str:
     """Generate a hash.

petab_select/model.py

@@ -36,6 +36,13 @@
 )
 from .petab import PetabMixin
 
+__all__ = [
+    'Model',
+    'default_compare',
+    'models_from_yaml_list',
+    'models_to_yaml_list',
+]
+
 
 class Model(PetabMixin):
     """A (possibly uncalibrated) model.

petab_select/model_space.py

@@ -22,6 +22,13 @@
 from .model import Model
 from .model_subspace import ModelSubspace
 
+__all__ = [
+    "ModelSpace",
+    "get_model_space_df",
+    "read_model_space_file",
+    "write_model_space_df",
+]
+
 
 def read_model_space_file(filename: str) -> TextIO:
     """Read a model space file.

petab_select/model_subspace.py

@@ -26,6 +26,10 @@
 from .model import Model
 from .petab import PetabMixin
 
+__all__ = [
+    'ModelSubspace',
+]
+
 
 class ModelSubspace(PetabMixin):
     """Efficient representation of exponentially large model subspaces.

petab_select/petab.py

@@ -12,6 +12,16 @@ class PetabMixin:
     """Useful things for classes that contain a PEtab problem.
 
     All attributes/methods are prefixed with `petab_`.
+
+    Attributes:
+        petab_yaml:
+            The location of the PEtab problem YAML file.
+        petab_problem:
+            The PEtab problem.
+        petab_parameters:
+            The parameters from the PEtab parameters table, where keys are
+            parameter IDs, and values are either :obj:`ESTIMATE` if the
+            parameter is set to be estimated, else the nominal value.
     """
 
     def __init__(
@@ -48,6 +58,11 @@ def __init__(
 
     @property
     def petab_parameter_ids_estimated(self) -> List[str]:
+        """Get the IDs of all estimated parameters.
+
+        Returns:
+            The parameter IDs.
+        """
         return [
             parameter_id
             for parameter_id, parameter_value in self.petab_parameters.items()
@@ -56,6 +71,11 @@ def petab_parameter_ids_estimated(self) -> List[str]:
 
     @property
     def petab_parameter_ids_fixed(self) -> List[str]:
+        """Get the IDs of all fixed parameters.
+
+        Returns:
+            The parameter IDs.
+        """
         estimated = self.petab_parameter_ids_estimated
         return [
             parameter_id
@@ -65,6 +85,7 @@ def petab_parameter_ids_fixed(self) -> List[str]:
 
     @property
     def petab_parameters_singular(self) -> TYPE_PARAMETER_DICT:
+        """TODO deprecate and remove?"""
         return {
             parameter_id: one(parameter_value)
             for parameter_id, parameter_value in self.petab_parameters

petab_select/problem.py

@@ -20,6 +20,10 @@
 from .model import Model, default_compare
 from .model_space import ModelSpace
 
+__all__ = [
+    'Problem',
+]
+
 
 class Problem(abc.ABC):
     """Handle everything related to the model selection problem.

petab_select/ui.py

@@ -9,6 +9,14 @@
 from .model import Model, default_compare
 from .problem import Problem
 
+__all__ = [
+    'candidates',
+    'model_to_petab',
+    'models_to_petab',
+    'best',
+    'write_summary_tsv',
+]
+
 
 def candidates(
     problem: Problem,