imgaug.random

Classes and functions related to pseudo-random number generation.

This module deals with the generation of pseudo-random numbers. It provides the RNG class, which is the primary random number generator in imgaug. It also provides various utility functions related random number generation, such as copying random number generators or setting their state.

The main benefit of this module is to hide the actually used random number generation classes and methods behin imgaug-specific classes and methods. This allows to deal with numpy using two different interfaces (one old interface in numpy <=1.16 and a new one in numpy 1.17+). It also allows to potentially switch to a different framework/library in the future.

Definitions

  • numpy generator or numpy random number generator: Usually an instance of numpy.random.Generator. Can often also denote an instance of numpy.random.RandomState as both have almost the same interface.
  • RandomState: An instance of numpy.random.RandomState. Note that outside of this module, the term “random state” often roughly translates to “any random number generator with numpy-like interface in a given state”, i.e. it can then include instances of numpy.random.Generator or RNG.
  • RNG: An instance of RNG.

Examples

>>> import imgaug.random as iarandom
>>> rng = iarandom.RNG(1234)
>>> rng.integers(0, 1000)

Initialize a random number generator with seed 1234, then sample a single integer from the discrete interval [0, 1000). This will use a numpy.random.Generator in numpy 1.17+ and automatically fall back to numpy.random.RandomState in numpy <=1.16.

class imgaug.random.RNG(generator)[source]

Bases: object

Random number generator for imgaug.

This class is a wrapper around numpy.random.Generator and automatically falls back to numpy.random.RandomState in case of numpy version 1.16 or lower. It allows to use numpy 1.17’s sampling functions in 1.16 too and supports a variety of useful functions on the wrapped sampler, e.g. gettings its state or copying it.

Not supported sampling functions of numpy <=1.16:

  • numpy.random.RandomState.rand()
  • numpy.random.RandomState.randn()
  • numpy.random.RandomState.randint()
  • numpy.random.RandomState.random_integers()
  • numpy.random.RandomState.random_sample()
  • numpy.random.RandomState.ranf()
  • numpy.random.RandomState.sample()
  • numpy.random.RandomState.seed()
  • numpy.random.RandomState.get_state()
  • numpy.random.RandomState.set_state()

In choice(), the axis argument is not yet supported.

Parameters:

generator (None or int or RNG or numpy.random.Generator or numpy.random.BitGenerator or numpy.random.SeedSequence or numpy.random.RandomState) – The numpy random number generator to use. In case of numpy version 1.17 or later, this shouldn’t be a RandomState as that class is outdated. Behaviour for different datatypes:

  • If None: The global RNG is wrapped by this RNG (they are then effectively identical, any sampling on this RNG will affect the global RNG).
  • If int: In numpy 1.17+, the value is used as a seed for a Generator wrapped by this RNG. I.e. it will be provided as the entropy to a SeedSequence, which will then be used for an SFC64 bit generator and wrapped by a Generator. In numpy <=1.16, the value is used as a seed for a RandomState, which is then wrapped by this RNG.
  • If RNG: That RNG’s generator attribute will be used as the generator for this RNG, i.e. the same as RNG(other_rng.generator).
  • If numpy.random.Generator: That generator will be wrapped.
  • If numpy.random.BitGenerator: A numpy generator will be created (and wrapped by this RNG) that contains the bit generator.
  • If numpy.random.SeedSequence: A numpy generator will be created (and wrapped by this RNG) that contains an SFC64 bit generator initialized with the given SeedSequence.
  • If numpy.random.RandomState: In numpy <=1.16, this RandomState will be wrapped and used to sample random values. In numpy 1.17+, a seed will be derived from this RandomState and a new numpy.generator.Generator based on an SFC64 bit generator will be created and wrapped by this RNG.
Attributes:
state

Get the state of this RNG.

Methods

advance_(self) Advance the RNG’s internal state in-place by one step.
beta(self, a, b[, size]) Call numpy.random.Generator.beta().
binomial(self, n, p[, size]) Call numpy.random.Generator.binomial().
bytes(self, length) Call numpy.random.Generator.bytes().
chisquare(self, df[, size]) Call numpy.random.Generator.chisquare().
choice(self, a[, size, replace, p]) Call numpy.random.Generator.choice().
copy(self) Create a copy of this RNG.
copy_unless_global_rng(self) Create a copy of this RNG unless it is the global RNG.
create_fully_random() Create a new RNG, based on entropy provided from the OS.
create_pseudo_random_() Create a new RNG in pseudo-random fashion.
derive_rng_(self) Create a child RNG.
derive_rngs_(self, n) Create n child RNGs.
dirichlet(self, alpha[, size]) Call numpy.random.Generator.dirichlet().
duplicate(self, n) Create a list containing n times this RNG.
equals(self, other) Estimate whether this RNG and other have the same state.
equals_global_rng(self) Estimate whether this RNG has the same state as the global RNG.
exponential(self[, scale, size]) Call numpy.random.Generator.exponential().
f(self, dfnum, dfden[, size]) Call numpy.random.Generator.f().
gamma(self, shape[, scale, size]) Call numpy.random.Generator.gamma().
generate_seed_(self) Sample a random seed.
generate_seeds_(self, n) Generate n random seed values.
geometric(self, p[, size]) Call numpy.random.Generator.geometric().
gumbel(self[, loc, scale, size]) Call numpy.random.Generator.gumbel().
hypergeometric(self, ngood, nbad, nsample[, …]) Call numpy.random.Generator.hypergeometric().
integers(self, low[, high, size, dtype, …]) Call numpy’s integers() or randint().
is_global_rng(self) Estimate whether this RNG is identical to the global RNG.
laplace(self[, loc, scale, size]) Call numpy.random.Generator.laplace().
logistic(self[, loc, scale, size]) Call numpy.random.Generator.logistic().
lognormal(self[, mean, sigma, size]) Call numpy.random.Generator.lognormal().
logseries(self, p[, size]) Call numpy.random.Generator.logseries().
multinomial(self, n, pvals[, size]) Call numpy.random.Generator.multinomial().
multivariate_normal(self, mean, cov[, size, …]) Call numpy.random.Generator.multivariate_normal().
negative_binomial(self, n, p[, size]) Call numpy.random.Generator.negative_binomial().
noncentral_chisquare(self, df, nonc[, size]) Call numpy.random.Generator.noncentral_chisquare().
noncentral_f(self, dfnum, dfden, nonc[, size]) Call numpy.random.Generator.noncentral_f().
normal(self[, loc, scale, size]) Call numpy.random.Generator.normal().
pareto(self, a[, size]) Call numpy.random.Generator.pareto().
permutation(self, x) Call numpy.random.Generator.permutation().
poisson(self[, lam, size]) Call numpy.random.Generator.poisson().
power(self, a[, size]) Call numpy.random.Generator.power().
rand(self, *args) Call numpy.random.RandomState.rand().
randint(self, low[, high, size, dtype]) Call numpy.random.RandomState.randint().
randn(self, *args) Call numpy.random.RandomState.randn().
random(self, size[, dtype, out]) Call numpy’s random() or random_sample().
random_integers(self, low[, high, size]) Call numpy.random.RandomState.random_integers().
random_sample(self, size) Call numpy.random.RandomState.random_sample().
rayleigh(self[, scale, size]) Call numpy.random.Generator.rayleigh().
reset_cache_(self) Reset all cache of this RNG.
set_state_(self, value) Set the state if the RNG in-place.
shuffle(self, x) Call numpy.random.Generator.shuffle().
standard_cauchy(self[, size]) Call numpy.random.Generator.standard_cauchy().
standard_exponential(self[, size, dtype, …]) Call numpy.random.Generator.standard_exponential().
standard_gamma(self, shape[, size, dtype, out]) Call numpy.random.Generator.standard_gamma().
standard_normal(self[, size, dtype, out]) Call numpy.random.Generator.standard_normal().
standard_t(self, df[, size]) Call numpy.random.Generator.standard_t().
tomaxint(self[, size]) Call numpy.random.RandomState.tomaxint().
triangular(self, left, mode, right[, size]) Call numpy.random.Generator.triangular().
uniform(self[, low, high, size]) Call numpy.random.Generator.uniform().
use_state_of_(self, other) Copy and use (in-place) the state of another RNG.
vonmises(self, mu, kappa[, size]) Call numpy.random.Generator.vonmises().
wald(self, mean, scale[, size]) Call numpy.random.Generator.wald().
weibull(self, a[, size]) Call numpy.random.Generator.weibull().
zipf(self, a[, size]) Call numpy.random.Generator.zipf().
advance_(self)[source]

Advance the RNG’s internal state in-place by one step.

This advances the underlying generator’s state.

Note

This simply samples one or more random values. This means that a call of this method will not completely change the outputs of the next called sampling method. To achieve more drastic output changes, call derive_rng_().

Returns:The RNG itself.
Return type:RNG
beta(self, a, b, size=None)[source]

Call numpy.random.Generator.beta().

binomial(self, n, p, size=None)[source]

Call numpy.random.Generator.binomial().

bytes(self, length)[source]

Call numpy.random.Generator.bytes().

chisquare(self, df, size=None)[source]

Call numpy.random.Generator.chisquare().

choice(self, a, size=None, replace=True, p=None)[source]

Call numpy.random.Generator.choice().

copy(self)[source]

Create a copy of this RNG.

Returns:Copy of this RNG. The copy will produce the same random samples.
Return type:RNG
copy_unless_global_rng(self)[source]

Create a copy of this RNG unless it is the global RNG.

Returns:Copy of this RNG unless it is the global RNG. In the latter case the RNG instance itself will be returned without any changes.
Return type:RNG
classmethod create_fully_random()[source]

Create a new RNG, based on entropy provided from the OS.

Returns:A new RNG. It is not derived from any other previously created RNG, nor does it depend on the seeding of imgaug or numpy.
Return type:RNG
classmethod create_pseudo_random_()[source]

Create a new RNG in pseudo-random fashion.

A seed will be sampled from the current global RNG and used to initialize the new RNG.

This advandes the global RNG’s state.

Returns:A new RNG, derived from the current global RNG.
Return type:RNG
derive_rng_(self)[source]

Create a child RNG.

This advances the underlying generator’s state.

Returns:A child RNG.
Return type:RNG
derive_rngs_(self, n)[source]

Create n child RNGs.

This advances the underlying generator’s state.

Parameters:n (int) – Number of child RNGs to derive.
Returns:Child RNGs.
Return type:list of RNG
dirichlet(self, alpha, size=None)[source]

Call numpy.random.Generator.dirichlet().

duplicate(self, n)[source]

Create a list containing n times this RNG.

This method was mainly introduced as a replacement for previous calls of derive_rngs_(). These calls turned out to be very slow in numpy 1.17+ and were hence replaced by simple duplication (except for the cases where child RNGs absolutely had to be created). This RNG duplication method doesn’t help very much against code repetition, but it does mark the points where it would be desirable to create child RNGs for various reasons. Once deriving child RNGs is somehow sped up in the future, these calls can again be easily found and replaced.

Parameters:n (int) – Length of the output list.
Returns:List containing n times this RNG (same instances, no copies).
Return type:list of RNG
equals(self, other)[source]

Estimate whether this RNG and other have the same state.

Returns:True if this RNG’s generator and the generator of other have equal internal states. False otherwise.
Return type:bool
equals_global_rng(self)[source]

Estimate whether this RNG has the same state as the global RNG.

Returns:True is this RNG has the same state as the global RNG, i.e. it will lead to the same sampled values given the same sampling method calls. The RNGs don’t have to be identical object instances, which protects against e.g. copy effects. False otherwise.
Return type:bool
exponential(self, scale=1.0, size=None)[source]

Call numpy.random.Generator.exponential().

f(self, dfnum, dfden, size=None)[source]

Call numpy.random.Generator.f().

gamma(self, shape, scale=1.0, size=None)[source]

Call numpy.random.Generator.gamma().

generate_seed_(self)[source]

Sample a random seed.

This advances the underlying generator’s state.

See SEED_MIN_VALUE and SEED_MAX_VALUE for the seed’s value range.

Returns:The sampled seed.
Return type:int
generate_seeds_(self, n)[source]

Generate n random seed values.

This advances the underlying generator’s state.

See SEED_MIN_VALUE and SEED_MAX_VALUE for the seed’s value range.

Parameters:n (int) – Number of seeds to sample.
Returns:1D-array of int32 seeds.
Return type:ndarray
geometric(self, p, size=None)[source]

Call numpy.random.Generator.geometric().

gumbel(self, loc=0.0, scale=1.0, size=None)[source]

Call numpy.random.Generator.gumbel().

hypergeometric(self, ngood, nbad, nsample, size=None)[source]

Call numpy.random.Generator.hypergeometric().

integers(self, low, high=None, size=None, dtype='int32', endpoint=False)[source]

Call numpy’s integers() or randint().

Note

Changed dtype argument default value from numpy’s int64 to int32.

is_global_rng(self)[source]

Estimate whether this RNG is identical to the global RNG.

Returns:True is this RNG’s underlying generator is identical to the global RNG’s underlying generator. The RNGs themselves may be different, only the wrapped generator matters. False otherwise.
Return type:bool
laplace(self, loc=0.0, scale=1.0, size=None)[source]

Call numpy.random.Generator.laplace().

logistic(self, loc=0.0, scale=1.0, size=None)[source]

Call numpy.random.Generator.logistic().

lognormal(self, mean=0.0, sigma=1.0, size=None)[source]

Call numpy.random.Generator.lognormal().

logseries(self, p, size=None)[source]

Call numpy.random.Generator.logseries().

multinomial(self, n, pvals, size=None)[source]

Call numpy.random.Generator.multinomial().

multivariate_normal(self, mean, cov, size=None, check_valid='warn', tol=1e-08)[source]

Call numpy.random.Generator.multivariate_normal().

negative_binomial(self, n, p, size=None)[source]

Call numpy.random.Generator.negative_binomial().

noncentral_chisquare(self, df, nonc, size=None)[source]

Call numpy.random.Generator.noncentral_chisquare().

noncentral_f(self, dfnum, dfden, nonc, size=None)[source]

Call numpy.random.Generator.noncentral_f().

normal(self, loc=0.0, scale=1.0, size=None)[source]

Call numpy.random.Generator.normal().

pareto(self, a, size=None)[source]

Call numpy.random.Generator.pareto().

permutation(self, x)[source]

Call numpy.random.Generator.permutation().

poisson(self, lam=1.0, size=None)[source]

Call numpy.random.Generator.poisson().

power(self, a, size=None)[source]

Call numpy.random.Generator.power().

rand(self, *args)[source]

Call numpy.random.RandomState.rand().

Warning

This method is outdated in numpy. Use RNG.random() instead.

Added in 0.4.0.

randint(self, low, high=None, size=None, dtype='int32')[source]

Call numpy.random.RandomState.randint().

Note

Changed dtype argument default value from numpy’s I to int32.

Warning

This method is outdated in numpy. Use RNG.integers() instead.

Added in 0.4.0.

randn(self, *args)[source]

Call numpy.random.RandomState.randn().

Warning

This method is outdated in numpy. Use RNG.standard_normal() instead.

Added in 0.4.0.

random(self, size, dtype='float32', out=None)[source]

Call numpy’s random() or random_sample().

Note

Changed dtype argument default value from numpy’s d to float32.

random_integers(self, low, high=None, size=None)[source]

Call numpy.random.RandomState.random_integers().

Warning

This method is outdated in numpy. Use RNG.integers() instead.

Added in 0.4.0.

random_sample(self, size)[source]

Call numpy.random.RandomState.random_sample().

Warning

This method is outdated in numpy. Use RNG.uniform() instead.

Added in 0.4.0.

rayleigh(self, scale=1.0, size=None)[source]

Call numpy.random.Generator.rayleigh().

reset_cache_(self)[source]

Reset all cache of this RNG.

Returns:The RNG itself.
Return type:RNG
set_state_(self, value)[source]

Set the state if the RNG in-place.

Parameters:value (tuple or dict) – The new state of the RNG. Should correspond to the output of the state property.
Returns:The RNG itself.
Return type:RNG
shuffle(self, x)[source]

Call numpy.random.Generator.shuffle().

standard_cauchy(self, size=None)[source]

Call numpy.random.Generator.standard_cauchy().

standard_exponential(self, size=None, dtype='float32', method='zig', out=None)[source]

Call numpy.random.Generator.standard_exponential().

Note

Changed dtype argument default value from numpy’s d to float32.

standard_gamma(self, shape, size=None, dtype='float32', out=None)[source]

Call numpy.random.Generator.standard_gamma().

Note

Changed dtype argument default value from numpy’s d to float32.

standard_normal(self, size=None, dtype='float32', out=None)[source]

Call numpy.random.Generator.standard_normal().

Note

Changed dtype argument default value from numpy’s d to float32.

standard_t(self, df, size=None)[source]

Call numpy.random.Generator.standard_t().

state

Get the state of this RNG.

Returns:The state of the RNG. In numpy 1.17+, the bit generator’s state will be returned. In numpy <=1.16, the RandomState ‘s state is returned. In both cases the state is a copy. In-place changes will not affect the RNG.
Return type:tuple or dict
tomaxint(self, size=None)[source]

Call numpy.random.RandomState.tomaxint().

Warning

This method is outdated in numpy. Use RNG.integers() instead.

Added in 0.4.0.

triangular(self, left, mode, right, size=None)[source]

Call numpy.random.Generator.triangular().

uniform(self, low=0.0, high=1.0, size=None)[source]

Call numpy.random.Generator.uniform().

use_state_of_(self, other)[source]

Copy and use (in-place) the state of another RNG.

Note

It is often sensible to first verify that neither this RNG nor other are identical to the global RNG.

Parameters:other (RNG) – The other RNG, which’s state will be copied.
Returns:The RNG itself.
Return type:RNG
vonmises(self, mu, kappa, size=None)[source]

Call numpy.random.Generator.vonmises().

wald(self, mean, scale, size=None)[source]

Call numpy.random.Generator.wald().

weibull(self, a, size=None)[source]

Call numpy.random.Generator.weibull().

zipf(self, a, size=None)[source]

Call numpy.random.Generator.zipf().

imgaug.random.advance_generator_(generator)[source]

Advance a numpy random generator’s internal state in-place by one step.

This advances the generator’s state.

Note

This simply samples one or more random values. This means that a call of this method will not completely change the outputs of the next called sampling method. To achieve more drastic output changes, call derive_generator_().

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – Generator of which to advance the internal state.
imgaug.random.convert_seed_sequence_to_generator(seed_sequence)[source]

Convert a seed sequence to a numpy (random number) generator.

Parameters:seed_sequence (numpy.random.SeedSequence) – The seed value to use.
Returns:Generator initialized with the provided seed sequence.
Return type:numpy.random.Generator
imgaug.random.convert_seed_to_generator(entropy)[source]

Convert a seed value to a numpy (random number) generator.

Parameters:entropy (int) – The seed value to use.
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. Both are initialized with the provided seed.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.copy_generator(generator)[source]

Copy an existing numpy (random number) generator.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator to copy.
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. Both are copies of the input argument.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.copy_generator_unless_global_generator(generator)[source]

Copy a numpy generator unless it is the current global generator.

“global generator” here denotes the generator contained in the global RNG’s .generator attribute.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator to copy.
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. Both are copies of the input argument, unless that input is identical to the global generator. If it is identical, the instance itself will be returned without copying it.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.create_fully_random_generator()[source]

Create a new numpy (random) generator, derived from OS’s entropy.

Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. Both are initialized with entropy requested from the OS. They are hence independent of entered seeds or the library’s global RNG.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.create_pseudo_random_generator_()[source]

Create a new numpy (random) generator, derived from the global RNG.

This function advances the global RNG’s state.

Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. Both are initialized with a seed sampled from the global RNG.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.derive_generator_(generator)[source]

Create a child numpy (random number) generator from an existing one.

This advances the generator’s state.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator from which to derive a new child generator.
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. In both cases a derived child generator.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.derive_generators_(generator, n)[source]

Create child numpy (random number) generators from an existing one.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – The generator from which to derive new child generators.
  • n (int) – Number of child generators to derive.
Returns:

In numpy <=1.16 a list of RandomState s, in 1.17+ a list of Generator s. In both cases lists of derived child generators.

Return type:

list of numpy.random.Generator or list of numpy.random.RandomState

imgaug.random.generate_seed_(generator)[source]

Sample a seed from the provided generator.

This function advances the generator’s state.

See SEED_MIN_VALUE and SEED_MAX_VALUE for the seed’s value range.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator from which to sample the seed.
Returns:The sampled seed.
Return type:int
imgaug.random.generate_seeds_(generator, n)[source]

Sample n seeds from the provided generator.

This function advances the generator’s state.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – The generator from which to sample the seed.
  • n (int) – Number of seeds to sample.
Returns:

1D-array of int32 seeds.

Return type:

ndarray

imgaug.random.get_generator_state(generator)[source]

Get the state of this provided generator.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator, which’s state is supposed to be extracted.
Returns:The state of the generator. In numpy 1.17+, the bit generator’s state will be returned. In numpy <=1.16, the RandomState ‘s state is returned. In both cases the state is a copy. In-place changes will not affect the RNG.
Return type:tuple or dict
imgaug.random.get_global_rng()[source]

Get or create the current global RNG of imgaug.

Note that the first call to this function will create a global RNG.

Returns:The global RNG to use.
Return type:RNG
imgaug.random.is_generator_equal_to(generator, other_generator)[source]

Estimate whether two generator have the same class and state.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – First generator used in the comparison.
  • other_generator (numpy.random.Generator or numpy.random.RandomState) – Second generator used in the comparison.
Returns:

True if generator ‘s class and state are the same as the class and state of other_generator. False otherwise.

Return type:

bool

imgaug.random.normalize_generator(generator)[source]

Normalize various inputs to a numpy (random number) generator.

This function will first copy the provided argument, i.e. it never returns a provided instance itself.

Parameters:

generator (None or int or numpy.random.Generator or numpy.random.BitGenerator or numpy.random.SeedSequence or numpy.random.RandomState) – The numpy random number generator to normalize. In case of numpy version 1.17 or later, this shouldn’t be a RandomState as that class is outdated. Behaviour for different datatypes:

  • If None: The global RNG’s generator is returned.
  • If int: In numpy 1.17+, the value is used as a seed for a Generator, i.e. it will be provided as the entropy to a SeedSequence, which will then be used for an SFC64 bit generator and wrapped by a Generator, which is then returned. In numpy <=1.16, the value is used as a seed for a RandomState, which will then be returned.
  • If numpy.random.Generator: That generator will be returned.
  • If numpy.random.BitGenerator: A numpy generator will be created and returned that contains the bit generator.
  • If numpy.random.SeedSequence: A numpy generator will be created and returned that contains an SFC64 bit generator initialized with the given SeedSequence.
  • If numpy.random.RandomState: In numpy <=1.16, this RandomState will be returned. In numpy 1.17+, a seed will be derived from this RandomState and a new numpy.generator.Generator based on an SFC64 bit generator will be created and returned.
Returns:

In numpy <=1.16 a RandomState, in 1.17+ a Generator (even if the input was a RandomState).

Return type:

numpy.random.Generator or numpy.random.RandomState

imgaug.random.normalize_generator_(generator)[source]

Normalize in-place various inputs to a numpy (random number) generator.

This function will try to return the provided instance itself.

Parameters:generator (None or int or numpy.random.Generator or numpy.random.BitGenerator or numpy.random.SeedSequence or numpy.random.RandomState) – See normalize_generator().
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator (even if the input was a RandomState).
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.polyfill_integers(generator, low, high=None, size=None, dtype='int32', endpoint=False)[source]

Sample integers from a generator in different numpy versions.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – The generator to sample from. If it is a RandomState, numpy.random.RandomState.randint() will be called, otherwise numpy.random.Generator.integers().
  • low (int or array-like of ints) – See numpy.random.Generator.integers().
  • high (int or array-like of ints, optional) – See numpy.random.Generator.integers().
  • size (int or tuple of ints, optional) – See numpy.random.Generator.integers().
  • dtype ({str, dtype}, optional) – See numpy.random.Generator.integers().
  • endpoint (bool, optional) – See numpy.random.Generator.integers().
Returns:

See numpy.random.Generator.integers().

Return type:

int or ndarray of ints

imgaug.random.polyfill_random(generator, size, dtype='float32', out=None)[source]

Sample random floats from a generator in different numpy versions.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – The generator to sample from. Both RandomState and Generator support random(), but with different interfaces.
  • size (int or tuple of ints, optional) – See numpy.random.Generator.random().
  • dtype ({str, dtype}, optional) – See numpy.random.Generator.random().
  • out (ndarray, optional) – See numpy.random.Generator.random().
Returns:

See numpy.random.Generator.random().

Return type:

float or ndarray of floats

imgaug.random.reset_generator_cache_(generator)[source]

Reset a numpy (random number) generator’s internal cache.

This function modifies the generator’s state in-place.

Parameters:generator (numpy.random.Generator or numpy.random.RandomState) – The generator of which to reset the cache.
Returns:In numpy <=1.16 a RandomState, in 1.17+ a Generator. In both cases the input argument itself.
Return type:numpy.random.Generator or numpy.random.RandomState
imgaug.random.seed(entropy)[source]

Set the seed of imgaug’s global RNG (in-place).

The global RNG controls most of the “randomness” in imgaug.

The global RNG is the default one used by all augmenters. Under special circumstances (e.g. when an augmenter is switched to deterministic mode), the global RNG is replaced with a local one. The state of that replacement may be dependent on the global RNG’s state at the time of creating the child RNG.

Parameters:entropy (int) – The seed value to use.
imgaug.random.set_generator_state_(generator, state)[source]

Set the state of a numpy (random number) generator in-place.

Parameters:
  • generator (numpy.random.Generator or numpy.random.RandomState) – The generator, which’s state is supposed to be modified.
  • state (tuple or dict) – The new state of the generator. Should correspond to the output of get_generator_state().
imgaug.random.supports_new_numpy_rng_style()[source]

Determine whether numpy supports the new random interface (v1.17+).

Returns:True if the new random interface is supported by numpy, i.e. if numpy has version 1.17 or later. Otherwise False, i.e. numpy has version 1.16 or older and numpy.random.RandomState should be used instead.
Return type:bool
class imgaug.random.temporary_numpy_seed(entropy=None)[source]

Bases: object

Context to temporarily alter the random state of numpy.random.

The random state’s internal state will be set back to the original one once the context finishes.

Added in 0.4.0.

Parameters:entropy (None or int) – The seed value to use. If None then the seed will not be altered and the internal state of numpy.random will not be reset back upon context exit (i.e. this context will do nothing).