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 |
|
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
- parser (
-
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 anstr
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.
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).- logger (
-
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:
boost::random classes and methods
-
class
bob.core.random.
variate_generator
(engine, distribution)[source]¶ Bases:
object
A pure-python 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.
-
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
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 supportedt
: 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 useReturns:
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 supportedprobabilities
: [float] or iterable of floatsThe probabilities for drawing indexi
; 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 useReturns:
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.
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 dtypeThe data type to get the distribution for; only real-valued types are supportedalpha
: dtype[Default: 1.] The mean \(\alpha\) of the gamma distibutionClass 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 useReturns:
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.
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 real-valued types are supportedmean
: dtype[Default: 0.] The mean \(\mu\) of the lognormal distibutionsigma
: dtype[Default: 1.] The standard deviation \(\sigma\) of the lognormal distributiuonClass 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 useReturns:
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.
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 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 seedClass 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.
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 real-valued types are supportedmean
: dtype[Default: 0.] The mean \(\mu\) of the normal distibutionsigma
: dtype[Default: 1.] The standard deviation \(\sigma\) of the normal distributiuonClass 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 useReturns:
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.
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
andmax
are not given, they are assumed to bemin=0
andmax=9
, for integral distributions andmin=0.0
andmax=1.0
for real-valued distributions.Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution formin
: dtype[Default: 0] The minimum value to drawmax
: dtype[Default: 1. (for real-valueddtype
) 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 useReturns:
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 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
-
-
bob.core.
get_macros
() → macros[source]¶ Returns a list of preprocessor macros, such as
[(HAVE_BOOST, 1), (BOOST_VERSION,xx)]
. 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.
-
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 arraydtype
:numpy.dtype
or anything convertibleThe element data type for the returnedconverted
arraydest_range
: (dtype, dtype)[Default: full range ofdtype
] The range[min, max]
to be deployed at theconverted
arraysource_range
: (X, X)[Default: full range ofsrc
data type] Determines the input range[min,max]
that will be used for scalingReturns:
converted
: array_likeA new array with the same shape assrc
, but re-scaled and with its element type as given by thedtype