[Introduction](#introduction) | [Install](#install-using-pip) |
[Default Usage](#default-usage) |
[Adjusting # of Significant Figures on Error](#adjusting-significant-figures-on-error)
| [Adjusting cutoffs for switch to scientific notation](#adjusting-the-cutoffs-for-switching-to-scientific-notation)
| [Render Latex in Jupyter](#render-latex-in-jupyter) |
[Get Rounded Numbers Instead of Strings](#get-rounded-numbers-for-the-value-and-error) |
[Comments and Bug Reporting](#issues-or-comments) | [Change Log](#change-log)
| [License](#this-software-is-distributed-under-the-gnu-v3-license)
# Round Using Error
## Introduction
This package provides opinionated tools for formatting the output of values
with known errors. The general format is `value +/- error`. The values are
rounded so that the last digit reported for the value is the same order of
magnitude as the least significant digit reported on the error. The default
is to report the error to two significant figures. The opinionated
part is that the output switches automatically from decimal to scientific
notation. Scientific notation is used for values < 0.1 and > 1000. Where the
switch occurs can be changed with optional parameters.
The output is available as:
* tuple of strings (value, error, power_of_ten);
* text in format `value +/- error`;
* latex in the form `value \pm error`.
* rounded floating point numbers (value, error)
## Usage
### Install using pip
`pip install -U round_using_error`.
### Default usage:
```
>>> from round_using_error import *
>>> rndwitherr(0.001234, 0.000241)
('1.23', '0.24', '-3')
>>> rndwitherr(1299.845, 0.124)
('1.29985', '0.00012', '3')
>>> text_rndwitherr(1299.845, 0.124)
'(1.29985 +/- 0.00012) X 10^3'
>>> latex_rndwitherr(1299.845, 0.124)
'(1.29985\\pm0.00012)\\times 10^{3}'
>>> rndwitherr(0.001234, 0.000241)
('1.23', '0.24', '-3')
>>> text_rndwitherr(0.001234, 0.000241)
'(1.23 +/- 0.24) X 10^-3'
>>> latex_rndwitherr(0.001234, 0.000241)
'(1.23\\pm0.24)\\times 10^{-3}'
>>> rndwitherr(0.1234, 0.024)
('0.123', '0.024', '')
>>> text_rndwitherr(0.1234, 0.024)
'0.123 +/- 0.024'
>>> latex_rndwitherr(0.1234, 0.024)
'0.123\\pm0.024'
```
### Adjusting significant figures on error
```
>>> from round_using_error import *
>>> latex_rndwitherr(0.1234, 0.024)
'0.123\\pm0.024'
>>> rndwitherr(0.001234, 0.000241, errdig = 1)
('1.2', '0.2', '-3')
>>> rndwitherr(0.001234, 0.000241, errdig = 3)
('1.234', '0.241', '-3')
>>> text_rndwitherr(0.001234, 0.000241, errdig = 3)
'(1.234 +/- 0.241) X 10^-3'
>>> latex_rndwitherr(0.001234, 0.000241, errdig = 3)
'(1.234\\pm0.241)\\times 10^{-3}'
```
### Adjusting the cutoffs for switching to scientific notation
```
>>> rndwitherr(1247.325, 1.23, errdig = 1, highmag = 3)
('1247', '1', '')
>>> rndwitherr(3.53e-2,2.24e-3, errdig = 1, lowmag = -2)
('0.035', '0.002', '')
```
### Render Latex in Jupyter
### Get Rounded Numbers for the Value and Error
It is possible to get floating point numbers rounded as done by this package
rather than string representations, using the function `numbers_rndwitherr()`.
However, because of the way floating point numbers are printed, they may not
display with proper significant figures (see below). Use the
functions described above that return strings to guarantee proper
significant figures.
```
>>> numbers_rndwitherr(0.002345,0.0072)
(0.002, 0.007)
>>> numbers_rndwitherr(2.345864,0.0072)
(2.3459, 0.0072)
>>> numbers_rndwitherr(2.345864e-3,0.0072e-2)
(0.002346, 7.2e-05)
>>> numbers_rndwitherr(83e-4, 0)
(0.0083, 0)
```
#### Specifying number of error digits
```
>>> numbers_rndwitherr(1247.325, 1.23, errdig = 3)
(1247.33, 1.23)
```
#### Default floating point display may not give proper significant figures.
Compare the output of `numbers_rndwitherr` and `rndwitherr`.
```
>>> numbers_rndwitherr(1247.325, 1.23, errdig = 1) # bad
(1247.0, 1.0)
>>> rndwitherr(1247.325, 1.23, errdig = 1, highmag = 3) # good
('1247', '1', '')
```
## Issues or Comments
Ideas, suggestions, bug reports and general comments are welcome . Please
use the github repository issues tracker:
[https://github.com/gutow/round_using_error/issues](https://github.com/gutow/round_using_error/issues).
## Change Log
* 1.2.0 Introduced `numbers_rndwitherr()` function. Readme.md and docs updates.
* 1.1.1 More doctests. Tweaked handling of errors larger than values.
* 1.1.0 Increased error checking. Now raises warning for negative error
values. Also fixes an error that occurred with negative values.
## [This software is distributed under the GNU V3 license](https://gnu.org/licenses)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Copyright - Jonathan Gutow, 2021, 2022.
Raw data
{
"_id": null,
"home_page": "https://github.com/gutow/round_using_error",
"name": "round-using-error",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Jonathan Gutow",
"author_email": "gutow@uwosh.edu",
"download_url": "https://files.pythonhosted.org/packages/3b/96/c9b6041d3db8d3c782448be006f338773035dff115cefab852c6d0be18b5/round_using_error-1.2.0.tar.gz",
"platform": null,
"description": "[Introduction](#introduction) | [Install](#install-using-pip) | \n[Default Usage](#default-usage) | \n[Adjusting # of Significant Figures on Error](#adjusting-significant-figures-on-error)\n | [Adjusting cutoffs for switch to scientific notation](#adjusting-the-cutoffs-for-switching-to-scientific-notation)\n| [Render Latex in Jupyter](#render-latex-in-jupyter) | \n[Get Rounded Numbers Instead of Strings](#get-rounded-numbers-for-the-value-and-error) | \n[Comments and Bug Reporting](#issues-or-comments) | [Change Log](#change-log)\n | [License](#this-software-is-distributed-under-the-gnu-v3-license)\n# Round Using Error\n## Introduction\nThis package provides opinionated tools for formatting the output of values \nwith known errors. The general format is `value +/- error`. The values are \nrounded so that the last digit reported for the value is the same order of \nmagnitude as the least significant digit reported on the error. The default \nis to report the error to two significant figures. The opinionated \npart is that the output switches automatically from decimal to scientific \nnotation. Scientific notation is used for values < 0.1 and > 1000. Where the\nswitch occurs can be changed with optional parameters.\n\nThe output is available as:\n* tuple of strings (value, error, power_of_ten);\n* text in format `value +/- error`;\n* latex in the form `value \\pm error`.\n* rounded floating point numbers (value, error)\n\n## Usage\n### Install using pip\n`pip install -U round_using_error`.\n### Default usage:\n```\n>>> from round_using_error import *\n>>> rndwitherr(0.001234, 0.000241)\n('1.23', '0.24', '-3')\n>>> rndwitherr(1299.845, 0.124)\n('1.29985', '0.00012', '3')\n>>> text_rndwitherr(1299.845, 0.124)\n'(1.29985 +/- 0.00012) X 10^3'\n>>> latex_rndwitherr(1299.845, 0.124)\n'(1.29985\\\\pm0.00012)\\\\times 10^{3}'\n>>> rndwitherr(0.001234, 0.000241)\n('1.23', '0.24', '-3')\n>>> text_rndwitherr(0.001234, 0.000241)\n'(1.23 +/- 0.24) X 10^-3'\n>>> latex_rndwitherr(0.001234, 0.000241)\n'(1.23\\\\pm0.24)\\\\times 10^{-3}'\n>>> rndwitherr(0.1234, 0.024)\n('0.123', '0.024', '')\n>>> text_rndwitherr(0.1234, 0.024)\n'0.123 +/- 0.024'\n>>> latex_rndwitherr(0.1234, 0.024)\n'0.123\\\\pm0.024'\n```\n### Adjusting significant figures on error\n```\n>>> from round_using_error import *\n>>> latex_rndwitherr(0.1234, 0.024)\n'0.123\\\\pm0.024'\n>>> rndwitherr(0.001234, 0.000241, errdig = 1)\n('1.2', '0.2', '-3')\n>>> rndwitherr(0.001234, 0.000241, errdig = 3)\n('1.234', '0.241', '-3')\n>>> text_rndwitherr(0.001234, 0.000241, errdig = 3)\n'(1.234 +/- 0.241) X 10^-3'\n>>> latex_rndwitherr(0.001234, 0.000241, errdig = 3)\n'(1.234\\\\pm0.241)\\\\times 10^{-3}'\n```\n### Adjusting the cutoffs for switching to scientific notation\n```\n>>> rndwitherr(1247.325, 1.23, errdig = 1, highmag = 3)\n('1247', '1', '')\n>>> rndwitherr(3.53e-2,2.24e-3, errdig = 1, lowmag = -2)\n('0.035', '0.002', '')\n```\n### Render Latex in Jupyter\n\n\n### Get Rounded Numbers for the Value and Error\nIt is possible to get floating point numbers rounded as done by this package\nrather than string representations, using the function `numbers_rndwitherr()`.\nHowever, because of the way floating point numbers are printed, they may not\ndisplay with proper significant figures (see below). Use the \nfunctions described above that return strings to guarantee proper\nsignificant figures.\n\n```\n>>> numbers_rndwitherr(0.002345,0.0072)\n(0.002, 0.007)\n>>> numbers_rndwitherr(2.345864,0.0072)\n(2.3459, 0.0072)\n>>> numbers_rndwitherr(2.345864e-3,0.0072e-2)\n(0.002346, 7.2e-05)\n>>> numbers_rndwitherr(83e-4, 0)\n(0.0083, 0)\n```\n#### Specifying number of error digits\n```\n>>> numbers_rndwitherr(1247.325, 1.23, errdig = 3)\n(1247.33, 1.23)\n```\n#### Default floating point display may not give proper significant figures.\nCompare the output of `numbers_rndwitherr` and `rndwitherr`.\n```\n>>> numbers_rndwitherr(1247.325, 1.23, errdig = 1) # bad\n(1247.0, 1.0)\n>>> rndwitherr(1247.325, 1.23, errdig = 1, highmag = 3) # good\n('1247', '1', '')\n```\n## Issues or Comments\nIdeas, suggestions, bug reports and general comments are welcome . Please\nuse the github repository issues tracker:\n[https://github.com/gutow/round_using_error/issues](https://github.com/gutow/round_using_error/issues).\n\n## Change Log\n* 1.2.0 Introduced `numbers_rndwitherr()` function. Readme.md and docs updates.\n* 1.1.1 More doctests. Tweaked handling of errors larger than values.\n* 1.1.0 Increased error checking. Now raises warning for negative error \n values. Also fixes an error that occurred with negative values.\n\n## [This software is distributed under the GNU V3 license](https://gnu.org/licenses)\nThis program is free software: you can redistribute it and/or modify\n it under the terms of the GNU General Public License as published by\n the Free Software Foundation, either version 3 of the License, or\n (at your option) any later version.\n This program is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU General Public License for more details.\n\nCopyright - Jonathan Gutow, 2021, 2022.\n",
"bugtrack_url": null,
"license": "GPL-3.0+",
"summary": "Output numbers +/- error with appropriate rounding.",
"version": "1.2.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "6bda76b3f3f4f7edfbe23c23a29e9a34",
"sha256": "ed66aa49a8b191730ff6099b676800efe4bb858724bbbec838418c50fc677492"
},
"downloads": -1,
"filename": "round_using_error-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6bda76b3f3f4f7edfbe23c23a29e9a34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18820,
"upload_time": "2022-12-13T21:55:55",
"upload_time_iso_8601": "2022-12-13T21:55:55.636863Z",
"url": "https://files.pythonhosted.org/packages/4c/9e/4388decafdb784c256c34618447fc8bdf64f0c81fd4155a80a3f26ba4e73/round_using_error-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "d35ec7096bf9b8cb14ccf79fc7a7f31b",
"sha256": "635f81b18889935c30efde3c623dcca8f4a0cd2d5f2f9161b0cbd2d9139ece4d"
},
"downloads": -1,
"filename": "round_using_error-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d35ec7096bf9b8cb14ccf79fc7a7f31b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18097,
"upload_time": "2022-12-13T21:55:57",
"upload_time_iso_8601": "2022-12-13T21:55:57.383407Z",
"url": "https://files.pythonhosted.org/packages/3b/96/c9b6041d3db8d3c782448be006f338773035dff115cefab852c6d0be18b5/round_using_error-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-13 21:55:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "gutow",
"github_project": "round_using_error",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "round-using-error"
}
JSON
