d3m.metadata.hyperparams module

class d3m.metadata.hyperparams.Hyperparameter(default: T, *, semantic_types: Sequence[str] = None, description: str = 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.

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

An optional natural language description of the hyper-parameter.

Type:str
can_accept_value_type(structural_type: Union[type, List[type]]) → bool[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: Any, cls: type) → bool[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.
Returns:

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

Return type:

bool

contribute_to_class(name: str) → None[source]
get_default(path: str = None) → Any[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 (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() → Optional[int][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:int
infer_type(value: Any) → type[source]

Infers a structural type of value.

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

Parameters:value (Any) – Value to infer a type for.
Returns:Type of value, or value itself if value is a primitive class.
Return type:type
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → T[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure() → Dict[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: T, transform: Callable, index: int = 0) → T[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 (Any) – 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:

Any

traverse() → Iterator[d3m.metadata.hyperparams.Hyperparameter][source]

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

Yields:Hyperparamater – The next child hyper-parameter of this hyper-parameter.
validate(value: T) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
validate_default() → None[source]

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

If not, it throws an exception.

value_from_json(json: Any) → T[source]
value_from_json_structure(json: Any) → T[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:Any
value_to_json(value: T) → Any[source]
value_to_json_structure(value: T) → Any[source]

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

Parameters:value (Any) – Value to convert.
Returns:A JSON-compatible value.
Return type:Any
class d3m.metadata.hyperparams.Primitive(default: Type[T], primitive_families: Optional[Sequence[d3m.metadata.base.PrimitiveFamily]] = None, algorithm_types: Optional[Sequence[d3m.metadata.base.PrimitiveAlgorithmType]] = None, produce_methods: Sequence[str] = None, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:Sequence[PrimitiveFamily]
algorithm_types[source]

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

Type:Sequence[PrimitiveAlgorithmType]
produce_methods[source]

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

Type:Sequence[str]
can_accept_value_type(structural_type: Union[type, List[type]]) → bool[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() → Optional[int][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:int
populate_primitives(all_primitives: Sequence[type] = None) → 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 (Sequence[Type[PrimitiveBase]]) – An alternative list of all primitive classes to find matching primitives among.
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → Union[T, Type[T]][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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[Union[T, Type[T]]][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure[source]
validate(value: Union[T, Type[T]]) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
value_from_json(json: Any) → Union[T, Type[T]][source]
value_from_json_structure(json: Any) → Union[T, Type[T]][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:Any
value_to_json(value: Union[T, Type[T]]) → Any[source]
value_to_json_structure(value: Union[T, Type[T]]) → Any[source]

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

Parameters:value (Any) – Value to convert.
Returns:A JSON-compatible value.
Return type:Any
class d3m.metadata.hyperparams.Constant(default: T, *, semantic_types: Sequence[str] = None, description: str = 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.

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

An optional natural language description of the hyper-parameter.

Type:str
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → T[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

validate(value: T) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
class d3m.metadata.hyperparams.Bounded(lower: T, upper: T, default: T, *, lower_inclusive: bool = True, upper_inclusive: bool = True, semantic_types: Sequence[str] = None, description: str = 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.

Type:Any
lower_inclusive[source]

Is the lower bound inclusive?

Type:bool
upper[source]

An upper bound.

Type:Any
upper_inclusive[source]

Is the upper bound inclusive?

Type:bool
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → T[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure() → Dict[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: T) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
validate_default() → None[source]

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

If not, it throws an exception.

class d3m.metadata.hyperparams.Enumeration(values: Sequence[T], default: T, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:Sequence[Any]
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → T[source]

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

It samples a value from values.

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure() → Dict[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: T) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
class d3m.metadata.hyperparams.UniformBool(default: bool, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:Sequence[Any]
to_simple_structure() → Dict[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.UniformInt(lower: int, upper: int, default: int, *, lower_inclusive: bool = True, upper_inclusive: bool = False, semantic_types: Sequence[str] = None, description: str = 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.

Type:int
lower_inclusive[source]

Is the lower bound inclusive?

Type:bool
upper[source]

An upper bound.

Type:int
upper_inclusive[source]

Is the upper bound inclusive?

Type:bool
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → int[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:int
class d3m.metadata.hyperparams.Uniform(lower: float, upper: float, default: float, q: float = None, *, lower_inclusive: bool = True, upper_inclusive: bool = False, semantic_types: Sequence[str] = None, description: str = 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.

Type:float
upper[source]

An upper bound.

Type:float
q[source]

An optional quantization factor.

Type:float
lower_inclusive[source]

Is the lower bound inclusive?

Type:bool
upper_inclusive[source]

Is the upper bound inclusive?

Type:bool
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → float[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:float
to_simple_structure() → Dict[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: float, upper: float, default: float, q: float = None, *, lower_inclusive: bool = True, upper_inclusive: bool = False, semantic_types: Sequence[str] = None, description: str = 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.

Type:float
upper[source]

An upper bound.

Type:float
q[source]

An optional quantization factor.

Type:float
lower_inclusive[source]

Is the lower bound inclusive?

Type:bool
upper_inclusive[source]

Is the upper bound inclusive?

Type:bool
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → float[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:float
to_simple_structure() → Dict[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.Normal(mu: float, sigma: float, default: float, q: float = None, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:float
sigma[source]

A standard deviation of normal distribution.

Type:float
q[source]

An optional quantization factor.

Type:float
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → float[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:float
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:

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

Return type:

Sequence[Any]

to_simple_structure() → Dict[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.LogNormal(mu: float, sigma: float, default: float, q: float = None, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:float
sigma[source]

A standard deviation of normal distribution.

Type:float
q[source]

An optional quantization factor.

Type:float
get_max_samples() → Optional[int][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:int
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → float[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:float
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure() → Dict[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.Union(configuration: collections.OrderedDict[str, Hyperparameter], default: str, *, semantic_types: Sequence[str] = None, description: str = 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).

Type:FrozenOrderedDict
contribute_to_class(name: str) → None[source]
get_max_samples[source]
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → T[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure[source]
traverse() → Iterator[d3m.metadata.hyperparams.Hyperparameter][source]

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

Yields:Hyperparamater – The next child hyper-parameter of this hyper-parameter.
validate(value: T) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
value_from_json_structure(json: Any) → T[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:Any
value_to_json_structure(value: T) → Any[source]

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

Parameters:value (Any) – Value to convert.
Returns:A JSON-compatible value.
Return type:Any
class d3m.metadata.hyperparams.Choice(choices: Dict[str, Type[d3m.metadata.hyperparams.Hyperparams]], default: str, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:frozendict
contribute_to_class(name: str) → None[source]
get_default(path: str = None) → Any[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 (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]
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → dict[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[T][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

to_simple_structure[source]
transform_value(value: dict, transform: Callable, index: int = 0) → dict[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 (Any) – 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:

Any

traverse() → Iterator[d3m.metadata.hyperparams.Hyperparameter][source]

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

Yields:Hyperparamater – The next child hyper-parameter of this hyper-parameter.
validate(value: dict) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
value_from_json(json: Any) → dict[source]
value_from_json_structure(json: Any) → dict[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:Any
value_to_json(value: dict) → Any[source]
value_to_json_structure(value: dict) → Any[source]

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

Parameters:value (Any) – Value to convert.
Returns:A JSON-compatible value.
Return type:Any
class d3m.metadata.hyperparams.Set(elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]], default: S, min_size: int = 0, max_size: int = None, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:Union[Hyperparameter, Type[Hyperparams]]
min_size[source]

A minimal number of elements in the set.

Type:int
max_size[source]

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

Type:int
is_configuration[source]

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

Type:bool
get_max_samples[source]
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → S[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[S][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

validate(value: S) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
class d3m.metadata.hyperparams.SortedSet(elements: d3m.metadata.hyperparams.Hyperparameter, default: S, min_size: int = 0, max_size: int = None, *, ascending: bool = True, semantic_types: Sequence[str] = None, description: str = 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).

Type:bool
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → S[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
to_simple_structure() → Dict[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: S) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
class d3m.metadata.hyperparams.List(elements: Union[d3m.metadata.hyperparams.Hyperparameter, Type[d3m.metadata.hyperparams.Hyperparams]], default: S, min_size: int = 0, max_size: int = None, *, semantic_types: Sequence[str] = None, description: str = 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.

Type:Union[Hyperparameter, Type[Hyperparams]]
min_size[source]

A minimal number of elements in the set.

Type:int
max_size[source]

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

Type:int
is_configuration[source]

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

Type:bool
get_max_samples[source]
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → S[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[S][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 (int) – A maximum number of samples to return.
  • random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
  • with_replacement (bool) – Are we sampling with replacement or without?
Returns:

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

Return type:

Sequence[Any]

class d3m.metadata.hyperparams.SortedList(elements: d3m.metadata.hyperparams.Hyperparameter, default: S, min_size: int = 0, max_size: int = None, *, ascending: bool = True, semantic_types: Sequence[str] = None, description: str = 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).

Type:bool
get_max_samples[source]
sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → S[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, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:A sampled value.
Return type:Any
to_simple_structure() → Dict[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: S) → None[source]

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

If not, it throws an exception.

Parameters:value (Any) – Value to validate.
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:FrozenOrderedDict
classmethod can_accept_value_type(structural_type: Union[type, List[type]]) → bool[source]
clear() → None. Remove all items from D.[source]
configuration = <FrozenOrderedDict OrderedDict()>[source]
classmethod defaults(path: str = None) → Any[source]

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

Parameters:path (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: collections.OrderedDict[str, Hyperparameter], *, class_name: str = None, module_name: str = None, set_names: bool = False) → Type[H][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 (OrderedDict[str, Hyperparameter]) – A hyper-parameters configuration.
  • class_name (str) – Class name of the subclass.
  • module_name (str) – Module name of the subclass.
  • set_names (bool) – 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:

A subclass itself.

Return type:

type

classmethod get_max_samples() → Optional[int][source]
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: Dict[str, Any]) → H[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:Hyperparams
classmethod sample(random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None) → H[source]

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

Parameters:random_state (Union[Integral, integer, RandomState]) – A random seed or state to be used when sampling.
Returns:An instance of hyper-parameters.
Return type:Hyperparams
classmethod sample_multiple(min_samples: int = 0, max_samples: int = None, random_state: Union[numbers.Integral, numpy.random.mtrand.RandomState] = None, *, with_replacement: bool = False) → Sequence[H][source]
setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D[source]
classmethod to_simple_structure() → Dict[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: dict, transform: Callable, index: int = 0) → H[source]
classmethod traverse() → Iterator[d3m.metadata.hyperparams.Hyperparameter][source]

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

Yields:Hyperparamater – The next hyper-parameter used in this hyper-parameters configuration.
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: dict) → None[source]
classmethod values_from_json_structure(json: Dict[str, Dict]) → H[source]

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

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

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

Returns:A JSON-compatible dict.
Return type:Dict