py-formatted-value
![Build Status](https://travis-ci.org/MartyO256/py-formatted-value.svg?branch=master)
Format experimental values and their uncertainties using appropriate significant figures and matching decimal places.
Installation
To install fvalue
, run:
pip install fvalue
Examples
The following examples showcase the core features of the library.
from fvalue import FormattedValue
from decimal import Decimal
FormattedValue(
value=10_973_731.768_160,
error=0.000_021,
error_significant_figures=2,
rounding=FormattedValue.RoundingOption.ROUND_HALF_EVEN,
).formatted(
template=FormattedValue.SIUNITX_TEMPLATE,
units=r"\per\meter",
)
FormattedValue(
value=0.000_002_671,
error=0.000_000_452,
error_significant_figures=1,
).formatted(
template=FormattedValue.SIUNITX_NUM_TEMPLATE,
)
FormattedValue(
0.000_002_671,
0.000_000_452,
error_significant_figures=2,
).formatted(
FormattedValue.SIUNITX_NUM_TEMPLATE,
multiplier=10 ** 3,
)
FormattedValue(
Decimal("1.602_176_634E-19"),
).formatted(
FormattedValue.SIUNITX_VALUE_TEMPLATE,
units=r"\coulomb",
)
FormattedValue(
Decimal("1.416_784E32"),
Decimal("0.000_016E32"),
error_significant_figures=2,
).formatted(
FormattedValue.NATURAL_TEMPLATE,
units=r"K",
)
FormattedValue(
656,
10,
).formatted(
FormattedValue.NATURAL_TEMPLATE,
units=r"nm",
)
Usage
Instances of FormattedValue
are used to produce string representations of experimental quantities with their uncertainties.
The number of significant figures in the error on a value is set on instantiation.
The decimal places of the value always match that of the error in formatted strings.
Values of small magnitude are automatically formatted with an appropriate decimal exponent in the scientific notation.
Rounding
The rounding policies used in the formatting are those of the decimal
library, namely: ROUND_HALF_EVEN
, ROUND_05UP
, ROUND_CEILING
, ROUND_DOWN
, ROUND_FLOOR
, ROUND_HALF_DOWN
, ROUND_HALF_UP
and ROUND_UP
.
All of these are conveniently available as an enumeration at FormattedValue.RoundingOption
.
By default, ROUND_HALF_EVEN
is used to mitigate some biases.
Templates
Templates allow for the placement in strings of the rounded value, error, decimal exponent, and units optionally.
Using the formatted
method of an instance of FormattedValue
, strings and callable templates can be used.
If a given template is a string, then:
{0}
corresponds to the rounded value;{1}
corresponds to the rounded error;{2}
corresponds to the decimal exponent in scientific notation;{3}
corresponds to the units.
For instance, "({0} ± {1}) x 10^{2} {3}"
would generate "(10 ± 1) x 10^0 m"
for a formatted value with value 10
, error 1
, and units "m"
.
If a given template is a function, then it should have type signature Callable[[str, str, str, str], str]
, with arguments (value: str, error: str, exponent: str, units: str) -> str
.
One such template is accessible at FormattedValue.NATURAL_TEMPLATE
.
Various templates are available to speed up the generation of formatted strings.
The default template is for SIUNITX, which is accessible at FormattedValue.SIUNITX_TEMPLATE
and produces strings as "\SI{{0} \pm {1} e{2}}{{3}}"
.
Other templates include: Formatted.SIUNITX_VALUE_TEMPLATE
, Formatted.SIUNITX_ERROR_TEMPLATE
, Formatted.SIUNITX_NUM_TEMPLATE
, Formatted.SIUNITX_NUM_VALUE_TEMPLATE
, Formatted.SIUNITX_NUM_ERROR_TEMPLATE
.
Multiplier
The formatted
method of instances of FormattedValue
allows for a multiplier to be applied to both the value and error of the instance.
This allows for an experimental value to be used using the International System of Units for data processing, and prefixed units to be used for the presentation of results in reports.
About
Authors
License
This project is licensed under the MIT License. See the LICENSE.md
file for details.