Options & Customization

Pandas - Options and Customization

Pandas provides a flexible system for customizing its behavior, particularly how data is displayed (e.g., number of rows/columns shown, decimal precision). This is useful for tailoring output in different environments like scripts, Jupyter notebooks, or terminals.

The options system API includes several key functions:

• pd.get_option(param): Retrieves the current value of a specific option.
• pd.set_option(param, value): Sets a new value for a specific option globally.
• pd.reset_option(param): Resets a specific option back to its default value.
• pd.describe_option(param): Prints a detailed description of an option, including its default and current values.
• pd.option_context(param, value, ...): A context manager to temporarily set option(s) within a with block.

Let’s explore how these functions work with common display options.

Getting Option Values (get_option)

get_option takes the option name (as a string) and returns its current setting.

Example: display.max_rows

This option controls the maximum number of rows Pandas will display when printing a DataFrame. If the DataFrame exceeds this limit, it’s typically truncated.

import pandas as pd

# Get the default maximum number of rows to display
default_max_rows = pd.get_option("display.max_rows")
print(f"Default value for display.max_rows: {default_max_rows}")

Output (default might vary slightly based on Pandas version/environment):

Default value for display.max_rows: 60

Example: display.max_columns

This option controls the maximum number of columns Pandas displays. Beyond this limit, columns might be truncated (represented by ...). Setting it to None typically displays all columns.

import pandas as pd

# Get the default maximum number of columns to display
default_max_cols = pd.get_option("display.max_columns")
print(f"Default value for display.max_columns: {default_max_cols}")

Output (default might vary):

Default value for display.max_columns: 20

Setting Option Values (set_option)

set_option takes the option name and the desired new value. This change affects subsequent Pandas operations globally within the current session.

Example: Increasing display.max_rows

import pandas as pd

print(f"Original max_rows: {pd.get_option('display.max_rows')}")

# Set max_rows to display up to 100 rows
pd.set_option("display.max_rows", 100)

print(f"New max_rows: {pd.get_option('display.max_rows')}")

Output:

Original max_rows: 60
New max_rows: 100

Example: Displaying All Columns (display.max_columns)

import pandas as pd

print(f"Original max_columns: {pd.get_option('display.max_columns')}")

# Set max_columns to None to display all columns
pd.set_option("display.max_columns", None)

print(f"New max_columns: {pd.get_option('display.max_columns')}")

Output:

Original max_columns: 20
New max_columns: None

Resetting Option Values (reset_option)

reset_option reverts a specified option back to its original default value.

Example: Resetting display.max_rows

import pandas as pd

# Assume we previously changed max_rows
pd.set_option("display.max_rows", 999)
print(f"Current max_rows: {pd.get_option('display.max_rows')}")

# Reset max_rows back to its default
pd.reset_option("display.max_rows")

print(f"max_rows after reset: {pd.get_option('display.max_rows')}")

Output (assumes default is 60):

Current max_rows: 999
max_rows after reset: 60

Describing Options (describe_option)

describe_option provides helpful documentation about an option, including its purpose, type, default value, and current setting. This doesn’t change the option.

Example: Describing display.precision

The display.precision option controls the number of decimal places shown for floating-point numbers.

import pandas as pd

pd.describe_option("display.precision")

Output (exact text might change slightly with Pandas versions):

display.precision : int
    Floating point output precision in terms of number of places after the
    decimal, for regular formatting as well as scientific notation. Similar
    to ``numpy.set_printoptions`` precision parameter.
    [default: 6] [currently: 6]

Temporary Settings with option_context

The option_context context manager is extremely useful for applying specific settings only within a with block. Once the block is exited, the options automatically revert to their previous values.

Example: Temporarily Changing display.max_rows and display.precision

import pandas as pd
import numpy as np

# Create a sample DataFrame
df = pd.DataFrame(np.random.rand(15, 5) * 100)

print(f"Outside context: max_rows = {pd.get_option('display.max_rows')}, precision = {pd.get_option('display.precision')}")
print("DataFrame with default settings (likely truncated):\n", df.head()) # Show head to avoid large output

print("\nEntering option_context...")
with pd.option_context("display.max_rows", 10, "display.precision", 2):
    print(f"Inside context: max_rows = {pd.get_option('display.max_rows')}, precision = {pd.get_option('display.precision')}")
    print("DataFrame inside context (rows=10, precision=2):\n", df)

print("\nExited option_context.")
print(f"Outside context again: max_rows = {pd.get_option('display.max_rows')}, precision = {pd.get_option('display.precision')}")
print("DataFrame with original settings restored:\n", df.head()) # Show head again

Output (random values and default settings might differ):

Outside context: max_rows = 60, precision = 6
DataFrame with default settings (likely truncated):
           0          1          2          3          4
0  50.123456  10.987654  80.456789  30.123456  70.987654
1  20.654321  90.876543  40.345678  60.789012  10.456789
2  70.234567   5.567890  95.876543  25.123456  85.678901
3  40.789012  65.432109  15.987654  55.345678   5.876543
4  90.345678  20.876543  75.234567  80.789012  35.123456

Entering option_context...
Inside context: max_rows = 10, precision = 2
DataFrame inside context (rows=10, precision=2):
        0      1      2      3      4
0   50.12  10.99  80.46  30.12  70.99
1   20.65  90.88  40.35  60.79  10.46
2   70.23   5.57  95.88  25.12  85.68
3   40.79  65.43  15.99  55.35   5.88
4   90.35  20.88  75.23  80.79  35.12
..    ...    ...    ...    ...    ...
10  11.22  33.44  55.66  77.88  99.00
11  98.76  87.65  76.54  65.43  54.32
12  12.34  23.45  34.56  45.67  56.78
13  67.89  78.90  89.01  90.12  11.23
14  22.34  33.45  44.56  55.67  66.78

[15 rows x 5 columns]

Exited option_context.
Outside context again: max_rows = 60, precision = 6
DataFrame with original settings restored:
           0          1          2          3          4
0  50.123456  10.987654  80.456789  30.123456  70.987654
1  20.654321  90.876543  40.345678  60.789012  10.456789
2  70.234567   5.567890  95.876543  25.123456  85.678901
3  40.789012  65.432109  15.987654  55.345678   5.876543
4  90.345678  20.876543  75.234567  80.789012  35.123456

Note how the DataFrame display changes inside the with block (truncated to 10 rows, 2 decimal places) and reverts back afterward.

Frequently Used Parameters

Option Name	Description
display.max_rows	Maximum number of rows to display. None means unlimited.
display.max_columns	Maximum number of columns to display. None means unlimited.
display.expand_frame_repr	Whether to print DataFrames wide (‘expand’) or wrap columns to fit terminal width (‘truncate’).
display.max_colwidth	Maximum width (in characters) of elements in a column. Longer strings get truncated. None means unlimited.
display.precision	Number of decimal places for floating-point numbers.
mode.chained_assignment	Controls behavior for chained assignment ('warn', 'raise', None). See SettingWithCopyWarning.

Refer to the official Pandas documentation for a complete list of available options. Find them here: Pandas Options and Settings