Models

Inheritance diagram of gmmvi.models.full_cov_gmm.FullCovGMM, gmmvi.models.gmm.GMM, gmmvi.models.diagonal_gmm.DiagonalGMM, gmmvi.models.gmm_wrapper.GmmWrapper
class gmmvi.models.gmm.GMM(log_weights: Variable, means: Variable, chol_covs: Variable)[source]

An abstract class for Gaussian mixture models (GMMs).

This class stores the parameters of a GMM (weights, means and Cholesky matrices) and provides functionality that is common for different types of GMMs (e.g., GMMs with full covariance matrices, and those with diagonal covariance matrices). For example, this class provides methods for sampling the GMM, evaluating its probability density function, and entropy, while relying on the subclass for sampling the components, etc.

Parameters:
  • log_weights – tf.Variable(float) A tensorflow Variable for storing the log-probabilities of the component weights.

  • means – tf.Variable(float) A tensorflow Variable for storing the component means (number of components X number of dimensions)

  • chol_covar – tf.Variable(float) A tensorflow Variable for storing the Cholesky matrix of the component’s covariance matrix. The first dimension specifies the index of the components. The rank may vary depending on the subclass. For example, when storing the Cholesky matrix for a diagonal covariance matrix, it is possible to use a rank-2 Tensor (number of components X number of dimensions) for better memory efficiency.

add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)[source]

Add a component to the mixture model. The weights will be automatically normalized.

Parameters:
  • initial_weight – tf.Tensor The weight of the new component (before re-normalization)

  • initial_mean – tf.Tensor The mean of the new component

  • initial_cov – tf.Tensor The covariance matrix of the new component

component_entropies() Tensor[source]

Computes the entropy of each component.

Returns:

a one-dimensional tensor of shape num_components containing the component entropies.

Return type:

tf.Tensor

component_log_densities(samples: Tensor) Tensor[source]

Evaluate the log densities for each mixture component on the given samples.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

Return type:

tf.Tensor

component_log_density(index: int, samples: Tensor) Tensor[source]

Use the specified component to evaluate the Gaussian log-density at the given samples.

Parameters:
  • index – int The index of the component of which we want to compute the log densities.

  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a one-dimensional tensor of size number_of_samples, containing the log-densities.

Return type:

tf.Tensor

component_log_density_and_grad(index: int, samples: Tensor) [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>][source]

Evaluates for the given component the log-density and its gradient.

Parameters:
  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

  • Returns

    component_log_densities - a one-dimensional tf.Tensor of shape num_samples containing the log-densities of the given component.

    component_log_density_grads - a two-dimensional tf.Tensor of shape num_samples x num_dimensions containing the gradients of the component’s log-densities.

component_marginal_log_densities(samples: Tensor, dimension: int) Tensor[source]

Evaluate the marginal log densities for each mixture component along the given dimension for each sample.

Parameters:
  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate. Note that for providing an easier interface, each sample has the number of dimensions compatible with this GMM, although only a single entry is actually used for evaluating the marginal density.

  • dimension – int The dimension of interest.

Returns:

a two-dimensional tensor of size number_of_components x number_of_samples, containing the marginal log-densities for each component.

Return type:

tf.Tensor

property covs: Tensor

Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

density(samples: Tensor) Tensor[source]

Evaluates the given samples on this GMM.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

Returns:

a one-dimensional tensor of shape num_samples containing the model densities.

Return type:

tf.Tensor

gaussian_entropy(chol: Tensor) Tensor[source]

Computes the entropy of Gaussian distribution with the given Cholesky matrix.

Parameters:

chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

Returns:

The entropy

Return type:

tf.float32

get_average_entropy() tf.float32[source]

Averages the entropies of the individual components based on their respective weights.

Returns:

the average component entropy

Return type:

tf.float32

log_densities_also_individual(samples: Tensor) [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>][source]

Evaluates the given samples on this GMM, but also returns individual log-densities for each Gaussian component.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

Returns:

model_log_densities - a one-dimensional tnsor of shape num_samples containing the model log-densities.

component_log_densities - a two-dimensional tensor of shape num_components x num_samples containing the component log-densities

Return type:

tuple(tf.Tensor, tf.Tensor)

log_density(samples: Tensor) Tensor[source]

Evaluates the given samples on this GMM.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a one-dimensional tensor of shape num_samples containing the model log-densities.

Return type:

tf.Tensor

log_density_and_grad(samples: Tensor) [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>][source]

Evaluates the given samples on this GMM, returns the log-densities of the whole model, their gradients, and also the individual log-densities for each Gaussian component.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

model_log_densities - a one-dimensional tensor of shape num_samples containing the model log-densities.

model_log_density_grads - a two-dimensional tf.Tensor of shape num_samples x num_dimensions containing the gradients of the model log-densities.

component_log_densities - a two-dimensional tf.Tensor of shape num_components x num_samples containing the component log-densities.

Return type:

tuple(tf.Tensor, tf.Tensor)

marginal_log_density(samples: Tensor, dimension: int) Tensor[source]

Evaluates this GMM on the given samples with respect to the marginal log-density along the given dimensions

Parameters:
  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate

  • dimension – int The dimension of interest

Returns:

a one-dimensional tensor of shape num_samples containing the marginal log-densities

Return type:

tf.Tensor

property num_components: int

Returns: int: the number of components of this GMM

remove_component(idx: int)[source]

Removes the specified component, and renormalizes the weights afterwards.

Parameters:

idx – int The idx of the component to be removed.

replace_components(new_means: Tensor, new_chols: Tensor)[source]

Updates the means and covariances matrices (Cholesky) of the GMM. The weights and, therefore, the number of components can not be changed with this method.

Parameters:
  • new_means – tf.Tensor a two-dimensional tensor of shape current_number_of_components x dimensions, specifying the updated means.

  • new_chols – tf.Tensor a three-dimensional tensor of shape current_number_of_components x dimensions x dimensions, specifying the updated Cholesky matrix.

replace_weights(new_log_weights: Tensor)[source]

Overwrites the component log(weights). This method will take care of normalization.

Parameters:

new_log_weights – tf.Tensor a one-dimensional tensor of size num_components, containing the new log(weights)

sample(num_samples: int) [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>][source]

Draw samples from this GMM, also returns for every sample, the index of the component that was used for sampling it.

Parameters:

num_samples – int The number of samples to be drawn

Returns:

drawn_samples - a two-dimensional tensor of shape num_samples x num_dimensions, containing the drawn samples.

component_indices - a one-dimensional tensor of int, containing the component indices.

Return type:

tuple(tf.Tensor, tf.Tensor)

sample_categorical(num_samples: int) Tensor[source]

Sample components according to the weights

Parameters:

num_samples – int The number of components to be drawn

Returns:

a one-dimensional tensor of int, containing the component indices.

Return type:

tf.Tensor

sample_from_component(index: int, num_samples: int) Tensor[source]

draw samples from the specified components

Parameters:
  • index – int The index of the component from which we want to sample.

  • num_samples – int The number of samples to be drawn.

Returns:

The drawn samples, tensor of size num_samples x dimensions.

Return type:

tf.Tensor

sample_from_components(samples_per_component: Tensor) Tensor[source]

Draws from each component the corresponding number of samples (provided as a one-dimensional tensor).

Parameters:

samples_per_component – tf.Tensor a one-dimensional tensor of size number_of_component, containint for each component the number of samples to be drawn.

Returns:

a tensor of shape sum(samples_per_component) x num_dimensions containing the samples (shuffled).

Return type:

tf.Tensor

sample_from_components_no_shuffle(samples_per_component: Tensor) [<class 'tensorflow.python.framework.ops.Tensor'>, <class 'tensorflow.python.framework.ops.Tensor'>][source]

Draws from each component the corresponding number of samples (provided as a one-dimensional tensor). Similar to sample_from_components, but the returned samples are not shuffled.

Parameters:

samples_per_component – tf.Tensor a one-dimensional tensor of size number_of_component, containint for each component the number of samples to be drawn.

Returns:

a tensor of shape sum(samples_per_component) x num_dimensions containing the samples (not shuffled).

Return type:

tf.Tensor

property weights: Tensor

Returns: tf.Tensor: a one-dimensional tensor of size num_components, containing the component weights.

class gmmvi.models.full_cov_gmm.FullCovGMM(weights: Tensor, means: Tensor, covs: Tensor)[source]

A Gaussian mixture model with full covariance matrices.

Parameters:
  • weights – tf.Tensor a one-dimensional tensor containing the initial weights of the GMM.

  • means – tf.Tensor a two-dimensional tensor containing the component means.

  • covs – tf.Tensor a three-dimensional tensor containing the component covariance matrices.

add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)[source]

Add a component to the mixture model. The weights will be automatically normalized.

Parameters:
  • initial_weight – tf.Tensor The weight of the new component (before re-normalization)

  • initial_mean – tf.Tensor The mean of the new component

  • initial_cov – tf.Tensor The covariance matrix of the new component

component_log_densities(samples: Tensor) Tensor[source]

Evaluate the log densities for each mixture component on the given samples.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

Return type:

tf.Tensor

component_log_density(index: int, samples: Tensor) Tensor[source]

Use the specified component to evaluate the Gaussian log-density at the given samples.

Parameters:
  • index – int The index of the component of which we want to compute the log densities.

  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a one-dimensional tensor of size number_of_samples, containing the log-densities.

Return type:

tf.Tensor

component_marginal_log_densities(samples: Tensor, dim: int) Tensor[source]

Evaluate the marginal log densities for each mixture component along the given dimension for each sample.

Parameters:
  • samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate. Note that for providing an easier interface, each sample has the number of dimensions compatible with this GMM, although only a single entry is actually used for evaluating the marginal density.

  • dimension – int The dimension of interest.

Returns:

a two-dimensional tensor of size number_of_components x number_of_samples, containing the marginal log-densities for each component.

Return type:

tf.Tensor

property covs: Tensor

Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

gaussian_entropy(chol: Tensor) Tensor[source]

Computes the entropy of Gaussian distribution with the given Cholesky matrix.

Parameters:

chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

Returns:

The entropy

Return type:

tf.float32

sample_from_component(index: int, num_samples: int) Tensor[source]

draw samples from the specified components

Parameters:
  • index – int The index of the component from which we want to sample.

  • num_samples – int The number of samples to be drawn.

Returns:

The drawn samples, tensor of size num_samples x dimensions.

Return type:

tf.Tensor

class gmmvi.models.diagonal_gmm.DiagonalGMM(weights: Tensor, means: Tensor, covs: Tensor)[source]

A Gaussian mixture model with diagonal covariance matrices.

Parameters:
  • weights – tf.Tensor a one-dimensional tensor containing the initial weights of the GMM.

  • means – tf.Tensor a two-dimensional tensor containing the component means.

  • covs – tf.Tensor a two-dimensional tensor containing the diagonal entries of the component covariances.

add_component(initial_weight: Tensor, initial_mean: Tensor, initial_cov: Tensor)[source]

Add a component to the mixture model. The weights will be automatically normalized.

Parameters:
  • initial_weight – tf.Tensor The weight of the new component (before re-normalization)

  • initial_mean – tf.Tensor The mean of the new component

  • initial_cov – tf.Tensor The covariance matrix of the new component

component_log_densities(samples: Tensor) Tensor[source]

Evaluate the log densities for each mixture component on the given samples.

Parameters:

samples – tf.Tensor A two-dimensional tensor of shape number_of_samples x num_dimensions, which we want to evaluate.

Returns:

a two-dimensional tensor of size number_of_components x number_of_samples, containing the log-densities for each component.

Return type:

tf.Tensor

property covs: Tensor

Returns: tf.Tensor: the covariance matrices as a 3-dimensional tensor of shape num_components x num_dimensions x num_dimensions

static diagonal_gaussian_log_pdf(dim: int, mean: Tensor, chol: Tensor, x: Tensor) Tensor[source]
gaussian_entropy(chol: Tensor) Tensor[source]

Computes the entropy of Gaussian distribution with the given Cholesky matrix.

Parameters:

chol – tf.Tensor A two-dimensional tensor of shape number_of_dimensions x number_of_dimensions specifying the Cholesky matrix

Returns:

The entropy

Return type:

tf.float32

sample_from_component(index: int, num_samples: int) Tensor[source]

draw samples from the specified components

Parameters:
  • index – int The index of the component from which we want to sample.

  • num_samples – int The number of samples to be drawn.

Returns:

The drawn samples, tensor of size num_samples x dimensions.

Return type:

tf.Tensor

class gmmvi.models.gmm_wrapper.GmmWrapper(model: GMM, initial_stepsize: float, initial_regularizer: float, max_reward_history_length: int)[source]

This method wraps around the model to keep track of component-specific meta-information used by the learner (e.g. component-specific stepsizes). This class can be used just like a model, because any methods not implemented within the GmmWrapper are forwarded to the encapuslated model. However, some functions have slightly different behavior, for example, when removing a component, not only the component in the encapuslated model will be removed, but also the meta-information, stored in this GmmWrapper. Hence, the model should always be accessed through the GmmWrapper.

Whenever adding a new component (via py:meth:gmmvi.models.gmm.GmmWrapper.add_component), the GmmWrapper will initialize the meta-information (stepsize and l2-regularizer) with the provided initial_values.

Parameters:
  • modelgmmvi.models.gmm.GMM The model to be encapuslated.

  • initial_stepsize – float The stepsize, that is assigned to a newly added component

  • initial_regularizer – float The l2 regularizer, that is assigned to a newly added component (only used when using a py:class:MoreNgEstimator<gmmvi.optimization.gmmvi_modules.ng_estimator.MoreNgEstimator> for estimating the natural gradients).

  • max_reward_history_length – int The GmmWrapper also keeps track how much reward each component obtained at the previous iterations. This parameter controls after how many iterations the component rewards are forgotten (to save memory).

add_component(initial_weight: tf.float32, initial_mean: Tensor, initial_cov: Tensor, adding_threshold: Tensor, initial_entropy: Tensor)[source]

Adds a new component to the encapuslated model (see GMM, but also stores / intializes meta-information.

Parameters:
  • initial_weight – tf.Tensor The weight of the new component (before re-normalization)

  • initial_mean – tf.Tensor The mean of the new component

  • initial_cov – tf.Tensor The covariance matrix of the new component

  • adding_threshold – tf.Tensor The threshold used by VipsComponentAdaptation, stored for debugging.

  • initial_entropy – tf.Tensor The initial entropy of the new component (can be computed from initial_cov).

static build_from_config(model: GMM, config: dict)[source]

Create a GmmWrapper instance from a configuration dictionary.

This static method provides a convenient way to create a GmmWrapper instance, based on an initial GMM, and a dictionary containing the parameters.

Parameters:
  • config – dict The dictionary is typically read from YAML a file, and holds all hyperparameters. The max_reward_history_length, which is needed for instantiating the GmmWrapper is typically not provided directly, but chosen depending on whether VipsComponentAdaptation is used or not.

  • modelGMM The model that we want to encapsulate.

remove_component(idx: int)[source]

Deletes the given component in the encapuslated model (see GMM), but also deletes the corresponding meta-information.

Parameters:

idx – int The idx of the component to be removed.

replace_weights(new_log_weights: Tensor)[source]

Overwrites the weights of the encapuslated model, see (see GMM), but also keeps track of each component’s weight from previous iterations.

Parameters:

new_log_weights – tf.Tensor A one dimensional tensor of size number_of_components, containing the log of the new weight for each component.

store_rewards(rewards: Tensor)[source]

Store the provided reward of each component.

Parameters:
  • rewards – tf.Tensor

  • number_of_components (A one dimensional tensor of size) –

  • component (containing the reward for each) –

update_stepsizes(new_stepsizes: Tensor)[source]

This method updates the stepsize for each component.

Parameters:
  • new_stepsizes – tf.Tensor

  • number_of_components (A one dimensional tensor of size) –

  • component (containing the new stepsize for each) –