Python API¶

This section includes information for using the pure Python API of bob.core.

Logging¶

`bob.core.log.setup`(logger_name[, format])	This function returns a logger object that is set up to perform logging using Bob loggers.
`bob.core.log.add_command_line_option`(parser)	Adds the verbosity command line option to the given parser.
`bob.core.log.set_verbosity_level`(logger, level)	Sets the log level for the given logger.
`bob.core.log.reset`	reset() -> None

Random Numbers¶

`bob.core.random.mt19937`	A Mersenne-Twister Random Number Generator (RNG)
`bob.core.random.uniform`	Models a random uniform distribution
`bob.core.random.normal`	Models a random normal distribution
`bob.core.random.lognormal`	Models a random lognormal distribution
`bob.core.random.gamma`	Models a random gamma distribution
`bob.core.random.binomial`	Models a random binomial distribution
`bob.core.random.discrete`	Models a random discrete distribution
`bob.core.random.variate_generator`(engine, ...)	A pure-python version of the boost::variate_generator<> class

Functions¶

`bob.core.convert`(src, dtype, [dest_range], ...)	Converts array data type, with optional range squash/expansion
`bob.core.get_config`()	Returns a string containing the configuration information.

Details¶

Sets-up logging, centrally for Bob (including C++ code).

bob.core.log.add_command_line_option(parser, short_option='-v')[source]¶

Adds the verbosity command line option to the given parser.

The verbosity can by set to 0 (error), 1 (warning), 2 (info) or 3 (debug) by including the according number of –verbose command line arguments (e.g., -vv for info level).

Parameters

parser (argparse.ArgumentParser or one of its derivatives) – A command line parser that you want to add a verbose option to
short_option (str, optional) – The short command line option that should be used for increasing the verbosity. By default, '-v' is considered as the shortcut

bob.core.log.reset()¶

reset() -> None
reset(callable, [stream]) -> None

Resets the standard C++ logging devices, or sets it to the given callable

This function allows you to manipulate the sinks for messages emitted in C++, using Python callables. The first variant (without parameters) will reset all logging output to sys.stderr. The second variant will reset the given logger to the given callable. If stream is not specified, it resets all loggers.

This function raises a ValueError in case of problems setting or resetting any of the streams.

Parameters:

callable : callable

A python callable that receives an str and dumps messages to the desired output channel

stream : one of (‘debug’, ‘info’, warn’, ‘error’)

[optional] If specified, only the given logger is send to the given callable. Otherwise all loggers are reset to that callable.

bob.core.log.set_verbosity_level(logger, level)[source]¶

Sets the log level for the given logger.

Parameters

logger (logging.Logger or str) – The logger to generate logs for, or the name of the module to generate logs for.
level (int) – Possible log levels are: 0: Error; 1: Warning; 2: Info; 3: Debug.

Raises

ValueError – If the level is not in range(0, 4).

bob.core.log.setup(logger_name, format='%(name)s@%(asctime)s -- %(levelname)s: %(message)s')[source]¶

This function returns a logger object that is set up to perform logging using Bob loggers.

Parameters

logger_name (str) – The name of the module to generate logs for
format (str, optional) – The format of the logs, see logging.LogRecord for more details. By default, the log contains the logger name, the log time, the log level and the massage.

Returns

logger – The logger configured for logging. The same logger can be retrieved using the logging.getLogger() function.

Return type

logging.Logger

boost::random classes and methods

class bob.core.random.mt19937¶

Bases: object

A Mersenne-Twister Random Number Generator (RNG)

A Random Number Generator (RNG) based on the work Mersenne Twister: A 623-dimensionally equidistributed uniform pseudo-random number generator, Makoto Matsumoto and Takuji Nishimura, ACM Transactions on Modeling and Computer Simulation: Special Issue on Uniform Random Number Generation, Vol. 8, No. 1, January 1998, pp. 3-30

Objects of this class support comparison operators such as == or != and setting the seed with the method seed(). Two random number generators are equal if they are at the same state – i.e. they have been initialized with the same seed and have been called the same number of times for number generation.

Constructor Documentation:

bob.core.random.mt19937 ([seed])

Constructs and initializes a random number generator

If no seed is specified, the default seed (http://www.boost.org/doc/libs/1_59_0/doc/html/boost/random/mersenne_twister_engine.html) is used.

Parameters:

seed : int

[optional] An integral value determining the initial seed

Class Members:

seed(seed) → None¶

Sets the seed for this random number generator

Parameters:

seed : int

A new seed value for this RNG

class bob.core.random.uniform¶

Bases: object

Models a random uniform distribution

On each invocation, it returns a random value uniformly distributed in the set of numbers [min, max] (integer) and [min, max[ (real-valued)

Constructor Documentation:

bob.core.random.uniform (dtype, [min], [max])

Constructs a new uniform distribution object

If the values min and max are not given, they are assumed to be min=0 and max=9, for integral distributions and min=0.0 and max=1.0 for real-valued distributions.

Parameters:

dtype : numpy.dtype or anything that converts to a dtype

The data type to get the distribution for

min : dtype

[Default: 0] The minimum value to draw

max : dtype

[Default: 1. (for real-valued dtype) or 9 (for integral dtype)] The maximum value to be drawn

Class Members:

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the uniform distribution

dtype¶: numpy.dtype <– The type of scalars produced by this uniform distribution

max¶

dtype <– The largest value that the distributioncan produce

Integer uniform distributions are bound at [min, max], while real-valued distributions are bound at [min, max[.

min¶: dtype <– The smallest value that the distribution can produce

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

class bob.core.random.normal¶

Bases: object

Models a random normal distribution

This distribution produces random numbers \(x\) distributed with the probability density function

\[p(x) = \frac{1}{\sqrt{2\pi\sigma}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}\]

where the mean (\(\mu\)) and sigma (\(\sigma\), the standard deviation) are the parameters of this distribution class.

Constructor Documentation:

bob.core.random.normal (dtype, [mean], [sigma])

Constructs a new normal distribution object

Parameters:

dtype : numpy.dtype or anything that converts to a dtype

The data type to get the distribution for; only real-valued types are supported

mean : dtype

[Default: 0.] The mean \(\mu\) of the normal distibution

sigma : dtype

[Default: 1.] The standard deviation \(\sigma\) of the normal distributiuon

Class Members:

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the normal distribution

dtype¶: numpy.dtype <– The type of scalars produced by this normal distribution

mean¶: dtype <– The mean value the distribution will produce.

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

sigma¶: dtype <– The standard deviation the distribution will have

class bob.core.random.lognormal¶

Bases: object

Models a random lognormal distribution

This distribution produces random numbers \(x\) distributed with the probability density function

\[p(x) = \frac{1}{x \sigma_N \sqrt{2\pi}} e^{\frac{-\left(\log(x)-\mu_N\right)^2}{2\sigma_N^2}}\]

for \(x > 0\) and \(\sigma_N = \sqrt{\log\left(1 + \frac{\sigma^2}{\mu^2}\right)}\), where the mean (\(\mu\)) and sigma (\(\sigma\), the standard deviation) are the parameters of this distribution class.

Constructor Documentation:

bob.core.random.lognormal (dtype, [mean], [sigma])

Constructs a new lognormal distribution object

Parameters:

dtype : numpy.dtype or anything that converts to a dtype

The data type to get the distribution for; only real-valued types are supported

mean : dtype

[Default: 0.] The mean \(\mu\) of the lognormal distibution

sigma : dtype

[Default: 1.] The standard deviation \(\sigma\) of the lognormal distributiuon

Class Members:

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the lognormal distribution

dtype¶: numpy.dtype <– The type of scalars produced by this normal distribution

mean¶: dtype <– The mean value the distribution will produce.

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

sigma¶: dtype <– The standard deviation the distribution will have

class bob.core.random.gamma¶

Bases: object

Models a random gamma distribution

This distribution produces random numbers \(x\) distributed with the probability density function

\[p(x) = x^{\alpha-1}\frac{e^{-x}}{\Gamma(\alpha)}\]

where alpha (\(\alpha\)) is a parameter of this distribution class.

Constructor Documentation:

bob.core.random.gamma (dtype, [alpha])

Constructs a new gamma distribution object

Parameters:

dtype : numpy.dtype or anything that converts to a dtype

The data type to get the distribution for; only real-valued types are supported

alpha : dtype

[Default: 1.] The mean \(\alpha\) of the gamma distibution

Class Members:

alpha¶: dtype <– The alpha parameter that the distribution currently has

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the gamma distribution

dtype¶: numpy.dtype <– The type of scalars produced by this normal distribution

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

class bob.core.random.binomial¶

Bases: object

Models a random binomial distribution

This distribution produces random numbers \(x\) distributed with the probability density function

\[{{t}\choose{k}}p^k(1-p)^{t-k}\]

where t and p are parameters of the distribution.

Warning

This distribution requires that \(t >= 0\) and that \(0 <= p <= 1\).

Constructor Documentation:

bob.core.random.binomial (dtype, [t], [p])

Creates a new binomial distribution object

Parameters:

dtype : numpy.dtype

The data type for the drawn random numbers; only integral types are supported

t : float

[Default: 1.] The \(t\) parameter of the binomial distribution

p : float

[Default: 0.5] The \(p\) parameter of the binomial distribution

Class Members:

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the binomial distribution

dtype¶: numpy.dtype <– The type of scalars produced by this binomial distribution

p¶: float <– The parameter p of the distribution

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

t¶: float <– The parameter t of the distribution

class bob.core.random.discrete¶

Bases: object

Models a random discrete distribution

A discrete distribution can only assume certain values, which for this class is defined as a number i in the range [0, len(probabilities)[. Note that the condition \(\sum(P) = 1\), with P = probabilities, is enforced by normalizing the input values so that the sum over all probabilities always equals 1.

Constructor Documentation:

bob.core.random.discrete (dtype, probabilities)

Constructs a new discrete distribution object

Parameters:

dtype : numpy.dtype or anything that converts to a dtype

The data type to get the distribution for; only integral types are supported

probabilities : [float] or iterable of floats

The probabilities for drawing index i; this also defines the number of values that are drawn

Class Members:

draw(rng) → value¶

Draws one random number from this distribution using the given rng

Note

The __call__() function is a synonym for this draw.

Parameters:

rng : mt19937

The random number generator to use

Returns:

value : dtype

A random value that follows the discrete distribution

dtype¶: numpy.dtype <– The type of scalars produced by this discrete distribution

probabilities¶: [float] <– The values have been set for the discrete probabilities of every entry in this distribution

reset() → None¶

Resets this distribution

After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

class bob.core.random.variate_generator(engine, distribution)[source]¶

Bases: object

A pure-python version of the boost::variate_generator<> class

Constructor Parameters:

enginemt19937: An instance of the already initialized RNG you would like to use.
distributionone of the distributions defined in bob.core.random: The distribution to respect when generating scalars using the engine. The distribution object should be previously initialized.

seed(value)[source]¶: Resets the seed of the variate_generator with an (int) value

bob.core.convert(src, dtype[, dest_range][, source_range]) → converted¶

Converts array data type, with optional range squash/expansion

This function allows to convert/rescale a array of a given type into another array of a possibly different type. Typically, this can be used to rescale a 16 bit precision grayscale image (2D array) into an 8 bit precision grayscale image.

Parameters:

src : array_like

Input array

dtype : numpy.dtype or anything convertible

The element data type for the returned converted array

dest_range : (dtype, dtype)

[Default: full range of dtype] The range [min, max] to be deployed at the converted array

source_range : (X, X)

[Default: full range of src data type] Determines the input range [min,max] that will be used for scaling

Returns:

converted : array_like

A new array with the same shape as src, but re-scaled and with its element type as given by the dtype

bob.core.get_config()[source]¶: Returns a string containing the configuration information.

bob.core.get_macros() → macros[source]¶

Returns a list of preprocessor macros, such as [(HAVE_BOOST, 1)]. This function is automatically used by bob.extension.get_bob_libraries() to retrieve the prerpocessor definitions that are required to use the C bindings of this library in dependent classes. You shouldn’t normally need to call this function by hand.

Returns:

macros[str]: The list of preprocessor macros required to use the C bindings of this class.