qblox_scheduler.analysis.visualization.si_utilities#

Utilities for managing SI units with plotting systems.

Attributes#

`golden_mean`
`single_col_figsize`
`double_col_figsize`
`thesis_col_figsize`
`SI_PREFIXES`
`SI_UNITS`
`_SI_PREFIX_TO_FACTOR_MAPPING`
`_prefix_regexp`
`_si_regex`
`_prefixed_si_regex`

Classes#

SafeFormatter

A formatter that replaces "missing" values and "bad_fmt" to prevent unexpected

Functions#

`_get_scale_factor_and_offset_and_prefix`(→ tuple[float, ...)	Return a convenient scale factor, offset and SI prefix based on the tick values.
`_set_offset_string`(→ None)	Set the offset string of the Formatter to a conveniently scaled offset.
`set_xlabel`(→ matplotlib.axes.Axes)	Add a unit aware x-label to an axis object.
`set_ylabel`(→ matplotlib.axes.Axes \| None)	Add a unit aware y-label to an axis object.
`set_cbarlabel`(cbar, label[, unit])	Add a unit aware z-label to a colorbar object.
`adjust_axeslabels_SI`(→ None)	Auto adjust the labels of a plot generated by xarray to SI-unit aware labels.
`SI_prefix_and_scale_factor`(→ tuple[float, str])	Takes in a value and unit, returns a scale factor and scaled unit.
`SI_val_to_msg_str`(val[, unit, return_type])	Takes in a value with optional unit and returns a string tuple consisting of
`format_value_string`(→ str)	Format an lmfit parameter or uncertainties ufloat to a string of value with
`value_precision`(→ tuple[str, str])	Calculate the precision to which a parameter is to be specified, according to

Module Contents#

golden_mean[source]#

single_col_figsize[source]#

double_col_figsize[source]#

thesis_col_figsize[source]#

_get_scale_factor_and_offset_and_prefix(ticks: list[float], unit: str | None = None, precision: int = 4) → tuple[float, float, str][source]#

Return a convenient scale factor, offset and SI prefix based on the tick values.

This function uses the SI_prefix_and_scale_factor() function to determine a scale factor such that the distance between ticks is in the range [0.1, 100.0), plus the corresponding scaled SI unit (e.g. ‘mT’, ‘kV’), deduced from the input unit, to represent the tick values in those scaled units. In addition, an offset is calculated such that the maximum absolute tick value is less than 10^precision.

Parameters:

ticks – A list of axis tick values.
unit – The unit of the tick values.
precision – The maximum amount of digits to display as tick labels.

Returns:

scale_factor: The scale factor to multiply the tick values with.
offset: The offset to subtract from the tick values.
unit: The unit including the SI prefix.

Examples

>>> _get_scale_factor_and_offset_and_prefix(
...     ticks=[2100000, 2100100, 2100200],
...     unit="Hz",
...     precision=4,
... )
(1.0, 2100000, 'Hz')

_set_offset_string(formatter: matplotlib.ticker.FixedFormatter | matplotlib.ticker.FuncFormatter, offset: float, unit: str) → None[source]#

Set the offset string of the Formatter to a conveniently scaled offset.

This function scales the given offset and unit using SI_prefix_and_scale_factor(), and sets the offset string of the Formatter to the scaled offset value.

Parameters:

formatter – The matplotlib Formatter.
offset – The value to scale and display.
unit – The unit of the value.

set_xlabel(label: str, unit: str | None = None, axis: matplotlib.axes.Axes | None = None, auto_scale: bool = True, **kw) → matplotlib.axes.Axes[source]#

Add a unit aware x-label to an axis object.

Parameters:

label – the desired label
unit – the unit
auto_scale – If True, then automatically scale the units
axis – matplotlib axis object to set label on
**kw – keyword argument to be passed to matplotlib.set_xlabel

set_ylabel(label: str, unit: str | None = None, axis: matplotlib.axes.Axes | None = None, auto_scale: bool = True, **kw) → matplotlib.axes.Axes | None[source]#

Add a unit aware y-label to an axis object.

Parameters:

label – the desired label
unit – the unit
axis – matplotlib axis object to set label on
auto_scale – If True, then automatically scale the units
**kw – keyword argument to be passed to matplotlib.set_ylabel

set_cbarlabel(cbar: matplotlib.colorbar.Colorbar, label: str, unit: str | None = None, **kw)[source]#

Add a unit aware z-label to a colorbar object.

Parameters:

cbar – colorbar object to set label on
label – the desired label
unit – the unit
**kw – keyword argument to be passed to cbar.set_label

adjust_axeslabels_SI(ax) → None[source]#: Auto adjust the labels of a plot generated by xarray to SI-unit aware labels.

SI_PREFIXES[source]#

SI_UNITS = ['SI_PREFIX_ONLY', 'm', 's', 'g', 'W', 'J', 'V', 'A', 'F', 'T', 'Hz', 'Ohm', 'S', 'N', 'C',...[source]#

_SI_PREFIX_TO_FACTOR_MAPPING[source]#

_prefix_regexp = '()'[source]#

_si_regex = '()'[source]#

_prefixed_si_regex[source]#

SI_prefix_and_scale_factor(val: float, unit: str | None = None) → tuple[float, str][source]#

Takes in a value and unit, returns a scale factor and scaled unit. It returns a scale factor to convert the input value to a value in the range [1.0, 1000.0), plus the corresponding scaled SI unit (e.g. ‘mT’, ‘kV’), deduced from the input unit, to represent the input value in those scaled units.

The scaling is only applied if the unit is an unscaled or scaled unit present in the variable :data::SI_UNITS.

If the unit is None, no scaling is done. If the unit is “SI_PREFIX_ONLY”, the value is scaled and an SI prefix is applied without a base unit.

Parameters:

val – the value
unit – the unit of the value

Returns:

scale_factor: scale_factor needed to convert value
scaled_unit: unit including the prefix

SI_val_to_msg_str(val: float | int, unit: str | None = None, return_type=str)[source]#

Takes in a value with optional unit and returns a string tuple consisting of (value_str, unit) where the value and unit are rescaled according to SI prefixes, IF the unit is an SI unit (according to the comprehensive list of SI units in this file ;).

the value_str is of the type specified in return_type (str) by default.

class SafeFormatter(missing: str = '~~', bad_fmt: str = '!!')[source]#

Bases: string.Formatter

A formatter that replaces “missing” values and “bad_fmt” to prevent unexpected Exceptions being raised.

Parameters:

missing – Replaces missing values with specified string.
bad_fmt – Replaces values that cannot be formatted with specified string.

Notes

Based on StackOverflow discussion: https://stackoverflow.com/questions/20248355/how-to-get-python-to-gracefully-format-none-and-non-existing-fields

get_field(field_name, args, kwargs)[source]#

format_field(value, format_spec)[source]#

format_value_string(par_name: str, parameter: lmfit.Parameter | uncertainties.core.Variable | uncertainties.core.AffineScalarFunc | float, end_char='', unit=None) → str[source]#

Format an lmfit parameter or uncertainties ufloat to a string of value with uncertainty.

If there is no stderr, use 5 significant figures. If there is a standard error use a precision one order of magnitude more precise than the size of the error and display the stderr itself to two significant figures in standard index notation in the same units as the value.

Parameters:

par_name – A name of the parameter to use in the string
parameter (lmfit.parameter.Parameter,) – uncertainties.core.Variable or float. A Parameter object or an object e.g., returned by uncertainties.ufloat(). The value and stderr of this parameter will be used. If a float is given, the stderr is taken to be None.
end_char – A character that will be put at the end of the line.
unit – A unit. If this is an SI unit it will be used in automatically determining a prefix for the unit and rescaling accordingly.

Returns:

: The parameter and its error formatted as a string

value_precision(val: float, stderr=None) → tuple[str, str][source]#

Calculate the precision to which a parameter is to be specified, according to its standard error. Returns the appropriate format specifier string.

If there is no stderr, use 5 significant figures. If there is a standard error use a precision one order of magnitude more precise than the size of the error and display the stderr itself to two significant figures in standard index notation in the same units as the value.

Parameters:

val – the nominal value of the parameter
stderr – the standard error on the parameter

Returns:

val_format_specifier: python format specifier which sets the precision of the parameter value
err_format_specifier: python format specifier which set the precision of the error