bounds - Limiting data values for a palette¶

Continuous variables have values anywhere in the range minus infinite to plus infinite. However, when creating a visual representation of these values what usually matters is the relative difference between the values. This is where rescaling comes into play.

The values are mapped onto a range that a scale can deal with. For graphical representation that range tends to be \([0, 1]\) or \([0, n]\), where \(n\) is some number that makes the plotted object overflow the plotting area.

Although a scale may be able handle the \([0, n]\) range, it may be desirable to have a lower bound greater than zero. For example, if data values get mapped to zero on a scale whose graphical representation is the size/area/radius/length some data will be invisible. The solution is to restrict the lower bound e.g. \([0.1, 1]\). Similarly you can restrict the upper bound -- using these functions.

mizani.bounds.censor(x: TFloatVector, range: tuple[float, float] = (0, 1), only_finite: bool = True) → TFloatVector[source]¶

Convert any values outside of range to a NULL type object.

Parameters:

xnumpy:array_like: Values to manipulate
rangepython:tuple: (min, max) giving desired output range
only_finitebool: If True (the default), will only modify finite values.

Returns:

xnumpy:array_like: Censored array

Notes

All values in x should be of the same type. only_finite parameter is not considered for Datetime and Timedelta types.

The NULL type object depends on the type of values in x.

float - float('nan')
int - float('nan')
datetime.datetime : np.datetime64(NaT)
datetime.timedelta : np.timedelta64(NaT)

Examples

>>> a = np.array([1, 2, np.inf, 3, 4, -np.inf, 5])
>>> censor(a, (0, 10))
array([  1.,   2.,  inf,   3.,   4., -inf,   5.])
>>> censor(a, (0, 10), False)
array([ 1.,  2., nan,  3.,  4., nan,  5.])
>>> censor(a, (2, 4))
array([ nan,   2.,  inf,   3.,   4., -inf,  nan])

mizani.bounds.expand_range(range: tuple[float, float], mul: float = 0, add: float = 0, zero_width: float = 1) → tuple[float, float][source]¶

Expand a range with a multiplicative or additive constant

Parameters:

rangepython:tuple: Range of data. Size 2.
mulpython:int | python:float: Multiplicative constant
addpython:int | python:float | timedelta: Additive constant
zero_widthpython:int | python:float | timedelta: Distance to use if range has zero width

Returns:

outpython:tuple: Expanded range

Notes

If expanding datetime or timedelta types, add and zero_width must be suitable timedeltas i.e. You should not mix types between Numpy, Pandas and the datetime module.

Examples

>>> expand_range((3, 8))
(3, 8)
>>> expand_range((0, 10), mul=0.1)
(-1.0, 11.0)
>>> expand_range((0, 10), add=2)
(-2, 12)
>>> expand_range((0, 10), mul=.1, add=2)
(-3.0, 13.0)
>>> expand_range((0, 1))
(0, 1)

When the range has zero width

>>> expand_range((5, 5))
(4.5, 5.5)

mizani.bounds.rescale(x: FloatArrayLike, to: tuple[float, float] = (0, 1), _from: tuple[float, float] | None = None) → NDArrayFloat[source]¶

Rescale numeric vector to have specified minimum and maximum.

Parameters:

xnumpy:array_like | numeric: 1D vector of values to manipulate.
topython:tuple: output range (numeric vector of length two)
_frompython:tuple: input range (numeric vector of length two). If not given, is calculated from the range of x

Returns:

outnumpy:array_like: Rescaled values

Examples

>>> x = [0, 2, 4, 6, 8, 10]
>>> rescale(x)
array([0. , 0.2, 0.4, 0.6, 0.8, 1. ])
>>> rescale(x, to=(0, 2))
array([0. , 0.4, 0.8, 1.2, 1.6, 2. ])
>>> rescale(x, to=(0, 2), _from=(0, 20))
array([0. , 0.2, 0.4, 0.6, 0.8, 1. ])

mizani.bounds.rescale_max(x: FloatArrayLike, to: tuple[float, float] = (0, 1), _from: tuple[float, float] | None = None) → NDArrayFloat[source]¶

Rescale numeric vector to have specified maximum.

Parameters:

xnumpy:array_like: 1D vector of values to manipulate.
topython:tuple: output range (numeric vector of length two)
_frompython:tuple: input range (numeric vector of length two). If not given, is calculated from the range of x. Only the 2nd (max) element is essential to the output.

Returns:

outnumpy:array_like: Rescaled values

Examples

>>> x = np.array([0, 2, 4, 6, 8, 10])
>>> rescale_max(x, (0, 3))
array([0. , 0.6, 1.2, 1.8, 2.4, 3. ])

Only the 2nd (max) element of the parameters to and _from are essential to the output.

>>> rescale_max(x, (1, 3))
array([0. , 0.6, 1.2, 1.8, 2.4, 3. ])
>>> rescale_max(x, (0, 20))
array([ 0.,  4.,  8., 12., 16., 20.])

If max(x) < _from[1] then values will be scaled beyond the requested maximum (to[1]).

>>> rescale_max(x, to=(1, 3), _from=(-1, 6))
array([0., 1., 2., 3., 4., 5.])

If the values are the same, they taken on the requested maximum. This includes an array of all zeros.

>>> rescale_max(np.array([5, 5, 5]))
array([1., 1., 1.])
>>> rescale_max(np.array([0, 0, 0]))
array([1, 1, 1])

mizani.bounds.rescale_mid(x: FloatArrayLike, to: tuple[float, float] = (0, 1), _from: tuple[float, float] | None = None, mid: float = 0) → NDArrayFloat[source]¶

Rescale numeric vector to have specified minimum, midpoint, and maximum.

Parameters:

xnumpy:array_like: 1D vector of values to manipulate.
topython:tuple: output range (numeric vector of length two)
_frompython:tuple: input range (numeric vector of length two). If not given, is calculated from the range of x
midnumeric: mid-point of input range

Returns:

outnumpy:array_like: Rescaled values

Examples

>>> rescale_mid([1, 2, 3], mid=1)
array([0.5 , 0.75, 1.  ])
>>> rescale_mid([1, 2, 3], mid=2)
array([0. , 0.5, 1. ])

rescale_mid does have the same signature as rescale and rescale_max. In cases where we need a compatible function with the same signature, we use a closure around the extra mid argument.

>>> def rescale_mid_compat(mid):
...     def _rescale(x, to=(0, 1), _from=None):
...         return rescale_mid(x, to, _from, mid=mid)
...     return _rescale

>>> rescale_mid2 = rescale_mid_compat(mid=2)
>>> rescale_mid2([1, 2, 3])
array([0. , 0.5, 1. ])

mizani.bounds.squish_infinite(x: FloatArrayLike, range: tuple[float, float] = (0, 1)) → NDArrayFloat[source]¶

Truncate infinite values to a range.

Parameters:

xnumpy:array_like: Values that should have infinities squished.
rangepython:tuple: The range onto which to squish the infinites. Must be of size 2.

Returns:

outnumpy:array_like: Values with infinites squished.

Examples

>>> arr1 = np.array([0, .5, .25, np.inf, .44])
>>> arr2 = np.array([0, -np.inf, .5, .25, np.inf])
>>> squish_infinite(arr1)
array([0.  , 0.5 , 0.25, 1.  , 0.44])
>>> squish_infinite(arr2, (-10, 9))
array([  0.  , -10.  ,   0.5 ,   0.25,   9.  ])

mizani.bounds.zero_range(x: tuple[Any, Any], tol: float = 2.220446049250313e-14) → bool[source]¶

Determine if range of vector is close to zero.

Parameters:

xnumpy:array_like: Value(s) to check. If it is an array_like, it should be of length 2.
tolpython:float: Tolerance. Default tolerance is the machine epsilon times \(10^2\).

Returns:

outbool: Whether x has zero range.

Examples

>>> zero_range([1, 1])
True
>>> zero_range([1, 2])
False
>>> zero_range([1, 2], tol=2)
True

mizani.bounds.expand_range_distinct(range: tuple[float, float], expand: tuple[float, float] | tuple[float, float, float, float] = (0, 0, 0, 0), zero_width: float = 1) → tuple[float, float][source]¶

Expand a range with a multiplicative or additive constants

Similar to expand_range() but both sides of the range expanded using different constants

Parameters:

rangepython:tuple: Range of data. Size 2
expandpython:tuple: Length 2 or 4. If length is 2, then the same constants are used for both sides. If length is 4 then the first two are are the Multiplicative (mul) and Additive (add) constants for the lower limit, and the second two are the constants for the upper limit.
zero_widthpython:int | python:float | timedelta: Distance to use if range has zero width

Returns:

outpython:tuple: Expanded range

Examples

>>> expand_range_distinct((3, 8))
(3, 8)
>>> expand_range_distinct((0, 10), (0.1, 0))
(-1.0, 11.0)
>>> expand_range_distinct((0, 10), (0.1, 0, 0.1, 0))
(-1.0, 11.0)
>>> expand_range_distinct((0, 10), (0.1, 0, 0, 0))
(-1.0, 10)
>>> expand_range_distinct((0, 10), (0, 2))
(-2, 12)
>>> expand_range_distinct((0, 10), (0, 2, 0, 2))
(-2, 12)
>>> expand_range_distinct((0, 10), (0, 0, 0, 2))
(0, 12)
>>> expand_range_distinct((0, 10), (.1, 2))
(-3.0, 13.0)
>>> expand_range_distinct((0, 10), (.1, 2, .1, 2))
(-3.0, 13.0)
>>> expand_range_distinct((0, 10), (0, 0, .1, 2))
(0, 13.0)

mizani.bounds.squish(x: FloatArrayLike, range: tuple[float, float] = (0, 1), only_finite: bool = True) → NDArrayFloat[source]¶

Squish values into range.

Parameters:

xnumpy:array_like: Values that should have out of range values squished.
rangepython:tuple: The range onto which to squish the values.
only_finite: boolean: When true, only squishes finite values.

Returns:

outnumpy:array_like: Values with out of range values squished.

Examples

>>> squish([-1.5, 0.2, 0.8, 1.0, 1.2])
array([0. , 0.2, 0.8, 1. , 1. ])

>>> squish([-np.inf, -1.5, 0.2, 0.8, 1.0, np.inf], only_finite=False)
array([0. , 0. , 0.2, 0.8, 1. , 1. ])