Random generators

Summary

Random generators, which can be used inside letstune.Params.

Random params generator

A RandomParamsGenerator is an object with method get_random_params, which takes numpy.random.Generator and returns a random value.

All functions in this module return a random generator. Classes deriving from letstune.Params are also random generators.

Function oneof() allows to compose many random generators.

Generic

letstune.rand.oneof(candidates: Sequence[T | RandomParamsGenerator[T]], weights: Sequence[float | int] | None = None) → RandomParamsGenerator[T]

Returns a randomly chosen candidate.

>>> gen = oneof([2, 4, 8])
>>> rng = np.random.default_rng(42)
>>> gen.get_random_params(rng)
2
>>> gen.get_random_params(rng)
8

Weights

An optional parameter weights takes relative weights of each candidate. If present, candidates with higher weight will be chosen more often.

Random generators

If the chosen candidate has get_random_params method, then a result of this method is returned. Therefore, oneof() can be used with other random generators:

>>> gen = oneof([uniform(1, 2), uniform(4, 5)])
>>> rng = np.random.default_rng(131)
>>> gen.get_random_params(rng)  
1.60...
>>> gen.get_random_params(rng)  
4.53...

oneof() can be used with classes deriving from letstune.Params:

>>> import letstune
>>> from letstune import rand
>>> class DigitsTrainingParams(letstune.Params):
...     layer_number: int = rand.oneof([1, 2, 3])
...     learning_rate: float = rand.uniform(0.01, 0.1)

>>> rng = np.random.default_rng(42)
>>> gen = oneof([DigitsTrainingParams])
>>> gen.get_random_params(rng)  
DigitsTrainingParams(layer_number=..., learning_rate=...)

This allows to make samples from various model families:

gen = oneof([LassoParams, RandomForestParams])

There is an exception: if the chosen candidate is an instance of letstune.Params, then it is just returned:

>>> gen = oneof([DigitsTrainingParams(
...     layer_number=4,
...     learning_rate=0.001,
... )])

>>> gen.get_random_params(rng)
DigitsTrainingParams(layer_number=4, learning_rate=0.001)

Integer

letstune.rand.ints(low: int, high: int) → RandomParamsGenerator[int]

Returns a random integer in the range low, high (both sides inclusive).

Boolean

letstune.rand.bools(probability: float = 0.5) → RandomParamsGenerator[bool]

Returns True with given probability.

Float

letstune.rand.uniform(low: float = 0.0, high: float = 1.0, *, log: bool = False) → RandomParamsGenerator[float]

Returns a number from uniform distribution. [1]

If log is True, then the sample is from loguniform distribution. [2]

[1]

See scipy.stats.uniform.

[2]

See scipy.stats.loguniform.

letstune.rand.normal(median: float = 0.0, scale: float = 1.0, *, log: bool = False) → RandomParamsGenerator[float]

Returns a number from normal distribution [3] with given median [4] and scale (standard deviation).

If log is True, then the sample is from loguniform distribution. [5] Then scale is the standard deviation of natural logarithm of the variable.

[3]

See scipy.stats.norm.

[4]

Median of normal distribution is equal to its mean.

[5]

See scipy.stats.lognorm. The distribution from scipy has a different parametrization then this function.

Protocol

class letstune.rand.RandomParamsGenerator(*args, **kwargs)

Bases: Protocol[T]

An object with method get_random_params, which takes numpy.random.Generator and returns a random value of type T.

All functions in letstune.rand module return a RandomParamsGenerator. Classes deriving from letstune.Params are also a RandomParamsGenerator.

get_random_params(rng: Generator) → T