Pixyz documentation

Pixyz is a library for developing deep generative models in a more concise, intuitive and extendable way!

pixyz.distributions (Distribution API)

Distribution

class pixyz.distributions.distributions.Distribution(cond_var=[], var=['x'], name='p', dim=1)[source]

Bases: torch.nn.modules.module.Module

Distribution class. In pixyz, all distributions are required to inherit this class.

var : list
Variables of this distribution.
cond_var : list
Conditional variables of this distribution. In case that cond_var is not empty, we must set the corresponding inputs in order to sample variables or estimate the log likelihood.
dim : int
Number of dimensions of this distribution. This might be ignored depending on the shape which is set in the sample method and on its parent distribution. Moreover, this is not consider when this class is inherited by DNNs. This is set to 1 by default.
name : str
Name of this distribution. This name is displayed in prob_text and prob_factorized_text. This is set to “p” by default.
distribution_name
name
var
cond_var
input_var

Normally, input_var has same values as cond_var.

prob_text
prob_factorized_text
get_params(params_dict)[source]

This method aims to get parameters of this distributions from constant parameters set in initialization and outputs of DNNs.

params_dict : dict
Input parameters.
output_dict : dict
Output parameters
>>> print(dist_1.prob_text, dist_1.distribution_name)
p(x) Normal
>>> dist_1.get_params()
{"loc": 0, "scale": 1}
>>> print(dist_2.prob_text, dist_2.distribution_name)
p(x|z) Normal
>>> dist_1.get_params({"z": 1})
{"loc": 0, "scale": 1}
sample(x={}, shape=None, batch_size=1, return_all=True, reparam=False)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
log_likelihood(x_dict)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.
forward(*args, **kwargs)[source]

When this class is inherited by DNNs, it is also intended that this method is overrided.

sample_mean(x)[source]
replace_var(**replace_dict)[source]
marginalize_var(marginalize_list)[source]

Exponential families

Normal

class pixyz.distributions.Normal(cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.distributions.DistributionBase

distribution_name
sample_mean(x)[source]

Bernoulli

class pixyz.distributions.Bernoulli(cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.distributions.DistributionBase

distribution_name
sample_mean(x)[source]

RelaxedBernoulli

class pixyz.distributions.RelaxedBernoulli(temperature, cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.distributions.DistributionBase

distribution_name
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.
sample_mean(x)[source]

FactorizedBernoulli

class pixyz.distributions.FactorizedBernoulli(cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.exponential_distributions.Bernoulli

Generative Models of Visually Grounded Imagination

distribution_name

Categorical

class pixyz.distributions.Categorical(one_hot=True, cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.distributions.DistributionBase

distribution_name
sample_mean(x)[source]

RelaxedCategorical

class pixyz.distributions.RelaxedCategorical(temperature, cond_var=[], var=['x'], name='p', dim=1, **kwargs)[source]

Bases: pixyz.distributions.distributions.DistributionBase

distribution_name
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.
sample_mean(x)[source]

Special distributions

NormalPoE

class pixyz.distributions.NormalPoE(prior, dists=[], **kwargs)[source]

Bases: torch.nn.modules.module.Module

p(z|x,y) \propto p(z)p(z|x)p(z|y)

dists : list
Other distributions.
prior : Distribution
Prior distribution.
>>> poe = NormalPoE(c, [a, b])
get_params(params, **kwargs)[source]
experts(loc, scale, eps=1e-08)[source]
sample(x=None, return_all=True, **kwargs)[source]
log_likelihood(x)[source]
sample_mean(x, **kwargs)[source]

Deterministic

class pixyz.distributions.Deterministic(**kwargs)[source]

Bases: pixyz.distributions.distributions.Distribution

Deterministic distribution (or degeneration distribution)

distribution_name
sample(x={}, return_all=True, **kwargs)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.

DataDistribution

class pixyz.distributions.DataDistribution(var, name='p_data')[source]

Bases: pixyz.distributions.distributions.Distribution

Data distribution. TODO: Fix this behavior if multiplied with other distributions

distribution_name
sample(x={}, **kwargs)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
input_var

In DataDistribution, input_var is same as var.

CustomLikelihoodDistribution

class pixyz.distributions.CustomLikelihoodDistribution(var=['x'], likelihood=None, **kwargs)[source]

Bases: pixyz.distributions.distributions.Distribution

input_var

In CustomLikelihoodDistribution, input_var is same as var.

distribution_name
log_likelihood(x_dict)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.

Flow-based

PlanarFlow

class pixyz.distributions.PlanarFlow(prior, dim, num_layers=1, var=[], **kwargs)[source]

Bases: pixyz.distributions.flows.Flow

RealNVP

class pixyz.distributions.RealNVP(prior, dim, num_multiscale_layers=2, var=[], image=False, name='p', **kwargs)[source]

Bases: pixyz.distributions.distributions.Distribution

prob_text
forward(x, inverse=False, jacobian=False)[source]

When this class is inherited by DNNs, it is also intended that this method is overrided.

sample(x={}, only_flow=False, return_all=True, **kwargs)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
sample_inv(x, return_all=True, **kwargs)[source]
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.

Operators

ReplaceVarDistribution

class pixyz.distributions.distributions.ReplaceVarDistribution(a, replace_dict)[source]

Bases: pixyz.distributions.distributions.Distribution

Replace names of variables in Distribution.

a : pixyz.Distribution (not pixyz.MultiplyDistribution)
Distribution.
replace_dict : dict
Dictionary.
forward(*args, **kwargs)[source]

When this class is inherited by DNNs, it is also intended that this method is overrided.

get_params(params_dict)[source]

This method aims to get parameters of this distributions from constant parameters set in initialization and outputs of DNNs.

params_dict : dict
Input parameters.
output_dict : dict
Output parameters
>>> print(dist_1.prob_text, dist_1.distribution_name)
p(x) Normal
>>> dist_1.get_params()
{"loc": 0, "scale": 1}
>>> print(dist_2.prob_text, dist_2.distribution_name)
p(x|z) Normal
>>> dist_1.get_params({"z": 1})
{"loc": 0, "scale": 1}
sample(x={}, shape=None, batch_size=1, return_all=True, reparam=False)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.
sample_mean(x)[source]
input_var

Normally, input_var has same values as cond_var.

distribution_name

MarginalizeVarDistribution

class pixyz.distributions.distributions.MarginalizeVarDistribution(a, marginalize_list)[source]

Bases: pixyz.distributions.distributions.Distribution

Marginalize variables in Distribution. p(x) = \int p(x,z) dz

a : pixyz.Distribution (not pixyz.DistributionBase)
Distribution.
marginalize_list : list
Variables to marginalize.
forward(*args, **kwargs)[source]

When this class is inherited by DNNs, it is also intended that this method is overrided.

get_params(params_dict)[source]

This method aims to get parameters of this distributions from constant parameters set in initialization and outputs of DNNs.

params_dict : dict
Input parameters.
output_dict : dict
Output parameters
>>> print(dist_1.prob_text, dist_1.distribution_name)
p(x) Normal
>>> dist_1.get_params()
{"loc": 0, "scale": 1}
>>> print(dist_2.prob_text, dist_2.distribution_name)
p(x|z) Normal
>>> dist_1.get_params({"z": 1})
{"loc": 0, "scale": 1}
sample(x={}, shape=None, batch_size=1, return_all=True, reparam=False)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.
sample_mean(x)[source]
input_var

Normally, input_var has same values as cond_var.

distribution_name
prob_factorized_text

MultiplyDistribution

class pixyz.distributions.distributions.MultiplyDistribution(a, b)[source]

Bases: pixyz.distributions.distributions.Distribution

Multiply by given distributions, e.g, p(x,y|z) = p(x|z,y)p(y|z). In this class, it is checked if two distributions can be multiplied.

p(x|z)p(z|y) -> Valid

p(x|z)p(y|z) -> Valid

p(x|z)p(y|a) -> Valid

p(x|z)p(z|x) -> Invalid (recursive)

p(x|z)p(x|y) -> Invalid (conflict)

a : pixyz.Distribution
Distribution.
b : pixyz.Distribution
Distribution.
>>> p_multi = MultipleDistribution([a, b])
>>> p_multi = a * b
inh_var
input_var

Normally, input_var has same values as cond_var.

prob_factorized_text
sample(x={}, shape=None, batch_size=1, return_all=True, reparam=False)[source]

Sample variables of this distribution. If cond_var is not empty, we should set inputs as a dictionary format.

x : torch.Tensor, list, or dict
Input variables.
shape : tuple
Shape of samples. If set, batch_size and dim are ignored.
batch_size : int
Batch size of samples. This is set to 1 by default.
return_all : bool
Choose whether the output contains input variables.
reparam : bool
Choose whether we sample variables with reparameterized trick.
output : dict
Samples of this distribution.
log_likelihood(x)[source]

Estimate the log likelihood of this distribution from inputs formatted by a dictionary.

x_dict : dict
Input samples.
log_like : torch.Tensor
Log-likelihood.

Functions

pixyz.distributions.distributions.sum_samples(samples)[source]

pixyz.losses (Loss API)

Loss

class pixyz.losses.losses.Loss(p1, p2=None, input_var=None)[source]

Bases: object

input_var
loss_text
mean()[source]
sum()[source]
estimate(x={}, **kwargs)[source]
train(x={}, **kwargs)[source]

Train the implicit (adversarial) loss function.

test(x={}, **kwargs)[source]

Test the implicit (adversarial) loss function.

Negative expected value of log-likelihood (entropy)

CrossEntropy

class pixyz.losses.CrossEntropy(p1, p2, input_var=None)[source]

Bases: pixyz.losses.losses.Loss

Cross entropy, a.k.a., the negative expected value of log-likelihood (Monte Carlo approximation).

-\mathbb{E}_{q(x)}[\log p(x)] \approx -\frac{1}{L}\sum_{l=1}^L \log p(x_l),

where x_l \sim q(x).

loss_text
estimate(x={})[source]

Entropy

class pixyz.losses.Entropy(p1, input_var=None)[source]

Bases: pixyz.losses.losses.Loss

Entropy (Monte Carlo approximation).

-\mathbb{E}_{p(x)}[\log p(x)] \approx -\frac{1}{L}\sum_{l=1}^L \log p(x_l),

where x_l \sim p(x).

Note:
This class is a special case of the CrossEntropy class. You can get the same result with CrossEntropy.
loss_text
estimate(x={})[source]

StochasticReconstructionLoss

class pixyz.losses.StochasticReconstructionLoss(encoder, decoder, input_var=None)[source]

Bases: pixyz.losses.losses.Loss

Reconstruction Loss (Monte Carlo approximation).

-\mathbb{E}_{q(z|x)}[\log p(x|z)] \approx -\frac{1}{L}\sum_{l=1}^L \log p(x|z_l),

where z_l \sim q(z|x).

Note:
This class is a special case of the CrossEntropy class. You can get the same result with CrossEntropy.
loss_text
estimate(x={})[source]

Negative log-likelihood

NLL

class pixyz.losses.NLL(p, input_var=None)[source]

Bases: pixyz.losses.losses.Loss

Negative log-likelihood.

\log p(x)

loss_text
estimate(x={})[source]

Lower bound

ELBO

class pixyz.losses.ELBO(p, approximate_dist, input_var=None)[source]

Bases: pixyz.losses.losses.Loss

The evidence lower bound (Monte Carlo approximation).

\mathbb{E}_{q(z|x)}[\log \frac{p(x,z)}{q(z|x)}] \approx \frac{1}{L}\sum_{l=1}^L \log p(x, z_l),

where z_l \sim q(z|x).

loss_text
estimate(x={}, batch_size=None)[source]

Similarity

SimilarityLoss

class pixyz.losses.SimilarityLoss(p1, p2, input_var=None, var=['z'], margin=0)[source]

Bases: pixyz.losses.losses.Loss

Learning Modality-Invariant Representations for Speech and Images (Leidai et. al.)

estimate(x)[source]

MultiModalContrastivenessLoss

class pixyz.losses.MultiModalContrastivenessLoss(p1, p2, input_var=None, margin=0.5)[source]

Bases: pixyz.losses.losses.Loss

Disentangling by Partitioning: A Representation Learning Framework for Multimodal Sensory Data

estimate(x)[source]

Adversarial loss (GAN loss)

AdversarialJSDivergence

class pixyz.losses.AdversarialJSDivergence(p_data, p, discriminator, input_var=None, optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={}, inverse_g_loss=True)[source]

Bases: pixyz.losses.losses.Loss

Adversarial loss (Jensen-Shannon divergence).

\mathcal{L}_{adv} = 2 \dot JS[p_{data}(x)||p(x)] + const.

loss_text
estimate(x={}, discriminator=False)[source]
d_loss(y1, y2, batch_size)[source]
g_loss(y1, y2, batch_size)[source]
train(train_x, **kwargs)[source]

Train the implicit (adversarial) loss function.

test(test_x, **kwargs)[source]

Test the implicit (adversarial) loss function.

AdversarialWassersteinDistance

class pixyz.losses.AdversarialWassersteinDistance(p_data, p, discriminator, clip_value=0.01, **kwargs)[source]

Bases: pixyz.losses.adversarial_loss.AdversarialJSDivergence

Adversarial loss (Wasserstein Distance).

loss_text
d_loss(y1, y2, *args, **kwargs)[source]
g_loss(y1, y2, *args, **kwargs)[source]
train(train_x, **kwargs)[source]

Train the implicit (adversarial) loss function.

Loss for special purpose

Parameter

class pixyz.losses.losses.Parameter(input_var)[source]

Bases: pixyz.losses.losses.Loss

estimate(x={}, **kwargs)[source]
loss_text

Operators

LossOperator

class pixyz.losses.losses.LossOperator(loss1, loss2)[source]

Bases: pixyz.losses.losses.Loss

loss_text
estimate(x={}, **kwargs)[source]
train(x, **kwargs)[source]

TODO: Fix

test(x, **kwargs)[source]

TODO: Fix

LossSelfOperator

class pixyz.losses.losses.LossSelfOperator(loss1)[source]

Bases: pixyz.losses.losses.Loss

train(x={}, **kwargs)[source]

Train the implicit (adversarial) loss function.

test(x={}, **kwargs)[source]

Test the implicit (adversarial) loss function.

AddLoss

class pixyz.losses.losses.AddLoss(loss1, loss2)[source]

Bases: pixyz.losses.losses.LossOperator

loss_text
estimate(x={}, **kwargs)[source]

SubLoss

class pixyz.losses.losses.SubLoss(loss1, loss2)[source]

Bases: pixyz.losses.losses.LossOperator

loss_text
estimate(x={}, **kwargs)[source]

MulLoss

class pixyz.losses.losses.MulLoss(loss1, loss2)[source]

Bases: pixyz.losses.losses.LossOperator

loss_text
estimate(x={}, **kwargs)[source]

DivLoss

class pixyz.losses.losses.DivLoss(loss1, loss2)[source]

Bases: pixyz.losses.losses.LossOperator

loss_text
estimate(x={}, **kwargs)[source]

NegLoss

class pixyz.losses.losses.NegLoss(loss1)[source]

Bases: pixyz.losses.losses.LossSelfOperator

loss_text
estimate(x={}, **kwargs)[source]

BatchMean

class pixyz.losses.losses.BatchMean(loss1)[source]

Bases: pixyz.losses.losses.LossSelfOperator

Loss averaged over batch data.

\mathbb{E}_{p_{data}(x)}[\mathcal{L}(x)] \approx \frac{1}{N}\sum_{i=1}^N \mathcal{L}(x_i),

where x_i \sim p_{data}(x) and \mathcal{L} is a loss function.

loss_text
estimate(x={}, **kwargs)[source]

BatchSum

class pixyz.losses.losses.BatchSum(loss1)[source]

Bases: pixyz.losses.losses.LossSelfOperator

Loss summed over batch data.

\sum_{i=1}^N \mathcal{L}(x_i),

where x_i \sim p_{data}(x) and \mathcal{L} is a loss function.

loss_text
estimate(x={}, **kwargs)[source]

pixyz.models (Model API)

Model

class pixyz.models.Model(loss, test_loss=None, distributions=[], optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={})[source]

Bases: object

set_loss(loss, test_loss=None)[source]
train(train_x={}, **kwargs)[source]
test(test_x={}, **kwargs)[source]

Pre-implementation models

ML

class pixyz.models.ML(p, other_distributions=[], optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={})[source]

Bases: pixyz.models.model.Model

Maximum Likelihood (log-likelihood)

train(train_x={}, **kwargs)[source]
test(test_x={}, **kwargs)[source]

VAE

class pixyz.models.VAE(encoder, decoder, other_distributions=[], regularizer=[], optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={})[source]

Bases: pixyz.models.model.Model

Variational Autoencoder

[Kingma+ 2013] Auto-Encoding Variational Bayes

train(train_x={}, **kwargs)[source]
test(test_x={}, **kwargs)[source]

VI

class pixyz.models.VI(p, approximate_dist, other_distributions=[], optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={})[source]

Bases: pixyz.models.model.Model

Variational Inference (Amortized inference)

train(train_x={}, **kwargs)[source]
test(test_x={}, **kwargs)[source]

GAN

class pixyz.models.GAN(p_data, p, discriminator, optimizer=<class 'torch.optim.adam.Adam'>, optimizer_params={}, d_optimizer=<class 'torch.optim.adam.Adam'>, d_optimizer_params={})[source]

Bases: pixyz.models.model.Model

Generative Adversarial Network

train(train_x={}, adversarial_loss=True, **kwargs)[source]
test(test_x={}, adversarial_loss=True, **kwargs)[source]

pixyz.utils

pixyz.utils.set_epsilon(eps)[source]
pixyz.utils.epsilon()[source]
pixyz.utils.get_dict_values(dicts, keys, return_dict=False)[source]
pixyz.utils.delete_dict_values(dicts, keys)[source]
pixyz.utils.detach_dict(dicts)[source]
pixyz.utils.replace_dict_keys(dicts, replace_list_dict)[source]
pixyz.utils.tolist(a)[source]

Indices and tables