Models¶

- 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
- 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
- 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 amodel
, 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:
model –
gmmvi.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 initialGMM
, 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 whetherVipsComponentAdaptation
is used or not.model –
GMM
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.