diff --git a/doc/source/_static/option_unicode01.png b/doc/source/_static/option_unicode01.png deleted file mode 100644 index d7168de126c5b..0000000000000 Binary files a/doc/source/_static/option_unicode01.png and /dev/null differ diff --git a/doc/source/_static/option_unicode02.png b/doc/source/_static/option_unicode02.png deleted file mode 100644 index 89e81e4f5f0ed..0000000000000 Binary files a/doc/source/_static/option_unicode02.png and /dev/null differ diff --git a/doc/source/_static/option_unicode03.png b/doc/source/_static/option_unicode03.png deleted file mode 100644 index 0b4ee876e17fe..0000000000000 Binary files a/doc/source/_static/option_unicode03.png and /dev/null differ diff --git a/doc/source/_static/option_unicode04.png b/doc/source/_static/option_unicode04.png deleted file mode 100644 index 1b839a44422b3..0000000000000 Binary files a/doc/source/_static/option_unicode04.png and /dev/null differ diff --git a/doc/source/user_guide/options.rst b/doc/source/user_guide/options.rst index f6e98b68afdc9..c7f5d3ddf66d3 100644 --- a/doc/source/user_guide/options.rst +++ b/doc/source/user_guide/options.rst @@ -8,8 +8,8 @@ Options and settings Overview -------- -pandas has an options system that lets you customize some aspects of its behaviour, -display-related options being those the user is most likely to adjust. +pandas has an options API configure and customize global behavior related to +:class:`DataFrame` display, data behavior and more. Options have a full "dotted-style", case-insensitive name (e.g. ``display.max_rows``). You can get/set options directly as attributes of the top-level ``options`` attribute: @@ -31,10 +31,12 @@ namespace: * :func:`~pandas.option_context` - execute a codeblock with a set of options that revert to prior settings after execution. -**Note:** Developers can check out `pandas/core/config_init.py `_ for more information. +.. note:: + + Developers can check out `pandas/core/config_init.py `_ for more information. All of the functions above accept a regexp pattern (``re.search`` style) as an argument, -and so passing in a substring will work - as long as it is unambiguous: +to match an unambiguous substring: .. ipython:: python @@ -51,17 +53,13 @@ The following will **not work** because it matches multiple option names, e.g. .. ipython:: python :okexcept: - try: - pd.get_option("max") - except KeyError as e: - print(e) + pd.get_option("max") -**Note:** Using this form of shorthand may cause your code to break if new options with similar names are added in future versions. +.. warning:: + Using this form of shorthand may cause your code to break if new options with similar names are added in future versions. -You can get a list of available options and their descriptions with ``describe_option``. When called -with no argument ``describe_option`` will print out the descriptions for all available options. .. ipython:: python :suppress: @@ -69,6 +67,18 @@ with no argument ``describe_option`` will print out the descriptions for all ava pd.reset_option("all") +.. _options.available: + +Available options +----------------- + +You can get a list of available options and their descriptions with :func:`~pandas.describe_option`. When called +with no argument :func:`~pandas.describe_option` will print out the descriptions for all available options. + +.. ipython:: python + + pd.describe_option() + Getting and setting options --------------------------- @@ -82,9 +92,11 @@ are available from the pandas namespace. To change an option, call pd.set_option("mode.sim_interactive", True) pd.get_option("mode.sim_interactive") -**Note:** The option 'mode.sim_interactive' is mostly used for debugging purposes. +.. note:: + + The option ``'mode.sim_interactive'`` is mostly used for debugging purposes. -All options also have a default value, and you can use ``reset_option`` to do just that: +You can use :func:`~pandas.reset_option` to revert to a setting's default value .. ipython:: python :suppress: @@ -108,7 +120,7 @@ It's also possible to reset multiple options at once (using a regex): pd.reset_option("^display") -``option_context`` context manager has been exposed through +:func:`~pandas.option_context` context manager has been exposed through the top-level API, allowing you to execute code with given option values. Option values are restored automatically when you exit the ``with`` block: @@ -124,7 +136,9 @@ are restored automatically when you exit the ``with`` block: Setting startup options in Python/IPython environment ----------------------------------------------------- -Using startup scripts for the Python/IPython environment to import pandas and set options makes working with pandas more efficient. To do this, create a .py or .ipy script in the startup directory of the desired profile. An example where the startup folder is in a default IPython profile can be found at: +Using startup scripts for the Python/IPython environment to import pandas and set options makes working with pandas more efficient. +To do this, create a ``.py`` or ``.ipy`` script in the startup directory of the desired profile. +An example where the startup folder is in a default IPython profile can be found at: .. code-block:: none @@ -144,10 +158,10 @@ More information can be found in the `IPython documentation Frequently used options ----------------------- -The following is a walk-through of the more frequently used display options. +The following is a demonstrates the more frequently used display options. ``display.max_rows`` and ``display.max_columns`` sets the maximum number -of rows and columns displayed when a frame is pretty-printed. Truncated +of rows and columns displayed when a frame is pretty-printed. Truncated lines are replaced by an ellipsis. .. ipython:: python @@ -175,8 +189,8 @@ determines how many rows are shown in the truncated repr. pd.reset_option("display.max_rows") pd.reset_option("display.min_rows") -``display.expand_frame_repr`` allows for the representation of -dataframes to stretch across pages, wrapped over the full column vs row-wise. +``display.expand_frame_repr`` allows for the representation of a +:class:`DataFrame` to stretch across pages, wrapped over the all the columns. .. ipython:: python @@ -187,8 +201,8 @@ dataframes to stretch across pages, wrapped over the full column vs row-wise. df pd.reset_option("expand_frame_repr") -``display.large_repr`` lets you select whether to display dataframes that exceed -``max_columns`` or ``max_rows`` as a truncated frame, or as a summary. +``display.large_repr`` displays a :class:`DataFrame` that exceed +``max_columns`` or ``max_rows`` as a truncated frame or summary. .. ipython:: python @@ -220,8 +234,8 @@ of this length or longer will be truncated with an ellipsis. df pd.reset_option("max_colwidth") -``display.max_info_columns`` sets a threshold for when by-column info -will be given. +``display.max_info_columns`` sets a threshold for the number of columns +displayed when calling :meth:`~pandas.DataFrame.info`. .. ipython:: python @@ -232,10 +246,10 @@ will be given. df.info() pd.reset_option("max_info_columns") -``display.max_info_rows``: ``df.info()`` will usually show null-counts for each column. -For large frames this can be quite slow. ``max_info_rows`` and ``max_info_cols`` -limit this null check only to frames with smaller dimensions then specified. Note that you -can specify the option ``df.info(null_counts=True)`` to override on showing a particular frame. +``display.max_info_rows``: :meth:`~pandas.DataFrame.info` will usually show null-counts for each column. +For a large :class:`DataFrame`, this can be quite slow. ``max_info_rows`` and ``max_info_cols`` +limit this null check to the specified rows and columns respectively. The :meth:`~pandas.DataFrame.info` +keyword argument ``null_counts=True`` will override this. .. ipython:: python @@ -248,7 +262,6 @@ can specify the option ``df.info(null_counts=True)`` to override on showing a pa pd.reset_option("max_info_rows") ``display.precision`` sets the output display precision in terms of decimal places. -This is only a suggestion. .. ipython:: python @@ -258,8 +271,8 @@ This is only a suggestion. pd.set_option("display.precision", 4) df -``display.chop_threshold`` sets at what level pandas rounds to zero when -it displays a Series of DataFrame. This setting does not change the +``display.chop_threshold`` sets the rounding threshold to zero when displaying a +:class:`Series` or :class:`DataFrame`. This setting does not change the precision at which the number is stored. .. ipython:: python @@ -272,7 +285,7 @@ precision at which the number is stored. pd.reset_option("chop_threshold") ``display.colheader_justify`` controls the justification of the headers. -The options are 'right', and 'left'. +The options are ``'right'``, and ``'left'``. .. ipython:: python @@ -288,238 +301,6 @@ The options are 'right', and 'left'. pd.reset_option("colheader_justify") - -.. _options.available: - -Available options ------------------ - -======================================= ============ ================================== -Option Default Function -======================================= ============ ================================== -display.chop_threshold None If set to a float value, all float - values smaller then the given - threshold will be displayed as - exactly 0 by repr and friends. -display.colheader_justify right Controls the justification of - column headers. used by DataFrameFormatter. -display.column_space 12 No description available. -display.date_dayfirst False When True, prints and parses dates - with the day first, eg 20/01/2005 -display.date_yearfirst False When True, prints and parses dates - with the year first, eg 2005/01/20 -display.encoding UTF-8 Defaults to the detected encoding - of the console. Specifies the encoding - to be used for strings returned by - to_string, these are generally strings - meant to be displayed on the console. -display.expand_frame_repr True Whether to print out the full DataFrame - repr for wide DataFrames across - multiple lines, ``max_columns`` is - still respected, but the output will - wrap-around across multiple "pages" - if its width exceeds ``display.width``. -display.float_format None The callable should accept a floating - point number and return a string with - the desired format of the number. - This is used in some places like - SeriesFormatter. - See core.format.EngFormatter for an example. -display.large_repr truncate For DataFrames exceeding max_rows/max_cols, - the repr (and HTML repr) can show - a truncated table (the default), - or switch to the view from df.info() - (the behaviour in earlier versions of pandas). - allowable settings, ['truncate', 'info'] -display.latex.repr False Whether to produce a latex DataFrame - representation for Jupyter frontends - that support it. -display.latex.escape True Escapes special characters in DataFrames, when - using the to_latex method. -display.latex.longtable False Specifies if the to_latex method of a DataFrame - uses the longtable format. -display.latex.multicolumn True Combines columns when using a MultiIndex -display.latex.multicolumn_format 'l' Alignment of multicolumn labels -display.latex.multirow False Combines rows when using a MultiIndex. - Centered instead of top-aligned, - separated by clines. -display.max_columns 0 or 20 max_rows and max_columns are used - in __repr__() methods to decide if - to_string() or info() is used to - render an object to a string. In - case Python/IPython is running in - a terminal this is set to 0 by default and - pandas will correctly auto-detect - the width of the terminal and switch to - a smaller format in case all columns - would not fit vertically. The IPython - notebook, IPython qtconsole, or IDLE - do not run in a terminal and hence - it is not possible to do correct - auto-detection, in which case the default - is set to 20. 'None' value means unlimited. -display.max_colwidth 50 The maximum width in characters of - a column in the repr of a pandas - data structure. When the column overflows, - a "..." placeholder is embedded in - the output. 'None' value means unlimited. -display.max_info_columns 100 max_info_columns is used in DataFrame.info - method to decide if per column information - will be printed. -display.max_info_rows 1690785 df.info() will usually show null-counts - for each column. For large frames - this can be quite slow. max_info_rows - and max_info_cols limit this null - check only to frames with smaller - dimensions then specified. -display.max_rows 60 This sets the maximum number of rows - pandas should output when printing - out various output. For example, - this value determines whether the - repr() for a dataframe prints out - fully or just a truncated or summary repr. - 'None' value means unlimited. -display.min_rows 10 The numbers of rows to show in a truncated - repr (when ``max_rows`` is exceeded). Ignored - when ``max_rows`` is set to None or 0. When set - to None, follows the value of ``max_rows``. -display.max_seq_items 100 when pretty-printing a long sequence, - no more then ``max_seq_items`` will - be printed. If items are omitted, - they will be denoted by the addition - of "..." to the resulting string. - If set to None, the number of items - to be printed is unlimited. -display.memory_usage True This specifies if the memory usage of - a DataFrame should be displayed when the - df.info() method is invoked. -display.multi_sparse True "Sparsify" MultiIndex display (don't - display repeated elements in outer - levels within groups) -display.notebook_repr_html True When True, IPython notebook will - use html representation for - pandas objects (if it is available). -display.pprint_nest_depth 3 Controls the number of nested levels - to process when pretty-printing -display.precision 6 Floating point output precision in - terms of number of places after the - decimal, for regular formatting as well - as scientific notation. Similar to - numpy's ``precision`` print option -display.show_dimensions truncate Whether to print out dimensions - at the end of DataFrame repr. - If 'truncate' is specified, only - print out the dimensions if the - frame is truncated (e.g. not display - all rows and/or columns) -display.width 80 Width of the display in characters. - In case Python/IPython is running in - a terminal this can be set to None - and pandas will correctly auto-detect - the width. Note that the IPython notebook, - IPython qtconsole, or IDLE do not run in a - terminal and hence it is not possible - to correctly detect the width. -display.html.table_schema False Whether to publish a Table Schema - representation for frontends that - support it. -display.html.border 1 A ``border=value`` attribute is - inserted in the ```` tag - for the DataFrame HTML repr. -display.html.use_mathjax True When True, Jupyter notebook will process - table contents using MathJax, rendering - mathematical expressions enclosed by the - dollar symbol. -display.max_dir_items 100 The number of columns from a dataframe that - are added to dir. These columns can then be - suggested by tab completion. 'None' value means - unlimited. -io.excel.xls.writer xlwt The default Excel writer engine for - 'xls' files. - - .. deprecated:: 1.2.0 - - As `xlwt `__ - package is no longer maintained, the ``xlwt`` - engine will be removed in a future version of - pandas. Since this is the only engine in pandas - that supports writing to ``.xls`` files, - this option will also be removed. - -io.excel.xlsm.writer openpyxl The default Excel writer engine for - 'xlsm' files. Available options: - 'openpyxl' (the default). -io.excel.xlsx.writer openpyxl The default Excel writer engine for - 'xlsx' files. -io.hdf.default_format None default format writing format, if - None, then put will default to - 'fixed' and append will default to - 'table' -io.hdf.dropna_table True drop ALL nan rows when appending - to a table -io.parquet.engine None The engine to use as a default for - parquet reading and writing. If None - then try 'pyarrow' and 'fastparquet' -io.sql.engine None The engine to use as a default for - sql reading and writing, with SQLAlchemy - as a higher level interface. If None - then try 'sqlalchemy' -mode.chained_assignment warn Controls ``SettingWithCopyWarning``: - 'raise', 'warn', or None. Raise an - exception, warn, or no action if - trying to use :ref:`chained assignment `. -mode.sim_interactive False Whether to simulate interactive mode - for purposes of testing. -mode.use_inf_as_na False True means treat None, NaN, -INF, - INF as NA (old way), False means - None and NaN are null, but INF, -INF - are not NA (new way). -compute.use_bottleneck True Use the bottleneck library to accelerate - computation if it is installed. -compute.use_numexpr True Use the numexpr library to accelerate - computation if it is installed. -plotting.backend matplotlib Change the plotting backend to a different - backend than the current matplotlib one. - Backends can be implemented as third-party - libraries implementing the pandas plotting - API. They can use other plotting libraries - like Bokeh, Altair, etc. -plotting.matplotlib.register_converters True Register custom converters with - matplotlib. Set to False to de-register. -styler.sparse.index True "Sparsify" MultiIndex display for rows - in Styler output (don't display repeated - elements in outer levels within groups). -styler.sparse.columns True "Sparsify" MultiIndex display for columns - in Styler output. -styler.render.repr html Standard output format for Styler rendered in Jupyter Notebook. - Should be one of "html" or "latex". -styler.render.max_elements 262144 Maximum number of datapoints that Styler will render - trimming either rows, columns or both to fit. -styler.render.max_rows None Maximum number of rows that Styler will render. By default - this is dynamic based on ``max_elements``. -styler.render.max_columns None Maximum number of columns that Styler will render. By default - this is dynamic based on ``max_elements``. -styler.render.encoding utf-8 Default encoding for output HTML or LaTeX files. -styler.format.formatter None Object to specify formatting functions to ``Styler.format``. -styler.format.na_rep None String representation for missing data. -styler.format.precision 6 Precision to display floating point and complex numbers. -styler.format.decimal . String representation for decimal point separator for floating - point and complex numbers. -styler.format.thousands None String representation for thousands separator for - integers, and floating point and complex numbers. -styler.format.escape None Whether to escape "html" or "latex" special - characters in the display representation. -styler.html.mathjax True If set to False will render specific CSS classes to - table attributes that will prevent Mathjax from rendering - in Jupyter Notebook. -styler.latex.multicol_align r Alignment of headers in a merged column due to sparsification. Can be in {"r", "c", "l"}. -styler.latex.multirow_align c Alignment of index labels in a merged row due to sparsification. Can be in {"c", "t", "b"}. -styler.latex.environment None If given will replace the default ``\\begin{table}`` environment. If "longtable" is specified - this will render with a specific "longtable" template with longtable features. -styler.latex.hrules False If set to True will render ``\\toprule``, ``\\midrule``, and ``\bottomrule`` by default. -======================================= ============ ================================== - - .. _basics.console_output: Number formatting @@ -532,8 +313,6 @@ Use the ``set_eng_float_format`` function to alter the floating-point formatting of pandas objects to produce a particular format. -For instance: - .. ipython:: python import numpy as np @@ -549,7 +328,7 @@ For instance: pd.reset_option("^display") -To round floats on a case-by-case basis, you can also use :meth:`~pandas.Series.round` and :meth:`~pandas.DataFrame.round`. +Use :meth:`~pandas.DataFrame.round` to specifically control rounding of an individual :class:`DataFrame` .. _options.east_asian_width: @@ -564,15 +343,11 @@ Unicode formatting Some East Asian countries use Unicode characters whose width corresponds to two Latin characters. If a DataFrame or Series contains these characters, the default output mode may not align them properly. -.. note:: Screen captures are attached for each output to show the actual results. - .. ipython:: python df = pd.DataFrame({"国籍": ["UK", "日本"], "名前": ["Alice", "しのぶ"]}) df -.. image:: ../_static/option_unicode01.png - Enabling ``display.unicode.east_asian_width`` allows pandas to check each character's "East Asian Width" property. These characters can be aligned properly by setting this option to ``True``. However, this will result in longer render times than the standard ``len`` function. @@ -582,19 +357,16 @@ times than the standard ``len`` function. pd.set_option("display.unicode.east_asian_width", True) df -.. image:: ../_static/option_unicode02.png - -In addition, Unicode characters whose width is "Ambiguous" can either be 1 or 2 characters wide depending on the +In addition, Unicode characters whose width is "ambiguous" can either be 1 or 2 characters wide depending on the terminal setting or encoding. The option ``display.unicode.ambiguous_as_wide`` can be used to handle the ambiguity. -By default, an "Ambiguous" character's width, such as "¡" (inverted exclamation) in the example below, is taken to be 1. +By default, an "ambiguous" character's width, such as "¡" (inverted exclamation) in the example below, is taken to be 1. .. ipython:: python df = pd.DataFrame({"a": ["xxx", "¡¡"], "b": ["yyy", "¡¡"]}) df -.. image:: ../_static/option_unicode03.png Enabling ``display.unicode.ambiguous_as_wide`` makes pandas interpret these characters' widths to be 2. (Note that this option will only be effective when ``display.unicode.east_asian_width`` is enabled.) @@ -606,7 +378,6 @@ However, setting this option incorrectly for your terminal will cause these char pd.set_option("display.unicode.ambiguous_as_wide", True) df -.. image:: ../_static/option_unicode04.png .. ipython:: python :suppress: @@ -619,8 +390,8 @@ However, setting this option incorrectly for your terminal will cause these char Table schema display -------------------- -``DataFrame`` and ``Series`` will publish a Table Schema representation -by default. False by default, this can be enabled globally with the +:class:`DataFrame` and :class:`Series` will publish a Table Schema representation +by default. This can be enabled globally with the ``display.html.table_schema`` option: .. ipython:: python diff --git a/doc/source/whatsnew/v0.17.0.rst b/doc/source/whatsnew/v0.17.0.rst index 991b9a40d151b..7067407604d24 100644 --- a/doc/source/whatsnew/v0.17.0.rst +++ b/doc/source/whatsnew/v0.17.0.rst @@ -363,16 +363,12 @@ Some East Asian countries use Unicode characters its width is corresponding to 2 .. ipython:: python df = pd.DataFrame({u"国籍": ["UK", u"日本"], u"名前": ["Alice", u"しのぶ"]}) - df; - -.. image:: ../_static/option_unicode01.png + df .. ipython:: python pd.set_option("display.unicode.east_asian_width", True) - df; - -.. image:: ../_static/option_unicode02.png + df For further details, see :ref:`here ` diff --git a/pandas/_config/config.py b/pandas/_config/config.py index 5a0f58266c203..8815bb46318c4 100644 --- a/pandas/_config/config.py +++ b/pandas/_config/config.py @@ -289,6 +289,8 @@ def __doc__(self): Notes ----- +Please reference the :ref:`User Guide ` for more information. + The available options with its descriptions: {opts_desc} @@ -323,6 +325,8 @@ def __doc__(self): Notes ----- +Please reference the :ref:`User Guide ` for more information. + The available options with its descriptions: {opts_desc} @@ -355,6 +359,8 @@ def __doc__(self): Notes ----- +Please reference the :ref:`User Guide ` for more information. + The available options with its descriptions: {opts_desc} @@ -385,6 +391,8 @@ def __doc__(self): Notes ----- +Please reference the :ref:`User Guide ` for more information. + The available options with its descriptions: {opts_desc}