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.

lower[source]

A lower bound.

Type

Any

Type

Any

lower_inclusive[source]

Is the lower bound inclusive?

Type

bool

Type

bool

upper[source]

An upper bound.

Type

Any

Type

Any

upper_inclusive[source]

Is the upper bound inclusive?

Type

bool

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
lower: 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

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
Returns

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

Return type
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

upper: 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[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.

choices[source]

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

Type

frozendict.frozendict

Type

frozendict

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

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
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
Returns

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

Return type
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 (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
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

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.

name[source]

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

Type

Optional[str]

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

Type

Type

Type

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.

Type

Sequence[str]

Type
description[source]

An optional natural language description of the hyper-parameter.

Type

Optional[str]

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

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
Returns

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

Return type
semantic_types: Sequence[str][source]
structural_type: 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[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.

values[source]

A list of choice values.

Type

Sequence[Any]

Type
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
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
Returns

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

Return type
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]
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.

name[source]

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

Type

Optional[str]

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

Type

Type

Type

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.

Type

Sequence[str]

Type
description[source]

An optional natural language description of the hyper-parameter.

Type

Optional[str]

Type
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
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: Optional[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

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

name: Optional[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

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
Returns

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

Return type
semantic_types: Sequence[str][source]
structural_type: 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

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

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.

Type

ClassVar[frozendict.FrozenOrderedDict]

Type

ClassVar[FrozenOrderedDict]

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

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

elements[source]

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

Type
Type
min_size[source]

A minimal number of elements in the set.

Type

int

Type

int

max_size[source]

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

Type

Optional[int]

Type
is_configuration[source]

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

Type

bool

Type

bool

elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]][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

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

Return type
is_configuration: bool[source]
max_size: Optional[int][source]
min_size: int[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

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
Returns

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

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

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.

Type

float

Type

float

sigma[source]

A standard deviation of normal distribution.

Type

float

Type

float

q[source]

An optional quantization factor.

Type

Optional[float]

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

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
Returns

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

Return type
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

A dict.

Return type

Dict

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

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.

Type

float

Type

float

upper[source]

An upper bound.

Type

float

Type

float

q[source]

An optional quantization factor.

Type

Optional[float]

Type
lower_inclusive[source]

Is the lower bound inclusive?

Type

bool

Type

bool

upper_inclusive[source]

Is the upper bound inclusive?

Type

bool

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

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

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

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.

Type

float

Type

float

sigma[source]

A standard deviation of normal distribution.

Type

float

Type

float

q[source]

An optional quantization factor.

Type

Optional[float]

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

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
Returns

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

Return type
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

A dict.

Return type

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

primitive_families[source]

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

Type

Type
algorithm_types[source]

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

Type

Type
produce_methods[source]

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

Type

Sequence[str]

Type
algorithm_types: Sequence[d3m.metadata.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

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
matching_primitives: Optional[Sequence[Union[T, Type[T]]]][source]
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: Sequence[d3m.metadata.base.PrimitiveFamily][source]
produce_methods: 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

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
Returns

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

Return type
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 (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

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.

elements[source]

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

Type
Type
min_size[source]

A minimal number of elements in the set.

Type

int

Type

int

max_size[source]

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

Type

Optional[int]

Type
is_configuration[source]

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

Type

bool

Type

bool

elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]][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

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

Return type
is_configuration: bool[source]
max_size: Optional[int][source]
min_size: int[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

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
Returns

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

Return type
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[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.

ascending[source]

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

Type

bool

Type

bool

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

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

Return type
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

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.

ascending[source]

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

Type

bool

Type

bool

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

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

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

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.

Type

float

Type

float

upper[source]

An upper bound.

Type

float

Type

float

q[source]

An optional quantization factor.

Type

Optional[float]

Type
lower_inclusive[source]

Is the lower bound inclusive?

Type

bool

Type

bool

upper_inclusive[source]

Is the upper bound inclusive?

Type

bool

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

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

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

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

values[source]

A list of choice values.

Type

Sequence[Any]

Type
description: Optional[str][source]
name: str[source]
semantic_types: Sequence[str][source]
structural_type: 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

A dict.

Return type

Dict

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

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

lower[source]

A lower bound.

Type

int

Type

int

lower_inclusive[source]

Is the lower bound inclusive?

Type

bool

Type

bool

upper[source]

An upper bound.

Type

int

Type

int

upper_inclusive[source]

Is the upper bound inclusive?

Type

bool

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

A sampled value.

Return type

int

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

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

Type

frozendict.FrozenOrderedDict

Type

FrozenOrderedDict

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

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

Return type
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
Returns

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

Return type
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

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