format-multiple-errors 0.0.2__py3-none-any.whl

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/__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()

format_multiple_errors/formatter.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+
+"""Implementation of multiple error formatting."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence, Set
+
+# It would be nice to vectorise this with numpy, but that needs more clever thinking.
+import math
+
+from typing import Callable, TypeVar
+
+from .typing import Value, Error, Errors
+
+
+def format_multiple_errors(
+    value: Value,
+    *errors: Error,
+    length_control: str = "smallest",
+    significant_figures: int = 2,
+    abbreviate: bool = False,
+    exponential: bool = False,
+    latex: bool = False,
+) -> str:  # pylint: disable=r0913
+    """Formats the value and errors consistently.
+
+    Parameters:
+
+    value:
+        The central value to format.
+        If a number with error (pyerrors.Obs or uncertainties.UFloat),
+        then the nominal value is taken and the uncertainty is prepended to `errors`.
+
+    *errors:
+        The uncertainties to format.
+        Each should be a single number (symmetric), or a tuple of two numbers (upper, lower).
+
+    length_control (default: "smallest"):
+        The variable to use for controlling the length of the printed number.
+        Options:
+            "smallest": The smallest uncertainty is printed
+                        with `significant_figures` significant figures.
+            "central": The central `value` is printed
+                       with `significant_figures` significant figures.
+
+    significant_figures (default: 2):
+        The number of significant figures to format.
+        Other values printed may have more significant figures, but will not have fewer.
+
+    abbreviate (default: False):
+        Abbreviate the uncertainties with bracketed notation.
+        (I.e. 1.234(56) instead of 1.234 +/- 0.056.)
+
+    exponential (default: False):
+        Use standard form (e.g. 1.2 × 10^{-3}) rather than leading/trailing zeroes (0.0012).
+
+    latex (default: False):
+        Format the numbers in LaTeX form rather than plain text.
+    """
+
+    normalised_value, normalised_errors = _normalize_integrated_errors(
+        value, list(errors)
+    )
+    exponent = 0
+    if exponential:
+        normalised_value, normalised_errors, exponent = _normalize(
+            normalised_value, normalised_errors
+        )
+
+    length_value = _get_length_value(
+        normalised_value, normalised_errors, length_control
+    )
+    first_digit_index, decimal_places = _get_rounding_indices(
+        length_value, significant_figures
+    )
+
+    if _decimals_required(first_digit_index, significant_figures, exponential):
+        formatted_numbers = [f"{normalised_value:.0{decimal_places}f}"] + list(
+            _format_errors_only(normalised_errors, decimal_places, abbreviate)
+        )
+    else:
+        formatted_numbers = _map_recursive(
+            lambda v: str(int(round(v, decimal_places))),
+            [normalised_value] + list(normalised_errors),
+        )
+
+    return _join_numbers(
+        formatted_numbers, exponent=exponent, abbreviate=abbreviate, latex=latex
+    )
+
+
+def _normalize_integrated_errors(
+    value: Value, errors: list[Error]
+) -> tuple[float, Errors]:
+    """Take any errors already included in `value` and prepends them to `errors`.
+
+    Parameters:
+
+    value:
+        A central value that may have an associated uncertainty.
+
+    errors:
+        A list of other uncertainties.
+
+    Returns:
+        A tuple containing the central value, and a combined list of errors.
+    """
+
+    if hasattr(value, "nominal_value") and hasattr(value, "std_dev"):
+        errors = [value.std_dev] + errors
+        value = value.nominal_value
+    elif hasattr(value, "value") and hasattr(value, "dvalue"):
+        if value.dvalue == 0.0:
+            raise ValueError(
+                "pyerrors will not give an error before calling .gamma_method()"
+            )
+        errors = [value.dvalue] + errors
+        value = value.value
+
+    return value, errors
+
+
+def _normalize(value: Value, errors: Errors) -> tuple[float, Errors, int]:
+    """
+    Divides `value` and all elements of `errors` by a common power of 10
+    such that `value` is in [1, 10).
+
+    Arguments:
+
+        value: a central value
+
+        errors: a list of errors, either numbers or tuples of two numbers
+
+    Returns:
+
+        value: the normalized central value
+
+        errors: the normalized errors
+
+        exponent: the power of 10 by which the values have been multiplied
+    """
+
+    if value == 0:
+        exponent = _first_digit(max(_flatten_errors(errors)))
+    else:
+        exponent = _first_digit(value)
+
+    return (
+        value / 10**exponent,
+        _map_recursive(lambda error: error / 10**exponent, errors),
+        exponent,
+    )
+
+
+RecursiveMappable = TypeVar("RecursiveMappable", list, tuple)
+
+
+def _map_recursive(func: Callable, data: RecursiveMappable) -> RecursiveMappable:
+    """
+    Map a function `f` across elements in some non-uniform nested structure of iterables.
+    """
+    to_return = []
+    for datum in data:
+        # Ideally this would be done with isinstance(datum, InstantiableSequence)
+        # where InstantiableSequence is like Sequence, but can be instantiated from
+        # elements as is done below. I haven't got that to work with mypy however.
+        if isinstance(datum, list):
+            to_return.append(_map_recursive(func, datum))
+        elif isinstance(datum, tuple):
+            to_return.append(list(_map_recursive(func, datum)))
+        else:
+            to_return.append(func(datum))
+
+    return type(data)(to_return)
+
+
+def _first_digit(value: float) -> int:
+    """
+    Return the first digit position of the given value, as an integer.
+    0 is the digit just before the decimal point. Digits to the right
+    of the decimal point have a negative position.
+    Return 0 for a null value.
+    """
+    if value == 0:
+        return 0
+
+    return int(math.floor(math.log10(abs(value))))
+
+
+def _get_length_value(value: float, errors: Errors, length_control: str) -> float:
+    """
+    Get the value that will be controlling the length,
+    from either the central `value` or the list of `errors`.
+    """
+
+    if length_control == "central":
+        return value
+    if length_control == "smallest":
+        length = _get_smallest(errors)
+        if length is None:
+            return value
+
+        return length
+
+    raise ValueError(
+        f"{length_control} is not a value option for length_control."
+        '(Available options are "smallest", "central".)'
+    )
+
+
+def _get_smallest(errors: Errors) -> float | None:
+    """Given a list of errors (number or tuples of two numbers),
+    find the smallest number."""
+    flat_errors = _flatten_errors(errors, exclude=[0, 0.0])
+    if not flat_errors:
+        return None
+
+    return min(flat_errors)
+
+
+def _flatten_errors(errors: Errors, exclude: Set | Sequence = frozenset()) -> list:
+    """Given a list of errors (number or tuples of two numbers),
+    flatten it to a list of numbers."""
+
+    flat_errors = []
+    for error in errors:
+        try:
+            for value in error:  # type: ignore[union-attr]
+                if value not in exclude:
+                    flat_errors.append(value)
+        except (TypeError, ValueError):
+            if error not in exclude:
+                flat_errors.append(error)
+
+    return flat_errors
+
+
+def _get_rounding_indices(
+    length_value: float, significant_figures: int
+) -> tuple[int, int]:
+    """
+    Get the index of the first digit of length_value,
+    and from it the number of decimal places corresponding to the
+    given value of significant_figures.
+    """
+
+    # Repeat, as the first pass will break
+    # if the rounding changes the number of significant figures
+    for _ in range(2):
+        first_digit_index = _first_digit(length_value)
+        decimal_places = significant_figures - first_digit_index - 1
+        length_value = round(length_value, decimal_places)
+
+    return first_digit_index, decimal_places
+
+
+def _decimals_required(
+    first_digit_index: int, significant_figures: int, exponential: bool
+) -> bool:
+    """
+    Determine whether a decimal point is needed to represent a number to a particular precision.
+    """
+    return first_digit_index + 1 < significant_figures or exponential
+
+
+def _format_errors_only(
+    errors: Errors, decimal_places: int, abbreviate: bool
+) -> list[str]:
+    """
+    Return a list of `errors` formatted to the specified number of `decimal_places`.
+    If `abbreviate` is specified, format only the portion of the number needed
+    to express the error.
+    """
+    formatters = {True: _abbreviated_single_error, False: _unabbreviated_single_error}
+
+    return _map_recursive(
+        lambda error: formatters[abbreviate](error, decimal_places), errors
+    )
+
+
+def _abbreviated_single_error(error: float, decimal_places: int) -> str:
+    """
+    Take a single `error` and return its correct abbreviation
+    to the given number of `decimal_places`.
+    """
+    if error >= 1:
+        return f"{error:.0{decimal_places}f}"
+
+    return str(int(round(error * 10**decimal_places)))
+
+
+def _unabbreviated_single_error(error: float, decimal_places: int) -> str:
+    """
+    Take a single `error` and return its correct unabbreviated format
+    to the given number of `decimal_places`.
+    """
+
+    rounded_error = round(error, decimal_places)
+    if rounded_error == 0:
+        if decimal_places > 0:
+            return "0.0"
+
+        return "0"
+
+    return f"{rounded_error:.0{decimal_places}f}"
+
+
+def _join_numbers(
+    formatted_numbers: list[str], abbreviate: bool, latex: bool, exponent: int = 0
+) -> str:
+    """Take a list of `formatted_numbers`, and join them to form a full formatted string."""
+
+    # Dict indexed by the tuple (abbreviate, latex, [is single-component])
+    formatters = {
+        (True, True, True): "({error})",
+        (True, True, False): "({{}}^{{{error[0]}}}_{{{error[1]}}})",
+        (True, False, True): "({error})",
+        (True, False, False): "(+{error[0]}/-{error[1]})",
+        (False, True, True): " \\pm {error}",
+        (False, True, False): " {{}}^{{+{error[0]}}}_{{-{error[1]}}}",
+        (False, False, True): " ± {error}",
+        (False, False, False): " (+{error[0]} / -{error[1]})",
+    }
+
+    elements = list(formatted_numbers[:1])
+    for error in formatted_numbers[1:]:
+        elements.append(
+            formatters[abbreviate, latex, isinstance(error, str)].format(error=error)
+        )
+
+    if exponent:
+        if not abbreviate:
+            # Errors and central value must be grouped together
+            # so the exponent applies to all
+            elements = ["("] + elements + [")"]
+        if latex:
+            elements.append(f" \\times 10^{{{exponent}}}")
+        else:
+            elements.append(f"e{exponent}")
+
+    return "".join(elements)

format_multiple_errors/pandas.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+
+"""Functions to assist with formatting errors in Pandas DataFrames."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import cast
+import warnings
+
+try:
+    import pandas as pd
+except ImportError:
+    warnings.warn("Unable to import Pandas.", RuntimeWarning)
+
+from .formatter import format_multiple_errors
+
+
+def _format_column(value: pd.Series, *errors: pd.Series, **fme_kwargs) -> pd.Series:
+    """Formats the values and errors in a list of columns consistently.
+
+    Parameters:
+
+    value:
+        A Pandas Series containing the central value to format.
+        If a number with error (pyerrors.Obs or uncertainties.UFloat),
+        then the nominal value is taken and the uncertainty is prepended to `errors`.
+
+    *errors:
+        A Pandas Series containing the uncertainties to format.
+        Columns should contain a single number (symmetric),
+        or a tuple of two numbers (upper, lower);
+        a tuple of two columns may also be used to specify (upper, lower).
+
+    **fme_kwargs:
+        Optional keyword arguments passed to `format_multiple_errors`
+        and documented therein.
+    """
+    errors_flattened = []
+    for error in errors:
+        if isinstance(error, tuple):
+            errors_flattened.append(_tuplify(error))
+        else:
+            errors_flattened.append(error)
+
+    df = pd.concat([value] + errors_flattened, axis=1)
+    index = []
+    formatted_errors = []
+    for single_index, single_value, *single_errors in df.itertuples():
+        index.append(single_index)
+        number = format_multiple_errors(single_value, *single_errors, **fme_kwargs)
+        if fme_kwargs.get("latex"):
+            formatted_errors.append(f"${number}$")
+        else:
+            formatted_errors.append(number)
+
+    return pd.Series(data=formatted_errors, index=index)
+
+
+def _tuplify(columns: list[pd.Series]) -> pd.Series:
+    """
+    Turn columns into one column of tuples.
+    Given a list of Pandas Series, returns a single Series
+    containing the elements of each input series as a tuple.
+
+    Parameters:
+
+    columns:
+        A list of Pandas Series objects.
+    """
+    df = pd.concat(columns, axis=1)
+    index = []
+    values = []
+    for row in df.itertuples():
+        index.append(row[0])
+        values.append(tuple(row[1:]))
+    return pd.Series(data=values, index=index)
+
+
+def format_column_errors(
+    value: str | pd.Series,
+    *errors: str | pd.Series,
+    df: pd.DataFrame | None = None,
+    **fme_kwargs,
+):
+    """Formats the values and errors in a DataFrame consistently.
+
+    Parameters:
+
+    value:
+        The column containing the central value to format.
+        This may be a Pandas Series object, or if `df` is specified,
+        then it may be the name of a column.
+        If a number with error (pyerrors.Obs or uncertainties.UFloat),
+        then the nominal value is taken and the uncertainty is prepended to `errors`.
+
+    *errors:
+        The columns containing the uncertainties to format.
+        This may be a Pandas Series object, or if `df` is specified,
+        then they may be the names of a columns,
+        consistently with the argument to `values`.
+        Columns should contain a single number (symmetric),
+        or a tuple of two numbers (upper, lower);
+        a tuple of two columns may also be used to specify (upper, lower).
+
+    **fme_kwargs:
+        Optional keyword arguments passed to `format_multiple_errors`
+        and documented therein.
+    """
+
+    if df is None:
+        value = cast(pd.Series, value)
+        errors = cast(tuple[pd.Series], errors)
+        return _format_column(value, *errors, **fme_kwargs)
+
+    if not isinstance(value, str):
+        message = (
+            "If `df` is specified, then `value` must be a column name, "
+            f"not {type(value)}."
+        )
+        raise TypeError(message)
+    error_series = []
+    for error_idx, error in enumerate(errors):
+        if isinstance(error, str):
+            error_series.append(df[error])
+        elif isinstance(error, tuple):
+            error_series.append(_tuplify([df[element] for element in error]))
+        else:
+            message = (
+                f"Invalid error at index {error_idx}. "
+                "If `df` is specified, then each element of `errors` must be "
+                f"a column name or tuple of column names, not {type(error)}."
+            )
+            raise TypeError(message)
+
+    return _format_column(df[value], *error_series, **fme_kwargs)
+
+
+@dataclass
+class ColumnSpec:
+    """
+    Specification of columns to include in calls to `format_dataframe_errors()`
+    """
+
+    def __init__(self, value: str, *errors: str, name: str | None = None, **fme_kwargs):
+        """
+        Specify a set of columns to turn into a single column containing formatted
+        values and uncertainties.
+
+        Arguments:
+
+        value:
+            The name of the column to use as the central value.
+            If the column contains numbers with errors
+            (pyerrors.Obs or uncertainties.UFloat), then the
+            nominal value is taken and the uncertainty is prepended to `errors`.
+
+        errors:
+            Names of columns to use as symmetric uncertainties,
+            and/or tuples of pairs of columns to use as upper and lower uncertainties.
+
+        name:
+            The name to give the resulting series.
+            If not specified, the `value` argument will be used.
+
+        **fme_kwargs:
+            Arguments for formatting the uncertainties,
+            to be passed to `format_multiple_errors()`.
+        """
+        self.value = value
+        self.errors = errors
+        self.fme_kwargs = fme_kwargs
+        if name is not None:
+            self.name = name
+        else:
+            self.name = value
+
+
+def format_dataframe_errors(
+    df: pd.DataFrame, columns: list[str], **fme_kwargs
+) -> pd.DataFrame:
+    """
+    Formats groups of columns in a DataFrame into strings with errors.
+
+    Parameters:
+
+    df:
+        The Pandas DataFrame to take data from.
+
+    columns:
+        A list of column specifications, either `str`, `tuple`, `list`, or `ColumnSpec`.
+        Strings will be interpreted as columns to take with no modification.
+
+        For tuples and lists,
+        the first element is the name of the column containing the central value,
+        and the subsequent elements the names of the columns containing the uncertainties
+        (or tuples of column names for upper and lower uncertainties).
+        The name of the value column will be used as the name of the formatted column.
+
+    **fme_kwargs:
+        Default arguments for formatting the errors.
+        If columns are specified using ColumnSpec instances,
+        then any arguments set therein will take priority over those specified here.
+    """
+    content = []
+    for column_index, column in enumerate(columns):
+        if isinstance(column, str):
+            content.append(df[column])
+            continue
+
+        if isinstance(column, (tuple, list)):
+            column = ColumnSpec(column[0], *column[1:])
+
+        if not isinstance(column, ColumnSpec):
+            message = (
+                "Each column must be a str, tuple, list, or ColumnSpec, "
+                f"not {type(column)} as found at index {column_index}."
+            )
+            raise TypeError(message)
+
+        new_column = format_column_errors(
+            column.value, *column.errors, df=df, **{**fme_kwargs, **column.fme_kwargs}
+        )
+        new_column.name = column.name
+        content.append(new_column)
+
+    return pd.concat(content, axis=1)

format_multiple_errors/typing.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+
+from typing import Union, TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pyerrors import Obs  # type: ignore[import-untyped]
+    from uncertainties import UFloat  # type: ignore[import-untyped]
+
+    Value = Union[float, Obs, UFloat]
+else:
+    Value = float
+
+
+Error = Union[float, tuple[float, float]]
+Errors = list[Error]

format_multiple_errors-0.0.2.dist-info/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+format_multiple_errors/__init__.py,sha256=ZLtmZ1Pe3zyxnic-b4nhtuajNj8llWykspVPpFaN7Rc,460
+format_multiple_errors/__main__.py,sha256=tV8VPGPwq2d3CWJp9hFSDDMyHHL3uY2jvipxeoH_dGY,5825
+format_multiple_errors/formatter.py,sha256=GnfJjP4HbYXxTq-Yx1E8DhbviPqRj0t3_icPTYgQ2P0,10744
+format_multiple_errors/pandas.py,sha256=qoK_UvXIErJJdWKfJRyOvtMNeR6JHaUv_QUlTZjnCHg,7605
+format_multiple_errors/typing.py,sha256=k0p3GDaHGXHd3zmBtNg0-cvcMzEupzN4RHaLdNvxX6U,342
+format_multiple_errors-0.0.2.dist-info/LICENSE,sha256=G3SZheaYJW8JV0Njnnyfi7QwUJWh9evcPRQ-nAXi8Ro,1086
+format_multiple_errors-0.0.2.dist-info/METADATA,sha256=1vJY4LlcZhCuxYANbRIGpUxs8coFFgecUKof8zuk6t4,6334
+format_multiple_errors-0.0.2.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+format_multiple_errors-0.0.2.dist-info/entry_points.txt,sha256=PeHYlzbvQciSJX3DWuM-Y5Xwi9Is0jO-LlUgdSkUTp4,79
+format_multiple_errors-0.0.2.dist-info/top_level.txt,sha256=I_xD5oYbrw0qjNhbzAlj_sqNhLrkoJsTE_ozCqnlaZc,23
+format_multiple_errors-0.0.2.dist-info/RECORD,,

format_multiple_errors-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

format_multiple_errors-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+format_multiple_errors = format_multiple_errors.__main__:cli

format_multiple_errors-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+format_multiple_errors