d3m.metadata.hyperparams module

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

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.

lower[source]

A lower bound.

lower_inclusive[source]

Is the lower bound inclusive?

upper[source]

An upper bound.

upper_inclusive[source]

Is the upper bound inclusive?

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

lower: typing.Any[source]
lower_inclusive: bool[source]
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

Return type

A sampled value.

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

Return type

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

to_simple_structure()[source]

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

Returns

Return type

A dict.

upper: typing.Any[source]
upper_inclusive: bool[source]
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

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

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

choices[source]

A map between choices and their classes defining their hyper-parameters configuration.

choices: frozendict.frozendict[source]
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

Return type

A default value.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

Return type

A sampled value.

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

Return type

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

to_simple_structure()[source]

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

Returns

Return type

A 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

Return type

A transformed value.

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

Return type

Converted value.

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

Return type

A JSON-compatible value.

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

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

name[source]

A name of this hyper-parameter in the configuration of all hyper-parameters.

structural_type[source]

A Python type of this hyper-parameter. All values of the hyper-parameter, including the default value, should be of this type.

semantic_types[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.

description[source]

An optional natural language description of the hyper-parameter.

description[source]
name[source]
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

Return type

A sampled value.

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

Return type

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

semantic_types[source]
structural_type[source]
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

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

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

values[source]

A list of choice values.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

Return type

A sampled value.

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

Return type

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

to_simple_structure()[source]

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

Returns

Return type

A 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: typing.Sequence[typing.Any][source]
class d3m.metadata.hyperparams.Hyperparameter(default, *, semantic_types=None, description=None)[source]

Bases: typing.Generic

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.

name[source]

A name of this hyper-parameter in the configuration of all hyper-parameters.

structural_type[source]

A Python type of this hyper-parameter. All values of the hyper-parameter, including the default value, should be of this type.

semantic_types[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.

description[source]

An optional natural language description of the hyper-parameter.

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

Return type

If value of given type can be accepted by this hyper-parameter.

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

description: str[source]
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

Return type

A default value.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

Return type

Type of value, or value itself if value is a primitive class.

name: str[source]
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

Return type

A sampled value.

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

Return type

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

semantic_types: typing.Sequence[str][source]
structural_type: typing.Type[source]
to_simple_structure()[source]

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

Returns

Return type

A 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

Return type

A transformed value.

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

Return type

Converted value.

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

Return type

A JSON-compatible value.

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.

configuration[source]

A hyper-parameters configuration.

classmethod can_accept_value_type(structural_type)[source]
Return type

bool

clear() → None. Remove all items from D.[source]
configuration: ClassVar[frozendict.FrozenOrderedDict] = <FrozenOrderedDict OrderedDict()>[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

Return type

An instance of hyper-parameters or a default value of a hyper-parameter under path.

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

Return type

A copy of the object with replaced values.

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

Return type

An instance of hyper-parameters.

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

Return type

A 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

Return type

An instance of this class with values from json argument.

values_to_json_structure()[source]

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

Returns

Return type

A JSON-compatible dict.

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

Bases: d3m.metadata.hyperparams._Sequence

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.

elements[source]

A hyper-parameter or hyper-parameters configuration of set elements.

min_size[source]

A minimal number of elements in the set.

max_size[source]

A maximal number of elements in the set. Can be None for no limit.

is_configuration[source]

Is elements a hyper-parameter or hyper-parameters configuration?

elements[source]
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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

is_configuration[source]
max_size[source]
min_size[source]
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

Return type

A sampled value.

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

Return type

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

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

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

mu[source]

A mean of normal distribution.

sigma[source]

A standard deviation of normal distribution.

q[source]

An optional quantization factor.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

mu: float[source]
q: float[source]
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

Return type

A sampled value.

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

Return type

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

sigma: float[source]
to_simple_structure()[source]

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

Returns

Return type

A dict.

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

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.

lower[source]

A lower bound.

upper[source]

An upper bound.

q[source]

An optional quantization factor.

lower_inclusive[source]

Is the lower bound inclusive?

upper_inclusive[source]

Is the upper bound inclusive?

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

lower: float[source]
lower_inclusive: bool[source]
q: float[source]
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

Return type

A sampled value.

to_simple_structure()[source]

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

Returns

Return type

A dict.

upper: float[source]
upper_inclusive: bool[source]
class d3m.metadata.hyperparams.Normal(mu, sigma, default, q=None, *, semantic_types=None, description=None)[source]

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

mu[source]

A mean of normal distribution.

sigma[source]

A standard deviation of normal distribution.

q[source]

An optional quantization factor.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

mu: float[source]
q: float[source]
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

Return type

A sampled value.

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

Return type

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

sigma: float[source]
to_simple_structure()[source]

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

Returns

Return type

A dict.

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

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).

primitive_families[source]

A list of primitive families a matching primitive should be part of.

algorithm_types[source]

A list of algorithm types a matching primitive should implement at least one.

produce_methods[source]

A list of produce methods a matching primitive should provide all.

algorithm_types: typing.Tuple[base.PrimitiveAlgorithmType, …][source]
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

Return type

If value of given type can be accepted by this hyper-parameter.

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

primitive_families: typing.Tuple[base.PrimitiveFamily, …][source]
produce_methods: typing.Sequence[str][source]
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

Return type

A sampled value.

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

Return type

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

to_simple_structure()[source]

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

Returns

Return type

A 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

Return type

Converted value.

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

Return type

A JSON-compatible value.

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

Bases: d3m.metadata.hyperparams._Sequence

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.

elements[source]

A hyper-parameter or hyper-parameters configuration of set elements.

min_size[source]

A minimal number of elements in the set.

max_size[source]

A maximal number of elements in the set. Can be None for no limit.

is_configuration[source]

Is elements a hyper-parameter or hyper-parameters configuration?

elements[source]
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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

is_configuration[source]
max_size[source]
min_size[source]
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

Return type

A sampled value.

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

Return type

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

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

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

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.

ascending[source]

Are values required to be sorted from smallest to largest (True) or the opposite (False).

ascending: bool[source]
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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

Return type

A sampled value.

to_simple_structure()[source]

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

Returns

Return type

A 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

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

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.

ascending[source]

Are values required to be sorted from smallest to largest (True) or the opposite (False).

ascending: bool[source]
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

Return type

A sampled value.

to_simple_structure()[source]

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

Returns

Return type

A 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

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

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.

lower[source]

A lower bound.

upper[source]

An upper bound.

q[source]

An optional quantization factor.

lower_inclusive[source]

Is the lower bound inclusive?

upper_inclusive[source]

Is the upper bound inclusive?

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

lower: float[source]
lower_inclusive: bool[source]
q: float[source]
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

Return type

A sampled value.

to_simple_structure()[source]

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

Returns

Return type

A dict.

upper: float[source]
upper_inclusive: bool[source]
class d3m.metadata.hyperparams.UniformBool(default, *, semantic_types=None, description=None)[source]

Bases: d3m.metadata.hyperparams.Enumeration

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

values[source]

A list of choice values.

to_simple_structure()[source]

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

Returns

Return type

A dict.

values[source]
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

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

lower[source]

A lower bound.

lower_inclusive[source]

Is the lower bound inclusive?

upper[source]

An upper bound.

upper_inclusive[source]

Is the upper bound inclusive?

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

lower: int[source]
lower_inclusive: bool[source]
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

Return type

A sampled value.

upper: int[source]
upper_inclusive: bool[source]
class d3m.metadata.hyperparams.Union(configuration, default, *, semantic_types=None, description=None)[source]

Bases: d3m.metadata.hyperparams.Hyperparameter

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.

configuration[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).

configuration: frozendict.FrozenOrderedDict[source]
contribute_to_class(name)[source]
Return type

None

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

Return type

A maximum number of samples that can be returned at once. Or None if there is no limit.

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

Return type

A sampled value.

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

Return type

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

to_simple_structure()[source]

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

Returns

Return type

A 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

Return type

Converted value.

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

Return type

A JSON-compatible value.