format-multiple-errors 0.0.2__tar.gz

format_multiple_errors-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ed Bennett/Swansea University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

format_multiple_errors-0.0.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.1
+Name: format_multiple_errors
+Version: 0.0.2
+Summary: A small widget to be able to format multiple, asymmetric errors easily.
+Author-email: Ed Bennett <e.j.bennett@swansea.ac.uk>
+Project-URL: Homepage, https://github.com/edbennett/format_multiple_errors
+Project-URL: Bug Tracker, https://github.com/edbennett/format_multiple_errors/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# format_multiple_errors
+
+[![Run tests](https://github.com/edbennett/format_multiple_errors/actions/workflows/pytest.yaml/badge.svg)](https://github.com/edbennett/format_multiple_errors/actions/workflows/pytest.yaml)
+[![Code quality](https://github.com/edbennett/format_multiple_errors/actions/workflows/codequality.yaml/badge.svg)](https://github.com/edbennett/format_multiple_errors/actions/workflows/codequality.yaml)
+
+A small library intended to make it easy to format numbers like
+
+$$1.623(11)({}^{3}_{4})\times 10^{-7}$$
+
+or
+
+$$(6.829 \pm 0.013 {}^{+0.104}_{-0.096})\times10^{5}$$
+
+
+## Installation
+
+To install, open a terminal and run:
+
+    pip install https://github.com/edbennett/format_multiple_errors
+
+
+## Usage as a library
+
+### Formatting numbers
+
+The `format_multiple_errors` package provides a function to format numbers,
+also named `format_multiple_errors`.
+
+    from format_multiple_errors import format_multiple_errors
+
+This function takes a central value,
+and zero or more uncertainties.
+It returns a string containing all numbers formatted to the same absolute precision.
+
+Uncertainties may be single numbers:
+
+    >>> format_multiple_errors(1, 0.1, 0.2)
+    '1.00 ± 0.10 ± 0.20'
+
+or they may also be tuples of two numbers,
+representing the upper and lower error respectively:
+
+    >>> format_multiple_errors(1, 0.1, (0.2, 0.3))
+    '1.00 ± 0.10 (+0.20 / -0.30)'
+
+A number of keyword arguments control the formatting.
+The `abbreviate` option uses the compact form of expressing errors:
+
+    >>> format_multiple_errors(1.001, 0.010, (0.020, 0.034), abbreviate=True)
+    '1.001(10)(+20 / -34)'
+
+The `latex` option uses LaTeX macros rather than Unicode characters,
+and generally formats the result for inclusion in a LaTeX document:
+
+    >>> format_multiple_errors(1.001, 0.010, (0.020, 0.034), latex=True)
+    '1.001 \\pm 0.010 {}^{+0.020}_{-0.034}'
+
+Numbers are formatted by default with leading or trailing zeroes.
+To use exponential notation instead,
+use the `exponential` parameter:
+
+    >>> format_multiple_errors(0.00123, 0.00045, (0.00067, 0.00089), exponential=True)
+    '(1.23 ± 0.45 (+0.67 / -0.89))e-3'
+
+By default the precision is controlled
+by setting the number of significant digits presented for the smallest uncertainty.
+Setting `length_control="central"` instead controls the significant digits of the central value:
+
+    >>> format_multiple_errors(1.0, 0.1, (0.2, 0.3), length_control="central")
+    '1.0 ± 0.1 (+0.2 / -0.3)'
+
+The number of significant figures presented can be controlled with the `significant_figures` parameter:
+
+    >>> format_multiple_errors(1.001, 0.001, (0.002, 0.0034), significant_figures=1)
+    '1.001 ± 0.001 (+0.002 / -0.003)'
+
+These options may be combined:
+
+    >>> format_multiple_errors(123.45, 3.14, (2.82, 12.91), length_control="central", significant_figures=5, latex=True, abbreviate=True, exponential=True)
+    '1.2345(314)({}^{282}_{1291}) \\times 10^{2}'
+
+
+### Formatting DataFrames
+
+The library provides two functions for working with Pandas DataFrames.
+
+The `format_column_errors` function accepts and returns columns.
+For example,
+it can take `pd.Series` objects:
+
+    >>> import pandas as pd
+    >>> from format_multiple_errors import format_column_errors
+    >>> df = pd.DataFrame([{"a": 3.14, "b": 0.59, "c": 0.26}, {"a": 2.17, "b": 0.82, "c":   0.81}])
+    >>> format_column_errors(df["a"], (df["b"], df["c"]), abbreviate=True)
+    0    3.14(+59/-26)
+    1    2.17(+82/-81)
+    dtype: object
+
+It can also take a `pd.DataFrame` and specifications of the column names to use:
+
+    >>> format_column_errors("a", ("b", "c"), df=df, abbreviate=True)
+    0    3.14(+59/-26)
+    1    2.17(+82/-81)
+    dtype: object
+
+
+### Interaction with `pyerrors` and `uncertainties`
+
+If the central value passed to `format_multiple_errors` already has an uncertainty,
+due to being an instance of `pyerrors.Obs` or `uncertainties.UFloat`,
+then this is prepended to the list of errors.
+For example,
+
+    >>> from uncertainties import ufloat
+    >>> result = ufloat(1.01, 0.1)
+    >>> systematic = (0.2, 0.34)
+    >>> format_multiple_errors(result, systematic)
+    '1.01 ± 0.10 (+0.20 / -0.34)'
+
+Instances of `pyerrors.Obs` must already have an uncertainty computed
+(must have had the `.gamma_method()` method called on them)
+before being passed to `format_multiple_errors`,
+otherwise an error is raised.
+
+
+## Command-line interface
+
+A command-line interface is also provided.
+To format a single number,
+use the `format_multiple_errors format` command:
+
+    $ format_multiple_errors --abbreviate format 3.141 0.059 0.026,0.053
+    3.141(59)(+26/-53)
+
+To format a CSV as a LaTeX table,
+use the `format_multiple_errors table` command:
+
+    $ format_multiple_errors --latex --abbreviate table input.csv \
+    > a b c_value,c_error d_value,d_upper-d_lower,d_systematic \
+    > --headings '$a$' '$b$' '$c$' '$d$' --output_file output.tex
+    $ cat output.tex
+    \begin{tabular}{rrll}
+    \toprule
+    $a$ & $b$ & $c$ & $d$ \\
+    \midrule
+    3 & 1 & $4.16(26)$ & $3.59({}^{79}_{24})(46)$ \\
+    2 & 7 & $1.83(18)$ & $8.459({}^{45}_{235})(360)$ \\
+    \bottomrule
+    \end{tabular}
+
+Formatting options are specified before the subcommand (`format` or `table`).
+Options specific to the command are specified afterwards.
+
+
+## Development
+
+To be able to run the test suite,
+create a virtual environment using the tooling of your choice,
+and then install the developer dependencies:
+
+    pip install -r requirements_dev.txt
+
+
+The test suite can then be run by calling
+
+    pytest
+
+Before committing,
+you should ensure that the repository's pre-commit hooks are installed:
+
+    pre-commit install
+
+Then some basic code quality checks will be run by Git
+before it accepts your commit.

format_multiple_errors-0.0.2/README.md

@@ -0,0 +1,174 @@
+# format_multiple_errors
+
+[![Run tests](https://github.com/edbennett/format_multiple_errors/actions/workflows/pytest.yaml/badge.svg)](https://github.com/edbennett/format_multiple_errors/actions/workflows/pytest.yaml)
+[![Code quality](https://github.com/edbennett/format_multiple_errors/actions/workflows/codequality.yaml/badge.svg)](https://github.com/edbennett/format_multiple_errors/actions/workflows/codequality.yaml)
+
+A small library intended to make it easy to format numbers like
+
+$$1.623(11)({}^{3}_{4})\times 10^{-7}$$
+
+or
+
+$$(6.829 \pm 0.013 {}^{+0.104}_{-0.096})\times10^{5}$$
+
+
+## Installation
+
+To install, open a terminal and run:
+
+    pip install https://github.com/edbennett/format_multiple_errors
+
+
+## Usage as a library
+
+### Formatting numbers
+
+The `format_multiple_errors` package provides a function to format numbers,
+also named `format_multiple_errors`.
+
+    from format_multiple_errors import format_multiple_errors
+
+This function takes a central value,
+and zero or more uncertainties.
+It returns a string containing all numbers formatted to the same absolute precision.
+
+Uncertainties may be single numbers:
+
+    >>> format_multiple_errors(1, 0.1, 0.2)
+    '1.00 ± 0.10 ± 0.20'
+
+or they may also be tuples of two numbers,
+representing the upper and lower error respectively:
+
+    >>> format_multiple_errors(1, 0.1, (0.2, 0.3))
+    '1.00 ± 0.10 (+0.20 / -0.30)'
+
+A number of keyword arguments control the formatting.
+The `abbreviate` option uses the compact form of expressing errors:
+
+    >>> format_multiple_errors(1.001, 0.010, (0.020, 0.034), abbreviate=True)
+    '1.001(10)(+20 / -34)'
+
+The `latex` option uses LaTeX macros rather than Unicode characters,
+and generally formats the result for inclusion in a LaTeX document:
+
+    >>> format_multiple_errors(1.001, 0.010, (0.020, 0.034), latex=True)
+    '1.001 \\pm 0.010 {}^{+0.020}_{-0.034}'
+
+Numbers are formatted by default with leading or trailing zeroes.
+To use exponential notation instead,
+use the `exponential` parameter:
+
+    >>> format_multiple_errors(0.00123, 0.00045, (0.00067, 0.00089), exponential=True)
+    '(1.23 ± 0.45 (+0.67 / -0.89))e-3'
+
+By default the precision is controlled
+by setting the number of significant digits presented for the smallest uncertainty.
+Setting `length_control="central"` instead controls the significant digits of the central value:
+
+    >>> format_multiple_errors(1.0, 0.1, (0.2, 0.3), length_control="central")
+    '1.0 ± 0.1 (+0.2 / -0.3)'
+
+The number of significant figures presented can be controlled with the `significant_figures` parameter:
+
+    >>> format_multiple_errors(1.001, 0.001, (0.002, 0.0034), significant_figures=1)
+    '1.001 ± 0.001 (+0.002 / -0.003)'
+
+These options may be combined:
+
+    >>> format_multiple_errors(123.45, 3.14, (2.82, 12.91), length_control="central", significant_figures=5, latex=True, abbreviate=True, exponential=True)
+    '1.2345(314)({}^{282}_{1291}) \\times 10^{2}'
+
+
+### Formatting DataFrames
+
+The library provides two functions for working with Pandas DataFrames.
+
+The `format_column_errors` function accepts and returns columns.
+For example,
+it can take `pd.Series` objects:
+
+    >>> import pandas as pd
+    >>> from format_multiple_errors import format_column_errors
+    >>> df = pd.DataFrame([{"a": 3.14, "b": 0.59, "c": 0.26}, {"a": 2.17, "b": 0.82, "c":   0.81}])
+    >>> format_column_errors(df["a"], (df["b"], df["c"]), abbreviate=True)
+    0    3.14(+59/-26)
+    1    2.17(+82/-81)
+    dtype: object
+
+It can also take a `pd.DataFrame` and specifications of the column names to use:
+
+    >>> format_column_errors("a", ("b", "c"), df=df, abbreviate=True)
+    0    3.14(+59/-26)
+    1    2.17(+82/-81)
+    dtype: object
+
+
+### Interaction with `pyerrors` and `uncertainties`
+
+If the central value passed to `format_multiple_errors` already has an uncertainty,
+due to being an instance of `pyerrors.Obs` or `uncertainties.UFloat`,
+then this is prepended to the list of errors.
+For example,
+
+    >>> from uncertainties import ufloat
+    >>> result = ufloat(1.01, 0.1)
+    >>> systematic = (0.2, 0.34)
+    >>> format_multiple_errors(result, systematic)
+    '1.01 ± 0.10 (+0.20 / -0.34)'
+
+Instances of `pyerrors.Obs` must already have an uncertainty computed
+(must have had the `.gamma_method()` method called on them)
+before being passed to `format_multiple_errors`,
+otherwise an error is raised.
+
+
+## Command-line interface
+
+A command-line interface is also provided.
+To format a single number,
+use the `format_multiple_errors format` command:
+
+    $ format_multiple_errors --abbreviate format 3.141 0.059 0.026,0.053
+    3.141(59)(+26/-53)
+
+To format a CSV as a LaTeX table,
+use the `format_multiple_errors table` command:
+
+    $ format_multiple_errors --latex --abbreviate table input.csv \
+    > a b c_value,c_error d_value,d_upper-d_lower,d_systematic \
+    > --headings '$a$' '$b$' '$c$' '$d$' --output_file output.tex
+    $ cat output.tex
+    \begin{tabular}{rrll}
+    \toprule
+    $a$ & $b$ & $c$ & $d$ \\
+    \midrule
+    3 & 1 & $4.16(26)$ & $3.59({}^{79}_{24})(46)$ \\
+    2 & 7 & $1.83(18)$ & $8.459({}^{45}_{235})(360)$ \\
+    \bottomrule
+    \end{tabular}
+
+Formatting options are specified before the subcommand (`format` or `table`).
+Options specific to the command are specified afterwards.
+
+
+## Development
+
+To be able to run the test suite,
+create a virtual environment using the tooling of your choice,
+and then install the developer dependencies:
+
+    pip install -r requirements_dev.txt
+
+
+The test suite can then be run by calling
+
+    pytest
+
+Before committing,
+you should ensure that the repository's pre-commit hooks are installed:
+
+    pre-commit install
+
+Then some basic code quality checks will be run by Git
+before it accepts your commit.

format_multiple_errors-0.0.2/format_multiple_errors/__init__.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+
+"""A package for formatting numbers with zero or more errors or pairs of errors"""
+
+import warnings
+
+from .formatter import format_multiple_errors as format_multiple_errors
+
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore")
+    from .pandas import (
+        format_column_errors as format_column_errors,
+        format_dataframe_errors as format_dataframe_errors,
+        ColumnSpec as ColumnSpec,
+    )
+
+del warnings

format_multiple_errors-0.0.2/format_multiple_errors/__main__.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+
+"""Command-line interface for format_multiple_errors"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, FileType, Namespace
+import logging
+from sys import exit, stderr
+
+try:
+    import pandas as pd
+except ImportError:
+    pd = None
+
+from .formatter import format_multiple_errors
+from .pandas import format_dataframe_errors, ColumnSpec
+
+
+def _format_numbers(args: Namespace) -> None:
+    """Format a single number."""
+    print(
+        format_multiple_errors(
+            args.value,
+            *args.errors,
+            length_control=args.length_control,
+            significant_figures=args.significant_figures,
+            abbreviate=args.abbreviate,
+            exponential=args.exponential,
+            latex=args.latex,
+        )
+    )
+
+
+def _check_pandas() -> None:
+    """Check if Pandas is available; complain and exit if not."""
+    if pd is None:
+        print(
+            "Pandas is not installed, but is required to process a table.",
+            file=stderr,
+        )
+        exit()
+
+
+def _format_table(args: Namespace) -> None:
+    """Format a table from a CSV."""
+    _check_pandas()
+    if not args.latex:
+        logging.warning(
+            "--latex not specified; for LaTeX table output this will be forced on.",
+        )
+
+    if not args.headings:
+        args.headings = None
+    else:
+        assert len(args.headings) == len(args.column_specs)
+
+    df = pd.read_csv(args.input_file)
+    formatted_df = format_dataframe_errors(
+        df=df,
+        columns=args.column_specs,
+        length_control=args.length_control,
+        significant_figures=args.significant_figures,
+        abbreviate=args.abbreviate,
+        exponential=args.exponential,
+        latex=True,
+    )
+    formatted_df.to_latex(args.output_file, index=False, header=args.headings)
+
+
+def _float_or_pair(arg: str) -> float | tuple[float, float]:
+    """Takes a string containing either a float, or two floats separated by commas,
+    and returns them as either a float or a tuple of floats."""
+
+    split_arg = arg.split(",")
+    if len(split_arg) == 1:
+        return float(arg)
+    elif len(split_arg) == 2:
+        return tuple(map(float, split_arg))
+    else:
+        message = f"Can't parse {arg} as a number or pair of numbers."
+        raise ValueError(message)
+
+
+def _parse_columnspec(arg: str) -> str | ColumnSpec:
+    """Take a string containing a specification for columns,
+    and return a column name (if a single column is specified)
+    or a ColumnSpec (if multiple columns are specified)."""
+
+    split_arg = arg.split(",")
+    if len(split_arg) == 1:
+        return arg
+
+    if not isinstance(split_arg[0], str):
+        raise ValueError("First column has to be a single central value.")
+
+    error_columns = []
+    for error_spec in split_arg[1:]:
+        split_error = error_spec.split("-")
+        if len(split_error) == 1:
+            error_columns.append(error_spec)
+        else:
+            error_columns.append(tuple(split_error))
+
+    return ColumnSpec(split_arg[0], *error_columns)
+
+
+def get_args(override_args: list | None = None) -> Namespace:
+    """Parse command line."""
+    parser = ArgumentParser(prog="format_multiple_errors")
+    parser.add_argument(
+        "--abbreviate",
+        action="store_true",
+        help="Abbreviate the uncertainty - e.g. 1.23(4) instead of 1.23 ± 0.04",
+    )
+    parser.add_argument(
+        "--exponential", action="store_true", help="Use exponential notation"
+    )
+    parser.add_argument(
+        "--latex",
+        action="store_true",
+        help="Use LaTeX rather than plain text format - e.g. 1.23 \\pm 0.04 instead of 1.23 ± 0.04",
+    )
+    parser.add_argument(
+        "--significant_figures",
+        type=int,
+        default=2,
+        help="Number of significant figures to display (used in conjunction with --length_control)",
+    )
+    parser.add_argument(
+        "--length_control",
+        default="smallest",
+        choices=["smallest", "central"],
+        help="Value to control the significant figures of (`smallest` uncertainty or `central` value)",
+    )
+
+    subparsers = parser.add_subparsers(title="commands")
+
+    format_parser = subparsers.add_parser("format", help="Format a single number")
+    format_parser.add_argument("value", type=float, help="The central value")
+    format_parser.add_argument(
+        "errors",
+        type=_float_or_pair,
+        metavar="error",
+        nargs="+",
+        help="Uncertainties in the value. Asymmetric uncertainties are specified as upper,lower.",
+    )
+    format_parser.set_defaults(func=_format_numbers)
+
+    table_parser = subparsers.add_parser(
+        "table", help="Format a CSV file into a LaTeX table"
+    )
+    table_parser.add_argument(
+        "input_file", type=FileType("r"), default="-", help="The CSV file to read in"
+    )
+    table_parser.add_argument(
+        "--output_file",
+        type=FileType("w"),
+        default="-",
+        help="Where to place the output LaTeX",
+    )
+    table_parser.add_argument(
+        "column_specs",
+        type=_parse_columnspec,
+        metavar="column_spec",
+        nargs="+",
+        help="Specifications of columns to include in the table, in the form value_column[,error_column[-lower_error_column]][,error_column[-lower_error_column]][...]",
+    )
+    table_parser.add_argument(
+        "--headings",
+        nargs="+",
+        metavar="heading",
+        help="Column headings to use. By default, these are taken from the CSV. If supplied, the count must match the number of specified columns",
+    )
+    table_parser.set_defaults(func=_format_table)
+    return parser.parse_args(override_args)
+
+
+def cli(override_args: list | None = None) -> None:
+    """Run the CLI."""
+    args = get_args(override_args)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    cli()