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

This function returns a logger object that is set up to perform logging using Bob loggers. 
Adds the verbosity command line option to the given parser. 


Sets the log level for the given logger. 

Random Numbers¶
A MersenneTwister Random Number Generator (RNG) 

Models a random uniform distribution 

Models a random normal distribution 

Models a random lognormal distribution 

Models a random gamma distribution 

Models a random binomial distribution 

Models a random discrete distribution 


A purepython version of the boost::variate_generator<> class 
Functions¶

Converts array data type, with optional range squash/expansion 
Returns a string containing the configuration information. 
Details¶
Setsup logging, centrally for Bob (including C++ code).

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

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.
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. Ifstream
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
: callableA python callable that receives an
str
and dumps messages to the desired output channelstream
: 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.
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 toshort_option (
str
, optional) – The short command line option that should be used for increasing the verbosity. By default,'v'
is considered as the shortcut
boost::random classes and methods

class
bob.core.random.
mt19937
¶ Bases:
object
A MersenneTwister Random Number Generator (RNG)
A Random Number Generator (RNG) based on the work Mersenne Twister: A 623dimensionally equidistributed uniform pseudorandom 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. 330
Objects of this class support comparison operators such as
==
or!=
and setting the seed with the methodseed()
. 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
: intA 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[ (realvalued)
Constructor Documentation:
bob.core.random.uniform (dtype, [min], [max])
Constructs a new uniform distribution object
If the values
min
andmax
are not given, they are assumed to bemin=0
andmax=9
, for integral distributions andmin=0.0
andmax=1.0
for realvalued distributions.Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution for
min
: dtype[Default: 0] The minimum value to draw
max
: dtype[Default: 1. (for realvalued
dtype
) or 9 (for integraldtype
)] The maximum value to be drawnClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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 realvalued 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\)) andsigma
(\(\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 dtypeThe data type to get the distribution for; only realvalued 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 thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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\)) andsigma
(\(\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 dtypeThe data type to get the distribution for; only realvalued 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 thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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^{\alpha1}\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 dtypeThe data type to get the distribution for; only realvalued 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 thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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(1p)^{tk}\]where
t
andp
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 distributionp
: float[Default:
0.5
] The \(p\) parameter of the binomial distributionClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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\), withP = 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 dtypeThe data type to get the distribution for; only integral types are supported
probabilities
: [float] or iterable of floatsThe probabilities for drawing index
i
; this also defines the number of values that are drawnClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to use
Returns:
value
: dtypeA 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 purepython version of the boost::variate_generator<> class
Constructor Parameters:
engine
mt19937
An instance of the already initialized RNG you would like to use.
distribution
one of the distributions defined inbob.core.random
The distribution to respect when generating scalars using the engine. The distribution object should be previously initialized.

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_likeInput array
dtype
:numpy.dtype
or anything convertibleThe element data type for the returned
converted
arraydest_range
: (dtype, dtype)[Default: full range of
dtype
] The range[min, max]
to be deployed at theconverted
arraysource_range
: (X, X)[Default: full range of
src
data type] Determines the input range[min,max]
that will be used for scalingReturns:
converted
: array_likeA new array with the same shape as
src
, but rescaled and with its element type as given by thedtype

bob.core.
get_macros
() → macros[source]¶ Returns a list of preprocessor macros, such as
[(HAVE_BOOST, 1)]
. This function is automatically used bybob.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.