API Documentation¶
This guide explains the interface to the round() function along with all the accepted parameters and how they effect the output:
Arguments¶
The first argument specifies the number to be rounded and/or reformatted. Can be of any numeric data type or type which can be interpreted as a number (ie. string ‘1.567’). The type of the returned value will be the same as this argument’s type unless otherwise specified by the type keyword argument or by including uncertainty. ValueError will be raised in the event of uninterpretable input.
The second argument specifies either the number of significant figures (if int data type), or the uncertainty to which the first argument will be rounded (if any numeric-interpreted data type is given aside from int). ValueError will be raised in the event of uninterpretable input.
Additional arguments (aside from the keyword arguments specified below) are ignored
Rounding Operations¶
Only 1 of the 3 rounding operation may be used at a time. In the event multiple operations are requested, rounding by uncertainty will take precedence over rounding by significant figures which will take priority over rounding by number of decimals. Selecting a rounding operation is not mandatory and can be ignored when round() is being called strictly for formatting operations.
sigfigs¶
Default value: None
Controls how many significant figures the given number is to be rounded to in accordance with significant figures rounding rules. Can be specified with sigfigs keyword argument or by passing as 2nd argument of type int. When specified, it should be an int greater than 0.
>>> from sigfig import round
>>> round(12.7654, sigfigs=4)
12.77
>>> round(12.7654, 3)
12.8
decimals¶
Default value: None
Controls how many decimal places (or negative ten’s power) the given number is to be rounded to in accordance with decimal place rounding rules. When specified, it should be an int of any value.
>>> from sigfig import round
>>> round(12.7654, decimals=3)
12.765
>>> round('12.7654', decimals=-1)
'10'
uncertainty¶
Default value: None
Takes the uncertainty which will determine how many decimal places the given number is rounded to in accordance with Uncertainty Rounding Rules and cutoff value (default value: 9). In the default cutoff case these rules dictate that the uncertainty is rounded to 1 significant figure and the given number is rounded to the same number of decimals as the uncertainty.
By specifying an uncertainty, both the rounded number and rounded uncertainty will be returned (in a string separated by ” ± ” by default)
Can be specified with uncertainty/unc keyword argument or by passing as 2nd argument in numeric-interpreted type (except int) to round().
>>> from sigfig import round
>>> round('3.14159', uncertainty='0.6567')
'3.1 ± 0.7'
>>> round(3.14159, 0.001567)
'3.142 ± 0.002'
Uncertainty Rounding Rules¶
A number’s uncertainty or error is a measure of how accurate that number is. Consequently, the uncertainty’s order of magnitude (aka number of decimals) is of greater importance than it’s value resulting in the uncertainty usually being displayed with only 1 significant figure so as to not distract from it’s associated number. However, many of those in the scientific community will give 2 figures of uncertainty if the uncertainty begins with a 1 or 2. One prominent research group (The Particle Data Group) rounds their measured uncertainties to 2 decimal places if they begin with 35 (after being rounded) and will round to 1 decimal place if they begin with 36 or higher. This behavior is modified through the cutoff keyword argument which will always round to 1 decimal place in the event of cutoff=9, round to 2 decimal places if the uncertainty begins with a 1 or 2 with cutoff=29 (numbers beginning with 3-9 will be rounded to 1 decimal), and The Particle Data Group’s preference sets cutoff=35.
Following the rounding of the uncertainty, the given number (not uncertainty) will be rounded to the smallest magnitude of the resulting rounded uncertainty. After all it would be confusing (or even misleading) to state a number with 6 decimals of accuracy when you’re uncertain of any digit beyond the first decimal point.
cutoff (crop)¶
Default value: 9
The uncertainty magnitude value (int ≥ 9) after which the uncertainty value is rounded with 1 less digit.
>>> from sigfig import round
>>> round('3.14159', '0.6567', cutoff=65)
'3.1 ± 0.7'
>>> round('3.14159', '0.6567', cutoff=66)
'3.14 ± 0.66'
>>> round('3.14159', '0.6567', crop=77)
'3.14 ± 0.66'
Formatting Output¶
notation (form)¶
Default value: 'standard'
Output number format notation can be one of standard/std (default) for standard notation without exponentiation, engineering/eng for engineering notation, or scientific/sci for scientific notation.
>>> from sigfig import round
>>> round('3679.14159', decimals=2, notation='scientific')
'3.67914E3'
>>> round('16248055.209', notation='eng')
'16.248055209E6'
>>> round('16248055.209', '19923.456', notation='eng')
'16.25E6 ± 0.02E6'
Note
Should not be used in conjunction with kwarg format/style or type/output_type (since that would essentially be asking for conflicting outputs).
output_type (type)¶
Default value: type(arg[0])
Return type can be any numeric-interpreted type (i.e. decimal.Decimal, float, str, int) and should not be a string of that type (i.e. Use float instead of 'float').
>>> from sigfig import round
>>> from decimal import Decimal
>>> round('3679.14159', decimals=2, output_type=float)
3679.14
>>> round(16248055.209, type=Decimal)
Decimal('16248055.209')
Note
Should not be used in conjunction with kwarg format/style or notation/form (since these will require str output type).
Formatting Output with Uncertainty¶
separation (sep)¶
Default value: ' ± '
Changes the string which separates a number from it’s uncertainty. Recognizes the special strings 'brackets' for in-line bracketed uncertainty, 'external_brackets' for the special case of uncertainties greater than 10, and tuple or list which allows number and uncertainty to be stored independently.
>>> from sigfig import round
>>> round('3679.14159', '0.00123', separation='+/-')
'3679.142+/-0.001'
>>> round('3679.14159', 0.000123, sep='brackets')
'3679.1416(1)'
>>> round('97.74159', 0.393, sep=tuple)
('97.7', '0.4')
>>> round('3679990.14159', '123.00123', sep='brackets')
'36800(1)00'
>>> round('3679990.14159', '123.00123', sep='external_brackets')
'3680000(100)'
format (style)¶
Default value: None
Allows choice of predefined formats 'Drake' and 'PDG' for The Drake Group’s preferred formatting of cutoff=29, spacer=3, spacing=' ', separation='brackets' and The Particle Data Group’s preferred formatting of cutoff=35 (see 5.3 Rounding).
>>> from sigfig import round
>>> round('3679990.14159', '0.00125', format='Drake')
'3 679 990.141 6(1 3)'
>>> round('3679990.14159', '0.00125', style='PDG')
'3679990.1416 ± 0.0013'
Note
Should not be used in conjunction with kwarg output_type/type or notation/form.
Other “Features”¶
order of keyword arguments¶
The interface for round() allows for conflicting keyword arguments (i.e. cutoff=19, cutoff=20 or format='Drake', sep='+/-') where subsequent kwargs overwrite what comes before them. However, this feature assumes insert-ordered dictionaries which is not guaranteed until Python 3.7 (and beyond). If you are using sigfig with earlier versions of Python (before 3.7) without insert-ordered dict’s the recommended usage is to avoid conflicting keyword arguments.
prefix¶
Default value: None
This is an experimental feature which adds a metric SI unit prefix to the end of the outputted string (or multiple prefixes in the case of very big or very small numbers). This feature behaves similar to engineering notation except using prefixes instead of exponents. It has some unresolved edge cases that can be fully flushed out if found useful and requested.
>>> from sigfig import round
>>> round('3679990.14159', '97654', style='Drake', prefix=True)
'3.68(10)M'
>>> round('3.67999014159E-10', '0.00125E-10', prefix=True)
'(368.0 ± 0.1)p'
zero behaviour¶
Any number with a value of zero that is known to 1 or more decimal places will be represented with all trailing zeros (ie. 0.00 is known to 2 decimal places and all trailing zeros are displayed). Conversely any number with a value of zero that is known to -1 or fewer decimal places will be represented with only 1 digit (ie. 000 will only be displayed as 0). The only exception is in the case of (non-external) bracketed uncertainty when the number is zero and known to -1 or fewer decimal places. Below is an example of each scenario:
>>> from sigfig import round
>>> round('0.00004567', decimals=3)
'0.000'
>>> round('23', '4732')
'0 ± 5000'
>>> round('23', '4732', sep='brackets')
'0(5)000'
warning suppression¶
While it’s recommended to use Python’s built-in warning control through from warnings import filterwarnings to define which warnings are presented, you can explicitly define warning behviour with this interface:
>>> from sigfig import round
>>> round('12', sigfigs=5)
sigfig.py:587: UserWarning: warning: 5 significant figures requested from number with only 2 significant figures
'12.000'
>>> round('12', sigfigs=4, warn=False)
'12.00'