Skip to content

DOC: closes gh6838. Breakout options.rst from basics.rst #7578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 7, 2014
+411 −187
Merged

DOC: closes gh6838. Breakout options.rst from basics.rst #7578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 0 additions & 149 deletions doc/source/basics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1552,152 +1552,3 @@ While float dtypes are unchanged.
casted = dfa[df2>0]
casted
casted.dtypes


Working with package options
----------------------------

.. _basics.working_with_options:
.. versionadded:: 0.10.1

pandas has an options system that let's you customize some aspects of it's behaviour,
display-related options being those the user is must likely to adjust.

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:

.. ipython:: python

import pandas as pd
pd.options.display.max_rows
pd.options.display.max_rows = 999
pd.options.display.max_rows


There is also an API composed of 4 relevant functions, available directly from the ``pandas``
namespace, and they are:

- ``get_option`` / ``set_option`` - get/set the value of a single option.
- ``reset_option`` - reset one or more options to their default value.
- ``describe_option`` - print the descriptions of one or more options.

**Note:** developers can check out pandas/core/config.py for more info.

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 :

.. ipython:: python

get_option("display.max_rows")
set_option("display.max_rows",101)
get_option("display.max_rows")
set_option("max_r",102)
get_option("display.max_rows")


The following will **not work** because it matches multiple option names, e.g. ``display.max_colwidth``, ``display.max_rows``, ``display.max_columns``:

.. ipython:: python
:okexcept:

try:
get_option("display.max_")
except KeyError as e:
print(e)


**Note:** 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:

reset_option("all")


.. ipython:: python

describe_option()


or you can get the description for just the options that match the regexp you pass in:

.. ipython:: python

describe_option("date")


All options also have a default value, and you can use the ``reset_option`` to do just that:

.. ipython:: python
:suppress:

reset_option("display.max_rows")


.. ipython:: python

get_option("display.max_rows")
set_option("display.max_rows",999)
get_option("display.max_rows")
reset_option("display.max_rows")
get_option("display.max_rows")


It's also possible to reset multiple options at once (using a regex):

.. ipython:: python

reset_option("^display")


.. versionadded:: 0.13.1

Beginning with v0.13.1 the `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:

.. ipython:: python

with option_context("display.max_rows",10,"display.max_columns", 5):
print get_option("display.max_rows")
print get_option("display.max_columns")

print get_option("display.max_rows")
print get_option("display.max_columns")


Console Output Formatting
-------------------------

.. _basics.console_output:

Use the ``set_eng_float_format`` function in the ``pandas.core.common`` module
to alter the floating-point formatting of pandas objects to produce a particular
format.

For instance:

.. ipython:: python

set_eng_float_format(accuracy=3, use_eng_prefix=True)
s = Series(randn(5), index=['a', 'b', 'c', 'd', 'e'])
s/1.e3
s/1.e6

.. ipython:: python
:suppress:

reset_option('^display\.')


The ``set_printoptions`` function has a number of options for controlling how
floating point numbers are formatted (using the ``precision`` argument) in the
console and . The ``max_rows`` and ``max_columns`` control how many rows and
columns of DataFrame objects are shown by default. If ``max_columns`` is set to
0 (the default, in fact), the library will attempt to fit the DataFrame's
string representation into the current terminal width, and defaulting to the
summary view otherwise.
38 changes: 0 additions & 38 deletions doc/source/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,44 +24,6 @@ Frequently Asked Questions (FAQ)
options.display.mpl_style='default'
from pandas.compat import lrange


.. _ref-repr-control:

How do I control the way my DataFrame is displayed?
---------------------------------------------------

pandas users rely on a variety of environments for using pandas: scripts, terminal,
IPython qtconsole/ notebook, (IDLE, spyder, etc').
Each environment has it's own capabilities and limitations: HTML support,
horizontal scrolling, auto-detection of width/height.
To appropriately address all these environments, the display behavior is controlled
by several options, which you're encouraged to tweak to suit your setup.

As of 0.13, these are the relevant options, all under the `display` namespace,
(e.g. ``display.width``, etc.):

- notebook_repr_html: if True, IPython frontends with HTML support will display
dataframes as HTML tables when possible.
- large_repr (default 'truncate'): when a :class:`~pandas.DataFrame`
exceeds max_columns or max_rows, it can be displayed either as a
truncated table or, with this set to 'info', as a short summary view.
- max_columns (default 20): max dataframe columns to display.
- max_rows (default 60): max dataframe rows display.
- show_dimensions (default True): controls the display of the row/col counts footer.

Two additional options only apply to displaying DataFrames in terminals,
not to the HTML view:

- expand_repr (default True): when the frame width cannot fit within
the screen, the output will be broken into multiple pages.
- width: width of display screen in characters, used to determine the
width of lines when expand_repr is active. Setting this to None will
trigger auto-detection of terminal width.

IPython users can use the IPython startup file to import pandas and set these
options automatically when starting up.


.. _ref-monkey-patching:

Adding Features to your pandas Installation
Expand Down
1 change: 1 addition & 0 deletions doc/source/index.rst.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,7 @@ See the package overview for more detail about what's in the library.
cookbook
dsintro
basics
options
indexing
computation
missing_data
Expand Down
Loading