Formatting Uncertain Numbers

Formatting an uncertain number is useful for display purposes. The number of significant digits for the value and the uncertainty can be controlled, based on the uncertainty. The number of digits displayed after the decimal point for the degrees of freedom and the correlation coefficient can also be specified.

Three functions help to format and display uncertain numbers:

Generating strings

As an example, consider the following uncertain number

>>> un = ureal(3.14159e-3, 2.71828e-4, 9.876)

We create an object to control the format using the create_format() function

>>> fmt = create_format(un)

The fmt object contains formatting specifications

>>> fmt
Format(format_spec='.2f', df_precision=0, r_precision=3)

Fixed-point notation, f, is used. The .2 indicates that 2 significant digits will be retained in the uncertainty and the value will be displayed using the same number of significant digits. The degrees of freedom will be truncated to a precision of 0 digits after the decimal point, and the correlation coefficient will be rounded to a precision of 3 digits after the decimal point.

Note that the meaning of the .2f field in the format_spec is different from the usual Python interpretation. In GTC, this field specifies the number of significant digits of the uncertainty that will be displayed, which also affects the number of digits displayed for the value.

There are two ways to use a format specification to display the string representation of an uncertain number. The first, is to use the builtin format() function

>>> '{:.2f}'.format(un)
'0.00314(27)'

The second is to use the to_string() function

>>> to_string(un, fmt)
'0.00314(27)'

Scientific notation is also supported. For example,

>>> '{:e}'.format(un)
'3.14(27)e-03'

Alternatively, the create_format() and to_string() functions can be used

>>> fmt = create_format(un, type='e')
>>> to_string(un, fmt)
'3.14(27)e-03'

The order of characters in the format_spec is important. Python supports a specific grammar when using the format() function (see Format Specification Mini-Language). The GTC-specific field—style—must occur after the builtin fields. The equivalent format-specification grammar for GTC is:

[[fill]align][sign][#][0][width][grouping][.digits][type][style]

Note the use of digits (not precision) and style (there are two styles: L (\(\LaTeX\)) and U (Unicode)).

The following examples illustrate for an uncertain number.

Use 3 significant digits and scientific notation

>>> fmt = create_format(un, digits=3, type='e')
>>> to_string(un, fmt)
'3.142(272)e-03'
>>> '{:.3e}'.format(un)
'3.142(272)e-03'

Use 1 significant digit, scientific notation, and unicode style

>>> fmt = create_format(un, digits=1, type='e', style='U')
>>> to_string(un, fmt)
'3.1(3)×10⁻³'
>>> '{:.1eU}'.format(un)
'3.1(3)×10⁻³'

Use 4 significant digits, scientific notation, and \(\LaTeX\) style

>>> fmt = create_format(un, digits=4, type='e', style='L')
>>> to_string(un, fmt)
'3.1416\\left(2718\\right)\\times10^{-3}'
>>> '{:.4eL}'.format(un)
'3.1416\\left(2718\\right)\\times10^{-3}'

In this case, the text output may not be easy to interpret in Python, but it becomes \(3.1416\left(2718\right)\times10^{-3}\) when rendered in a \(\LaTeX\) document.

Fill with *, align right >, show a + sign with positive values, a width of 20 characters and 1 significant digit

>>> fmt = create_format(un, fill='*', align='>', sign='+', width=20, digits=1)
>>> to_string(un, fmt)
'**********+0.0031(3)'
>>> '{:*>+20.1}'.format(un)
'**********+0.0031(3)'

Generating formatted attributes

The apply_format() function formats an uncertain number. The returned object is a namedtuple with numerical attributes that have been manipulated to have the specified number of digits for: value, uncertainty, degrees of freedom, and correlation coefficient (for uncertain complex numbers).

>>> fmt = create_format(un)
>>> formatted = apply_format(un, fmt)
>>> formatted
FormattedUncertainReal(x=0.00314, u=0.00027, df=9.0, label=None)
>>> formatted.x
0.00314

We can specify that 3 significant digits will be used for the uncertainty (and value) and truncate the degrees of freedom to 2 digits of precision

>>> fmt = create_format(un, digits=3, df_precision=2)
>>> formatted = apply_format(un, fmt)
>>> formatted
FormattedUncertainReal(x=0.003142, u=0.000272, df=9.87, label=None)
>>> formatted.x
0.003142
>>> formatted.df
9.87

The following functions are available.

apply_format(un, fmt)

Apply the format to an uncertain number.

New in version 1.4.0.

Parameters:
Return type:

FormattedUncertainReal or FormattedUncertainComplex

Note

Although the format type may be specified as '%', this will be interpreted as 'f' and the value and uncertainty will not be multiplied by 100. See create_format() for more details.

create_format(obj, digits=None, df_precision=None, r_precision=None, style=None, **kwargs)

Create a format specification.

Formatting an uncertain number rounds the value and the uncertainty to the specified number of significant digits (based on the uncertainty component), and truncates the degrees of freedom and rounds the correlation coefficient to the specified precision (the number of digits after the decimal point).

New in version 1.4.0.

Parameters:
  • obj (float, complex, UncertainReal, UncertainComplex or StandardUncertainty) – An object to use to create the format specification. If an UncertainReal or an UncertainComplex, then the uncertainty component is used when creating the format. Otherwise this function assumes that the uncertainty component was passed in as obj.

  • digits (int) – The number of significant digits in the uncertainty component to retain. Default is 2.

  • df_precision (int) – The number of digits that should be kept after the decimal point for the degrees of freedom. The value is truncated. Default is 0.

  • r_precision (int) – The number of digits that should be kept after the decimal point for the correlation coefficient. The value is rounded. Default is 3.

  • style (str) – The style to use when formatting an uncertain number as a string. Can be either 'L' (\(\LaTeX\)) or 'U' (Unicode). When a style is used, the + sign and any leading 0’s are removed from the exponent, for example, e+06 becomes \(10^{6}\) instead of \(10^{+06}\). Also, if the exponential term is equal to e+00 then the exponential term is completely removed (i.e., it becomes an empty string instead of \(10^{+00}\)). Default is to not use styling.

  • **kwargs

    All additional keyword arguments correspond to the format-specification fields (see Format Specification Mini-Language). These fields are used when formatting an uncertain number as a string.

    • fill (str): Can be any character, except for '{' or '}'.

    • align (str): Can be one of '<', '>', '=' or '^'.

    • sign (str): Can be one of '+', '-' or ' ' (i.e., a space).

    • hash (bool): Whether to include the # field.

    • zero (bool): Whether to include the 0 field.

    • width (int): The total width of the string.

    • grouping (str): Can be one of ',' or '_'.

    • type (str): Can be one of 'e', 'E', 'f', 'F', 'g', 'G', 'n' or '%'.

    Note

    The '%' type applies to both the value and standard uncertainty. In keeping with the behaviour of '%' for floats, the value and standard uncertainty will be multiplied by 100 and displayed in fixed 'f' format followed by a percent sign.

    Note

    The precision field is treated differently for uncertain numbers in GTC. The digits keyword argument (number of significant digits) is used instead of the typical concept of precision (number of digits, either after the decimal place or in total depending on the value of type).

    Note

    If the uncertainty component is 0 then the string representation of the uncertain number does not include the uncertainty in parentheses and digits is equivalent to precision.

    >>> ur = ureal(3.1415926536, 0)
    >>> '{:.5f}'.format(ur)
    '3.14159'
    

Return type:

Format

to_string(obj, fmt)

Convert a numeric object to a string.

New in version 1.4.0.

Parameters:
Return type:

str

class Format(**kwargs)

Format specification for an uncertain number.

Do not instantiate this class directly. The proper way to create a Format object is via the create_format() function.

This class does not have any user-facing attributes. It is only meant to be passed as an argument to apply_format() or to_string().

New in version 1.4.0.