tyche.distributions

This module contains several classes of probability distributions that can be easily manipulated (e.g., shift, scale, or add to distributions to get new distributions).

Example:

person_height_cm = NormalDist(mean=180, std_dev=5)
heel_height_cm = NormalDist(mean=5, std_dev=3)

total_height_cm = person_height_cm + heel_height_cm
total_height_ft = total_height_cm * 0.0328084

hoop_height_ft = 10
distance_to_hoop_ft = hoop_height_ft - total_height_ft

# Result: distance_to_hoop_ft = Normal(mean=3.930, std_dev=0.191)

The following probability distributions are currently available:

This aims to allow the more flexible and intuitive use of probability distributions, by reducing the amount of manual work that is required to manipulate and use them.

exception tyche.distributions.TycheDistributionsException(message)[source]

An exception type that is thrown when errors occur in the construction or use of probability distributions.

Parameters:

message (str) – A message describing the reason that this exception was raised.

class tyche.distributions.ProbDist[source]

A probability distribution over a space of numeric values.

sample(rng, shape=None)[source]

Samples random values from this distribution.

Parameters:

  • rng (Generator) – A NumPy random number generator that is used to generate random samples from this distribution.

  • shape (Optional[Union[int, tuple]]) – Configures the format of the returned samples from this probability distribution. By default, a single sampled value is returned. If an int is provided, then a NumPy array of shape values will be returned. If a tuple is provided, then a NumPy array of sampled values will be returned with the tuple used as the array’s shape.

Return type:

ArrayLike

class tyche.distributions.ContinuousProbDist[source]

Bases: ProbDist

A probability distribution over a continuous space of numeric values.

truncate(minimum, maximum)[source]

Returns a new distribution that represents the truncation of this distribution to the range [minimum, maximum].

Parameters:

  • minimum (float) – A lower limit on the numeric values in this distribution after truncation.

  • maximum (float) – An upper limit on the numeric values in this distribution after truncation.

Return type:

ContinuousProbDist

sample(rng, shape=None)[source]

Samples random values from this distribution.

Parameters:

  • rng (Generator) – A NumPy random number generator that is used to generate random samples from this distribution.

  • shape (Optional[Union[int, tuple]]) – Configures the format of the returned samples from this probability distribution. By default, a single sampled value is returned. If an int is provided, then a NumPy array of shape values will be returned. If a tuple is provided, then a NumPy array of sampled values will be returned with the tuple used as the array’s shape.

Return type:

ArrayLike

cdf(x)[source]

Evaluates the cumulative density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

mean()[source]

Evaluates to the mean value of this distribution.

Return type:

float

variance()[source]

Evaluates to the variance of this distribution.

Return type:

float

std_dev()[source]

Evaluates to the standard deviation of this distribution.

Return type:

float

pdf(x)[source]

Evaluates the probability density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the probability density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

inverse_cdf(prob)[source]

Evaluates the inverse cumulative density function of this distribution at prob. This involves calculating the value in this distribution that would produce the given probability, prob, if it was used to evaluate the cumulative density function of this distribution.

Parameters:

prob (ArrayLike) – The point or points at which to evaluate the inverse cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of prob.

Return type:

ArrayLike

class tyche.distributions.LinearTransformContinuousProbDist(dist, shift, scale)[source]

Bases: ContinuousProbDist

Applies a linear transformation (scale + shift) to a ContinuousProbDist. The scaling of values is performed before the shift of values.

Parameters:

  • dist (ContinuousProbDist) – A delegate continuous probability distribution to scale and shift.

  • shift (float) – A shift to be applied to the delegate distribution, dist, after the scale is applied.

  • scale (float) – A scale to be applied to the delegate distribution, dist, before the shift is applied.

sample(rng, shape=None)[source]

Samples random values from this distribution.

Parameters:

  • rng (Generator) – A NumPy random number generator that is used to generate random samples from this distribution.

  • shape (Optional[int]) – Configures the format of the returned samples from this probability distribution. By default, a single sampled value is returned. If an int is provided, then a NumPy array of shape values will be returned. If a tuple is provided, then a NumPy array of sampled values will be returned with the tuple used as the array’s shape.

Return type:

ArrayLike

cdf(x)[source]

Evaluates the cumulative density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

variance()[source]

Evaluates to the variance of this distribution.

Return type:

float

pdf(x)[source]

Evaluates the probability density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the probability density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

inverse_cdf(prob)[source]

Evaluates the inverse cumulative density function of this distribution at prob. This involves calculating the value in this distribution that would produce the given probability, prob, if it was used to evaluate the cumulative density function of this distribution.

Parameters:

prob (ArrayLike) – The point or points at which to evaluate the inverse cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of prob.

Return type:

ArrayLike

class tyche.distributions.TruncatedContinuousProbDist(dist, minimum, maximum)[source]

Bases: ContinuousProbDist

Applies a truncation to a ContinuousProbDist. All values below minimum and above maximum are discarded.

Parameters:

  • dist (ContinuousProbDist) – A delegate continuous probability distribution to truncate.

  • minimum (float) – The lower bound to use to truncate the delegate distribution.

  • maximum (float) – The upper bound to use to truncate the delegate distribution.

truncate(minimum, maximum)[source]

Returns a new distribution that represents the truncation of this distribution to the range [minimum, maximum].

Parameters:

  • minimum (float) – A lower limit on the numeric values in this distribution after truncation.

  • maximum (float) – An upper limit on the numeric values in this distribution after truncation.

Return type:

ContinuousProbDist

cdf(x)[source]

Evaluates the cumulative density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

pdf(x)[source]

Evaluates the probability density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the probability density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

inverse_cdf(prob)[source]

Evaluates the inverse cumulative density function of this distribution at prob. This involves calculating the value in this distribution that would produce the given probability, prob, if it was used to evaluate the cumulative density function of this distribution.

Parameters:

prob (ArrayLike) – The point or points at which to evaluate the inverse cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of prob.

Return type:

ArrayLike

class tyche.distributions.UniformDist(minimum, maximum)[source]

Bases: ContinuousProbDist

A uniform probability distribution over the range [minimum, maximum]. All values within this range have equal probability of being sampled.

Parameters:

  • minimum (float) – The lower bound on values that could be sampled from this uniform probability distribution.

  • maximum (float) – The upper bound on values that could be sampled from this uniform probability distribution.

cdf(x)[source]

Evaluates the cumulative density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

variance()[source]

Evaluates to the variance of this distribution.

Return type:

float

pdf(x)[source]

Evaluates the probability density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the probability density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

inverse_cdf(prob)[source]

Evaluates the inverse cumulative density function of this distribution at prob. This involves calculating the value in this distribution that would produce the given probability, prob, if it was used to evaluate the cumulative density function of this distribution.

Parameters:

prob (ArrayLike) – The point or points at which to evaluate the inverse cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of prob.

Return type:

ArrayLike

class tyche.distributions.NormalDist(mean, std_dev)[source]

Bases: ContinuousProbDist

A normal probability distribution centered around mean with a standard deviation of std_dev.

Parameters:

  • mean (float) – The mean of this normal distribution.

  • std_dev (float) – The standard deviation of this normal distribution.

cdf(x)[source]

Evaluates the cumulative density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

variance()[source]

Evaluates to the variance of this distribution.

Return type:

float

std_dev()[source]

Evaluates to the standard deviation of this distribution.

Return type:

float

pdf(x)[source]

Evaluates the probability density function of this distribution at x. The resulting value should fall in the range [0, 1], although numerical error can cause slightly lower or higher values to be returned.

Parameters:

x (ArrayLike) – The point or points at which to evaluate the probability density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of x.

Return type:

ArrayLike

inverse_cdf(prob)[source]

Evaluates the inverse cumulative density function of this distribution at prob. This involves calculating the value in this distribution that would produce the given probability, prob, if it was used to evaluate the cumulative density function of this distribution.

Parameters:

prob (ArrayLike) – The point or points at which to evaluate the inverse cumulative density function of this distribution. If a numerical value is provided, a numerical value is returned. If a NumPy array of values is provided, then a NumPy array of values will be returned that matches the shape of prob.

Return type:

ArrayLike