revised runs docstrings

automl · Feb 8, 2024 · bb61cd4 · bb61cd4
1 parent 1c4c55a
commit bb61cd4
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 96 deletions.
diff --git a/deepcave/runs/group.py b/deepcave/runs/group.py
@@ -246,57 +246,64 @@ def get_original_config_id(self, config_id: int) -> int:
 
     def get_original_run(self, config_id: int) -> AbstractRun:
         """
-        Get the original abstract run.
+        Get the original run.
 
         Parameters
         ----------
         config_id : int
-            The identificator of a configuration.
+            The identificator of the configuration.
 
         Returns
         -------
         AbstractRun
-            The original abstract run.
+            The original run.
         """
         run_id = self._original_config_mapping[config_id][0]
         return self.runs[run_id]
 
     def get_model(self, config_id: int) -> Optional[Any]:
         """
-        Get the model of the runs.
+        Get the model given the configuration id.
 
         Parameters
         ----------
         config_id : int
-            The identificator of a configuration.
+            The identificator of the configuration.
 
         Returns
         -------
         Optional[Any]
-            The model of the runs.
+            The model.
         """
         run_id, config_id = self._original_config_mapping[config_id]
         return self.runs[run_id].get_model(config_id)
 
     # Types dont match superclass
     def get_trajectory(self, *args, **kwargs):  # type: ignore
         """
-        Get the trajectory of the group.
+        Calculate the trajectory of the given objective and budget.
 
         This includes the times, the mean costs, and the standard deviation of the costs.
 
         Parameters
         ----------
         *args
-            The arguments for the trajectory of a run.
-            Should be an objective.
+            Should be the objective to calculate the trajectory from.
         **kwargs
-            Keyword arguments for the trajectory of a run.
-            Should bean int, float or None, representing the budget.
+            Should be the budget to calculate the trajectory for.
 
         Returns
         -------
-        The trajectory of the grouped runs.
+        times : List[float]
+            Times of the trajectory.
+        costs_mean : List[float]
+            Costs of the trajectory.
+        costs_std : List[float]
+            Standard deviation of the costs of the trajectory.
+        ids : List[int]
+            The "global" ids of the selected trial.
+        config_ids : List[int]
+            The configuration ids of the selected trials.
         """
         # Cache costs
         run_costs = []

diff --git a/deepcave/runs/handler.py b/deepcave/runs/handler.py
@@ -2,9 +2,10 @@
 """
 # Handler
 
-This module handles the run.
+This module provides utilities to handle a run.
+
 It can retrieve working directories, run paths, run names, as well as groups of runs.
-It provides utilities to update and remove runs as well a groups of runs.
+It provides utilities to update and remove runs as well as groups of runs.
 
 # Classes
     - RunHandler: Handle the runs.
@@ -37,15 +38,15 @@ class RunHandler:
     Properties
     ----------
     c : Cache
-        The cache for the different information.
+        The cache containing information about a run(s).
     rc : RunCaches
         The caches for the selected runs.
     logger : Logger
         The logger for the run handler.
     available_run_yfes : List[Type[Run]]
         A list of the available converters.
     runs : Dict[str, AbstractRun]
-        A dictionary of abstract runs with their path as key.
+        A dictionary of runs with their path as key.
     groups : Dict[str, Group]
         A dictionary of the groups.
     available_run_classes : List[Type[Run]]
@@ -93,7 +94,7 @@ def get_working_directory(self) -> Path:
         Raises
         ------
         AssertionError
-            If the working directory is not a string or a path like, an error is thrown.
+            If the working directory is not a string or a Path, an error is thrown.
         """
         working_dir = self.c.get("working_dir")
         assert isinstance(
@@ -189,12 +190,12 @@ def get_selected_groups(self) -> Dict[str, List[str]]:
         Returns
         -------
         Dict[str, List[str]]
-            Dictionary of the selected groups.
+            Dictionary with the selected groups.
 
         Raises
         ------
         AssertionError
-            If groups in cache is not a dict, an error is thrown.
+            If groups in cache is not a dictionary, an error is thrown.
         """
         selected_groups = self.c.get("groups")
         assert isinstance(
@@ -204,7 +205,9 @@ def get_selected_groups(self) -> Dict[str, List[str]]:
 
     def add_run(self, run_path: str) -> bool:
         """
-        Add a run path to the cache. If run path is already in cache, do nothing.
+        Add a run path to the cache. 
+        
+        If run path is already in cache, do nothing.
 
         Parameters
         ----------
@@ -228,7 +231,9 @@ def add_run(self, run_path: str) -> bool:
 
     def remove_run(self, run_path: str) -> None:
         """
-        Remove a run path from the cache. If run path is not in cache, do nothing.
+        Remove a run path from the cache. 
+        
+        If run path is not in cache, do nothing.
 
         Parameters
         ----------
@@ -288,15 +293,15 @@ def update_runs(self) -> bool:
         """
         Load selected runs and update cache if files changed.
 
-        Raises
-        ------
-        NotValidRunError
-            If directory can not be transformed into a run, an error is thrown.
-
         Returns
         -------
         bool
             True if all selected runs could be loaded, False otherwise.
+
+        Raises
+        ------
+        NotValidRunError
+            If directory can not be transformed into a run, an error is thrown.
         """
         runs: Dict[str, AbstractRun] = {}  # run_path: Run
         success = True
@@ -330,15 +335,15 @@ def update_run(
         Parameters
         ----------
         run_path : str
-            The path where the run should be stored.
+            The path of the run.
         class_hint : Optional[Type[Run]], optional
             A hint/suggestion of what the Type of the Run is.
             Default is None.
 
         Returns
         -------
         Optional[AbstractRun]
-            The Abstract Run added to the cache.
+            The Run added to the cache.
 
         Raises
         ------
@@ -402,7 +407,7 @@ def update_groups(self, groups: Optional[Dict[str, List[str]]] = None) -> None:
         Parameters
         ----------
         groups : Optional[Dict[str, str]], optional
-            A dictionary used to instantiate the groups.
+            A dictionary with the groups.
             Default is None.
 
         Raises

diff --git a/deepcave/runs/objective.py b/deepcave/runs/objective.py
@@ -25,9 +25,9 @@ class Objective:
 
     Properties
     ----------
-    lower : int | float | None
+    lower : Optional[Union[int, float]]
         The lower bound of the objective.
-    upper : int | float | None
+    upper : Optional[Union[int, float]]
         The upper bound of the objective.
     optimize : str
         Define whether to optimize lower or upper.
@@ -76,12 +76,12 @@ def __post_init__(self) -> None:
 
     def to_json(self) -> Dict[str, Any]:
         """
-        Convert objectives attributes to a JSON format.
+        Convert objectives attributes to a dictionary in a JSON friendly format.
 
         Returns
         -------
         Dict[str, Any]
-            A dictionary with the objects attributes in a JSON format.
+            A dictionary in a JSON friendly format with the objects attributes.
         """
         return {
             "name": self.name,
@@ -95,7 +95,7 @@ def to_json(self) -> Dict[str, Any]:
     @staticmethod
     def from_json(d: Dict[str, Any]) -> "Objective":
         """
-        Create an objective from a JSON format.
+        Create an objective from a JSON friendly dictionary format.
 
         Parameters
         ----------
@@ -105,7 +105,7 @@ def from_json(d: Dict[str, Any]) -> "Objective":
         Returns
         -------
         Objective
-            An objective created from the provided JSON data.
+            An objective created from the provided data.
         """
         objective = Objective(
             name=d["name"],
@@ -121,7 +121,7 @@ def from_json(d: Dict[str, Any]) -> "Objective":
 
     def __eq__(self, other: Any) -> bool:
         """
-        Compare if two instances are qual based on their attributes.
+        Compare if two instances are equal based on their attributes.
 
         Parameters
         ----------
@@ -142,9 +142,7 @@ def __eq__(self, other: Any) -> bool:
 
     def merge(self, other: Any) -> None:
         """
-        Merge two Objectives with its attributes.
-
-        Fit the attributes of self to the attributes of the other Objective.
+        Merge two Objectives over their attributes.
 
         Parameters
         ----------