Search space

neps.search_spaces.search_space

SearchSpace

SearchSpace(**hyperparameters)

Bases: Mapping[str, Any]

Source code in neps/search_spaces/search_space.py

def __init__(self, **hyperparameters):
    self.hyperparameters: dict[str, Parameter] = {}

    self.fidelity = None
    self.has_prior = False
    for key, hyperparameter in hyperparameters.items():
        self.hyperparameters[key] = hyperparameter
        # Only integer / float parameters can be fidelities, so check these
        if hyperparameter.is_fidelity:
            if self.fidelity is not None:
                raise ValueError(
                    "neps only supports one fidelity parameter in the pipeline space,"
                    " but multiple were given. (Hint: check you pipeline space for "
                    "multiple is_fidelity=True)"
                )
            if not isinstance(hyperparameter, FloatParameter):
                raise ValueError(
                    "neps only suport float and integer fidelity parameters"
                )
            self.fidelity = hyperparameter

        # Check if defaults exists to construct prior from, except of
        # ConstantParameter because default gets init always by the given value
        if (
            hasattr(hyperparameter, "default")
            and hyperparameter.default is not None
            and not isinstance(hyperparameter, ConstantParameter)
        ):
            self.has_prior = True
        elif hasattr(hyperparameter, "has_prior") and hyperparameter.has_prior:
            self.has_prior = True

    # Variables for tabular bookkeeping
    self.custom_grid_table = None
    self.raw_tabular_space = None
    self.has_tabular = None

set_custom_grid_space

set_custom_grid_space(
    grid_table: Series | DataFrame,
    raw_space: SearchSpace | ConfigurationSpace,
)

Set a custom grid space for the search space.

This function is used to set a custom grid space for the pipeline space. NOTE: Only to be used if a custom set of hyperparameters from the search space is to be sampled or used for acquisition functions. WARNING: The type check and the table format requirement is loose and can break certain components.

Source code in neps/search_spaces/search_space.py

def set_custom_grid_space(
    self,
    grid_table: pd.Series | pd.DataFrame,
    raw_space: SearchSpace | CS.ConfigurationSpace,
):
    """Set a custom grid space for the search space.

    This function is used to set a custom grid space for the pipeline space.
    NOTE: Only to be used if a custom set of hyperparameters from the search space
    is to be sampled or used for acquisition functions.
    WARNING: The type check and the table format requirement is loose and
    can break certain components.
    """
    self.custom_grid_table: pd.DataFrame | pd.Series = grid_table
    self.raw_tabular_space = (
        SearchSpace(**raw_space)
        if not isinstance(raw_space, SearchSpace)
        else raw_space
    )
    if self.custom_grid_table is None or self.raw_tabular_space is None:
        raise ValueError(
            "Both grid_table and raw_space must be set!\n"
            "A table or list of fixed configs must be supported with a "
            "continuous space representing the type and bounds of each "
            "hyperparameter for accurate modeling."
        )
    self.has_tabular = True

pipeline_space_from_yaml

pipeline_space_from_yaml(
    yaml_file_path: str | Path,
) -> dict[
    str,
    FloatParameter
    | IntegerParameter
    | CategoricalParameter
    | ConstantParameter,
]

Reads configuration details from a YAML file and constructs a pipeline space dictionary.

This function extracts parameter configurations from a YAML file, validating and translating them into corresponding parameter objects. The resulting dictionary maps parameter names to their respective configuration objects.

PARAMETER	DESCRIPTION
yaml_file_path	Path to the YAML file containing parameter TYPE: str | Path

RETURNS	DESCRIPTION
dict	A dictionary where keys are parameter names and values are parameter objects (like IntegerParameter, FloatParameter, etc.). TYPE: dict[str, FloatParameter | IntegerParameter | CategoricalParameter | ConstantParameter]

RAISES	DESCRIPTION
SearchSpaceFromYamlFileError	This custom exception is raised if there are issues

Note

The YAML file should be properly structured with valid keys and values as per the expected parameter types. The function employs modular validation and type deduction logic, ensuring each parameter's configuration adheres to expected formats and constraints. Any deviation results in an appropriately raised error, which is then captured by SearchSpaceFromYamlFileError for streamlined error handling.

Example

To use this function with a YAML file 'config.yaml', you can do: pipeline_space = pipeline_space_from_yaml('config.yaml')

Source code in neps/search_spaces/search_space.py

def pipeline_space_from_yaml(
    yaml_file_path: str | Path,
) -> dict[
    str, FloatParameter | IntegerParameter | CategoricalParameter | ConstantParameter
]:
    """
    Reads configuration details from a YAML file and constructs a pipeline space
    dictionary.

    This function extracts parameter configurations from a YAML file, validating and
    translating them into corresponding parameter objects. The resulting dictionary
    maps parameter names to their respective configuration objects.

    Args:
        yaml_file_path (str | Path): Path to the YAML file containing parameter
        configurations.

    Returns:
        dict: A dictionary where keys are parameter names and values are parameter
              objects (like IntegerParameter, FloatParameter, etc.).

    Raises:
        SearchSpaceFromYamlFileError: This custom exception is raised if there are issues
        with the YAML file's format or contents. It encapsulates underlying exceptions
        (KeyError, TypeError, ValueError) that occur during the processing of the YAML
        file. This approach localizes error handling, providing clearer context and
        diagnostics. The raised exception includes the type of the original error and
        a descriptive message.

    Note:
        The YAML file should be properly structured with valid keys and values as per the
        expected parameter types. The function employs modular validation and type
        deduction logic, ensuring each parameter's configuration adheres to expected
        formats and constraints. Any deviation results in an appropriately raised error,
        which is then captured by SearchSpaceFromYamlFileError for streamlined error
        handling.

    Example:
        To use this function with a YAML file 'config.yaml', you can do:
        pipeline_space = pipeline_space_from_yaml('config.yaml')
    """
    try:
        # try to load the YAML file
        try:
            with open(yaml_file_path) as file:
                config = yaml.safe_load(file)
        except FileNotFoundError as e:
            raise FileNotFoundError(
                f"Unable to find the specified file for 'pipeline_space' at "
                f"'{yaml_file_path}'. Please verify the path specified in the "
                f"'pipeline_space' argument and try again."
            ) from e
        except yaml.YAMLError as e:
            raise ValueError(
                f"The file at {str(yaml_file_path)} is not a valid YAML file."
            ) from e

        # check for init key pipeline_space
        if "pipeline_space" not in config:
            raise KeyError(
                "The YAML file is incorrectly constructed: the 'pipeline_space:' "
                "reference is missing at the top of the file."
            )

        # Initialize the pipeline space
        pipeline_space = {}

        # Iterate over the items in the YAML configuration
        for name, details in config["pipeline_space"].items():
            # get parameter type
            param_type = deduce_and_validate_param_type(name, details)

            # init parameter by checking type
            if param_type in ("int", "integer"):
                # Integer Parameter
                pipeline_space[name] = IntegerParameter(
                    lower=details["lower"],
                    upper=details["upper"],
                    log=details.get("log", False),
                    is_fidelity=details.get("is_fidelity", False),
                    default=details.get("default", None),
                    default_confidence=details.get("default_confidence", "low"),
                )
            elif param_type == "float":
                # Float Parameter
                pipeline_space[name] = FloatParameter(
                    lower=details["lower"],
                    upper=details["upper"],
                    log=details.get("log", False),
                    is_fidelity=details.get("is_fidelity", False),
                    default=details.get("default", None),
                    default_confidence=details.get("default_confidence", "low"),
                )
            elif param_type in ("cat", "categorical"):
                # Categorical parameter
                pipeline_space[name] = CategoricalParameter(
                    choices=details["choices"],
                    is_fidelity=details.get("is_fidelity", False),
                    default=details.get("default", None),
                    default_confidence=details.get("default_confidence", "low"),
                )
            elif param_type in ("const", "constant"):
                # Constant parameter
                pipeline_space[name] = ConstantParameter(
                    value=details["value"],
                    is_fidelity=details.get("is_fidelity", False),
                )
            else:
                # Handle unknown parameter type
                raise TypeError(
                    f"Unsupported parameter type{details['type']} for '{name}'.\n"
                    f"Supported Types for argument type are:\n"
                    "For integer parameter: int, integer\n"
                    "For float parameter: float\n"
                    "For categorical parameter: cat, categorical\n"
                    "For constant parameter: const, constant\n"
                )
    except (KeyError, TypeError, ValueError, FileNotFoundError) as e:
        raise SearchSpaceFromYamlFileError(e) from e
    return pipeline_space