Python API

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

Logging

Sets-up logging, centrally for Bob.

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

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

Keyword parameters:

logger_name : str

The name of the module to generate logs for

format : str

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 : logging.Logger

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

bob.core.log.add_command_line_option(parser, short_option='-v')

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).

Keyword 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

The short command line option that should be used for increasing the verbosity.

bob.core.log.set_verbosity_level(logger, level)

Sets the log level.

Keyword 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.

bob.core.log.reset([debug[, info[, warn[, error]]]]) → None

Resets the standard C++ logging devices.

This function allows you to manipulate the sinks for messages emitted in C++, using Python callables.

Keyword Parameters:

debug

[optional] (callable) A callable that receives a string and dumps messages to the desired output channel.

info

[optional] (callable) A callable that receives a string and dumps messages to the desired output channel.

warn

[optional] (callable) A callable that receives a string and dumps messages to the desired output channel.

error

[optional] (callable) A callable that receives a string and dumps messages to the desired output channel.

Raises a ValueError in case of problems setting or resetting any of the streams.

Random Numbers

boost::random classes and methods

class bob.core.random.variate_generator(engine, distribution)

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

Keyword parameters:

engine

An instance of the RNG you would like to use. This has to be an object of the class bob.core.random.mt19937, already initialized.

distribution

The distribution to respect when generating scalars using the engine. The distribution object should be previously initialized.

seed(value)

Resets the seed of the variate_generator with a (integer) value

class bob.core.random.binomial

Bases: object

binomial(dtype, [t=1.0, p=0.5]]) -> new binomial distribution

Models a random binomial distribution

This distribution class models a binomial random distribution. Such a 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.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this binomial distribution.

p

x.p -> scalar

This value corresponds to the parameter p of the distribution.

reset() → None

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

x.t -> scalar

This value corresponds to the parameter t of the distribution.

class bob.core.random.discrete

Bases: object

discrete(dtype, probabilities) -> new discrete distribution

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)]. Notice 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.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this discrete distribution.

probabilities

x.probabilities -> sequence

This property corresponds to the values you have set for the discrete probabilities of every entry in this distribution.

reset() → None

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

gamma(dtype, [alpha=1.]]) -> new gamma distribution

Models a random gamma distribution

This distribution class models a gamma random distribution. Such a distribution produces random numbers x distributed with the probability density function p(x) = x^{\alpha-1}\frac{e^{-x}}{\Gamma(\alpha)}, where the alpha (\alpha) is a parameter of the distribution.

alpha

x.alpha -> scalar

This value corresponds to the alpha parameter the distribution current has.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this gamma distribution.

reset() → None

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

lognormal(dtype, [mean=0., sigma=1.]]) -> new log-normal distribution

Models a random lognormal distribution

This distribution models a log-normal random distribution. Such a 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) the parameters of the distribution.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this lognormal distribution.

mean

x.mean -> scalar

This value corresponds to the mean value the distribution will produce.

reset() → None

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

x.sigma -> scalar

This value corresponds to the standard deviation value the distribution will have.

class bob.core.random.mt19937

Bases: object

mt19937([seed]) -> new random number generator

A Mersenne-Twister Random Number Generator (RNG)

Constructor parameters:

seed

[optional] A integral value determining the initial seed

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(int). 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.

seed(x) → None

Sets the seed for this random number generator

This method sets the seed for this random number generator. The input value needs to be convertible to a long integer.

class bob.core.random.normal

Bases: object

normal(dtype, [mean=0., sigma=1.]]) -> new normal distribution

Models a random normal distribution

This distribution class models a normal random distribution. Such a 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) the parameters of the distribution.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this normal distribution.

mean

x.mean -> scalar

This value corresponds to the mean value the distribution will produce.

reset() → None

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

x.sigma -> scalar

This value corresponds to the standard deviation value the distribution will have.

class bob.core.random.uniform

Bases: object

uniform(dtype, [min=m, max=M]]) -> new uniform distribution

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).

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.

dtype

x.dtype -> numpy dtype

The type of scalars produced by this uniform distribution.

max

x.max -> scalar

This value corresponds to the largest value that the distribution can produce. Integer uniform distributions are bound at [min, max], while real-valued distributions are bound at [min, max[.

min

x.min -> scalar

This value corresponds to the smallest value that the distribution can produce.

reset() → None

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

Functions

bob.core.convert(array, dtype[, dst_range[, src_range]]) → array

Converts array data type, with optional range squash/expansion.

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

Keyword Parameters:

array

(array) Input array

dtype

(object) Any object that can be convertible to a numpy.dtype. Controls the output element type for the returned array.

dest_range

(tuple) Determines the range to be deployed at the returned array.

source_range

(tuple) Determines the input range that will be used for scaling.

Returns a new array with the same shape as this one, but re-scaled and with its element type as indicated by the user.