Skip to content

Experiment Planning

omnirec.runner.plan.ExperimentPlan(plan_name: Optional[str] = None)

Source code in src\omnirec\runner\plan.py 
16
17
18
def __init__(self, plan_name: Optional[str] = None):
    self._name = plan_name
    self._config: dict[str, AlgorithmConfig] = {}

add_algorithm(algorithm: Algorithms | str, algorithm_config: Optional[AlgorithmConfig] = None, force=False)

Adds an algorithm to the experiment plan.

Parameters:

Name Type Description Default
algorithm Algorithms | str

The algorithm to add.

 required
algorithm_config Optional[AlgorithmConfig]

The configuration for the algorithm. Each value in the config dict can be either a plain value or a PlanComponentBase instance that controls how hyperparameter combinations are generated:

  • Grid(values): Enumerate all provided values (grid search).
  • RandomChoice(choices, n): Randomly sample n items from a discrete list.
  • RandomRange(start, end, n): Randomly sample n values from a numeric range.

Plain (non-PlanComponentBase) values are treated as fixed and used as-is in every combination. Algorithm config keys depend on the origin library of the algorithm; refer to its documentation for available hyperparameters.

 None
force bool

Whether to forcefully overwrite an existing algorithm config. Defaults to False.

 False
Example 
from omnirec.runner.plan import ExperimentPlan
from omnirec.runner.plan_components import Grid, RandomChoice, RandomRange

# Create a new experiment plan
plan = ExperimentPlan(plan_name="Example Plan")

# Define algorithm configuration based on the lenskit ItemKNNScorer parameters.
# Grid expands [10, 20] into separate combinations; min_nbrs and feedback are fixed.
lenskit_itemknn = {
    "max_nbrs": Grid([10, 20]),
    "min_nbrs": 5,
    "feedback": "implicit",
}

# Add algorithm with configuration to the plan
plan.add_algorithm(Algorithms.ItemKNNScorer, lenskit_itemknn)
Source code in src\omnirec\runner\plan.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def add_algorithm(
    self,
    algorithm: Algorithms | str,
    algorithm_config: Optional[AlgorithmConfig] = None,
    force=False,
):
    """Adds an algorithm to the experiment plan.

    Args:
        algorithm (Algorithms | str): The algorithm to add.
        algorithm_config (Optional[AlgorithmConfig], optional): The configuration for the
            algorithm. Each value in the config dict can be either a plain value or a
            `PlanComponentBase` instance that controls how hyperparameter combinations are
            generated:

            - `Grid(values)`: Enumerate all provided values (grid search).
            - `RandomChoice(choices, n)`: Randomly sample `n` items from a discrete list.
            - `RandomRange(start, end, n)`: Randomly sample `n` values from a numeric range.

            Plain (non-`PlanComponentBase`) values are treated as fixed and used as-is in
            every combination. Algorithm config keys depend on the origin library of the
            algorithm; refer to its documentation for available hyperparameters.
        force (bool, optional): Whether to forcefully overwrite an existing algorithm config.
            Defaults to False.

    Example:
        ```Python
        from omnirec.runner.plan import ExperimentPlan
        from omnirec.runner.plan_components import Grid, RandomChoice, RandomRange

        # Create a new experiment plan
        plan = ExperimentPlan(plan_name="Example Plan")

        # Define algorithm configuration based on the lenskit ItemKNNScorer parameters.
        # Grid expands [10, 20] into separate combinations; min_nbrs and feedback are fixed.
        lenskit_itemknn = {
            "max_nbrs": Grid([10, 20]),
            "min_nbrs": 5,
            "feedback": "implicit",
        }

        # Add algorithm with configuration to the plan
        plan.add_algorithm(Algorithms.ItemKNNScorer, lenskit_itemknn)
        ```
    """
    if isinstance(algorithm, Algorithms):
        algorithm_name = algorithm.value
    else:
        algorithm_name = algorithm

    if not algorithm_config:
        algorithm_config = {}
    if algorithm_name in self._config and force:
        logger.info(
            f'Config for "{algorithm_name}" already exists, but {force=}. Overwriting...'
        )
    elif algorithm_name in self._config:
        logger.critical(
            f'Config for "{algorithm_name}" already exists! Use "force=True" to overwrite or update it using "update_algorithm_config()"'
        )
        sys.exit(1)

    self._config[algorithm_name] = algorithm_config

update_algorithm(algorithm_name: str, algorithm_config: AlgorithmConfig)

Updates the configuration for an existing algorithm in the experiment plan.

Parameters:

Name Type Description Default
algorithm_name str

The name of the algorithm to update.

 required
algorithm_config AlgorithmConfig

The new configuration for the algorithm.

 required
Source code in src\omnirec\runner\plan.py 
84
85
86
87
88
89
90
91
92
93
94
def update_algorithm(self, algorithm_name: str, algorithm_config: AlgorithmConfig):
    """Updates the configuration for an existing algorithm in the experiment plan.

    Args:
        algorithm_name (str): The name of the algorithm to update.
        algorithm_config (AlgorithmConfig): The new configuration for the algorithm.
    """
    if algorithm_name not in self._config:
        self._config[algorithm_name] = algorithm_config
    else:
        self._config[algorithm_name].update(algorithm_config)