tensorflow_backend

class pyhf.tensor.tensorflow_backend.tensorflow_backend(**kwargs)

Bases: object

TensorFlow backend for pyhf

__init__(**kwargs)

Attributes

name

precision

dtypemap

default_do_grad

array_subtype

The array content type for tensorflow

array_type

The array type for tensorflow

Methods

_setup()

Run any global setups for the tensorflow lib.

abs(tensor)

astensor(tensor_in, dtype='float')

Convert to a TensorFlow Tensor.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> tensor = pyhf.tensorlib.astensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> tensor
<tf.Tensor: shape=(2, 3), dtype=float64, numpy=
array([[1., 2., 3.],
       [4., 5., 6.]])>
>>> type(tensor)
<class 'tensorflow.python.framework.ops.EagerTensor'>

Parameters:

tensor_in (Number or Tensor) – Tensor object

Returns:

A symbolic handle to one of the outputs of a tf.Operation.

Return type:

tf.Tensor

boolean_mask(tensor, mask)

clip(tensor_in, min_value, max_value)

Clips (limits) the tensor values to be within a specified min and max.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> a = pyhf.tensorlib.astensor([-2, -1, 0, 1, 2])
>>> t = pyhf.tensorlib.clip(a, -1, 1)
>>> print(t)
tf.Tensor([-1. -1.  0.  1.  1.], shape=(5,), dtype=float64)

Parameters:

• tensor_in (tensor) – The input tensor object

• min_value (scalar or tensor or None) – The minimum value to be clipped to

• max_value (scalar or tensor or None) – The maximum value to be clipped to

Returns:

A clipped tensor

Return type:

TensorFlow Tensor

concatenate(sequence, axis=0)

Join a sequence of arrays along an existing axis.

Parameters:

• sequence – sequence of tensors

• axis – dimension along which to concatenate

Returns:

the concatenated tensor

Return type:

output

conditional(predicate, true_callable, false_callable)

Runs a callable conditional on the boolean value of the evaluation of a predicate

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> tensorlib = pyhf.tensorlib
>>> a = tensorlib.astensor([4])
>>> b = tensorlib.astensor([5])
>>> t = tensorlib.conditional((a < b)[0], lambda: a + b, lambda: a - b)
>>> print(t)
tf.Tensor([9.], shape=(1,), dtype=float64)

Parameters:

• predicate (scalar) – The logical condition that determines which callable to evaluate

• true_callable (callable) – The callable that is evaluated when the predicate evaluates to true

• false_callable (callable) – The callable that is evaluated when the predicate evaluates to false

Returns:

The output of the callable that was evaluated

Return type:

TensorFlow Tensor

divide(tensor_in_1, tensor_in_2)

einsum(subscripts, *operands)

A generalized contraction between tensors of arbitrary dimension.

This function returns a tensor whose elements are defined by equation, which is written in a shorthand form inspired by the Einstein summation convention.

Parameters:

• subscripts – str, specifies the subscripts for summation

• operands – list of array_like, these are the tensors for the operation

Returns:

the calculation based on the Einstein summation convention

Return type:

TensorFlow Tensor

erf(tensor_in)

The error function of complex argument.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> a = pyhf.tensorlib.astensor([-2., -1., 0., 1., 2.])
>>> t = pyhf.tensorlib.erf(a)
>>> print(t)
tf.Tensor([-0.99532227 -0.84270079  0.          0.84270079  0.99532227], shape=(5,), dtype=float64)

Parameters:

tensor_in (tensor) – The input tensor object

Returns:

The values of the error function at the given points.

Return type:

TensorFlow Tensor

erfinv(tensor_in)

The inverse of the error function of complex argument.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> a = pyhf.tensorlib.astensor([-2., -1., 0., 1., 2.])
>>> t = pyhf.tensorlib.erfinv(pyhf.tensorlib.erf(a))
>>> print(t)
tf.Tensor([-2. -1.  0.  1.  2.], shape=(5,), dtype=float64)

Parameters:

tensor_in (tensor) – The input tensor object

Returns:

The values of the inverse of the error function at the given points.

Return type:

TensorFlow Tensor

exp(tensor_in)

gather(tensor, indices)

isfinite(tensor)

log(tensor_in)

normal(x, mu, sigma)

The probability density function of the Normal distribution evaluated at x given parameters of mean of mu and standard deviation of sigma.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.normal(0.5, 0., 1.)
>>> print(t) 
tf.Tensor(0.35206532..., shape=(), dtype=float64)
>>> values = pyhf.tensorlib.astensor([0.5, 2.0])
>>> means = pyhf.tensorlib.astensor([0., 2.3])
>>> sigmas = pyhf.tensorlib.astensor([1., 0.8])
>>> t = pyhf.tensorlib.normal(values, means, sigmas)
>>> print(t)
tf.Tensor([0.35206533 0.46481887], shape=(2,), dtype=float64)

Parameters:

• x (tensor or float) – The value at which to evaluate the Normal distribution p.d.f.

• mu (tensor or float) – The mean of the Normal distribution

• sigma (tensor or float) – The standard deviation of the Normal distribution

Returns:

Value of Normal(x|mu, sigma)

Return type:

TensorFlow Tensor

normal_cdf(x, mu=0.0, sigma=1)

Compute the value of cumulative distribution function for the Normal distribution at x.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.normal_cdf(0.8)
>>> print(t) 
tf.Tensor(0.78814460..., shape=(), dtype=float64)
>>> values = pyhf.tensorlib.astensor([0.8, 2.0])
>>> t = pyhf.tensorlib.normal_cdf(values)
>>> print(t)
tf.Tensor([0.7881446  0.97724987], shape=(2,), dtype=float64)

Parameters:

• x (tensor or float) – The observed value of the random variable to evaluate the CDF for

• mu (tensor or float) – The mean of the Normal distribution

• sigma (tensor or float) – The standard deviation of the Normal distribution

Returns:

The CDF

Return type:

TensorFlow Tensor

normal_dist(mu, sigma)

Construct a Normal distribution with mean mu and standard deviation sigma.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> means = pyhf.tensorlib.astensor([5, 8])
>>> stds = pyhf.tensorlib.astensor([1, 0.5])
>>> values = pyhf.tensorlib.astensor([4, 9])
>>> normals = pyhf.tensorlib.normal_dist(means, stds)
>>> t = normals.log_prob(values)
>>> print(t)
tf.Tensor([-1.41893853 -2.22579135], shape=(2,), dtype=float64)

Parameters:

• mu (tensor or float) – The mean of the Normal distribution

• sigma (tensor or float) – The standard deviation of the Normal distribution

Returns:

The Normal distribution class

Return type:

TensorFlow Probability Normal distribution

normal_logpdf(x, mu, sigma)

The log of the probability density function of the Normal distribution evaluated at x given parameters of mean of mu and standard deviation of sigma.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.normal_logpdf(0.5, 0., 1.)
>>> print(t) 
tf.Tensor(-1.04393853..., shape=(), dtype=float64)
>>> values = pyhf.tensorlib.astensor([0.5, 2.0])
>>> means = pyhf.tensorlib.astensor([0., 2.3])
>>> sigmas = pyhf.tensorlib.astensor([1., 0.8])
>>> t = pyhf.tensorlib.normal_logpdf(values, means, sigmas)
>>> print(t)
tf.Tensor([-1.04393853 -0.76610747], shape=(2,), dtype=float64)

Parameters:

• x (tensor or float) – The value at which to evaluate the Normal distribution p.d.f.

• mu (tensor or float) – The mean of the Normal distribution

• sigma (tensor or float) – The standard deviation of the Normal distribution

Returns:

Value of log(Normal(x|mu, sigma))

Return type:

TensorFlow Tensor

ones(shape, dtype='float')

outer(tensor_in_1, tensor_in_2)

percentile(tensor_in, q, axis=None, interpolation='linear')

Compute the \(q\)-th percentile of the tensor along the specified axis.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> a = pyhf.tensorlib.astensor([[10, 7, 4], [3, 2, 1]])
>>> t = pyhf.tensorlib.percentile(a, 50)
>>> print(t)
tf.Tensor(3.5, shape=(), dtype=float64)
>>> t = pyhf.tensorlib.percentile(a, 50, axis=1)
>>> print(t)
tf.Tensor([7. 2.], shape=(2,), dtype=float64)

Parameters:

• tensor_in (tensor) – The tensor containing the data

• q (float or tensor) – The \(q\)-th percentile to compute

• axis (number or tensor) – The dimensions along which to compute

• interpolation (str) –

  The interpolation method to use when the desired percentile lies between two data points i < j:

  • 'linear': i + (j - i) * fraction, where fraction is the fractional part of the index surrounded by i and j.

  • 'lower': i.

  • 'higher': j.

  • 'midpoint': (i + j) / 2.

  • 'nearest': i or j, whichever is nearest.

Returns:

The value of the \(q\)-th percentile of the tensor along the specified axis.

Return type:

TensorFlow Tensor

Added in version 0.7.0.

poisson(n, lam)

The continuous approximation, using \(n! = \Gamma\left(n+1\right)\), to the probability mass function of the Poisson distribution evaluated at n given the parameter lam.

Note

Though the p.m.f of the Poisson distribution is not defined for \(\lambda = 0\), the limit as \(\lambda \to 0\) is still defined, which gives a degenerate p.m.f. of

\[\begin{split}\lim_{\lambda \to 0} \,\mathrm{Pois}(n | \lambda) = \left\{\begin{array}{ll} 1, & n = 0,\\ 0, & n > 0 \end{array}\right.\end{split}\]

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.poisson(5., 6.)
>>> print(t) 
tf.Tensor(0.16062314..., shape=(), dtype=float64)
>>> values = pyhf.tensorlib.astensor([5., 9.])
>>> rates = pyhf.tensorlib.astensor([6., 8.])
>>> t = pyhf.tensorlib.poisson(values, rates)
>>> print(t)
tf.Tensor([0.16062314 0.12407692], shape=(2,), dtype=float64)

Parameters:

• n (tensor or float) – The value at which to evaluate the approximation to the Poisson distribution p.m.f. (the observed number of events)

• lam (tensor or float) – The mean of the Poisson distribution p.m.f. (the expected number of events)

Returns:

Value of the continuous approximation to Poisson(n|lam)

Return type:

TensorFlow Tensor

poisson_dist(rate)

Construct a Poisson distribution with rate parameter rate.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> rates = pyhf.tensorlib.astensor([5, 8])
>>> values = pyhf.tensorlib.astensor([4, 9])
>>> poissons = pyhf.tensorlib.poisson_dist(rates)
>>> t = poissons.log_prob(values)
>>> print(t)
tf.Tensor([-1.74030218 -2.0868536 ], shape=(2,), dtype=float64)

Parameters:

rate (tensor or float) – The mean of the Poisson distribution (the expected number of events)

Returns:

The Poisson distribution class

Return type:

TensorFlow Probability Poisson distribution

poisson_logpdf(n, lam)

The log of the continuous approximation, using \(n! = \Gamma\left(n+1\right)\), to the probability mass function of the Poisson distribution evaluated at n given the parameter lam.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.poisson_logpdf(5., 6.)
>>> print(t) 
tf.Tensor(-1.82869439..., shape=(), dtype=float64)
>>> values = pyhf.tensorlib.astensor([5., 9.])
>>> rates = pyhf.tensorlib.astensor([6., 8.])
>>> t = pyhf.tensorlib.poisson_logpdf(values, rates)
>>> print(t)
tf.Tensor([-1.8286944 -2.0868536], shape=(2,), dtype=float64)

Parameters:

• n (tensor or float) – The value at which to evaluate the approximation to the Poisson distribution p.m.f. (the observed number of events)

• lam (tensor or float) – The mean of the Poisson distribution p.m.f. (the expected number of events)

Returns:

Value of the continuous approximation to log(Poisson(n|lam))

Return type:

TensorFlow Tensor

power(tensor_in_1, tensor_in_2)

product(tensor_in, axis=None)

ravel(tensor)

Return a flattened view of the tensor, not a copy.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> tensor = pyhf.tensorlib.astensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> t_ravel = pyhf.tensorlib.ravel(tensor)
>>> print(t_ravel)
tf.Tensor([1. 2. 3. 4. 5. 6.], shape=(6,), dtype=float64)

Parameters:

tensor (Tensor) – Tensor object

Returns:

A flattened array.

Return type:

tf.Tensor

reshape(tensor, newshape)

shape(tensor)

simple_broadcast(*args)

Broadcast a sequence of 1 dimensional arrays.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> b = pyhf.tensorlib.simple_broadcast(
...   pyhf.tensorlib.astensor([1]),
...   pyhf.tensorlib.astensor([2, 3, 4]),
...   pyhf.tensorlib.astensor([5, 6, 7]))
>>> print([str(t) for t in b]) 
['tf.Tensor([1. 1. 1.], shape=(3,), dtype=float64)',
 'tf.Tensor([2. 3. 4.], shape=(3,), dtype=float64)',
 'tf.Tensor([5. 6. 7.], shape=(3,), dtype=float64)']

Parameters:

args (Array of Tensors) – Sequence of arrays

Returns:

The sequence broadcast together.

Return type:

list of Tensors

sqrt(tensor_in)

stack(sequence, axis=0)

sum(tensor_in, axis=None)

tile(tensor_in, repeats)

Repeat tensor data along a specific dimension

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> a = pyhf.tensorlib.astensor([[1.0], [2.0]])
>>> t = pyhf.tensorlib.tile(a, (1, 2))
>>> print(t)
tf.Tensor(
[[1. 1.]
 [2. 2.]], shape=(2, 2), dtype=float64)

Parameters:

• tensor_in (tensor) – The tensor to be repeated

• repeats (tensor) – The tuple of multipliers for each dimension

Returns:

The tensor with repeated axes

Return type:

TensorFlow Tensor

to_numpy(tensor_in)

Convert the TensorFlow tensor to a numpy.ndarray.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> tensor = pyhf.tensorlib.astensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> print(tensor)
tf.Tensor(
[[1. 2. 3.]
 [4. 5. 6.]], shape=(2, 3), dtype=float64)
>>> numpy_ndarray = pyhf.tensorlib.to_numpy(tensor)
>>> numpy_ndarray
array([[1., 2., 3.],
       [4., 5., 6.]])
>>> type(numpy_ndarray)
<class 'numpy.ndarray'>

Parameters:

tensor_in (tensor) – The input tensor object.

Returns:

The tensor converted to a NumPy ndarray.

Return type:

numpy.ndarray

tolist(tensor_in)

transpose(tensor_in)

Transpose the tensor.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> tensor = pyhf.tensorlib.astensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> print(tensor)
tf.Tensor(
[[1. 2. 3.]
 [4. 5. 6.]], shape=(2, 3), dtype=float64)
>>> tensor_T = pyhf.tensorlib.transpose(tensor)
>>> print(tensor_T)
tf.Tensor(
[[1. 4.]
 [2. 5.]
 [3. 6.]], shape=(3, 2), dtype=float64)

Parameters:

tensor_in (tensor) – The input tensor object.

Returns:

The transpose of the input tensor.

Return type:

TensorFlow Tensor

Added in version 0.7.0.

where(mask, tensor_in_1, tensor_in_2)

Apply a boolean selection mask to the elements of the input tensors.

Example

>>> import pyhf
>>> pyhf.set_backend("tensorflow")
>>> t = pyhf.tensorlib.where(
...     pyhf.tensorlib.astensor([1, 0, 1], dtype='bool'),
...     pyhf.tensorlib.astensor([1, 1, 1]),
...     pyhf.tensorlib.astensor([2, 2, 2]),
... )
>>> print(t)
tf.Tensor([1. 2. 1.], shape=(3,), dtype=float64)

Parameters:

• mask (bool) – Boolean mask (boolean or tensor object of booleans)

• tensor_in_1 (Tensor) – Tensor object

• tensor_in_2 (Tensor) – Tensor object

Returns:

The result of the mask being applied to the tensors.

Return type:

TensorFlow Tensor

zeros(shape, dtype='float')