pandas: Get and set options for display, data behavior, etc.
In pandas, you can customize global behavior, such as display format, by setting options.
This article describes the following contents.
- Get and set option values with attribute:
options - Print the description for options:
describe_option() - Get and set option values with functions:
get_option(),set_option() - Get and set multiple option values
- Reset options to default values:
reset_option() - Temporarily change settings with
with:option_context()
Note that changing options does not permanently rewrite them; another code uses the default settings again.
The pandas version in this sample code is as follows. Note that pprint is used to make the display easier to read.
import pandas as pd
import pprint
print(pd.__version__)
# 0.23.0
Get and set option values with attribute: options
You can get and set the option values by the attributes under pd.options.
print(pd.options.display.max_rows)
# 60
pd.options.display.max_rows = 100
print(pd.options.display.max_rows)
# 100
You can check what items are available with the built-in dir() function.
print(dir(pd.options))
# ['compute', 'display', 'html', 'io', 'mode', 'plotting']
pprint.pprint(dir(pd.options.display))
# ['chop_threshold',
# 'colheader_justify',
# 'column_space',
# 'date_dayfirst',
# 'date_yearfirst',
# 'encoding',
# 'expand_frame_repr',
# 'float_format',
# 'html',
# 'large_repr',
# 'latex',
# 'max_categories',
# 'max_columns',
# 'max_colwidth',
# 'max_info_columns',
# 'max_info_rows',
# 'max_rows',
# 'max_seq_items',
# 'memory_usage',
# 'multi_sparse',
# 'notebook_repr_html',
# 'pprint_nest_depth',
# 'precision',
# 'show_dimensions',
# 'unicode',
# 'width']
Print the description for options: describe_option()
You can print the description, default and current value of each option with the pd.describe_option() function.
If the argument is omitted, information on all options is displayed. The output is omitted here.
pd.describe_option()
You can specify a regular expression pattern string for the first argument. Options matching the pattern are displayed. [default: xxx] [currently: xxx] represents the default and current values.
pd.describe_option('max.*col')
# display.max_columns : int
# If max_cols is exceeded, switch to truncate view. Depending on
# `large_repr`, objects are either centrally truncated or printed as
# a summary view. 'None' value means unlimited.
# In case python/IPython is running in a terminal and `large_repr`
# equals 'truncate' this can be set to 0 and pandas will auto-detect
# the width of the terminal and print a truncated object which fits
# the screen width. The IPython notebook, IPython qtconsole, or IDLE
# do not run in a terminal and hence it is not possible to do
# correct auto-detection.
# [default: 20] [currently: 20]
# display.max_colwidth : int
# 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.
# [default: 50] [currently: 50]
# display.max_info_columns : int
# max_info_columns is used in DataFrame.info method to decide if
# per column information will be printed.
# [default: 100] [currently: 100]
If you specify just a string without any special characters of the regular expression, the options containing the string are displayed.
pd.describe_option('compute')
# compute.use_bottleneck : bool
# Use the bottleneck library to accelerate if it is installed,
# the default is True
# Valid values: False,True
# [default: True] [currently: True]
# compute.use_numexpr : bool
# Use the numexpr library to accelerate computation if it is installed,
# the default is True
# Valid values: False,True
# [default: True] [currently: True]
pd.describe_option('max_col')
# display.max_columns : int
# If max_cols is exceeded, switch to truncate view. Depending on
# `large_repr`, objects are either centrally truncated or printed as
# a summary view. 'None' value means unlimited.
# In case python/IPython is running in a terminal and `large_repr`
# equals 'truncate' this can be set to 0 and pandas will auto-detect
# the width of the terminal and print a truncated object which fits
# the screen width. The IPython notebook, IPython qtconsole, or IDLE
# do not run in a terminal and hence it is not possible to do
# correct auto-detection.
# [default: 20] [currently: 20]
# display.max_colwidth : int
# 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.
# [default: 50] [currently: 50]
Get and set option values with functions: get_option(), set_option()
You can also get and set option values with functions.
pd.get_option() returns the current option value.
print(pd.get_option('display.max_rows'))
# 100
You can set the option value with pd.set_option().
pd.set_option('display.max_rows', 60)
You can specify a regular expression pattern as an argument. You do not have to specify the full item name, but matching multiple items raises OptionError.
print(pd.get_option('max_r'))
# 60
pd.set_option('max_r', 100)
# pd.get_option('max')
# OptionError: 'Pattern matched multiple keys'
# pd.set_option('max', 60)
# OptionError: 'Pattern matched multiple keys'
Get and set multiple option values
Functions to get and set multiple option values are not provided.
This section shows how to get and set multiple option values with list comprehensions, etc.
Get option values of the listed item names with list and dict comprehensions.
l = ['display.max_rows', 'display.max_columns', 'display.max_colwidth']
print([pd.get_option(i) for i in l])
# [100, 20, 50]
print({i: pd.get_option(i) for i in l})
# {'display.max_rows': 100, 'display.max_columns': 20, 'display.max_colwidth': 50}
Set option values based on the dictionary of item names and the value with the dictionary methods, items() and keys().
d = {'display.max_rows': 80,
'display.max_columns': 80,
'display.max_colwidth': 80}
[pd.set_option(k, v) for k, v in d.items()]
print({i: pd.get_option(i) for i in d.keys()})
# {'display.max_rows': 80, 'display.max_columns': 80, 'display.max_colwidth': 80}
Reset options to default values: reset_option()
reset_option() resets options to default values.
You can specify a regular expression pattern string.
print(pd.options.display.max_rows)
# 80
pd.reset_option('display.max_rows')
print(pd.options.display.max_rows)
# 60
If multiple items are matched, all items are reset.
print(pd.options.display.max_columns)
print(pd.options.display.max_colwidth)
# 80
# 80
pd.reset_option('max_col')
print(pd.options.display.max_columns)
print(pd.options.display.max_colwidth)
# 20
# 50
For example, you can reset all options in display with the regular expression special character ^ that matches the beginning.
pd.options.display.max_rows = 100
pd.options.display.max_columns = 100
pd.options.display.max_colwidth = 100
pd.reset_option('^display', silent=True)
print(pd.options.display.max_rows)
print(pd.options.display.max_columns)
print(pd.options.display.max_colwidth)
# 60
# 20
# 50
'all' resets all items.
pd.reset_option('all')
# html.border has been deprecated, use display.html.border instead
# (currently both are identical)
# : boolean
# use_inf_as_null had been deprecated and will be removed in a future
# version. Use `use_inf_as_na` instead.
# /usr/local/lib/python3.6/site-packages/pandas/core/config.py:619: FutureWarning: html.border has been deprecated, use display.html.border instead
# (currently both are identical)
# warnings.warn(d.msg, FutureWarning)
# /usr/local/lib/python3.6/site-packages/pandas/core/config.py:619: FutureWarning:
# : boolean
# use_inf_as_null had been deprecated and will be removed in a future
# version. Use `use_inf_as_na` instead.
# warnings.warn(d.msg, FutureWarning)
If you do not want FutureWarning to be output, specify silent=True.
pd.reset_option('all', silent=True)
Temporarily change settings with with: option_context()
With pd.option_context(), settings are changed only in the with block.
with pd.option_context('display.max_rows', 100):
print(pd.options.display.max_rows)
# 100
print(pd.options.display.max_rows)
# 60
It is not reset to the default value, but returns to the value before the with block.
pd.options.display.max_rows = 80
with pd.option_context('display.max_rows', 100):
print(pd.options.display.max_rows)
# 100
print(pd.options.display.max_rows)
# 80
Multiple items can be changed by repeatedly specifying a regular expression pattern string and new value like (pat, val, val, ...).
with pd.option_context('display.max_rows', 100, 'display.max_columns', 100):
print(pd.options.display.max_rows)
print(pd.options.display.max_columns)
# 100
# 100
print(pd.options.display.max_rows)
print(pd.options.display.max_columns)
# 80
# 20