sciform
We would greatly appreciate you taking the time to fill out the
User Experience Survey to help
improve sciform.
Overview
sciform is used to convert python numbers into strings according to
a variety of user-selected scientific formatting options including
decimal, binary, fixed-point, scientific and engineering formats.
Where possible, formatting follows documented standards such as those
published by BIPM or
IEC.
sciform provides certain options, such as engineering notation,
well-controlled significant figure rounding, and separator customization
which are not provided by the python built-in
format specification mini-language (FSML).
Installation
Install the latest stable version from PyPi with:
python -m pip install sciform
or install the latest development version from GitHub with:
python -m pip install git+https://github.com/jagerber48/sciform.git
sciform is compatible with Python versions >=3.8.
Usage
Here we provide a few key usage examples. For many more details see Usage.
sciform provides a wide variety of formatting options which can be
controlled when constructing Formatter objects which are then used
to format numbers into strings according to the selected options.
>>> from sciform import Formatter
>>> formatter = Formatter(
... round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
... )
>>> print(formatter(51413.14159265359))
51 413.141 593
>>> formatter = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.78))
123.5e+03
Users can also format numbers by constructing SciNum objects and
using string formatting to format the SciNum instances according
to a custom FSML.
>>> from sciform import SciNum
>>> num = SciNum(12345)
>>> print(f"{num:!2f}")
12000
>>> print(f"{num:!2r}")
12e+03
In addition to formatting individual numbers, sciform can be used
to format pairs of numbers as value/uncertainty pairs.
This can be done by passing two numbers into a Formatter call or by
using the SciNum object.
>>> formatter = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
>>> print(formatter(123456.654321, 0.00345))
123 456.654 3 ± 0.003 4
>>> formatter = Formatter(ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.654321, 0.00345))
(123.456654321 ± 0.000003450)e+03
>>> num = SciNum(123456.654321, 0.00345)
>>> print(f"{num:!2f}")
123456.6543 ± 0.0034
>>> print(f"{num:!2f()}")
123456.6543(34)
Note that the above examples demonstrate that sciform uses
“round-to-even”
rounding.
>>> print(f"{SciNum(865):!2}")
860
>>> print(f"{SciNum(875):!2}")
880
See Formatting Options, Format Specification Mini-Language for more details and Examples for more examples.
Project Status
sciform adheres to semantic versioning.
The major version for sciform is still 0 indicating that
sciform is still in the development stage which means there may be
backwards-incompatible changes to the interface (e.g. function or object
behaviors and names) without a corresponding major version bump.
All changes are announced after new releases in the
changelog.
Backwards incompatible changes are indicated with the [BREAKING]
flag.
We are very excited to get your feedback to help stabilize the interface
and make sciform a more useful tool.
You can provide your feedback on your experience with sciform by
filling out
the user experience survey.
Now is a great time to share your sciform ideas or issues by
opening a
discussion or
issue.
If you would like to contribute to sciform then please see
How to Contribute.
sciform has undergone
peer review
by the PyOpenSci community and been
accepted into the PyOpenSci ecosystem.
You can view the review
here.
Acknowledgements
sciform was heavily motivated by the prefix formatting provided in
the prefixed
package and the value ± uncertainty formatting in the
uncertainties package.
Contents: