d3m.metadata.hyperparams¶

class d3m.metadata.hyperparams.Bounded(lower, upper, default, *, lower_inclusive=True, upper_inclusive=True, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[typing.T]

A bounded hyper-parameter with lower and upper bounds, but no other information about the distribution of the space of the hyper-parameter, besides a default value.

Both lower and upper bounds are inclusive by default. Each bound can be also None to signal that the hyper-parameter is unbounded for that bound. Both bounds cannot be None because then this is the same as Hyperparameter class, so you can use that one directly.

Type variable T is optional and if not provided an attempt to automatically infer it from bounds and default will be made.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

If it is bounded on both sides, it tries to sample from uniform distribution, otherwise returns a default value.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~T

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~T) – Value to validate.
Return type: None

validate_default()[source]¶

Validates that a default value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Return type: None

lower: Any[source]¶: A lower bound.

lower_inclusive: bool[source]¶: Is the lower bound inclusive?

upper: Any[source]¶: An upper bound.

upper_inclusive: bool[source]¶: Is the upper bound inclusive?

class d3m.metadata.hyperparams.Choice(choices, default, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[Dict]

A hyper-parameter which combines multiple hyper-parameter configurations into one hyper-parameter.

This is useful when a combination of hyper-parameters should exists together. Then such combinations can be made each into one choice.

No relation or probability distribution between choices is prescribed.

This is similar to Union hyper-parameter that it combines hyper-parameters, but Choice combines configurations of multiple hyper-parameters, while Union combines individual hyper-parameters.

contribute_to_class(name)[source]¶

Return type: None

get_default(path=None)[source]¶

Returns a default value of a hyper-parameter.

Remember to never modify it in-place it is a mutable value. Moreover, if it is an instance of a primitive, also copy the instance before you use it to not change its internal state.

Parameters: path (Optional[str]) – An optional path to get defaults for nested hyper-parameters, if a hyper-parameter has nested hyper-parameters. It can contain . to represent a path through nested hyper-parameters.
Returns: A default value.
Return type: Any

get_max_samples()[source]¶

Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first chooses a hyper-parameters configuration from available choices and then samples it.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: dict

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Return type: Dict

transform_value(value, transform, index=0)[source]¶

Transforms the value belonging to this hyper-parameter to a new value by calling transform on it. If the hyper-parameter has child hyper-parameters, it deconstructs the value, calls transform_value recursively, and constructs the new value back.

Parameters

value (dict) – A value to transform.
transform (Callable) – A function which receives as arguments: a hyper-parameter instance, the value, and a sequence index of iterating over a structure, and should return a new transformed value. It is called only for leaf hyper-parameters (those without child hyper-parameters).
index (int) – A sequence index which should be passed to transform. Used when iterating over a structure by the parent. It should be deterministic.

Returns

A transformed value.

Return type

dict

traverse()[source]¶

Traverse over all child hyper-parameters of this hyper-parameter.

Yields: Hyperparamater – The next child hyper-parameter of this hyper-parameter.
Return type: Iterator[Hyperparameter]

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (dict) – Value to validate.
Return type: None

value_from_json(json)[source]¶

Return type: dict

value_from_json_structure(json)[source]¶

Converts a JSON-compatible value to a value of this hyper-parameter.

Parameters: json (Any) – A JSON-compatible value.
Returns: Converted value.
Return type: dict

value_to_json(value)[source]¶

Return type: Any

value_to_json_structure(value)[source]¶

Converts a value of this hyper-parameter to a JSON-compatible value.

Parameters: value (dict) – Value to convert.
Returns: A JSON-compatible value.
Return type: Any

choices: frozendict.frozendict[source]¶: A map between choices and their classes defining their hyper-parameters configuration.

class d3m.metadata.hyperparams.Constant(default, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[typing.T]

A constant hyper-parameter that represents a constant default value.

Type variable T is optional and if not provided an attempt to automatically infer it from default will be made.

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~T

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

For the base class it always returns only a default value because the space is unknown.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~T) – Value to validate.
Return type: None

description: Optional[str][source]¶: An optional natural language description of the hyper-parameter.

name: Optional[str][source]¶: A name of this hyper-parameter in the configuration of all hyper-parameters.

semantic_types: Sequence[str][source]¶: A list of URIs providing semantic meaning of the hyper-parameter. This can help express how the hyper-parameter is being used, e.g., as a learning rate or as kernel parameter.

structural_type: Type[source]¶: A Python type of this hyper-parameter. All values of the hyper-parameter, including the default value, should be of this type.

class d3m.metadata.hyperparams.Enumeration(values, default, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[typing.T]

An enumeration hyper-parameter with a value drawn uniformly from a list of values.

If None is a valid choice, it should be listed among values.

Type variable T is optional and if not provided an attempt to automatically infer it from values will be made.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It samples a value from values.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~T

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

It samples values from values.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~T) – Value to validate.
Return type: None

values: Sequence[Any][source]¶: A list of choice values.

class d3m.metadata.hyperparams.Hyperparameter(default, *, semantic_types=None, description=None)[source]¶

Bases: Generic[typing.T]

A base class for hyper-parameter descriptions.

A base hyper-parameter does not give any information about the space of the hyper-parameter, besides a default value.

Type variable T is optional and if not provided an attempt to automatically infer it from default will be made. Attribute structural_type exposes this type.

There is a special case when values are primitives. In this case type variable T and structural_type should always be a primitive base class, but valid values used in hyper-parameters can be both primitive instances (of that base class or its subclasses) and primitive classes (that base class itself or its subclasses). Primitive instances allow one to specify a primitive much more precisely: values of their hyper-parameters, or even an already fitted primitive.

This means that TA2 should take care and check if values it is planning to use for this hyper-parameter are a primitive class or a primitive instance. It should make sure that it always passes only a primitive instance to the primitive which has a hyper-parameter expecting primitive(s). Even if the value is already a primitive instance, it must not pass it directly, but should make a copy of the primitive instance with same hyper-parameters and params. Primitive instances part of hyper-parameter definitions should be seen as immutable and as a template for primitives to pass and not to directly use.

TA2 is in the best position to create such instances during pipeline run as it has all necessary information to construct primitive instances (and can control a random seed, or example). Moreover, it is also more reasonable for TA2 to handle the life-cycle of a primitive and do any additional processing of primitives. TA2 can create such a primitive outside of the pipeline, or as part of the pipeline and pass it as a hyper-parameter value to the primitive. The latter approach allows pipeline to describe how is the primitive fitted and use data from the pipeline itself for fitting, before the primitive is passed on as a hyper-parameter value to another primitive.

__getstate__()[source]¶

Return type: dict

__setstate__(state)[source]¶

Return type: None

can_accept_value_type(structural_type)[source]¶

Returns True if a hyper-parameter can accept a value of type structural_type.

Parameters: structural_type (Union[type, List[type]]) – A structural type. Can be a type or a list of types.
Returns: If value of given type can be accepted by this hyper-parameter.
Return type: bool

check_type(value, cls)[source]¶

Check that the type of value matches given cls.

There is a special case if value is a primitive class, in that case it is checked that value is a subclass of cls.

Parameters

value (Any) – Value to check type for.
cls (type) – Type to check type against.

Return type

bool

Returns

True if value is an instance of cls, or if value is a primitive class, if it is a subclass of cls.

contribute_to_class(name)[source]¶

Return type: None

get_default(path=None)[source]¶

Returns a default value of a hyper-parameter.

Remember to never modify it in-place it is a mutable value. Moreover, if it is an instance of a primitive, also copy the instance before you use it to not change its internal state.

Parameters: path (Optional[str]) – An optional path to get defaults for nested hyper-parameters, if a hyper-parameter has nested hyper-parameters. It can contain . to represent a path through nested hyper-parameters.
Returns: A default value.
Return type: Any

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

infer_type(value)[source]¶

Infers a structural type of value.

There is a special case if value is a primitive class, in that case it is returned as is.

Parameters: value (Any) – Value to infer a type for.
Returns: Type of value, or value itself if value is a primitive class.
Return type: type

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

For the base class it always returns a default value because the space is unknown.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~T

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

For the base class it always returns only a default value because the space is unknown.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

transform_value(value, transform, index=0)[source]¶

Transforms the value belonging to this hyper-parameter to a new value by calling transform on it. If the hyper-parameter has child hyper-parameters, it deconstructs the value, calls transform_value recursively, and constructs the new value back.

Parameters

value (~T) – A value to transform.
transform (Callable) – A function which receives as arguments: a hyper-parameter instance, the value, and a sequence index of iterating over a structure, and should return a new transformed value. It is called only for leaf hyper-parameters (those without child hyper-parameters).
index (int) – A sequence index which should be passed to transform. Used when iterating over a structure by the parent. It should be deterministic.

Returns

A transformed value.

Return type

~T

traverse()[source]¶

Traverse over all child hyper-parameters of this hyper-parameter.

Yields: Hyperparamater – The next child hyper-parameter of this hyper-parameter.
Return type: Iterator[Hyperparameter]

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~T) – Value to validate.
Return type: None

validate_default()[source]¶

Validates that a default value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Return type: None

value_from_json(json)[source]¶

Return type: ~T

value_from_json_structure(json)[source]¶

Converts a JSON-compatible value to a value of this hyper-parameter.

Parameters: json (Any) – A JSON-compatible value.
Returns: Converted value.
Return type: ~T

value_to_json(value)[source]¶

Return type: Any

value_to_json_structure(value)[source]¶

Converts a value of this hyper-parameter to a JSON-compatible value.

Parameters: value (~T) – Value to convert.
Returns: A JSON-compatible value.
Return type: Any

description: Optional[str][source]¶: An optional natural language description of the hyper-parameter.

name: Optional[str][source]¶: A name of this hyper-parameter in the configuration of all hyper-parameters.

semantic_types: Sequence[str][source]¶: A list of URIs providing semantic meaning of the hyper-parameter. This can help express how the hyper-parameter is being used, e.g., as a learning rate or as kernel parameter.

structural_type: Type[source]¶: A Python type of this hyper-parameter. All values of the hyper-parameter, including the default value, should be of this type.

class d3m.metadata.hyperparams.Hyperparams(*args, **kwargs)[source]¶

Bases: dict

A base class to be subclassed and used as a type for Hyperparams type argument in primitive interfaces. An instance of this subclass is passed as a hyperparams argument to primitive’s constructor.

You should subclass the class and configure class attributes to hyper-parameters you want. They will be extracted out and put into the configuration attribute. They have to be an instance of the Hyperparameter class for this to happen.

You can define additional methods and attributes on the class. Prefix them with _ to not conflict with future standard ones.

When creating an instance of the class, all hyper-parameters have to be provided. Default values have to be explicitly passed.

__getstate__()[source]¶

Return type: dict

__setstate__(state)[source]¶

Return type: None

classmethod can_accept_value_type(structural_type)[source]¶

Return type: bool

clear() → None. Remove all items from D.[source]¶

classmethod defaults(path=None)[source]¶

Returns a hyper-parameters sample with all values set to defaults.

Parameters: path (Optional[str]) – An optional path to get defaults for. It can contain . to represent a path through nested hyper-parameters.
Returns: An instance of hyper-parameters or a default value of a hyper-parameter under path.
Return type: Any

classmethod define(configuration, *, class_name=None, module_name=None, set_names=False)[source]¶

Define dynamically a subclass of this class using configuration and optional class_name and module_name.

This is equivalent of defining a class statically in Python. configuration is what you would otherwise provide through class attributes.

Parameters

configuration – A hyper-parameters configuration.
class_name – Class name of the subclass.
module_name – Module name of the subclass.
set_names – Should all hyper-parameters defined have their names set. By default False. This is different from when defining a static subclass, where the default is True and names are set by the default.

Returns

Return type

A subclass itself.

classmethod get_max_samples()[source]¶

Return type: Optional[int]

pop(k[, d]) → v, remove specified key and return the corresponding value.[source]¶: If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a[source]¶: 2-tuple; but raise KeyError if D is empty.

replace(values)[source]¶

Creates a copy of hyper-parameters with values replaced with values from values.

This is equivalent of doing Hyperparams(hyperparams, **values).

Parameters: values (Dict[str, Any]) – Map between keys and values to replace.
Returns: A copy of the object with replaced values.
Return type: ~H

classmethod sample(random_state=None)[source]¶

Returns a hyper-parameters sample with all values sampled from their hyper-parameter configurations.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: An instance of hyper-parameters.
Return type: ~H

classmethod sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Return type: Sequence[~H]

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D[source]¶

classmethod to_simple_structure(cls)[source]¶

Converts the hyper-parameters configuration to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

classmethod transform_value(values, transform, index=0)[source]¶

Return type: ~H

classmethod traverse()[source]¶

Traverse over all hyper-parameters used in this hyper-parameters configuration.

Yields: Hyperparamater – The next hyper-parameter used in this hyper-parameters configuration.
Return type: Iterator[Hyperparameter]

update([E, ]**F) → None. Update D from dict/iterable E and F.[source]¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

classmethod validate(values)[source]¶

Return type: None

classmethod values_from_json_structure(json)[source]¶

Converts given JSON-compatible structure to an instance of this class with values from the structure.

Parameters: json (Dict[str, Dict]) – A JSON-compatible dict.
Returns: An instance of this class with values from json argument.
Return type: ~H

values_to_json_structure()[source]¶

Converts hyper-parameter values to a JSON-compatible structure.

Returns: A JSON-compatible dict.
Return type: Dict[str, Dict]

configuration: ClassVar[frozendict.FrozenOrderedDict] = <FrozenOrderedDict OrderedDict()>[source]¶: A hyper-parameters configuration.

class d3m.metadata.hyperparams.List(elements, default, min_size=0, max_size=None, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams._Sequence[typing.S]

A list hyper-parameter which samples with replacement multiple times another hyper-parameter or hyper-parameters configuration.

This is useful when a primitive is interested in more than one value of a hyper-parameter or hyper-parameters configuration.

Values are represented as tuples of elements. The order of elements matters and is preserved but is not prescribed.

Type variable S does not have to be specified because the structural type is a set from provided elements.

get_max_samples()[source]¶

Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first randomly chooses the size of the resulting sampled list and then samples this number of elements.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~S

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A list (represented as a tuple) of multiple sampled values.

Return type

Sequence[~S]

elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]][source]¶: A hyper-parameter or hyper-parameters configuration of set elements.

is_configuration: bool[source]¶: Is elements a hyper-parameter or hyper-parameters configuration?

max_size: Optional[int][source]¶: A maximal number of elements in the set. Can be None for no limit.

min_size: int[source]¶: A minimal number of elements in the set.

class d3m.metadata.hyperparams.LogNormal(mu, sigma, default, q=None, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[float]

A float hyper-parameter with a value drawn according to exp(normal(mu, sigma)) so that the logarithm of the value is normally distributed.

If q is provided, then the value is drawn according to round(exp(normal(mu, sigma)) / q) * q.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: float

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

mu: float[source]¶: A mean of normal distribution.

q: Optional[float][source]¶: An optional quantization factor.

sigma: float[source]¶: A standard deviation of normal distribution.

class d3m.metadata.hyperparams.LogUniform(lower, upper, default, q=None, *, lower_inclusive=True, upper_inclusive=False, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Bounded[float]

A float hyper-parameter with a value drawn from [lower, upper), by default, according to exp(uniform(log(lower), log(upper))) so that the logarithm of the value is uniformly distributed.

If q is provided, then the value is drawn according to round(exp(uniform(log(lower), log(upper))) / q) * q.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: float

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

lower: float[source]¶: A lower bound.

lower_inclusive: bool[source]¶: Is the lower bound inclusive?

q: Optional[float][source]¶: An optional quantization factor.

upper: float[source]¶: An upper bound.

upper_inclusive: bool[source]¶: Is the upper bound inclusive?

class d3m.metadata.hyperparams.Normal(mu, sigma, default, q=None, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[float]

A float hyper-parameter with a value drawn normally distributed according to mu and sigma.

If q is provided, then the value is drawn according to round(normal(mu, sigma) / q) * q.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: float

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

mu: float[source]¶: A mean of normal distribution.

q: Optional[float][source]¶: An optional quantization factor.

sigma: float[source]¶: A standard deviation of normal distribution.

class d3m.metadata.hyperparams.Primitive(default, primitive_families=None, algorithm_types=None, produce_methods=None, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[typing.T]

A hyper-parameter describing a primitive or primitives.

Matching primitives are determined based on their structural type (a matching primitive has to be an instance or a subclass of the structural type), their primitive’s family (a matching primitive’s family has to be among those listed in the hyper-parameter), their algorithm types (a matching primitive has to implement at least one of the listed in the hyper-parameter), and produce methods provided (a matching primitive has to provide all of the listed in the hyper-parameter).

Remember that valid values of a hyper-parameter which has primitive values are both primitive instances and primitive classes, but the structural type is always just a primitive base class. Hyper-parameter values being passed to a primitive which has a hyper-parameter expecting primitive(s) should always be primitive instances.

The default sampling method returns always classes (or a default value, which can be a primitive instance), but alternative implementations could sample across instances (and for example across also primitive’s hyper-parameters).

can_accept_value_type(structural_type)[source]¶

Returns True if a hyper-parameter can accept a value of type structural_type.

Parameters: structural_type (Union[type, List[type]]) – A structural type. Can be a type or a list of types.
Returns: If value of given type can be accepted by this hyper-parameter.
Return type: bool

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

populate_primitives(all_primitives=None)[source]¶

Populate a list of matching primitives.

Called automatically when needed using d3m.index primitives. If this is not desired, this method should be called using a list of primitive classes to find matching primitives among.

Parameters: all_primitives (Optional[Sequence[type]]) – An alternative list of all primitive classes to find matching primitives among.
Return type: None

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Returns a random primitive from primitives available through d3m.index, by default, or those given to a manual call of populate_primitives.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: Union[~T, Type[~T]]

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

It samples primitives available through d3m.index, by default, or those given to a manual call of populate_primitives.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[Union[~T, Type[~T]]]

to_simple_structure()[source]¶

Return type: Dict

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (Union[~T, Type[~T]]) – Value to validate.
Return type: None

value_from_json(json)[source]¶

Return type: Union[~T, Type[~T]]

value_from_json_structure(json)[source]¶

Converts a JSON-compatible value to a value of this hyper-parameter.

Parameters: json (Any) – A JSON-compatible value.
Returns: Converted value.
Return type: Union[~T, Type[~T]]

value_to_json(value)[source]¶

Return type: Any

value_to_json_structure(value)[source]¶

Converts a value of this hyper-parameter to a JSON-compatible value.

Parameters: value (Union[~T, Type[~T]]) – Value to convert.
Returns: A JSON-compatible value.
Return type: Any

algorithm_types: Sequence[d3m.metadata.base.PrimitiveAlgorithmType][source]¶: A list of algorithm types a matching primitive should implement at least one.

matching_primitives: Optional[Sequence[Union[T, Type[T]]]][source]¶

primitive_families: Sequence[d3m.metadata.base.PrimitiveFamily][source]¶: A list of primitive families a matching primitive should be part of.

produce_methods: Sequence[str][source]¶: A list of produce methods a matching primitive should provide all.

class d3m.metadata.hyperparams.Set(elements, default, min_size=0, max_size=None, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams._Sequence[typing.S]

A set hyper-parameter which samples without replacement multiple times another hyper-parameter or hyper-parameters configuration.

This is useful when a primitive is interested in more than one value of a hyper-parameter or hyper-parameters configuration.

Values are represented as tuples of unique elements. The order of elements does not matter (two different orders of same elements represent the same value), but order is meaningful and preserved to assure reproducibility.

Type variable S does not have to be specified because the structural type is a set from provided elements.

get_max_samples()[source]¶

Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first randomly chooses the size of the resulting sampled set and then samples this number of unique elements.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~S

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~S]

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~S) – Value to validate.
Return type: None

elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]][source]¶: A hyper-parameter or hyper-parameters configuration of set elements.

is_configuration: bool[source]¶: Is elements a hyper-parameter or hyper-parameters configuration?

max_size: Optional[int][source]¶: A maximal number of elements in the set. Can be None for no limit.

min_size: int[source]¶: A minimal number of elements in the set.

class d3m.metadata.hyperparams.SortedList(elements, default, min_size=0, max_size=None, *, ascending=True, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.List[typing.S]

Similar to List hyper-parameter, but elements of values are required to be sorted from smallest to largest, by default.

Hyper-parameters configuration as elements is not supported.

get_max_samples()[source]¶

Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first randomly chooses the size of the resulting sampled list and then samples this number of elements.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~S

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~S) – Value to validate.
Return type: None

ascending: bool[source]¶: Are values required to be sorted from smallest to largest (True) or the opposite (False).

class d3m.metadata.hyperparams.SortedSet(elements, default, min_size=0, max_size=None, *, ascending=True, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Set[typing.S]

Similar to Set hyper-parameter, but elements of values are required to be sorted from smallest to largest, by default.

Hyper-parameters configuration as elements is not supported.

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first randomly chooses the size of the resulting sampled set and then samples this number of unique elements.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~S

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~S) – Value to validate.
Return type: None

ascending: bool[source]¶: Are values required to be sorted from smallest to largest (True) or the opposite (False).

class d3m.metadata.hyperparams.Uniform(lower, upper, default, q=None, *, lower_inclusive=True, upper_inclusive=False, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Bounded[float]

A float hyper-parameter with a value drawn uniformly from [lower, upper), by default.

If q is provided, then the value is drawn according to round(uniform(lower, upper) / q) * q.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: float

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

lower: float[source]¶: A lower bound.

lower_inclusive: bool[source]¶: Is the lower bound inclusive?

q: Optional[float][source]¶: An optional quantization factor.

upper: float[source]¶: An upper bound.

upper_inclusive: bool[source]¶: Is the upper bound inclusive?

class d3m.metadata.hyperparams.UniformBool(default, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Enumeration[bool]

A bool hyper-parameter with a value drawn uniformly from {True, False}.

to_simple_structure()[source]¶

Converts the hyper-parameter to a simple structure, similar to JSON, but with values left as Python values.

Returns: A dict.
Return type: Dict

description: Optional[str][source]¶: An optional natural language description of the hyper-parameter.

name: str[source]¶: A name of this hyper-parameter in the configuration of all hyper-parameters.

semantic_types: Sequence[str][source]¶: A list of URIs providing semantic meaning of the hyper-parameter. This can help express how the hyper-parameter is being used, e.g., as a learning rate or as kernel parameter.

structural_type: Type[source]¶: A Python type of this hyper-parameter. All values of the hyper-parameter, including the default value, should be of this type.

values: Sequence[Any][source]¶: A list of choice values.

class d3m.metadata.hyperparams.UniformInt(lower, upper, default, *, lower_inclusive=True, upper_inclusive=False, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Bounded[int]

An int hyper-parameter with a value drawn uniformly from [lower, upper), by default.

get_max_samples()[source]¶

Returns a maximum number of samples that can be returned at once using sample_multiple, when with_replacement is False.

Returns: A maximum number of samples that can be returned at once. Or None if there is no limit.
Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: int

lower: int[source]¶: A lower bound.

lower_inclusive: bool[source]¶: Is the lower bound inclusive?

upper: int[source]¶: An upper bound.

upper_inclusive: bool[source]¶: Is the upper bound inclusive?

class d3m.metadata.hyperparams.Union(configuration, default, *, semantic_types=None, description=None)[source]¶

Bases: d3m.metadata.hyperparams.Hyperparameter[typing.T]

A union hyper-parameter which combines multiple other hyper-parameters.

This is useful when a hyper-parameter has multiple modalities and each modality can be described with a different hyper-parameter.

No relation or probability distribution between modalities is prescribed, but default sampling implementation assumes uniform distribution of modalities.

Type variable T does not have to be specified because the structural type can be automatically inferred as a union of all hyper-parameters in configuration.

This is similar to Choice hyper-parameter that it combines hyper-parameters, but Union combines individual hyper-parameters, while Choice combines configurations of multiple hyper-parameters.

contribute_to_class(name)[source]¶

Return type: None

get_max_samples()[source]¶

Return type: Optional[int]

sample(random_state=None)[source]¶

Samples a random value from the hyper-parameter search space.

It first chooses a hyper-parameter from its configuration and then samples it.

Parameters: random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
Returns: A sampled value.
Return type: ~T

sample_multiple(min_samples=0, max_samples=None, random_state=None, *, with_replacement=False)[source]¶

Samples multiple random values from the hyper-parameter search space. At least min_samples of them, and at most max_samples.

Parameters

min_samples (int) – A minimum number of samples to return.
max_samples (Optional[int]) – A maximum number of samples to return.
random_state (Union[Integral, RandomState, None]) – A random seed or state to be used when sampling.
with_replacement (bool) – Are we sampling with replacement or without?

Returns

A set (represented as a tuple) of multiple sampled values.

Return type

Sequence[~T]

to_simple_structure()[source]¶

Return type: Dict

traverse()[source]¶

Traverse over all child hyper-parameters of this hyper-parameter.

Yields: Hyperparamater – The next child hyper-parameter of this hyper-parameter.
Return type: Iterator[Hyperparameter]

validate(value)[source]¶

Validates that a given value belongs to the space of the hyper-parameter.

If not, it throws an exception.

Parameters: value (~T) – Value to validate.
Return type: None

value_from_json_structure(json)[source]¶

Converts a JSON-compatible value to a value of this hyper-parameter.

Parameters: json (Any) – A JSON-compatible value.
Returns: Converted value.
Return type: ~T

value_to_json_structure(value)[source]¶

Converts a value of this hyper-parameter to a JSON-compatible value.

Parameters: value (~T) – Value to convert.
Returns: A JSON-compatible value.
Return type: Any

configuration: frozendict.FrozenOrderedDict[source]¶: A configuration of hyper-parameters to combine into one. It is important that configuration uses an ordered dict so that order is reproducible (default dict has unspecified order).

d3m.metadata.hyperparams¶

Version

Table of Contents