sciform

.. container::

|Repo Status| |pyOpenSci| |Documentation Status| |PyPI Version| |PyPI Python| |Coverage Status| |GH Workflow Status| |Zenodo|

.. |Repo Status| image:: https://www.repostatus.org/badges/latest/wip.svg :target: https://www.repostatus.org/#wip :alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. .. |pyOpenSci| image:: https://tinyurl.com/y22nb8up :target: https://github.com/pyOpenSci/software-review/issues/121 :alt: pyOpenSci .. |Documentation Status| image:: https://img.shields.io/readthedocs/sciform?logo=readthedocs&link=https%3A%2F%2Fsciform.readthedocs.io%2Fen%2Fstable%2F :target: https://sciform.readthedocs.io/en/stable/ :alt: Read the Docs .. |PyPI Version| image:: https://img.shields.io/pypi/v/sciform?logo=pypi :target: https://pypi.org/project/sciform/ :alt: PyPI - Version .. |PyPI Python| image:: https://img.shields.io/pypi/pyversions/sciform?logo=python :target: https://pypi.org/project/sciform/ :alt: PyPI - Python Version .. |Coverage Status| image:: https://img.shields.io/codecov/c/github/jagerber48/sciform?logo=codecov :target: https://codecov.io/gh/jagerber48/sciform :alt: Codecov .. |GH Workflow Status| image:: https://img.shields.io/github/actions/workflow/status/jagerber48/sciform/python-package.yml?logo=github%20actions :target: https://github.com/jagerber48/sciform/blob/main/.github/workflows/python-package.yml :alt: GitHub Workflow Status .. |Zenodo| image:: https://zenodo.org/badge/645611310.svg :target: https://zenodo.org/doi/10.5281/zenodo.10645272 :alt: Zenodo

####### sciform #######

| Repository: <https://github.com/jagerber48/sciform>_ | Documentation: <https://sciform.readthedocs.io/en/stable/>_ | PyPi: <https://pypi.org/project/sciform/>_

We would greatly appreciate you taking the time to fill out the User Experience Survey <https://forms.gle/TkkKgywYyEMKu9U37>_ 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 fixed-point, scientific and engineering formats. Where possible, formatting follows documented standards such as those published by BIPM <https://www.bipm.org/en/>. 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) <https://docs.python.org/3/library/string.html#format-specification-mini-language>.

============ Installation

Install the latest stable version from PyPi <https://pypi.org/project/sciform/>_ with::

python -m pip install sciform

or install the latest development version from GitHub <https://github.com/jagerber48/sciform>_ 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 <https://sciform.readthedocs.io/en/stable/usage.html>_.

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" <https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even>_ rounding::

print(f"{SciNum(865):!2}") 860 print(f"{SciNum(875):!2}") 880

See Formatting Options <https://sciform.readthedocs.io/en/stable/options.html>, Format Specification Mini-Language <https://sciform.readthedocs.io/en/stable/fsml.html> for more details and Examples <https://sciform.readthedocs.io/en/stable/examples.html>_ for more examples.

============== Project Status

sciform adheres to semantic versioning <https://semver.org/>. 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 <https://sciform.readthedocs.io/en/stable/project.html#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 <https://forms.gle/TkkKgywYyEMKu9U37>. Now is a great time to share your sciform ideas or issues by opening a discussion <https://github.com/jagerber48/sciform/discussions> or issue <https://github.com/jagerber48/sciform/issues>. If you would like to contribute to sciform then please see How to Contribute <https://sciform.readthedocs.io/en/stable/project.html#how-to-contribute>.

sciform has undergone peer review <https://www.pyopensci.org/about-peer-review/index.html>_ by the PyOpenSci <https://www.pyopensci.org/>_ community and been accepted into the PyOpenSci ecosystem. You can view the review here <https://github.com/pyOpenSci/software-submission/issues/121>_.

================ Acknowledgements

sciform was heavily motivated by the prefix formatting provided in the prefixed <https://github.com/Rockhopper-Technologies/prefixed>_ package and the value ± uncertainty formatting in the uncertainties <https://github.com/lebigot/uncertainties>_ package.