opticks.utils.interval_data

Module Attributes

FunctCombinationMethod(*values)

Interval Data Combination Method Enum.

Classes

`FunctCombinationMethod`(*values)	Interval Data Combination Method Enum.
`IntervalData`([mapping_or_iterable, sample_size])	Generates a new IntervalData object.
`IntervalDataPlot`(interval_data_dict[, ...])	Convenience class to plot IntervalData objects.

class FunctCombinationMethod(*values)

Interval Data Combination Method Enum.

MULTIPLY = 'Multiplication'

SUM = 'Summation'

UNDEFINED = 'Undefined'

class IntervalData(mapping_or_iterable=None, sample_size=None)[source]

Generates a new IntervalData object.

If no argument is given, an empty IntervalData is created. If an argument is given, and is a mapping object (e.g., another IntervalData), an new IntervalData with the same key-value pairs (as well as combination method and sample size) is created. If an iterable is provided, it has to be a list of (key, value) pairs.

The sample_size parameter sets the default sample size to be used for each atomic interval for resampling when needed. If None is given, the one from the mapping_or_iterable is used. If it does not exist, the default value is used.

Parameters:

mapping_or_iterable – optional mapping or iterable
sample_size (int) – default sample size for resampling

as_atomic()[source]

Returns a list of tuples containing atomic intervals and corresponding functions.

Return type:: list[tuple[Interval, Any]]

property combination_method: FunctCombinationMethod: Combination method for the stack of functions.

combine(other, *, missing=None)[source]

Combines this IntervalData object with another one.

The combination method stacks the values or functions in the intersecting regions, but does not evaluate them, until get_value is called.

The combination is not possible when one IntervalDict is of Summation type and the other Multiplication type. Then one of them should be resampled, resetting the combination method, which then enables a combination between the two.

Similarly, two Undefined types cannot be combined as the get_value method on the combined object would not know how to combine the various functions.

The properties of the new object is reset, but the user can easily call copy_properties_to from one of the combined objects, so that its properties are exported to the new object.

The missing key is used for the values that are not intersecting between the two domains.

Return type:

IntervalData

Parameters:

other (IntervalData) – other object to be combined
missing (_type_, optional) – if set, use this value for missing values

Returns:

IntervalData – the new object with properties reset

copy_properties_to(other)[source]

Copies the properties (except for the IntervalDict) of Self to other.

Returns other for convenience.

Return type:: IntervalData
Parameters:: other (IntervalData)

classmethod from_interpolator(ipol, sample_size=None)[source]

Initialises the IntervalData object with an interpolator.

The interval of validity is the data range of the interpolator.

The sample_size parameter sets the default sample size to be used for resampling when needed. If None is given, the default value is used.

Return type:

IntervalData

Parameters:

ipol (PPolyWithUnits) – Interpolator
sample_size (int) – default sample size for resampling

Returns:

IntervalData – The new IntervalData object

classmethod from_math_funct(math_funct, valid_interval, sample_size=None)[source]

Initialises the IntervalData object with a math function.

The math function can be any callable, with a signature y=math_funct(x).

The sample_size parameter sets the default sample size to be used for resampling when needed. If None is given, the default value is used.

Return type:

IntervalData

Parameters:

funct – Math function with a signature y=math_funct(x).
valid_interval (Interval) – Interval of validity or domain
sample_size (int) – default sample size for resampling

Returns:

IntervalData – The new IntervalData object

get(x, default=None)[source]

Gets the functions at the arbitrary data point x.

This does not return the numerical result at x, rather it returns the list of functions (interpolators, mathematical functions or fixed values) at x. If the mathematical combination (summation or multiplication) of all the functions at x is desired, use the get_value method.

If x is a single value, it returns a single value (if it exists) or None (if it doesn’t).

If x is an Interval, it returns a new IntervalDict restricted to the requested interval. In that case, the default value is used to “fill the gaps” (if any) w.r.t. given x.

If x is not covered by the bounds of the Interval, the value in the default parameter is returned, which is by default None.

Return type:

type[IntervalDict] | Quantity | float

Parameters:

x (Quantity | Interval) – Requested data point or Interval
default – default value to be used, by default None

Returns:

IntervalDict | Quantity | float – an IntervalDict/IntervalData, or a single value if key is not an Interval.

get_value(x, default=None)[source]

Gets the value at the arbitrary data point x.

Computes and combines all the values of the mathematical functions at x. The combination method can be a summation or a multiplication, depending on the internal combination_method parameter. If the combination_method is set to neither and there are multiple values to be combined, a ValueError is thrown, as the method does not know how to handle the combination.

If x is not covered by the bounds of the Interval, the value in the default parameter is returned, which is by default None.

Return type:

Quantity | float

Parameters:

x (Quantity | float) – Requested data point
default – default value to be used, by default None

Returns:

Quantity | float – Value at the requested data point

integrate(interval=None)[source]

Integrates the IntervalData over a certain interval.

The integration can be over a user requested interval (with interval parameter defined) or can be over the full interval of the IntervalData object (when interval parameter is not defined).

Return type:: float | Quantity
Parameters:: interval (P.Interval, optional) – integration interval
Returns:: float | Quantity – value of the integration over the interval

plot()[source]

Convenience method to plot IntervalData objects.

Returns an IntervalDataPlot object. The set_plot_style method can be invoked for further styling options and also the usual matplotlib plot.ax and plot.fig options are available for advanced customisation.

Return type:: IntervalDataPlot

resample(**kwargs)[source]

Combines the stacked values and interpolators, via resampling and setting up a new interpolator.

The process decomposes the intervals into atomic intervals and therefore the interval structure is changed.

This analyses each interval enclosure within the dictionary and combines the functions / values. A None or zero takes precedence, and all other functions (continuous or interpolator) are resampled to create a new interpolator.

The combination method can be a summation or a multiplication, depending on the combination_method parameter.

The properties of this object is preserved in the returned object, but the combination properties is set to Undefined.

The interpolator is defined by the ipol_type parameter, with the extrapolate already set to True. The kwargs are passed on to the interpolator definition.

For the interpolator, each atomic interval is divided into an integer number of steps (given by the sample_size parameter) between its respective bounds.

Return type:: IntervalData
Parameters:: kwargs – Parameters to be passed on the interpolator
Returns:: IntervalData – The new IntervalData object

property sample_size: int: Sample size for each atomic interval during any resampling needed.

scale(scaling_value, *, missing=None, **kwargs)[source]

Scales the IntervalData object with a scalar.

The scalar may also be with units.

If this IntervalData object is of a Summation type, then the it is resampled using the internal sample_size and interpolator properties.

The properties of this object is preserved in the returned object.

Return type:

IntervalData

Parameters:

scaling_value (float | Quantity) – scalar value used in scaling
missing – if set, use this value for missing values when calling “how”, by default None
kwargs – Parameters to be passed on the interpolator

Returns:

IntervalData – the new, scaled IntervalData object

class IntervalDataPlot(interval_data_dict, plot_interval=None, apply_default_style=True)[source]

Convenience class to plot IntervalData objects.

Each IntervalData is used to generate the plot y values, using the dict key as the label. The optional plot_interval constrains the plot interval.

Uses a default combination method of multiplication for combined interval data, though a summation can also be used.

The plot samples each IntervalData object separately, therefore the sample points may not exactly match. If the points are required to match, then a plot_interval should be specified.

Parameters:

interval_data_dict (dict[str, IntervalData]) – dict of label and IntervalData objects plot_interval : Interval, optional
interval (plot) – for each IntervalData object
plotted (None means the entire domain is) – for each IntervalData object
apply_default_style (bool) – applies the default style
plot_interval (Interval | None)

set_plot_style(title=None, xlabel=None, ylabel=None, height=<Quantity 10. cm>, width=<Quantity 15. cm>, legend_off=False)[source]

Sets some basic style parameters for the plot.

Return type:

None

Parameters:

title (str, optional) – title of the plot, by default None
xlabel (str, optional) – x-axis label, by default None
ylabel (str, optional) – y-axis label, by default None
height (Quantity | float, optional) – height of the figure (in inches), by default 10 cm
width (Quantity | float, optional) – width of the figure (in inches), by default 15 cm
legend_off (bool, optional) – turns the legend off, by default False