`tabulation` Module

Tabulation class, PDS Ring-Moon Systems Node, SETI Institute

The Tabulation class represents a mathematical function by a sequence of linear interpolations between points defined by arrays of x and y coordinates. Although optimized to model filter bandpasses and spectral flux, the class is sufficiently general to be used in a wide range of applications. See the documentation for the Tabulation class for full details.

class tabulation.Tabulation(x, y)[source]

Bases: object

A class that represents a function by a sequence of linear interpolations.

Although optimized to model filter bandpasses and spectral flux, the class is sufficiently general to be used in a wide range of applications.

The interpolations are defined between points defined by arrays of x and y coordinates. The mathematical function is treated as equal to zero outside the domain of the x coordinates, with a step at the provided leading and trailing x coordinates.

The internal arrays of a Tabulation can be accessed directly via the x and y attributes. However, these arrays are not writeable.

Tabulation arithmetic is supported, using the standard +. -, *, and / operators. In-place operators +=, -=, *=, and /= are also supported. A Tabulation can be “sliced” using standard NumPy index notation; for example, t[:10] is a new Tabulation containing the first ten elements of Tabulation t.

In general, zero values (either supplied or computed) at either the leading or trailing ends are removed. However, if explicitly supplied, one leading and/or trailing zero value is considered significant because it anchors the interpolation of a ramp at the beginning or end of the domain. For example:

>>> t1 = Tabulation([2, 4], [10, 10])  # Leading & trailing step function
>>> t1.domain()
(2., 4.)
>>> t1([0,   1,   1.9, 2,   3,   3.9, 4,   5,   6])
array([ 0.,  0.,  0., 10., 10., 10., 10.,  0.,  0.])

>>> t2 = Tabulation([0, 2, 4], [0, 5, 5])  # Ramp on leading edge
>>> t2.domain()
(0., 4.)
>>> t2([0,    1,    1.9,  2,    3,    3.9,  4,    5,    6])
array([ 0.  , 2.5 , 4.75, 5.  , 5.  , 5.  , 5.  , 0.  , 0.  ])

By default it is assumed that the function never has leading or trailing zeros beyond the single zero necessary to anchor the interpolation, and the Tabulation object will automatically trim any additional leading and/or trailing regions of the domain that have purely zero values.

When mathematical operations are performed on Tabulations, new x-coordinates are added as necessary to keep the behavior of step functions. For example:

>>> t1.x
array([2., 4.])
>>> t2.x
array([0., 2., 4.])
>>> (t1-t2).x
array([0., 2., 2., 4.])
>>> (t1-t2).y
array([ 0., -5.,  5.,  5.])

Note that the new x-coordinates are epsilon away from the adjacent x-coordinates, essentially producing an infinitesimally narrow ramp to simulate the original step function:

>>> (t1-t2).x[1]
1.9999999999999998
>>> (t1-t2).x[2]
2.0

__array_priority__ = 1

__init__(x, y)[source]

Constructor for a Tabulation object.

Parameters:

x (array-like) – A 1-D array of x-coordinates, which must be monotonic (either increasing or decreasing).
y (array-like) – A 1-D array of y-values, given in the same order as the x-coordinates.

property shape: The shape of this Tabulation as a tuple.

__call__(x)[source]

The interpolated value corresponding to an x-coordinate.

This definition allows any Tabulation to be treated as a function, so if tab is a Tabulation, tab(x) returns the value of that Tabulation evaluated at x.

Parameters:: x (float or array-like) – The x-coordinate(s) at which to evaluate the Tabulation.
Returns:: The value(s) of the interpolated y-coordinate at the given x-coordinate(s).
Return type:: float or array-like

__mul__(other)[source]

Multiply, supporting the “*” operator.

Parameters:

other (Tabulation, float, or int) – The multiplier.

Returns:

The new Tabulation.

Return type:

Tabulation

Raises:

TypeError – If a Tabulation cannot be multiplied by an object of the given type.
ValueError – If the domains of the two Tabulations do not overlap.

Notes

If other is a Tabulation, the new domain is the intersection of the domains of the two Tabulations. Within this domain, the product is evaluated at the union of the Tabulations’ x-coordinates. Because interpolation is linear, values between the new x-coordinates will have reduced accuracy; if this is a concern, subsample one of the Tabulations first.

__rmul__(other)[source]

Multiply, supporting the “*” operator if the Tabulation comes second.

Parameters:: other (float or int) – The multiplier.
Returns:: The new Tabulation.
Return type:: Tabulation
Raises:: TypeError – If a Tabulation cannot be multiplied by an object of the given type.

__imul__(other)[source]

In-place multiply, supporting the “*=” operator.

Parameters:

other (Tabulation, float, or int) – The multiplier.

Returns:

The current Tabulation, mutated with the new values.

Return type:

Tabulation

Raises:

TypeError – If the Tabulation cannot be multiplied by an object of the given type.
ValueError – If the domains of the two Tabulations do not overlap.

Notes

If other is a Tabulation, the new domain is the intersection of the domains of the two Tabulations. Within this domain, the product is evaluated at the union of the Tabulations’ x-coordinates.

Because interpolation is linear, values between the new x-coordinates will have reduced accuracy; if this is a concern, subsample one of the Tabulations first.

__truediv__(other)[source]

Divide, supporting the “/” operator.

Parameters:

other (Tabulation, float, or int) – The divisor.

Returns:

The new Tabulation.

Return type:

Tabulation

Raises:

TypeError – If a Tabulation cannot be divided by an object of the given type.
ZeroDivisionError – If the divisor contains zero or has a narrower domain than this Tabulation.

Notes

The returned Tabulation inherits its domain from the numerator. If other is a Tabulation, its domain must span that of the numerator; otherwise, this is a divide-by-zero operation. The ratio is evaluated at the union of the Tabulations’ x-coordinates within the new domain. Because interpolation is linear, values between the new x-coordinates will have reduced accuracy; if this is a concern, subsample one of the Tabulations first.

__itruediv__(other)[source]

In-place divide, supporting the “/=” operator.

Parameters:

other (float or int) – The divisor.

Returns:

The current Tabulation, mutated with the new values.

Return type:

Tabulation

Raises:

TypeError – If a Tabulation cannot be divided by an object of the given type.
ZeroDivisionError – If the divisor contains zero or has a narrower domain than this Tabulation.

Notes

The returned Tabulation preserves has an unchanged domain. If other is a Tabulation, its domain must span that of the given Tabulation; otherwise, this is a divide-by-zero operation. The ratio is evaluated at the union of the Tabulations’ x-coordinates within the domain. Because interpolation is linear, values between the new x-coordinates will have reduced accuracy; if this is a concern, subsample one of the Tabulations first.

__add__(other)[source]

Add two Tabulations, supporting the “+” operator.

Parameters:: other (Tabulation) – The Tabulation to add.
Returns:: The new Tabulation, sampled at the union of the x-coordinates of both Tabulations.
Return type:: Tabulation

__iadd__(other)[source]

In-place addition, supporting the “+=” operator.

Parameters:: other (Tabulation) – The Tabulation to add.
Returns:: The current Tabulation, mutated with the new values. It is sampled at the union of the x-coordinates of both Tabulations.
Return type:: Tabulation

__sub__(other)[source]

Subtract two Tabulations, supporting the “-” operator.

Parameters:: other (Tabulation) – The Tabulation to subtract.
Returns:: The new Tabulation, sampled at the union of the x-coordinates of both Tabulations.
Return type:: Tabulation

__isub__(other)[source]

In-place addition, supporting the “+=” operator.

Parameters:: other (Tabulation) – The Tabulation to subtract.
Returns:: The current Tabulation mutated with the new values.
Return type:: Tabulation
Returns:: The current Tabulation, mutated with new values. It is sampled at the union of the x-coordinates of both Tabulations.
Return type:: Tabulation

__eq__(other)[source]

True if two Tabulations are everywhere equal.

Parameters:: other (Tabulation) – The Tabulation to compare.
Returns:: True if the Tabulations are equal.
Return type:: Tabulation

__getitem__(indx)[source]

An element or slice of this Tabulation using NumPy index notation.

This definition allows Python/NumPy indexing notation to be applied to a Tabulation using square brackets “[]”.

Most of the ways of indexing a NumPy array are supported. If the index is a single integer, the value of y at that index is returned. Otherwise, a new Tabulation is returned containing only the selected elements. For example, tab[:10] is a new Tabulation containing the first ten elements of Tabulation tab.

Parameters:

indx (int, array, list, or slice) – Index to apply.

Returns:

If the index is a single integer, the value of y at that index is returned. Otherwise, a new Tabulation including the selected elements of the x and y arrays is returned.

Return type:

(float or Tabulation)

Raises:

IndexError – If the index has an invalid value or type.
ValueError – If the set of elements of the Tabulation selected by the index do not represent a valid Tabulation.

__len__()[source]

Length of this Tabulation.

This definition supports the use of len(tab) to obtain the number of elements in Tabulation tab.

Returns:: Number of elements in this Tabulation.
Return type:: int

__str__()[source]

Brief string representation of this Tabulation.

This definition supports the use of str(tab) to obtain a brief string describing the contents of Tabulation tab.

Returns:: Brief string representation of this Tabulation.
Return type:: str

__repr__()[source]

Brief string representation of this Tabulation.

This definition supports the use of repr(tab) to obtain a brief string describing the contents of Tabulation tab.

Returns:: Brief string representation of this Tabulation.
Return type:: str

domain()[source]

The range of x-coordinates for which values have been provided.

Returns:: A tuple (xmin, xmax).
Return type:: tuple

clip(xmin=None, xmax=None)[source]

A Tabulation where the domain is (xmin, xmax).

Parameters:

xmin (float, optional) – The minimum value of the new x-coordinates; default is to retain the existing lower limit.
xmax (float, optional) – The maximum value of the new x-coordinates; default is to retain the existing upper limit.

Returns:

The new Tabulation, identical to the current Tabulation except that the x domain is now restricted to (xmin, xmax). If either x coordinate is outside the current domain, it is set to that limit of the domain.

Return type:

Tabulation

Raises:

ValueError – If the clip domain does not overlap with the Tabulation domain.

locate(yvalue)[source]

The x-coordinates where the Tabulation has the given value of y.

Note that the exact ends of the domain are not checked.

Parameters:: yvalue (float) – The value to look for.
Returns:: A list of x-coordinates where the Tabulation equals yvalue.
Return type:: list

integral(xmin=None, xmax=None)[source]

The integral of [y dx].

Parameters:

xmin (float, optional) – The lower limit of the integral; default is to use the lower limit of the Tabulation.
xmax (float, optional) – The upper limit of the integral; default is to use the upper limit of the Tabulation.

Returns:

The integral.

Return type:

float

resample(new_x)[source]

A new Tabulation re-sampled at the given x-coordinates.

Parameters:: new_x (array-like) – The new x-coordinates, which must be monotonic.
Returns:: A new Tabulation equivalent to the current Tabulation but sampled only at the given x-coordinates.
Return type:: Tabulation
Raises:: ValueError – If the x coordinates are not monotonic.

Notes

If the leading or trailing X coordinate corresponds to a non-zero value, then there will be a step at that edge. If the leading or trailing X coordinate corresponds to a zero value, then there will be a ramp at that edge. The resulting Tabulation is trimmed such that the domain does not include any zero-valued coordinates except for those necessary to anchor the leading or trailing edge.

subsample(new_x=None, *, dx=None, n=None)[source]

A new Tabulation re-sampled at a list of x-coords plus existing ones.

Parameters:

new_x (array-like, optional) – The new x-coordinates.
dx (float, optional) – If provided instead of new_x, an array of x-values uniformly sampled by dx within this Tabulation’s domain is used instead. If new_x is specified, this input is ignored.
n (int, optional) – If provided instead of new_x or dx, this is a number that will be used to subdivide the domain, and a new x-value will be inserted at each new point.

Returns:

A new Tabulation equivalent to the current Tabulation but sampled at both the existing x-coordinates and the given x-coordinates.

Return type:

Tabulation

Notes

If none of new_x, dx, and x are specified, this Tabulation is returned.

x_mean(dx=None)[source]

The weighted center x coordinate of the Tabulation.

Parameters:: dx (float, optional) – The minimum, uniform step size to use when evaluating the center position. If omitted, no resampling is performed.
Returns:: The x coordinate that corresponds to the weighted center of the function.
Return type:: float

bandwidth_rms(dx=None)[source]

The root-mean-square width of the Tabulation.

This is the mean value of (y * (x - x_mean)**2)**(1/2).

Parameters:: dx (float, optional) – The minimum, uniform step size to use when evaluating the center position. If omitted, no resampling is performed.
Returns:: The RMS width of the Tabulation.
Return type:: float

pivot_mean(precision=0.01)[source]

The “pivot” mean value of the tabulation.

The pivot value is the mean value of y(x) d(log(x)). Note all x must be positive.

Parameters:: precision (float, optional) – The step size at which to resample the Tabulation in log space.
Returns:: The pivot mean of the Tabulation.
Return type:: float

fwhm(fraction=0.5)[source]

The full-width-half-maximum of the Tabulation.

Parameters:: fraction (float, optional) – The fractional height at which to perform the measurement. 0.5 corresponds to “half” maximum for a normal FWHM.
Returns:: The FWHM for the given fractional height.
Return type:: float
Raises:: ValueError – If the Tabulation does not cross the fractional height exactly twice, or if the fraction is outside the range 0 to 1.

square_width()[source]

The square width of the Tabulation.

The square width is the width of a rectangular function with y value equal to the maximum of the original function and having the same area as the original function.

Returns:: The square width of the Tabulation.
Return type:: float

quantile(q)[source]

The specified quantile point within a Tabulation.

A quantile point is the x-value that divides the Tabulation into two parts such that fraction of the integral falls below this value and 1-fraction falls above it.

Parameters:: q (float) – A fractional value between 0 and 1 inclusive.
Returns:: The x-value corresponding to the quantile value q.
Return type:: float
Raises:: ValueError – If the fraction is outside the range 0 to 1.

tabulation Module

`tabulation` Module