(Further) clarify documentation for display.precision

[dmolesUC]

The generated "stable" docs for pandas.set_option() (as well as the Travis docs as of this writing) describe display.precision as:

Floating point output precision (number of significant digits)

However, the “Options and Settings“ docs for describe display.precision as

Floating point output precision in terms of number of places after the decimal

The second description appears to be more accurate (as well as newer; compare for instance the still-Google-popular 0.15 docs).

Code Sample

import pandas as pd
df = pd.DataFrame([[1234.0, 123.4, 12.34, 1.234, .1234, .01234, .001234]])
df
#         0      1      2      3       4        5         6
# 0  1234.0  123.4  12.34  1.234  0.1234  0.01234  0.001234
pd.options.display.precision = 1
df
#         0      1     2    3    4        5        6
# 0  1234.0  123.4  12.3  1.2  0.1  1.2e-02  1.2e-03

Expected Output

The output above clearly isn't significant digits, which (using numpy's format_float_positional()) would look something more like:

import numpy as np
df.applymap(lambda x: np.format_float_positional(x, 1, fractional=False).rstrip('.'))
#       0    1   2  3    4     5      6
# 0  1000  100  10  1  0.1  0.01  0.001

Problem description

The generated documentation for set_option() is inconsistent with the (hand-written?) “Options and Settings” doc. It’s not obvious which is correct until either you try it yourself, or dig through enough old docs to realize the “Options and Settings” doc has been more recently updated.

That said, "Number of places after the decimal" is also somewhat unclear, as it's not obvious why 1234.0 is 1234.0 rather than 1.2e+03, or why 123.4 isn't 1.2e+02. From experimentation, it looks like pandas decides this based on the entire series, rather than the individual value, so that if I transpose the frame, I do get a consistent one digit after the decimal point:

df.transpose()
#          0
# 0  1.2e+03
# 1  1.2e+02
# 2  1.2e+01
# 3  1.2e+00
# 4  1.2e-01
# 5  1.2e-02
# 6  1.2e-03

I'm sure this is documented somewhere, but it's not all that intuitive, and it would be nice if that document was linked from both the set_option() and “Options and Settings” docs for display.precision.

(Also, it would be nice if pandas had a display option for significant digits. :) )

Output of pd.show_versions()

[paste the output of pd.show_versions() here below this line]
INSTALLED VERSIONS

commit: None
python: 3.6.5.final.0
python-bits: 64
OS: Darwin
OS-release: 17.5.0
machine: x86_64
processor: i386
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: en_US.UTF-8

pandas: 0.22.0
pytest: None
pip: 10.0.1
setuptools: 39.1.0
Cython: None
numpy: 1.14.3
scipy: 1.0.1
pyarrow: None
xarray: None
IPython: 6.3.1
sphinx: None
patsy: None
dateutil: 2.7.2
pytz: 2018.4
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: 2.2.2
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: 1.0.1
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: 2.10
s3fs: None
fastparquet: None
pandas_gbq: None
pandas_datareader: None

[WillAyd]

Thanks for the callout - PRs to improve documentation are always welcome!

[hongshaoyang]

take