Python API¶

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

Classes¶

Trainers¶

`bob.learn.em.KMeansTrainer`	Trains a KMeans clustering k-means.This class
`bob.learn.em.ML_GMMTrainer`	This class implements the maximum likelihood M-step (MLE) of the expectation-maximisation algorithm for a GMM Machine.
`bob.learn.em.MAP_GMMTrainer`	This class implements the maximum a posteriori (MAP) M-step of the expectation-maximization algorithm for a GMM Machine.
`bob.learn.em.ISVTrainer`	ISVTrainerTrain Intersession varibility modeling ISV.
`bob.learn.em.JFATrainer`	Trains a Joint Factor Analysis (JFA) on top of GMMs
`bob.learn.em.IVectorTrainer`	IVectorTrainerTrains the Total Variability subspace $T$ to generate iVectors.
`bob.learn.em.PLDATrainer`	This class can be used to train the $F$ , $G$ and
`bob.learn.em.EMPCATrainer`	Trains a `bob.learn.linear.Machine` using an

Machines¶

`bob.learn.em.KMeansMachine`	Statistical model for the k-means .
`bob.learn.em.Gaussian`	This class implements a multivariate diagonal Gaussian distribution
`bob.learn.em.GMMStats`	A container for GMM statistics
`bob.learn.em.GMMMachine`	This class implements the statistical model for multivariate diagonal mixture Gaussian distribution (GMM).
`bob.learn.em.ISVBase`	A ISVBase instance can be seen as a container for U and D when performing Joint Factor Analysis (JFA).
`bob.learn.em.ISVMachine`	A ISVMachine.
`bob.learn.em.JFABase`	Container for $U$ , $V$ and $D$ when performing Joint Factor Analysis (JFA).
`bob.learn.em.JFAMachine`	A JFAMachine.
`bob.learn.em.IVectorMachine`	Statistical model for the Total Variability training for more
`bob.learn.em.PLDABase`	This class is a container for the $F$ (between class variantion matrix), $G$ (within class variantion matrix) and $\Sigma$ matrices and the mean vector $\mu$ of a PLDA model.
`bob.learn.em.PLDAMachine`	This class is a container for an enrolled identity/class.

Functions¶

`bob.learn.em.linear_scoring`((models, ubm, ...)	The Linear scoring is an approximation to the log-likelihood ratio that was shown to be as accurate and up to two orders of magnitude more efficient to compute [Glembek2009].
`bob.learn.em.tnorm`(...)	Normalise raw scores with T-Norm
`bob.learn.em.train`(trainer, machine, data[, ...])	Trains a machine given a trainer and the proper data
`bob.learn.em.train_jfa`(trainer, jfa_base, data)	Trains a `bob.learn.em.JFABase` given a `bob.learn.em.JFATrainer` and the proper data
`bob.learn.em.znorm`(...)	Normalise raw scores with Z-Norm
`bob.learn.em.ztnorm`(...)	Normalise raw scores with ZT-Norm.Assume that znorm and tnorm have no common subject id.
`bob.learn.em.ztnorm_same_value`(vect_a, vect_b)	Computes the matrix of boolean D for the ZT-norm, which indicates where the client ids of the T-Norm models and Z-Norm samples match.

Detailed Information¶

bob.learn.em.ztnorm_same_value(vect_a, vect_b)[source]¶

Computes the matrix of boolean D for the ZT-norm, which indicates where the client ids of the T-Norm models and Z-Norm samples match.

vect_a An (ordered) list of client_id corresponding to the T-Norm models vect_b An (ordered) list of client_id corresponding to the Z-Norm impostor samples

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

class bob.learn.em.EMPCATrainer¶

Bases: object

Trains a bob.learn.linear.Machine using an Expectation-Maximization algorithm on the given dataset [Bishop1999] [Roweis1998]

Notations used are the ones from [Bishop1999]

The probabilistic model is given by: $t = Wx + \mu + \epsilon$

$t$ is the observed data (dimension $f$ )

$W$ is a projection matrix (dimension $f \times d$ )

$x$ is the projected data (dimension $d < f$ )

$\mu$ is the mean of the data (dimension $f$ )

$\epsilon$ is the noise of the data (dimension $f$ )

Gaussian with zero-mean and covariance matrix $\sigma^2 Id$

Constructor Documentation:

bob.learn.em.EMPCATrainer (other)

bob.learn.em.EMPCATrainer ()

Creates a EMPCATrainer

Parameters:

other : bob.learn.em.EMPCATrainer

A EMPCATrainer object to be copied.

Class Members:

compute_likelihood(linear_machine) → None¶

Parameters:

linear_machine : bob.learn.linear.Machine

LinearMachine Object

e_step(linear_machine, data) → None¶

Parameters:

linear_machine : bob.learn.linear.Machine

LinearMachine Object

data : array_like <float, 2D>

Input data

initialize(linear_machine, data[, rng]) → None¶

Parameters:

linear_machine : bob.learn.linear.Machine

LinearMachine Object

data : array_like <float, 2D>

Input data

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

m_step(linear_machine, data) → None¶

Parameters:

linear_machine : bob.learn.linear.Machine

LinearMachine Object

data : array_like <float, 2D>

Input data

sigma2¶: float <– The noise sigma2 of the probabilistic model

class bob.learn.em.GMMMachine¶

Bases: object

This class implements the statistical model for multivariate diagonal mixture Gaussian distribution (GMM). A GMM is defined as $\sum_{c=0}^{C} \omega_c \mathcal{N}(x | \mu_c, \sigma_c)$ , where $C$ is the number of Gaussian components $\mu_c$ , $\sigma_c$ and $\omega_c$ are respectively the the mean, variance and the weight of each gaussian component $c$ .

See Section 2.3.9 of Bishop, “Pattern recognition and machine learning”, 2006

Constructor Documentation:

bob.learn.em.GMMMachine (n_gaussians,n_inputs)

bob.learn.em.GMMMachine (other)

bob.learn.em.GMMMachine (hdf5)

bob.learn.em.GMMMachine ()

Creates a GMMMachine

Parameters:

n_gaussians : int

Number of gaussians

n_inputs : int

Dimension of the feature vector

other : bob.learn.em.GMMMachine

A GMMMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

acc_statistics(input, stats) → None¶

Accumulate the GMM statistics (bob.learn.em.GMMStats) for this sample(s). Inputs are checked.

Parameters:

input : array_like <float, 2D>

Input vector

stats : bob.learn.em.GMMStats

Statistics of the GMM

acc_statistics_(input, stats) → None¶

Accumulate the GMM statistics (bob.learn.em.GMMStats) for this sample(s). Inputs are NOT checked.

Parameters:

input : array_like <float, 2D>

Input vector

stats : bob.learn.em.GMMStats

Statistics of the GMM

get_gaussian(i) → gaussian¶

Get the specified Gaussian (bob.learn.em.Gaussian) component.

Note

An exception is thrown if i is out of range.

Parameters:

i : int

Index of the gaussian

Returns:

gaussian : bob.learn.em.Gaussian

Gaussian object

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this GMMMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.GMMMachine

A GMMMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the GMMMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

log_likelihood(input) → output¶

Output the log likelihood of the sample, x, i.e. $log(p(x|GMM))$ . Inputs are checked.

Note

The __call__ function is an alias for this. If input is 2D the average along the samples will be computed ( $\frac{log(p(x|GMM))}{N}$ )

Parameters:

input : array_like <float, 1D>

Input vector

Returns:

output : float

The log likelihood

log_likelihood_(input) → output¶

Output the log likelihood of the sample, x, i.e. $log(p(x|GMM))$ . Inputs are NOT checked.

Parameters:

input : array_like <float, 1D>

Input vector

Returns:

output : float

The log likelihood

mean_supervector¶

array_like <float, 1D> <– The mean supervector of the GMMMachine

Concatenation of the mean vectors of each Gaussian of the GMMMachine

means¶: array_like <float, 2D> <– The means of the gaussians

resize(n_gaussians, n_inputs) → None¶

Allocates space for the statistics and resets to zero.

Parameters:

n_gaussians : int

Number of gaussians

n_inputs : int

Dimensionality of the feature vector

save(hdf5) → None¶

Save the configuration of the GMMMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

set_variance_thresholds(input) → None¶

Set the variance flooring thresholds in each dimension to the same vector for all Gaussian components if the argument is a 1D numpy arrray, and equal for all Gaussian components and dimensions if the parameter is a scalar.

Parameters:

input : float or array_like <float, 1D>

The new variance threshold, or a vector of thresholds for all Gaussian components

shape¶: (int,int) <– A tuple that represents the number of gaussians and dimensionality of each Gaussian (n_gaussians, dim).

variance_supervector¶

array_like <float, 1D> <– The variance supervector of the GMMMachine

Concatenation of the variance vectors of each Gaussian of the GMMMachine

variance_thresholds¶: array_like <float, 2D> <– Set the variance flooring thresholds in each dimension to the same vector for all Gaussian components if the argument is a 1D numpy arrray, and equal for all Gaussian components and dimensions if the parameter is a scalar.

variances¶: array_like <float, 2D> <– Variances of the gaussians

weights¶: array_like <float, 1D> <– The weights (also known as “mixing coefficients”)

class bob.learn.em.GMMStats¶

Bases: object

A container for GMM statistics

With respect to [Reynolds2000] the class computes:

Eq (8) is bob.learn.em.GMMStats.n: $n_i=\sum\limits_{t=1}^T Pr(i | x_t)$
Eq (9) is bob.learn.em.GMMStats.sum_px: $E_i(x)=\frac{1}{n(i)}\sum\limits_{t=1}^T Pr(i | x_t)x_t$
Eq (10) is bob.learn.em.GMMStats.sum_pxx: $E_i(x^2)=\frac{1}{n(i)}\sum\limits_{t=1}^T Pr(i | x_t)x_t^2$

Constructor Documentation:

bob.learn.em.GMMStats (n_gaussians,n_inputs)

bob.learn.em.GMMStats (other)

bob.learn.em.GMMStats (hdf5)

bob.learn.em.GMMStats ()

A container for GMM statistics.

Parameters:

n_gaussians : int

Number of gaussians

n_inputs : int

Dimension of the feature vector

other : bob.learn.em.GMMStats

A GMMStats object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

init() → None¶: Resets statistics to zero.

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this GMMStats with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.GMMStats

A GMMStats object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the GMMStats to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

log_likelihood¶: float <– The accumulated log likelihood of all samples

n¶: array_like <float, 1D> <– For each Gaussian, the accumulated sum of responsibilities, i.e. the sum of $P(gaussian_i|x)$

resize(n_gaussians, n_inputs) → None¶

Allocates space for the statistics and resets to zero.

Parameters:

n_gaussians : int

Number of gaussians

n_inputs : int

Dimensionality of the feature vector

save(hdf5) → None¶

Save the configuration of the GMMStats to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int) <– A tuple that represents the number of gaussians and dimensionality of each Gaussian (n_gaussians, dim).

sum_px¶: array_like <float, 2D> <– For each Gaussian, the accumulated sum of responsibility times the sample

sum_pxx¶: array_like <float, 2D> <– For each Gaussian, the accumulated sum of responsibility times the sample squared

t¶: int <– The number of samples

class bob.learn.em.Gaussian¶

Bases: object

This class implements a multivariate diagonal Gaussian distribution

Constructor Documentation:

bob.learn.em.Gaussian (n_inputs)

bob.learn.em.Gaussian (other)

bob.learn.em.Gaussian (hdf5)

bob.learn.em.Gaussian ()

Constructs a new multivariate gaussian object

Parameters:

n_inputs : int

Dimension of the feature vector

other : bob.learn.em.GMMStats

A GMMStats object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this Gaussian with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.Gaussian

A gaussian to be compared.

[r_epsilon] : float

Relative precision.

[a_epsilon] : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the Gassian Machine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

log_likelihood(input) → output¶

Output the log likelihood of the sample, x. The input size is checked.

Note

The __call__ function is an alias for this.

Parameters:

input : array_like <float, 1D>

Input vector

Returns:

output : float

The log likelihood

log_likelihood_(input) → output¶

Output the log likelihood given a sample. The input size is NOT checked.

Parameters:

input : array_like <float, 1D>

Input vector

Returns:

output : float

The log likelihood

mean¶: array_like <float, 1D> <– Mean of the Gaussian

resize(input) → None¶

Set the input dimensionality, reset the mean to zero and the variance to one.

Parameters:

input : int

Dimensionality of the feature vector

save(hdf5) → None¶

Save the configuration of the Gassian Machine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

set_variance_thresholds(input) → None¶

Set the variance flooring thresholds equal to the given threshold for all the dimensions.

Parameters:

input : float

Threshold

shape¶: (int) <– A tuple that represents the dimensionality of the Gaussian (dim,).

variance¶: array_like <float, 1D> <– Variance of the Gaussian

variance_thresholds¶

array_like <float, 1D> <– The variance flooring thresholds, i.e. the minimum allowed value of variance in each dimension.

The variance will be set to this value if an attempt is made to set it to a smaller value.

class bob.learn.em.ISVBase¶

Bases: object

A ISVBase instance can be seen as a container for U and D when performing Joint Factor Analysis (JFA).

References: [Vogt2008] [McCool2013]

Constructor Documentation:

bob.learn.em.ISVBase (ubm,ru)

bob.learn.em.ISVBase (other)

bob.learn.em.ISVBase (hdf5)

bob.learn.em.ISVBase ()

Creates a ISVBase

Parameters:

ubm : bob.learn.em.GMMMachine

The Universal Background Model.

ru : int

Size of U (Within client variation matrix). In the end the U matrix will have (number_of_gaussians * feature_dimension x ru)

other : bob.learn.em.ISVBase

A ISVBase object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

d¶: array_like <float, 1D> <– Returns the diagonal matrix diag(d) (as a 1D vector)

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this ISVBase with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.ISVBase

A ISVBase object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the ISVBase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

resize(rU) → None¶

Resets the dimensionality of the subspace U. U is hence uninitialized.

Parameters:

rU : int

Size of U (Within client variation matrix)

save(hdf5) → None¶

Save the configuration of the ISVBase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int) <– A tuple that represents the number of gaussians, dimensionality of each Gaussian, dimensionality of the rU (within client variability matrix) (#Gaussians, #Inputs, #rU).

supervector_length¶

int <– Returns the supervector length.

NGaussians x NInputs: Number of Gaussian components by the feature dimensionalityAn exception is thrown if no Universal Background Model has been set yet.

u¶: array_like <float, 2D> <– Returns the U matrix (within client variability matrix)

ubm¶: bob.learn.em.GMMMachine <– Returns the UBM (Universal Background Model

class bob.learn.em.ISVMachine¶

Bases: object

A ISVMachine. An attached bob.learn.em.ISVBase should be provided for Joint Factor Analysis. The bob.learn.em.ISVMachine carries information about the speaker factors $y$ and $z$ , whereas a bob.learn.em.JFABase carries information about the matrices $U$ and $D$ .

References: [Vogt2008] [McCool2013]

Constructor Documentation:

bob.learn.em.ISVMachine (isv_base)

bob.learn.em.ISVMachine (other)

bob.learn.em.ISVMachine (hdf5)

Constructor. Builds a new ISVMachine

Parameters:

isv_base : bob.learn.em.ISVBase

The ISVBase associated with this machine

other : bob.learn.em.ISVMachine

A ISVMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

estimate_ux(stats, input) → None¶

Estimates Ux (LPT assumption) given GMM statistics.

Estimates Ux from the GMM statistics considering the LPT assumption, that is the latent session variable x is approximated using the UBM.

Parameters:

stats : bob.learn.em.GMMStats

Statistics of the GMM

input : array_like <float, 1D>

Input vector

estimate_x(stats, input) → None¶

Estimates the session offset x (LPT assumption) given GMM statistics.

Estimates $x$ from the GMM statistics considering the LPT assumption, that is the latent session variable $x$ is approximated using the UBM

Parameters:

stats : bob.learn.em.GMMStats

Statistics of the GMM

input : array_like <float, 1D>

Input vector

forward_ux(stats, ux) → None¶

Computes a score for the given UBM statistics and given the Ux vector

Parameters:

stats : bob.learn.em.GMMStats

Statistics as input

ux : array_like <float, 1D>

Input vector

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this ISVMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.ISVMachine

A ISVMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

isv_base¶: bob.learn.em.ISVBase <– The ISVBase attached to this machine

load(hdf5) → None¶

Load the configuration of the ISVMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

save(hdf5) → None¶

Save the configuration of the ISVMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int, int) <– A tuple that represents the number of gaussians, dimensionality of each Gaussian and dimensionality of the rU (within client variability matrix)) (#Gaussians, #Inputs, #rU).

supervector_length¶

int <– Returns the supervector length.

NGaussians x NInputs: Number of Gaussian components by the feature dimensionality. An exception is thrown if no Universal Background Model has been set yet.

x¶

array_like <float, 1D> <– Returns the $X$ session factor. Eq (29) from [McCool2013]

The latent variable x (last one computed). This is a feature provided for convenience, but this attribute is not ‘part’ of the machine. The session latent variable $x$ is indeed not class-specific, but depends on the sample considered. Furthermore, it is not saved into the machine or used when comparing machines.

z¶: array_like <float, 1D> <– Returns the $z$ speaker factor. Eq (31) from [McCool2013]

class bob.learn.em.ISVTrainer¶

Bases: object

ISVTrainerTrain Intersession varibility modeling ISV.

Constructor Documentation:

bob.learn.em.ISVTrainer (relevance_factor)

bob.learn.em.ISVTrainer (other)

bob.learn.em.ISVTrainer ()

Constructor. Builds a new ISVTrainer

Parameters:

other : bob.learn.em.ISVTrainer

A ISVTrainer object to be copied.

relevance_factor : float

Class Members:

acc_u_a1¶: array_like <float, 3D> <– Accumulator updated during the E-step

acc_u_a2¶: array_like <float, 2D> <– Accumulator updated during the E-step

e_step(isv_base, stats) → None¶

Call the e-step procedure (for the U subspace).

Parameters:

isv_base : bob.learn.em.ISVBase

ISVBase Object

stats : bob.learn.em.GMMStats

GMMStats Object

enroll(isv_machine, features, n_iter) → None¶

Parameters:

isv_machine : bob.learn.em.ISVMachine

ISVMachine Object

features : list(bob.learn.em.GMMStats)`

n_iter : int

Number of iterations

initialize(isv_base, stats[, rng]) → None¶

Initialization before the EM steps

Parameters:

isv_base : bob.learn.em.ISVBase

ISVBase Object

stats : bob.learn.em.GMMStats

GMMStats Object

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

m_step(isv_base[, stats]) → None¶

Call the m-step procedure (for the U subspace).

Parameters:

isv_base : bob.learn.em.ISVBase

ISVBase Object

stats : object

Ignored.

class bob.learn.em.IVectorMachine¶

Bases: object

Statistical model for the Total Variability training for more information and explanation see the user guide in documentation (iVectors)

Constructor Documentation:

bob.learn.em.IVectorMachine (ubm,rt,variance_threshold)

bob.learn.em.IVectorMachine (other)

bob.learn.em.IVectorMachine (hdf5)

Constructor. Builds a new IVectorMachine

Parameters:

ubm : bob.learn.em.GMMMachine

The Universal Background Model.

rt : int

Size of the Total Variability matrix (CD x rt).

variance_threshold : float

Variance flooring threshold for the $\Sigma$ (diagonal) matrix

other : bob.learn.em.IVectorMachine

A IVectorMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this IVectorMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.IVectorMachine

A IVectorMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the IVectorMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

project(stats) → None¶

Projects the given GMM statistics into the i-vector subspace

Note

The __call__ function is an alias for this function

Parameters:

stats : bob.learn.em.GMMStats

Statistics as input

resize(rT) → None¶

Resets the dimensionality of the subspace T.

Parameters:

rT : int

Size of T (Total variability matrix)

save(hdf5) → None¶

Save the configuration of the IVectorMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int) <– A tuple that represents the number of gaussians, dimensionality of each Gaussian, dimensionality of the rT (total variability matrix) (#Gaussians, #Inputs, #rT).

sigma¶: array_like <float, 1D> <– The residual matrix of the model sigma

supervector_length¶

int <– Returns the supervector length.

NGaussians x NInputs: Number of Gaussian components by the feature dimensionalityAn exception is thrown if no Universal Background Model has been set yet.

t¶: array_like <float, 2D> <– Returns the Total Variability matrix, $T$

ubm¶: bob.learn.em.GMMMachine <– Returns the UBM (Universal Background Model)

variance_threshold¶: float <– Threshold for the variance contained in sigma

class bob.learn.em.IVectorTrainer¶

Bases: object

IVectorTrainerTrains the Total Variability subspace $T$ to generate iVectors.

Constructor Documentation:

bob.learn.em.IVectorTrainer (update_sigma)

bob.learn.em.IVectorTrainer (other)

bob.learn.em.IVectorTrainer ()

Constructor. Builds a new IVectorTrainer

Parameters:

other : bob.learn.em.IVectorTrainer

A IVectorTrainer object to be copied.

update_sigma : bool

Class Members:

acc_fnormij_wij¶: array_like <float, 3D> <– Accumulator updated during the E-step

acc_nij¶: array_like <float, 1D> <– Accumulator updated during the E-step

acc_nij_wij2¶: array_like <float, 3D> <– Accumulator updated during the E-step

acc_snormij¶: array_like <float, 2D> <– Accumulator updated during the E-step

e_step(ivector_machine, stats) → None¶

Call the e-step procedure (for the U subspace).

Parameters:

ivector_machine : bob.learn.em.ISVBase

IVectorMachine Object

stats : bob.learn.em.GMMStats

GMMStats Object

initialize(ivector_machine[, stats][, rng]) → None¶

Initialization before the EM steps

Parameters:

ivector_machine : bob.learn.em.IVectorMachine

IVectorMachine Object

stats : object

Ignored

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

m_step(ivector_machine[, stats]) → None¶

Call the m-step procedure (for the U subspace).

Parameters:

ivector_machine : bob.learn.em.ISVBase

IVectorMachine Object

stats : object

Ignored

reset_accumulators(ivector_machine) → None¶

Reset the statistics accumulators to the correct size and a value of zero.

Parameters:

ivector_machine : bob.learn.em.IVectorMachine

The IVector machine containing the right dimensions

class bob.learn.em.JFABase¶

Bases: object

Container for $U$ , $V$ and $D$ when performing Joint Factor Analysis (JFA).

Constructor Documentation:

bob.learn.em.JFABase (ubm,ru,rv)

bob.learn.em.JFABase (other)

bob.learn.em.JFABase (hdf5)

bob.learn.em.JFABase ()

Constructor. Builds a new JFABase

Parameters:

ubm : bob.learn.em.GMMMachine

The Universal Background Model.

ru : int

Size of $U$ (Within client variation matrix). In the end the U matrix will have (#gaussians * #feature_dimension x ru)

rv : int

Size of $V$ (Between client variation matrix). In the end the U matrix will have (#gaussians * #feature_dimension x rv)

other : bob.learn.em.JFABase

A JFABase object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

d¶: array_like <float, 1D> <– Returns the diagonal matrix $diag(d)$ (as a 1D vector)

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this JFABase with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.JFABase

A JFABase object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the JFABase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

resize(rU, rV) → None¶

Resets the dimensionality of the subspace U and V. U and V are hence uninitialized

Parameters:

rU : int

Size of $U$ (Within client variation matrix)

rV : int

Size of $V$ (Between client variation matrix)

save(hdf5) → None¶

Save the configuration of the JFABase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int, int) <– A tuple that represents the number of gaussians, dimensionality of each Gaussian, dimensionality of the $rU$ (within client variability matrix) and dimensionality of the $rV$ (between client variability matrix) (#Gaussians, #Inputs, #rU, #rV).

supervector_length¶

int <– Returns the supervector length.

NGaussians x NInputs: Number of Gaussian components by the feature dimensionalityAn exception is thrown if no Universal Background Model has been set yet.

u¶: array_like <float, 2D> <– Returns the $U$ matrix (within client variability matrix)

ubm¶: bob.learn.em.GMMMachine <– Returns the UBM (Universal Background Model

v¶: array_like <float, 2D> <– Returns the $V$ matrix (between client variability matrix)

class bob.learn.em.JFAMachine¶

Bases: object

A JFAMachine. An attached bob.learn.em.JFABase should be provided for Joint Factor Analysis. The bob.learn.em.JFAMachine carries information about the speaker factors $y$ and $z$ , whereas a bob.learn.em.JFABase carries information about the matrices $U$ , $V$ and $D$ .

References: [Vogt2008] [McCool2013]

Constructor Documentation:

bob.learn.em.JFAMachine (jfa_base)

bob.learn.em.JFAMachine (other)

bob.learn.em.JFAMachine (hdf5)

Constructor. Builds a new JFAMachine

Parameters:

jfa_base : bob.learn.em.JFABase

The JFABase associated with this machine

other : bob.learn.em.JFAMachine

A JFAMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

estimate_ux(stats, input) → None¶

Estimates Ux (LPT assumption) given GMM statistics.

Estimates Ux from the GMM statistics considering the LPT assumption, that is the latent session variable x is approximated using the UBM.

Parameters:

stats : bob.learn.em.GMMStats

Statistics of the GMM

input : array_like <float, 1D>

Input vector

estimate_x(stats, input) → None¶

Estimates the session offset x (LPT assumption) given GMM statistics.

Estimates x from the GMM statistics considering the LPT assumption, that is the latent session variable x is approximated using the UBM

Parameters:

stats : bob.learn.em.GMMStats

Statistics of the GMM

input : array_like <float, 1D>

Input vector

forward_ux(stats, ux) → None¶

Computes a score for the given UBM statistics and given the Ux vector

Parameters:

stats : bob.learn.em.GMMStats

Statistics as input

ux : array_like <float, 1D>

Input vector

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this JFAMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.JFAMachine

A JFAMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

jfa_base¶: bob.learn.em.JFABase <– The JFABase attached to this machine

load(hdf5) → None¶

Load the configuration of the JFAMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

log_likelihood(stats) → None¶

Computes the log-likelihood of the given samples

Note

the __call__ function is an alias for this function.

Parameters:

stats : bob.learn.em.GMMStats

Statistics as input

save(hdf5) → None¶

Save the configuration of the JFAMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int, int) <– A tuple that represents the number of gaussians, dimensionality of each Gaussian, dimensionality of the rU (within client variability matrix) and dimensionality of the rV (between client variability matrix) (#Gaussians, #Inputs, #rU, #rV).

supervector_length¶

int <– Returns the supervector length.

NGaussians x NInputs: Number of Gaussian components by the feature dimensionality. An exception is thrown if no Universal Background Model has been set yet.

x¶

array_like <float, 1D> <– Returns the $X$ session factor. Eq (29) from [McCool2013]

The latent variable $x$ (last one computed). This is a feature provided for convenience, but this attribute is not ‘part’ of the machine. The session latent variable $x$ is indeed not class-specific, but depends on the sample considered. Furthermore, it is not saved into the machine or used when comparing machines.

y¶: array_like <float, 1D> <– Returns the $y$ speaker factor. Eq (30) from [McCool2013]

z¶: array_like <float, 1D> <– Returns the $z$ speaker factor. Eq (31) from [McCool2013]

class bob.learn.em.JFATrainer¶

Bases: object

Trains a Joint Factor Analysis (JFA) on top of GMMs

Constructor Documentation:

bob.learn.em.JFATrainer (other)

bob.learn.em.JFATrainer ()

Constructor. Builds a new JFATrainer

Parameters:

other : bob.learn.em.JFATrainer

A JFATrainer object to be copied.

Class Members:

acc_d_a1¶: array_like <float, 1D> <– Accumulator updated during the E-step

acc_d_a2¶: array_like <float, 1D> <– Accumulator updated during the E-step

acc_u_a1¶: array_like <float, 3D> <– Accumulator updated during the E-step

acc_u_a2¶: array_like <float, 2D> <– Accumulator updated during the E-step

acc_v_a1¶: array_like <float, 3D> <– Accumulator updated during the E-step

acc_v_a2¶: array_like <float, 2D> <– Accumulator updated during the E-step

e_step_d(jfa_base, stats) → None¶

Call the 3rd e-step procedure (for the d subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

e_step_u(jfa_base, stats) → None¶

Call the 2nd e-step procedure (for the U subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

e_step_v(jfa_base, stats) → None¶

Call the 1st e-step procedure (for the V subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

enroll(jfa_machine, features, n_iter) → None¶

Parameters:

jfa_machine : bob.learn.em.JFAMachine

JFAMachine Object

features : [bob.learn.em.GMMStats]

n_iter : int

Number of iterations

finalize_d(jfa_base, stats) → None¶

Call the 3rd finalize procedure (for the d subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

finalize_u(jfa_base, stats) → None¶

Call the 2nd finalize procedure (for the U subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

finalize_v(jfa_base, stats) → None¶

Call the 1st finalize procedure (for the V subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

initialize(jfa_base, stats[, rng]) → None¶

Initialization before the EM steps

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

m_step_d(jfa_base, stats) → None¶

Call the 3rd m-step procedure (for the d subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

m_step_u(jfa_base, stats) → None¶

Call the 2nd m-step procedure (for the U subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

m_step_v(jfa_base, stats) → None¶

Call the 1st m-step procedure (for the V subspace).

Parameters:

jfa_base : bob.learn.em.JFABase

JFABase Object

stats : bob.learn.em.GMMStats

GMMStats Object

class bob.learn.em.KMeansMachine¶

Bases: object

Statistical model for the k-means . See Section 9.1 of Bishop, “Pattern recognition and machine learning”, 2006

Constructor Documentation:

bob.learn.em.KMeansMachine (n_means,n_inputs)

bob.learn.em.KMeansMachine (other)

bob.learn.em.KMeansMachine (hdf5)

bob.learn.em.KMeansMachine ()

Creates a KMeansMachine

Parameters:

n_means : int

Number of means

n_inputs : int

Dimension of the feature vector

other : bob.learn.em.KMeansMachine

A KMeansMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

get_closest_mean(input) → output¶

Calculate the index of the mean that is closest (in terms of square Euclidean distance) to the data sample, x.

Parameters:

input : array_like <float, 1D>

The data sample (feature vector)

Returns:

output : (int, int)

Tuple containing the closest mean and the minimum distance from the input

get_distance_from_mean(input, i) → output¶

Return the power of two of the square Euclidean distance of the sample, x, to the i’th mean.

Note

An exception is thrown if i is out of range.

Parameters:

input : array_like <float, 1D>

The data sample (feature vector)

i : int

The index of the mean

Returns:

output : float

Square Euclidean distance of the sample, x, to the i’th mean

get_mean(i) → mean¶

Get the i’th mean.

Note

An exception is thrown if i is out of range.

Parameters:

i : int

Index of the mean

Returns:

mean : array_like <float, 1D>

Mean array

get_min_distance(input) → output¶

Output the minimum (Square Euclidean) distance between the input and the closest mean

Parameters:

input : array_like <float, 1D>

The data sample (feature vector)

Returns:

output : float

The minimum distance

get_variances_and_weights_for_each_cluster(input) → output¶

For each mean, find the subset of the samples that is closest to that mean, and calculate 1) the variance of that subset (the cluster variance) 2) the proportion of the samples represented by that subset (the cluster weight)

Parameters:

input : array_like <float, 2D>

The data sample (feature vector)

Returns:

output : (array_like <float, 2D>, array_like <float, 1D>)

A tuple with the variances and the weights respectively

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this KMeansMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.KMeansMachine

A KMeansMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the KMeansMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

means¶: array_like <float, 2D> <– The means

resize(n_means, n_inputs) → None¶

Allocates space for the statistics and resets to zero.

Parameters:

n_means : int

Number of means

n_inputs : int

Dimensionality of the feature vector

save(hdf5) → None¶

Save the configuration of the KMeansMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

set_mean(i, mean) → None¶

Set the i’th mean.

Note

An exception is thrown if i is out of range.

Parameters:

i : int

Index of the mean

mean : array_like <float, 1D>

Mean array

shape¶: (int,int) <– A tuple that represents the number of means and dimensionality of the feature vector``(n_means, dim)``.

class bob.learn.em.KMeansTrainer¶

Bases: object

Trains a KMeans clustering k-means.This class implements the expectation-maximization algorithm for a k-means.See Section 9.1 of Bishop, “Pattern recognition and machine learning”, 2006It uses a random initialization of the means followed by the expectation-maximization algorithm

Constructor Documentation:

bob.learn.em.KMeansTrainer (initialization_method)

bob.learn.em.KMeansTrainer (other)

bob.learn.em.KMeansTrainer ()

Creates a KMeansTrainer

Parameters:

initialization_method : str

The initialization method of the means. Possible values are: ‘RANDOM’, ‘RANDOM_NO_DUPLICATE’, ‘KMEANS_PLUS_PLUS’

other : bob.learn.em.KMeansTrainer

A KMeansTrainer object to be copied.

Class Members:

average_min_distance¶: str <– Average min (square Euclidean) distance. Useful to parallelize the E-step.

compute_likelihood(kmeans_machine) → None¶

This functions returns the average min (Square Euclidean) distance (average distance to the closest mean)

Parameters:

kmeans_machine : bob.learn.em.KMeansMachine

KMeansMachine Object

e_step(kmeans_machine, data) → None¶

Compute the E-step, which is basically the distances

Accumulate across the dataset: -zeroeth and first order statistics -average (Square Euclidean) distance from the closest mean

Parameters:

kmeans_machine : bob.learn.em.KMeansMachine

KMeansMachine Object

data : array_like <float, 2D>

Input data

first_order_statistics¶: array_like <float, 2D> <– Returns the internal statistics. Useful to parallelize the E-step

initialization_method¶

str <– Initialization method.

Possible values:

RANDOM: Random initialization

RANDOM_NO_DUPLICATE: Random initialization without repetition

KMEANS_PLUS_PLUS: Apply the kmeans++ initialization http://en.wikipedia.org/wiki/K-means%2B%2B

initialize(kmeans_machine, data[, rng]) → None¶

Initialise the means randomly

Data is split into as many chunks as there are means, then each mean is set to a random example within each chunk.

Parameters:

kmeans_machine : bob.learn.em.KMeansMachine

KMeansMachine Object

data : array_like <float, 2D>

Input data

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

m_step(kmeans_machine[, data]) → None¶

Updates the mean based on the statistics from the E-step

Parameters:

kmeans_machine : bob.learn.em.KMeansMachine

KMeansMachine Object

data : object

Ignored.

reset_accumulators(kmeans_machine) → None¶

Reset the statistics accumulators to the correct size and a value of zero.

Parameters:

kmeans_machine : bob.learn.em.KMeansMachine

KMeansMachine Object

zeroeth_order_statistics¶: array_like <float, 1D> <– Returns the internal statistics. Useful to parallelize the E-step

class bob.learn.em.MAP_GMMTrainer¶

Bases: object

This class implements the maximum a posteriori (MAP) M-step of the expectation-maximization algorithm for a GMM Machine. The prior parameters are encoded in the form of a GMM (e.g. a universal background model). The EM algorithm thus performs GMM adaptation.

Constructor Documentation:

bob.learn.em.MAP_GMMTrainer (prior_gmm, relevance_factor, [update_means], [update_variances], [update_weights], [mean_var_update_responsibilities_threshold])

bob.learn.em.MAP_GMMTrainer (prior_gmm, alpha, [update_means], [update_variances], [update_weights], [mean_var_update_responsibilities_threshold])

bob.learn.em.MAP_GMMTrainer (other)

Creates a MAP_GMMTrainer

Additionally to the copy constructor, there are two different ways to call this constructor, one using the relevance_factor and one using the alpha, both which have the same signature. Hence, the only way to differentiate the two functions is by using keyword arguments.

Parameters:

prior_gmm : bob.learn.em.GMMMachine

The prior GMM to be adapted (Universal Background Model UBM).

relevance_factor : float

If set the Reynolds Adaptation procedure will be applied. See Eq (14) from [Reynolds2000]

alpha : float

Set directly the alpha parameter (Eq (14) from [Reynolds2000]), ignoring zeroth order statistics as a weighting factor.

update_means : bool

[Default: True] Update means on each iteration

update_variances : bool

[Default: True] Update variances on each iteration

update_weights : bool

[Default: True] Update weights on each iteration

mean_var_update_responsibilities_threshold : float

[Default: min_float] Threshold over the responsibilities of the Gaussians Equations 9.24, 9.25 of Bishop, Pattern recognition and machine learning, 2006 require a division by the responsibilities, which might be equal to zero because of numerical issue. This threshold is used to avoid such divisions.

other : bob.learn.em.MAP_GMMTrainer

A MAP_GMMTrainer object to be copied.

Class Members:

alpha¶: float <– Set directly the alpha parameter (Eq (14) from [Reynolds2000]), ignoring zeroth order statistics as a weighting factor.

compute_likelihood(gmm_machine) → None¶

This functions returns the average min (Square Euclidean) distance (average distance to the closest mean)

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

e_step(gmm_machine, data) → None¶

Calculates and saves statistics across the dataset and saves these as gmm_statistics.

Calculates the average log likelihood of the observations given the GMM,and returns this in average_log_likelihood.The statistics, gmm_statistics, will be used in the m_step() that follows.

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : array_like <float, 2D>

Input data

gmm_statistics¶

GMMStats <– The GMM statistics that were used internally in the E- and M-steps

Setting and getting the internal GMM statistics might be useful to parallelize the GMM training.

initialize(gmm_machine[, data]) → None¶

Initialization before the EM steps

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : object

Ignored.

m_step(gmm_machine[, data]) → None¶

Performs a maximum a posteriori (MAP) update of the GMM parameters using the accumulated statistics in gmm_statistics and the parameters of the prior model

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : object

Ignored.

relevance_factor¶: float <– If set the reynolds_adaptation parameters, will apply the Reynolds Adaptation Factor. See Eq (14) from [Reynolds2000]

class bob.learn.em.ML_GMMTrainer¶

Bases: object

This class implements the maximum likelihood M-step (MLE) of the expectation-maximisation algorithm for a GMM Machine.

Constructor Documentation:

bob.learn.em.ML_GMMTrainer (update_means, [update_variances], [update_weights], [mean_var_update_responsibilities_threshold])

bob.learn.em.ML_GMMTrainer (other)

Creates a ML_GMMTrainer

Parameters:

update_means : bool

Update means on each iteration

update_variances : bool

Update variances on each iteration

update_weights : bool

Update weights on each iteration

mean_var_update_responsibilities_threshold : float

Threshold over the responsibilities of the Gaussians Equations 9.24, 9.25 of Bishop, Pattern recognition and machine learning, 2006 require a division by the responsibilities, which might be equal to zero because of numerical issue. This threshold is used to avoid such divisions.

other : bob.learn.em.ML_GMMTrainer

A ML_GMMTrainer object to be copied.

Class Members:

compute_likelihood(gmm_machine) → None¶

This functions returns the average min (Square Euclidean) distance (average distance to the closest mean)

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

e_step(gmm_machine, data) → None¶

Calculates and saves statistics across the dataset,and saves these as m_ss.

Calculates the average log likelihood of the observations given the GMM,and returns this in average_log_likelihood.The statistics, gmm_statistics, will be used in the m_step() that follows.

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : array_like <float, 2D>

Input data

gmm_statistics¶

GMMStats <– The GMM statistics that were used internally in the E- and M-steps

Setting and getting the internal GMM statistics might be useful to parallelize the GMM training.

initialize(gmm_machine[, data]) → None¶

Initialization before the EM steps

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : object

Ignored.

m_step(gmm_machine[, data]) → None¶

Performs a maximum likelihood (ML) update of the GMM parameters using the accumulated statistics in gmm_statistics

See Section 9.2.2 of Bishop, “Pattern recognition and machine learning”, 2006

Parameters:

gmm_machine : bob.learn.em.GMMMachine

GMMMachine Object

data : object

Ignored.

class bob.learn.em.PLDABase¶

Bases: object

This class is a container for the $F$ (between class variantion matrix), $G$ (within class variantion matrix) and $\Sigma$ matrices and the mean vector $\mu$ of a PLDA model. This alsoprecomputes useful matrices to make the model scalable.References: [ElShafey2014,PrinceElder2007,LiFu2012]

Constructor Documentation:

bob.learn.em.PLDABase (dim_d,dim_f,dim_g,variance_threshold)

bob.learn.em.PLDABase (other)

bob.learn.em.PLDABase (hdf5)

Constructor, builds a new PLDABase. $F$ , $G$ and $\Sigma$ are initialized to the ‘eye’ matrix (matrix with 1’s on the diagonal and 0 outside), and $\mu$ is initialized to 0.

Parameters:

dim_d : int

Dimensionality of the feature vector.

dim_f : int

Size of $F$ (between class variantion matrix).

dim_g : int

Size of $G$ (within class variantion matrix).

variance_threshold : float

The smallest possible value of the variance (Ignored if set to 0.)

other : bob.learn.em.PLDABase

A PLDABase object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

clear_maps() → None¶: Clears the maps ( $\gamma_a$ and loglike_constterm_a).

compute_gamma(a, res) → None¶

Tells if the $\gamma_a$ matrix for a given a (number of samples) exists. $\gamma_a=(Id + a F^T \beta F)^{-1}$

Parameters:

a : int

Index

res : array_like <float, 2D>

Input data

compute_log_like_const_term(a, res) → None¶

Computes the log likelihood constant term for a given $a$ (number of samples), given the provided $\gamma_a$ matrix. $l_{a} = \frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|\gamma_a|)$

Parameters:

a : int

Index

res : array_like <float, 2D>

Input data

compute_log_likelihood_point_estimate(xij, hi, wij) → output¶

Gets the log-likelihood of an observation, given the current model and the latent variables (point estimate).This will basically compute $p(x_{ij} | h_{i}, w_{ij}, \Theta)$ , given by $\mathcal{N}(x_{ij}|[\mu + F h_{i} + G w_{ij} + \epsilon_{ij}, \Sigma])$ , which is in logarithm, $\frac{D}{2} log(2\pi) -\frac{1}{2} log(det(\Sigma)) -\frac{1}{2} {(x_{ij}-(\mu+F h_{i}+G w_{ij}))^{T}\Sigma^{-1}(x_{ij}-(\mu+F h_{i}+G w_{ij}))}$

Parameters:

xij : array_like <float, 1D>

hi : array_like <float, 1D>

wij : array_like <float, 1D>

Returns:

output : float

f¶: array_like <float, 2D> <– Returns the $F$ matrix (between class variantion matrix)

g¶: array_like <float, 2D> <– Returns the $G$ matrix (between class variantion matrix)

get_add_gamma(a) → output¶

Gets the $gamma_a$ matrix for a given $f_a$ (number of samples). $\gamma_a=(Id + a F^T \beta F)^{-1} =\mathcal{F}_{a}$ .Tries to find it from the base machine and then from this machine.

Parameters:

a : int

Index

Returns:

output : array_like <float, 2D>

get_add_log_like_const_term(a) → output¶

Gets the log likelihood constant term for a given $a$ (number of samples). $l_{a} = \frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|\gamma_a|)$

Parameters:

a : int

Index

Returns:

output : float

get_gamma(a) → output¶

Gets the $\gamma_a$ matrix for a given $a$ (number of samples). $\gamma_{a}=(Id + a F^T \beta F)^{-1} = \mathcal{F}_{a}$

Parameters:

a : int

Index

Returns:

output : array_like <float, 2D>

Get the $\gamma$ matrix

get_log_like_const_term(a) → output¶

Gets the log likelihood constant term for a given $a$ (number of samples). $l_{a}=\frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|\gamma_a|)$

Parameters:

a : int

Index

Returns:

output : float

has_gamma(a) → output¶

Tells if the $\gamma_a$ matrix for a given a (number of samples) exists. $\gamma_a=(Id + aF^T \beta F)^{-1}$

Parameters:

a : int

Index

Returns:

output : bool

has_log_like_const_term(a) → output¶

Tells if the log likelihood constant term for a given $a$ (number of samples) exists in this machine (does not check the base machine). $l_{a}=\frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|\gamma_a|)$

Parameters:

a : int

Index

Returns:

output : bool

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this PLDABase with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.PLDABase

A PLDABase object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the PLDABase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

mu¶: array_like <float, 1D> <– Gets the $\mu$ mean vector of the PLDA model

resize(dim_d, dim_f, dim_g) → None¶

Resizes the dimensionality of the PLDA model. Paramaters $\mu$ , $F$ , $G$ and $\Sigma$ are reinitialized.

Parameters:

dim_d : int

Dimensionality of the feature vector.

dim_f : int

Size of $F$ (between class variantion matrix).

dim_g : int

Size of $G$ (within class variantion matrix).

save(hdf5) → None¶

Save the configuration of the PLDABase to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int) <– A tuple that represents the dimensionality of the feature vector dim_d, the $F$ matrix and the $G$ matrix.

sigma¶: array_like <float, 1D> <– Gets the $\sigma$ (diagonal) covariance matrix of the PLDA model

variance_threshold¶: float <–

class bob.learn.em.PLDAMachine¶

Bases: object

This class is a container for an enrolled identity/class. It contains information extracted from the enrollment samples. It should be used in combination with a PLDABase instance.

References: [ElShafey2014], [PrinceElder2007], [LiFu2012]

Constructor Documentation:

bob.learn.em.PLDAMachine (plda_base)

bob.learn.em.PLDAMachine (other)

bob.learn.em.PLDAMachine (hdf5,plda_base)

Constructor, builds a new PLDAMachine.

Parameters:

plda_base : bob.learn.em.PLDABase

other : bob.learn.em.PLDAMachine

A PLDAMachine object to be copied.

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

Class Members:

clear_maps() → None¶: Clears the maps ( $\gamma_a$ and loglike_constterm_a).

compute_log_likelihood(sample, with_enrolled_samples) → output¶

Compute the log-likelihood of the given sample and (optionally) the enrolled samples

Parameters:

sample : array_like <float, 1D>,array_like <float, 2D>

Sample

with_enrolled_samples : bool

Returns:

output : float

The log-likelihood

get_add_gamma(a) → output¶

Gets the $gamma_a$ matrix for a given $f_a$ (number of samples). $\gamma_a=(Id + a F^T \beta F)^{-1} =\mathcal{F}_{a}$ .Tries to find it from the base machine and then from this machine.

Parameters:

a : int

Index

Returns:

output : array_like <float, 2D>

get_add_log_like_const_term(a) → output¶

Gets the log likelihood constant term for a given $a$ (number of samples). $l_{a} = \frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|gamma_a|)$

Parameters:

a : int

Index

Returns:

output : float

get_gamma(a) → output¶

Gets the $\gamma_a$ matrix for a given $a$ (number of samples). $\gamma_{a}=(Id + a F^T \beta F)^{-1}= \mathcal{F}_{a}$

Parameters:

a : int

Index

Returns:

output : array_like <float, 2D>

Get the $\gamma$ matrix

get_log_like_const_term(a) → output¶

Gets the log likelihood constant term for a given $a$ (number of samples). $l_{a}=\frac{a}{2}( -D log(2\pi) -log|\Sigma| +log|\alpha| + log|\gamma_a|)$

Parameters:

a : int

Index

Returns:

output : float

has_gamma(a) → output¶

Tells if the $\gamma_a$ matrix for a given a (number of samples) exists. $\gamma_a=(Id + a F^T \beta F)^{-1}$

Parameters:

a : int

Index

Returns:

output : bool

has_log_like_const_term(a) → output¶

Tells if the log likelihood constant term for a given $a$ (number of samples) exists in this machine (does not check the base machine). $l_{a}=\frac{a}{2} ( -D log(2\pi) -log|\Sigma| +log|\alpha| +log|\gamma_a|)$

Parameters:

a : int

Index

Returns:

output : bool

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this PLDAMachine with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.PLDAMachine

A PLDAMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

load(hdf5) → None¶

Load the configuration of the PLDAMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for reading

log_likelihood¶: float <– Get the current log likelihood

log_likelihood_ratio(samples) → output¶

Computes a log likelihood ratio from a 1D or 2D blitz::Array

Parameters:

samples : array_like <float, 1D>,array_like <float, 2D>

Sample

Returns:

output : float

The log-likelihood ratio

n_samples¶: int <– Number of enrolled samples

plda_base¶: bob.learn.em.PLDABase <– The PLDABase attached to this machine

save(hdf5) → None¶

Save the configuration of the PLDAMachine to a given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

An HDF5 file open for writing

shape¶: (int,int, int) <– A tuple that represents the dimensionality of the feature vector dim_d, the $F$ matrix and the $G$ matrix.

w_sum_xit_beta_xi¶: float <– Gets the $A = -0.5 \sum_{i} x_{i}^T \beta x_{i}$ value

weighted_sum¶: array_like <float, 1D> <– Get/Set $\sum_{i} F^T \beta x_{i}$ value

class bob.learn.em.PLDATrainer¶

Bases: object

This class can be used to train the $F$ , $G$ and $\Sigma$ matrices and the mean vector $\mu$ of a PLDA model.References: [ElShafey2014],[PrinceElder2007]_,[LiFu2012]_

Constructor Documentation:

bob.learn.em.PLDATrainer (use_sum_second_order)

bob.learn.em.PLDATrainer (other)

bob.learn.em.PLDATrainer ()

Default constructor.

Initializes a new PLDA trainer. The training stage will place the resulting components in the PLDABase.

Parameters:

other : bob.learn.em.PLDATrainer

A PLDATrainer object to be copied.

use_sum_second_order : bool

Class Members:

e_step(plda_base, data) → None¶

Expectation step before the EM steps

Parameters:

plda_base : bob.learn.em.PLDABase

PLDAMachine Object

data : list

enroll(plda_machine, data) → None¶

Main procedure for enrolling a PLDAMachine

Parameters:

plda_machine : bob.learn.em.PLDAMachine

PLDAMachine Object

data : list

finalize(plda_base, data) → None¶

finalize before the EM steps

Parameters:

plda_base : bob.learn.em.PLDABase

PLDAMachine Object

data : list

init_f_method¶

str <– The method used for the initialization of $F$ .

Possible values are: (‘RANDOM_F’, ‘BETWEEN_SCATTER’)

init_g_method¶

str <– The method used for the initialization of $G$ .

Possible values are: (‘RANDOM_G’, ‘WITHIN_SCATTER’)

init_sigma_method¶

str <– The method used for the initialization of $\Sigma$ .

Possible values are: (‘RANDOM_SIGMA’, ‘VARIANCE_G’, ‘CONSTANT’, ‘VARIANCE_DATA’)

initialize(plda_base, data[, rng]) → None¶

Initialization before the EM steps

Parameters:

plda_base : bob.learn.em.PLDABase

PLDAMachine Object

data : list

rng : bob.core.random.mt19937

The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop.

is_similar_to(other[, r_epsilon][, a_epsilon]) → output¶

Compares this PLDATrainer with the other one to be approximately the same.

The optional values r_epsilon and a_epsilon refer to the relative and absolute precision for the weights, biases and any other values internal to this machine.

Parameters:

other : bob.learn.em.PLDAMachine

A PLDAMachine object to be compared.

r_epsilon : float

Relative precision.

a_epsilon : float

Absolute precision.

Returns:

output : bool

True if it is similar, otherwise false.

m_step(plda_base, data) → None¶

Maximization step

Parameters:

plda_base : bob.learn.em.PLDABase

PLDAMachine Object

data : list

use_sum_second_order¶: bool <– Tells whether the second order statistics are stored during the training procedure, or only their sum.

z_first_order¶: array_like <float, 2D> <–

z_second_order¶: array_like <float, 3D> <–

z_second_order_sum¶: array_like <float, 2D> <–

bob.learn.em.linear_scoring(models, ubm, test_stats, test_channelOffset, frame_length_normalisation) → output¶

The Linear scoring is an approximation to the log-likelihood ratio that was shown to be as accurate and up to two orders of magnitude more efficient to compute [Glembek2009].

Parameters:

models : [bob.learn.em.GMMMachine]

ubm : bob.learn.em.GMMMachine

test_stats : [bob.learn.em.GMMStats]

test_channelOffset : [array_like<float,1>]

frame_length_normalisation : bool

Returns:

output : array_like<float,1>

Score

bob.learn.em.tnorm(rawscores_probes_vs_models, rawscores_probes_vs_tmodels) → output¶

Normalise raw scores with T-Norm

Parameters:

rawscores_probes_vs_models : array_like <float, 2D>

Raw set of scores

rawscores_probes_vs_tmodels : array_like <float, 2D>

T-Scores (raw scores of the T probes against the models)

Returns:

output : array_like <float, 2D>

The scores T Normalized

bob.learn.em.train(trainer, machine, data, max_iterations=50, convergence_threshold=None, initialize=True, rng=None, check_inputs=True)[source]¶

Trains a machine given a trainer and the proper data

Parameters:

trainer: A trainer mechanism
machine: A container machine
data: The data to be trained
max_iterations: The maximum number of iterations to train a machine
convergence_threshold: The convergence threshold to train a machine. If None, the training procedure will stop with the iterations criteria
initialize: If True, runs the initialization procedure
rng: The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loop
check_inputs:: Shallow checks in the inputs. Check for inf and NaN

bob.learn.em.train_jfa(trainer, jfa_base, data, max_iterations=10, initialize=True, rng=None)[source]¶

Trains a bob.learn.em.JFABase given a bob.learn.em.JFATrainer and the proper data

Parameters:

trainer: A JFA trainer mechanism
jfa_base: A container machine
data: The data to be trained
max_iterations: The maximum number of iterations to train a machine
initialize: If True, runs the initialization procedure
rng: The Mersenne Twister mt19937 random generator used for the initialization of subspaces/arrays before the EM loops

bob.learn.em.znorm(rawscores_probes_vs_models, rawscores_zprobes_vs_models) → output¶

Normalise raw scores with Z-Norm

Parameters:

rawscores_probes_vs_models : array_like <float, 2D>

Raw set of scores

rawscores_zprobes_vs_models : array_like <float, 2D>

Z-Scores (raw scores of the Z probes against the models)

Returns:

output : array_like <float, 2D>

The scores Z Normalized

bob.learn.em.ztnorm(rawscores_probes_vs_models, rawscores_zprobes_vs_models, rawscores_probes_vs_tmodels, rawscores_zprobes_vs_tmodels, mask_zprobes_vs_tmodels_istruetrial) → output¶

Normalise raw scores with ZT-Norm.Assume that znorm and tnorm have no common subject id.

Parameters:

rawscores_probes_vs_models : array_like <float, 2D>

Raw set of scores

rawscores_zprobes_vs_models : array_like <float, 2D>

Z-Scores (raw scores of the Z probes against the models)

rawscores_probes_vs_tmodels : array_like <float, 2D>

T-Scores (raw scores of the T probes against the models)

rawscores_zprobes_vs_tmodels : array_like <float, 2D>

ZT-Scores (raw scores of the Z probes against the T-models)

mask_zprobes_vs_tmodels_istruetrial : array_like <float, 2D>

Returns:

output : array_like <float, 2D>

The scores ZT Normalized