Skip to content

Categorical

ConfigSpace.api.types.categorical #

Categorical #

Categorical(
    name: str,
    items: Sequence[T],
    *,
    default: T | _NotSet = NotSet,
    weights: Sequence[float] | None = None,
    ordered: bool = False,
    meta: dict | None = None
) -> CategoricalHyperparameter | OrdinalHyperparameter

Creates a Categorical Hyperparameter.

CategoricalHyperparameter's can be used to represent a discrete choice. Optionally, you can specify that these values are also ordered in some manner, e.g. ["small", "medium", "large"].

# A simple categorical hyperparameter
c = Categorical("animals", ["cat", "dog", "mouse"])

# With a default
c = Categorical("animals", ["cat", "dog", "mouse"], default="mouse")

# Make them weighted
c = Categorical("animals", ["cat", "dog", "mouse"], weights=[0.1, 0.8, 3.14])

# Specify it's an OrdinalHyperparameter (ordered categories)
# ... note that you can't apply weights to an Ordinal
o = Categorical("size", ["small", "medium", "large"], ordered=True)

# Add some meta information for your own tracking
c = Categorical("animals", ["cat", "dog", "mouse"], meta={"use": "Favourite Animal"})

Note

Categorical is actually a function, please use the corresponding return types if doing an isinstance(param, type) check with either CategoricalHyperparameter and/or OrdinalHyperparameter.

PARAMETER DESCRIPTION
name

The name of the hyperparameter

TYPE: str

items

A list of items to put in the category.

Warning

Can't have duplicate categories, use weights if required.

TYPE: Sequence[T]

default

The default value of the categorical hyperparameter.

TYPE: T | _NotSet DEFAULT: NotSet

weights

The weights to apply to each categorical. Each item will be sampled according to these weights.

TYPE: Sequence[float] | None DEFAULT: None

ordered

Whether the categorical is ordered or not. If True, this will return an OrdinalHyperparameter, otherwise it remain a CategoricalHyperparameter.

TYPE: bool DEFAULT: False

meta

Any additional meta information you would like to store along with the hyperparamter.

TYPE: dict | None DEFAULT: None

Source code in src/ConfigSpace/api/types/categorical.py 
 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
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def Categorical(
    name: str,
    items: Sequence[T],
    *,
    default: T | _NotSet = NotSet,
    weights: Sequence[float] | None = None,
    ordered: bool = False,
    meta: dict | None = None,
) -> CategoricalHyperparameter | OrdinalHyperparameter:
    """Creates a Categorical Hyperparameter.

    CategoricalHyperparameter's can be used to represent a discrete
    choice. Optionally, you can specify that these values are also ordered in
    some manner, e.g. `#!python ["small", "medium", "large"]`.

    ```python
    # A simple categorical hyperparameter
    c = Categorical("animals", ["cat", "dog", "mouse"])

    # With a default
    c = Categorical("animals", ["cat", "dog", "mouse"], default="mouse")

    # Make them weighted
    c = Categorical("animals", ["cat", "dog", "mouse"], weights=[0.1, 0.8, 3.14])

    # Specify it's an OrdinalHyperparameter (ordered categories)
    # ... note that you can't apply weights to an Ordinal
    o = Categorical("size", ["small", "medium", "large"], ordered=True)

    # Add some meta information for your own tracking
    c = Categorical("animals", ["cat", "dog", "mouse"], meta={"use": "Favourite Animal"})
    ```

    !!! note

        `Categorical` is actually a function, please use the corresponding return types if
        doing an `isinstance(param, type)` check with either
        [`CategoricalHyperparameter`][ConfigSpace.hyperparameters.CategoricalHyperparameter]
        and/or [`OrdinalHyperparameter`][ConfigSpace.hyperparameters.OrdinalHyperparameter].

    Args:
        name: The name of the hyperparameter
        items:
            A list of items to put in the category.

            !!! warning

                Can't have duplicate categories, use weights if required.

        default: The default value of the categorical hyperparameter.
        weights:
            The weights to apply to each categorical. Each item will be sampled according
            to these weights.
        ordered:
            Whether the categorical is ordered or not. If `True`, this will return an
            [`OrdinalHyperparameter`][ConfigSpace.hyperparameters.OrdinalHyperparameter],
            otherwise it remain a
            [`CategoricalHyperparameter`][ConfigSpace.hyperparameters.CategoricalHyperparameter].
        meta:
            Any additional meta information you would like to store along with the
            hyperparamter.
    """  # noqa: E501
    if ordered and weights is not None:
        raise ValueError("Can't apply `weights` to `ordered` Categorical")

    if ordered:
        return OrdinalHyperparameter(
            name=name,
            sequence=items,
            default_value=default,
            meta=meta,
        )

    return CategoricalHyperparameter(
        name=name,
        choices=items,
        default_value=default,
        weights=weights,
        meta=meta,
    )