sciform 0.28.1__tar.gz → 0.29.0__tar.gz

{sciform-0.28.1 → sciform-0.29.0}/CHANGELOG.rst

@@ -1,7 +1,76 @@
+This project adheres to `Semantic Versioning <https://semver.org/>`_.
+
+----
+
 Unreleased
 ----------
 
-* No unreleased changes.
+* There are no unreleased changes
+
+----
+
+0.29.0 (2023-09-05)
+-------------------
+
+Changed
+^^^^^^^
+
+* Previously, when using ``bracket_unc=True`` with any exponent string
+  (such as ``e-06``, ``μ`` or ``ppm``), the value and uncertainty were
+  always wrapped in parentheses, e.g. ``(1.03(25))e-06``,
+  ``(1.03(25)) μ`` or ``(1.03(25)) ppm``.
+  Now, when using ``bracket_unc=True`` with prefix or parts-per exponent
+  format modes, if the exponent is replaced with an alphabetic
+  replacement, then the value and uncertainty are no longer wrapped in
+  parentheses, e.g. ``1.03(25) μ`` and ``1.03(25) ppm``.
+  This is consistent with
+  `BIPM Guide Section 7.2.2 <https://www.bipm.org/documents/20126/2071204/JCGM_100_2008_E.pdf/cb0ef43f-baa5-11cf-3f85-4dcd86f77bd6#page=37>`_.
+  Specifically, any time ``bracket_unc=False`` the value and uncertainty
+  are always wrapped in parentheses, and any time notation like ``e+02``
+  or ``b+02`` is used to indicate the exponent then the value and
+  uncertainty are always wrapped in parentheses.
+
+Fixed
+^^^^^
+
+* Correct ``fit_plot_with_sciform.py`` example script to use new
+  ``exp_format=ExpFormat.PREFIX`` instead of old ``prefix_exp=True``.
+
+Improved
+^^^^^^^^
+
+* Documentation improvements including typos and neatening up changelog.
+
+----
+
+0.28.2 (2023-08-31)
+-------------------
+
+Improved
+^^^^^^^^
+
+* General wording and grammar improvements throughout documentation.
+* Include more usage examples in the examples documentation in addition
+  to referring the reader to the test suite.
+
+Fixed
+^^^^^
+
+* Fixed a bug when using ``pdg_sig_figs`` with uncertainties larger than
+  about 1000 by cleaning up ``Decimal`` math.
+* Previously, when formatting using the format specification
+  mini-language, if the prefix exponent format flag was omitted then the
+  exponent format was forced to ``ExpFormat.STANDARD`` rather than
+  ``None``.
+  This meant that it was impossible, using the format specification
+  mini-language combined with global configuration options, to set
+  ``ExpFormat.PARTS_PER``.
+  Now when the prefix flag is omitted ``exp_format`` is set to ``None``
+  so that it will be populated by the global default option.
+  In the future a flag may be added to select "parts-per" formatting
+  using the format specification mini-language.
+
+----
 
 0.28.1 (2023-08-28)
 -------------------
@@ -17,6 +86,8 @@ Unreleased
 * Test against Python 3.11.
 * List supported Python versions in ``pyproject.toml`` classifiers.
 
+----
+
 0.28.0 (2023-08-27)
 -------------------
 
@@ -24,7 +95,7 @@ Unreleased
   with an ``exp_format`` option which can be configured to
   ``ExpFormat.STANDARD``, ``ExpFormat.PREFIX`` or
   ``ExpFormat.PARTS_PER``.
-* Previously formating a non-finite number in percent mode would always
+* Previously formatting a non-finite number in percent mode would always
   display a ``'%'`` symbol, e.g. ``'(nan)%'``.
   Now the brackets and ``'%'`` symbol will be omitted unless
   ``nan_inf_exp=True``.
@@ -43,11 +114,15 @@ Unreleased
   Rounding and truncating are not properly implemented in binary mode
   yet.
 
+----
+
 0.27.4 (2023-08-25)
 -------------------
 
 * Setup github action to automatically build and publish on release.
 
+----
+
 0.27.3 (2023-08-23)
 -------------------
 
@@ -57,12 +132,16 @@ Unreleased
   ``setuptools_scm``.
 * Stopped encouraging ``import FormatOptions as Fo``.
 
+----
+
 0.27.2 (2023-08-20)
 -------------------
 
 * Add ``__repr__()`` for ``FormatOptions`` and
   ``RenderedFormatOptions``.
 
+----
+
 0.27.1 (2023-08-18)
 -------------------
 
@@ -71,6 +150,8 @@ Unreleased
   outputs which appear in the documentation.
 * Remove extra ``readthedocs.yaml`` file.
 
+----
+
 0.27.0 (2023-08-18)
 -------------------
 
@@ -79,6 +160,8 @@ Unreleased
   ``ndigits=AutoRound``. Furthermore, ``AutoRound`` could likely be
   confused as being an option for ``round_mode``, which it is not.
 
+----
+
 0.26.2 (2023-08-18)
 -------------------
 
@@ -88,11 +171,15 @@ Unreleased
   The bug is fixed by re-checking the options combinations after merging
   in the global defaults but before formatting.
 
+----
+
 0.26.1 (2023-08-18)
 -------------------
 
 * Add unit tests, increase test coverage.
 
+----
+
 0.26.0 (2023-08-15)
 -------------------
 
@@ -120,16 +207,22 @@ Unreleased
    * Better explanations of ``AutoExpVal`` and ``AutoRound`` behavior.
    * More accurate descriptions of some invalid options combinations.
 
+----
+
 0.25.2 (2023-08-11)
 -------------------
 
 * Update roadmap
 
+----
+
 0.25.1 (2023-08-10)
 -------------------
 
 * Refactor ``get_pdg_round_digit()`` into a dedicated function.
 
+----
+
 0.25.0 (2023-08-02)
 -------------------
 
@@ -139,6 +232,8 @@ Unreleased
   ``FormatOptions`` instances using the ``merge()`` method.
 * Minor documentation improvements.
 
+----
+
 0.24.0 (2023-07-30)
 -------------------
 
@@ -146,6 +241,8 @@ Unreleased
   ``ExpMode.PERCENT``.
   There is no longer a ``percent`` keyword argument.
 
+----
+
 0.23.0 (2023-07-29)
 -------------------
 
@@ -161,17 +258,23 @@ Unreleased
   ``SciNumUnc`` objects.
 * Change ``pyproject.toml`` description
 
+----
+
 0.22.2 (2023-07-27)
 -------------------
 
 * Add ``.readthedocs.yaml`` and update documentation
   ``requirements.txt`` for reproducible documentation builds.
 
+----
+
 0.22.1 (2023-07-27)
 -------------------
 
 * Fix a date typo in the changelog for the entry for version ``0.22.0``.
 
+----
+
 0.22.0 (2023-07-27)
 -------------------
 
@@ -200,6 +303,8 @@ Unreleased
      was corrected.
    * Add "under construction" message to README.
 
+----
+
 0.21.0 (2023-07-22)
 -------------------
 
@@ -208,7 +313,9 @@ Unreleased
   ``float`` and more reliable rounding behavior.
 * Update particle data group uncertainty rounding unit tests since edge
   cases are now handled property as a result of adopting ``Decimal``.
-* Minor cleanup of ``sfloat`` arithemetic functions.
+* Minor cleanup of ``sfloat`` arithmetic functions.
+
+----
 
 0.20.1 (2023-06-24)
 -------------------
@@ -221,6 +328,8 @@ Unreleased
   ``format_float()`` and ``format_val_unc()`` directly instead of
   creating a ``Formatter`` object first.
 
+----
+
 0.20.0 (2023-06-22)
 -------------------
 
@@ -236,6 +345,8 @@ Unreleased
   mode: e.g. ``\text{Mi}``.
 * Link to test cases on examples page.
 
+----
+
 0.19.0 (2023-06-22)
 -------------------
 
@@ -243,11 +354,15 @@ Unreleased
   doc testing, and flake8 scans during github pull requests.
 * Minor flake8 cleanup
 
+----
+
 0.18.1 (2023-06-21)
 -------------------
 
 * Documentation improvements
 
+----
+
 0.18.0 (2023-06-19)
 -------------------
 
@@ -261,6 +376,8 @@ Unreleased
 * Expose ``AutoPrec`` and ``AutoExp`` sentinel classes so that users can
   explicitly indicate automatic precision and exponent selection.
 
+----
+
 0.17.1 (2023-06-19)
 -------------------
 
@@ -268,6 +385,8 @@ Unreleased
   including more verbose clarifying comments.
 * Minor documentation cleanup
 
+----
+
 0.17.0 (2023-06-19)
 -------------------
 
@@ -276,6 +395,8 @@ Unreleased
 * Fix typos in binary IEC prefixes table.
 * Fix some cross links in documentation.
 
+----
+
 0.16.0 (2023-06-18)
 -------------------
 
@@ -283,16 +404,22 @@ Unreleased
 * Refactor exponent string conversion.
 * Percent mode for non-finite numbers.
 
+----
+
 0.15.2 (2023-06-18)
 -------------------
 
 * Fix a bug involving space filling and separators.
 
+----
+
 0.15.1 (2023-06-17)
 -------------------
 
 * Changelog formatting typo.
 
+----
+
 0.15.0 (2023-06-17)
 -------------------
 
@@ -300,8 +427,12 @@ Unreleased
 * Forbid percent mode unless using fixed point exponent mode.
 * Add PyPi link to readme.
 
+----
+
 0.14.0 (2023-06-17)
 -------------------
 
 * Add Changelog.
 * Add ``unicode_pm`` option with documentation and tests.
+
+----

{sciform-0.28.1 → sciform-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sciform
-Version: 0.28.1
+Version: 0.29.0
 Summary: A package for formatting numbers into scientific formatted strings.
 Author-email: Justin Gerber <justin.gerber48@gmail.com>
 Project-URL: homepage, https://github.com/jagerber48/sciform
@@ -77,7 +77,7 @@ continue to change until version ``1.0.0`` is released.
 API changes will be announced after new releases in the
 `changelog <https://sciform.readthedocs.io/en/stable/project.html#changelog>`_.
 If you have an idea or opinion about how ``sciform`` should be designed,
-now is a great to
+now is a great time to
 `post a discussion topic <https://github.com/jagerber48/sciform/discussions>`_
 about it!
 
@@ -107,19 +107,6 @@ strings according to the selected options.
 >>> print(sform(123456.78))
 123.5e+03
 
-For brevity, the user may consider abbreviating ``FormatOptions`` as
-``Fo``.
-
->>> from sciform import (Formatter, FormatOptions, RoundMode,
-...                      GroupingSeparator, ExpMode)
->>> sform = Formatter(FormatOptions(
-...             round_mode=RoundMode.DEC_PLACE,
-...             ndigits=6,
-...             upper_separator=GroupingSeparator.SPACE,
-...             lower_separator=GroupingSeparator.SPACE))
->>> print(sform(51413.14159265359))
-51 413.141 593
-
 Users can also format numbers by constructing ``SciNum`` objects and
 using string formatting to format the ``SciNum`` instances according
 to a custom FSML.

{sciform-0.28.1 → sciform-0.29.0}/README.rst

@@ -60,7 +60,7 @@ continue to change until version ``1.0.0`` is released.
 API changes will be announced after new releases in the
 `changelog <https://sciform.readthedocs.io/en/stable/project.html#changelog>`_.
 If you have an idea or opinion about how ``sciform`` should be designed,
-now is a great to
+now is a great time to
 `post a discussion topic <https://github.com/jagerber48/sciform/discussions>`_
 about it!
 
@@ -90,19 +90,6 @@ strings according to the selected options.
 >>> print(sform(123456.78))
 123.5e+03
 
-For brevity, the user may consider abbreviating ``FormatOptions`` as
-``Fo``.
-
->>> from sciform import (Formatter, FormatOptions, RoundMode,
-...                      GroupingSeparator, ExpMode)
->>> sform = Formatter(FormatOptions(
-...             round_mode=RoundMode.DEC_PLACE,
-...             ndigits=6,
-...             upper_separator=GroupingSeparator.SPACE,
-...             lower_separator=GroupingSeparator.SPACE))
->>> print(sform(51413.14159265359))
-51 413.141 593
-
 Users can also format numbers by constructing ``SciNum`` objects and
 using string formatting to format the ``SciNum`` instances according
 to a custom FSML.

sciform-0.29.0/docs/source/examples.rst

@@ -0,0 +1,252 @@
+Examples
+########
+
+.. module:: sciform
+   :noindex:
+
+Test Cases
+==========
+
+The :mod:`sciform`
+`test suite <https://github.com/jagerber48/sciform/tree/main/tests>`_
+contains hundreds of example formatting test cases which showcase the
+many available formatting options.
+
+Formatter
+=========
+
+Here are a small selection of examples which demonstrate some of the
+available formatting options.
+
+>>> from sciform import (FormatOptions, Formatter, ExpMode, RoundMode,
+...                      SignMode, GroupingSeparator, ExpFormat)
+>>> num = 12345.54321
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.SCIENTIFIC,
+...             round_mode=RoundMode.SIG_FIG,
+...             ndigits=4))
+>>> print(sform(num))
+1.235e+04
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.ENGINEERING,
+...             round_mode=RoundMode.DEC_PLACE,
+...             ndigits=10,
+...             sign_mode=SignMode.SPACE,
+...             superscript_exp=True))
+>>> print(sform(num))
+ 12.3455432100×10³
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.FIXEDPOINT,
+...             upper_separator=GroupingSeparator.SPACE,
+...             decimal_separator=GroupingSeparator.COMMA,
+...             lower_separator=GroupingSeparator.UNDERSCORE,
+...             sign_mode=SignMode.ALWAYS))
+>>> print(sform(num))
++12 345,543_21
+
+>>> num = 0.076543
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.SCIENTIFIC,
+...             exp_val=-3,
+...             exp_format=ExpFormat.PARTS_PER,
+...             add_ppth_form=True))
+>>> print(sform(num))
+76.543 ppth
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.SCIENTIFIC,
+...             exp_val=-2,
+...             exp_format=ExpFormat.PREFIX,
+...             add_c_prefix=True))
+>>> print(sform(num))
+7.6543 c
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.SCIENTIFIC,
+...             exp_val=-6,
+...             exp_format=ExpFormat.PREFIX))
+>>> print(sform(num))
+76543 μ
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.PERCENT))
+>>> print(sform(num))
+7.6543%
+
+>>> num = 3141592.7
+>>> unc = 1618
+>>> sform = Formatter()
+>>> print(sform(num, unc))
+3141593 +/- 1618
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.ENGINEERING,
+...             exp_format=ExpFormat.PREFIX,
+...             pdg_sig_figs=True,
+...             unicode_pm=True,
+...             unc_pm_whitespace=False))
+>>> print(sform(num, unc))
+(3.1416±0.0016) M
+
+>>> num = 314159.27
+>>> unc = 1618
+>>> sform = Formatter(FormatOptions(
+...             exp_mode=ExpMode.ENGINEERING_SHIFTED,
+...             pdg_sig_figs=True,
+...             bracket_unc=True))
+>>> print(sform(num, unc))
+(0.3142(16))e+06
+
+SciNum, SciNumUnc, and Global Options
+=====================================
+
+Here are a small selection of examples which demonstrate some of the
+available string formatting options.
+Note that many options are not available through the :ref:`fsml`, so
+these options must be selected by configuring the global default options
+during formatting.
+Here this is done using the :class:`GlobalDefaultsContext` context
+manager, but this could have been done using :func:`set_global_defaults`
+instead.
+
+>>> from sciform import SciNum, SciNumUnc, GlobalDefaultsContext
+>>> snum = SciNum(12345.54321)
+>>> print(f'{snum:!4e}')
+1.235e+04
+>>> print(f'{snum: .10r}')
+ 12.3455432100e+03
+>>> print(f'{snum:+s,_}')
++12 345,543_21
+
+>>> snum = SciNum(0.076543)
+>>> with GlobalDefaultsContext(FormatOptions(
+...         exp_format=ExpFormat.PARTS_PER,
+...         add_ppth_form=True)):
+...     print(f'{snum:ex-3}')
+76.543 ppth
+>>> with GlobalDefaultsContext(FormatOptions(
+...             exp_format=ExpFormat.PREFIX,
+...             add_c_prefix=True)):
+...     print(f'{snum:ex-2}')
+7.6543 c
+>>> with GlobalDefaultsContext(FormatOptions(
+...             exp_mode=ExpMode.SCIENTIFIC,
+...             exp_val=-6,
+...             exp_format=ExpFormat.PREFIX)):
+...     print(f'{snum:ex-6}')
+76543 μ
+>>> print(f'{snum:%}')
+7.6543%
+
+>>> num_unc = SciNumUnc(3141592.7, 1618)
+>>> print(f'{num_unc}')
+3141593 +/- 1618
+>>> with GlobalDefaultsContext(FormatOptions(
+...             pdg_sig_figs=True,
+...             unicode_pm=True,
+...             unc_pm_whitespace=False)):
+...     print(f'{num_unc:rp}')
+(3.1416±0.0016) M
+
+>>> num_unc = SciNumUnc(314159.27, 1618)
+>>> with GlobalDefaultsContext(FormatOptions(
+...             pdg_sig_figs=True)):
+...     print(f'{num_unc:#r()}')
+(0.3142(16))e+06
+
+Plotting and Tabulating Fit Data
+================================
+
+We are given 3 data sets:
+
+.. collapse:: Data
+
+   .. literalinclude:: ../../examples/data/fit_data.json
+      :language: json
+
+We want to perform quadratic fits to these data sets, visualize
+the results, and print the best fit parameters including the uncertainty
+reported by the fit routine.
+For these tasks we will require the ``numpy``, ``scipy``,
+``matplotlib``, and ``tabulate`` packages.
+
+Without ``sciform``
+-------------------
+
+Without ``sciform`` we can perform the fit and plot the data and best
+fit lines and print out a table of best fit parameters and
+uncertainties:
+
+.. collapse:: Code
+
+   .. literalinclude:: ../../examples/fit_plot_no_sciform.py
+      :language: python
+
+This produces the plot:
+
+.. image:: ../../examples/outputs/fit_plot_no_sciform.png
+  :width: 400
+
+And the table:
+
+.. literalinclude:: ../../examples/outputs/fit_plot_no_sciform_table.txt
+   :language: python
+
+This plot and table suffer from a number of shortcomings which impede
+human readability.
+
+- In the table, the exponents for the values and uncertainties differ,
+  making it hard to identify the significant digits of the value.
+- The number of digits displayed for the values is not correlated with
+  the uncertainty for that value. For example, the ``y0`` values are
+  shown with precision to the 10\ :sup:`+8` place, but the uncertainty
+  indicates precision down to the 10\ :sup:`+3` place.
+- In the table, the exponents vary from one dataset to the next. It is
+  hard to see these differences at a glance.
+- The tick labels on the plot are illegible because each value has so
+  many digits.
+
+Of course, even without :mod:`sciform`, it would be possible to make
+manual adjustments to the plot and the table to improve these data
+visualizations.
+However, :mod:`sciform` will allow us to make the required changes in a
+general and automated way.
+
+With ``sciform``
+----------------
+
+We can address these problems using :mod:`sciform` by:
+
+#. Using prefix scientific notation to label the plot axes.
+   This will greatly reduce the number of symbols needed for each tick
+   value.
+#. Using value/uncertainty formatting in the table to collapse the value
+   and error column pairs into individual columns.
+   This will make obvious the relative scale between the uncertainty and
+   the value.
+   Using ``sciform``, the significant digits displayed for the value
+   will always match the precision of the uncertainty.
+   We will use bracket uncertainty format.
+#. Using engineering notation for the value/uncertainty in the table. This
+   will make the relative scale between different rows obvious.
+
+To do this we import :mod:`sciform` and make some helper functions for
+displaying the plot axes as described:
+
+.. collapse:: Code
+
+    .. literalinclude:: ../../examples/fit_plot_with_sciform.py
+      :language: python
+
+This produces the plot:
+
+.. image:: ../../examples/outputs/fit_plot_with_sciform.png
+  :width: 400
+
+and the table:
+
+.. literalinclude:: ../../examples/outputs/fit_plot_with_sciform_table.txt
+   :language: python
+
+We can see the plot and table are immediately much more legible.
+Less characters are needed to communicate the data in both
+visualizations.
+The relative scaling of parameters between datasets and the relative
+scaling between the value and uncertainty for each entry are
+immediately clear.

{sciform-0.28.1 → sciform-0.29.0}/docs/source/fsml.rst

@@ -1,6 +1,6 @@
 .. _fsml:
 
-Format Specification Mini Language
+Format Specification Mini-Language
 ##################################
 
 .. module:: sciform
@@ -14,7 +14,7 @@ configured using :class:`FormatOptions` instances, users can construct
 :class:`SciNum` or :class:`SciNumUnc` instances and format them using
 string formatting with format specification strings from the
 :mod:`sciform` format specification mini-language (FSML).
-This is analagous to how python :class:`int`, :class:`float`, and
+This is analogous to how python :class:`int`, :class:`float`, and
 :class:`Decimal` instances can be formatted using the built-in
 `format specification mini-language <https://docs.python.org/3/library/string.html#format-specification-mini-language>`_.
 The :mod:`sciform` format specification mini-language is given by::
@@ -126,7 +126,7 @@ Further details about the options can be found at
        See :ref:`bracket_uncertainty`.
 
 
-Incompatibilities With Built-in Format Specification Mini Language
+Incompatibilities With Built-in Format Specification Mini-Language
 ==================================================================
 
 The :mod:`sciform` FSML extends the functionality of the
@@ -158,12 +158,12 @@ for scientific formatting.
   * Inclusion of a hanging decimal point, e.g. ``123.``.
     :mod:`sciform` never includes a hanging decimal point.
 
-* For :class:`float` instances, Python formatting uses a default precion
-  of 6 for ``f``, ``F``, ``%``, ``e``, and ``E`` modes if no explicit
-  precision (``ndigits``) is supplied.
+* For :class:`float` instances, Python formatting uses a default
+  precision of 6 for ``f``, ``F``, ``%``, ``e``, and ``E`` modes if no
+  explicit precision (``ndigits``) is supplied.
   :mod:`sciform`, instead, converts :class:`float` instances into
   :class:`str` and then :class:`Decimal` so that they are displayed with
-  as many digits as necessary "round-trip" when no ``ndigits`` is
+  as many digits as necessary to "round-trip" when no ``ndigits`` is
   supplied.
   E.g. ``f'{float(0.3):f}'`` yields ``0.300000`` while
   ``f'{SciNum(0.3):f}`` yields ``0.3``.
@@ -182,7 +182,7 @@ for scientific formatting.
   There is no ``0`` flag, as in the built-in FSML, that may be placed
   before the width field to indicate sign-aware zero padding.
   E.g. ``f'{float(12): =4}`` yields ``'  12'`` while
-  ``f{SciNum(12): =4}`` yeilds ``'   12'``, fill characters are padded
+  ``f{SciNum(12): =4}`` yields ``'   12'``, fill characters are padded
   up to the 10\ :sup:`4` digits place.
 
 * The built-in FSML supports displaying negative zero, but also supports