"""
Module for applying conditional formatting to DataFrames and Series.
"""
from __future__ import annotations
from contextlib import contextmanager
import copy
from functools import partial
import operator
from typing import (
TYPE_CHECKING,
Any,
Callable,
overload,
)
import warnings
import numpy as np
from pandas._config import get_option
from pandas.compat._optional import import_optional_dependency
from pandas.util._decorators import (
Substitution,
doc,
)
from pandas.util._exceptions import find_stack_level
import pandas as pd
from pandas import (
IndexSlice,
RangeIndex,
)
import pandas.core.common as com
from pandas.core.frame import (
DataFrame,
Series,
)
from pandas.core.generic import NDFrame
from pandas.core.shared_docs import _shared_docs
from pandas.io.formats.format import save_to_buffer
jinja2 = import_optional_dependency("jinja2", extra="DataFrame.style requires jinja2.")
from pandas.io.formats.style_render import (
CSSProperties,
CSSStyles,
ExtFormatter,
StylerRenderer,
Subset,
Tooltips,
format_table_styles,
maybe_convert_css_to_tuples,
non_reducing_slice,
refactor_levels,
)
if TYPE_CHECKING:
from collections.abc import (
Generator,
Hashable,
Sequence,
)
from matplotlib.colors import Colormap
from pandas._typing import (
Axis,
AxisInt,
FilePath,
IndexLabel,
IntervalClosedType,
Level,
QuantileInterpolation,
Scalar,
StorageOptions,
WriteBuffer,
WriteExcelBuffer,
)
from pandas import ExcelWriter
try:
import matplotlib as mpl
import matplotlib.pyplot as plt
has_mpl = True
except ImportError:
has_mpl = False
@contextmanager
def _mpl(func: Callable) -> Generator[tuple[Any, Any], None, None]:
if has_mpl:
yield plt, mpl
else:
raise ImportError(f"{func.__name__} requires matplotlib.")
####
# Shared Doc Strings
subset_args = """subset : label, array-like, IndexSlice, optional
A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input
or single key, to `DataFrame.loc[:, ]` where the columns are
prioritised, to limit ``data`` to *before* applying the function."""
properties_args = """props : str, default None
CSS properties to use for highlighting. If ``props`` is given, ``color``
is not used."""
coloring_args = """color : str, default '{default}'
Background color to use for highlighting."""
buffering_args = """buf : str, path object, file-like object, optional
String, path object (implementing ``os.PathLike[str]``), or file-like
object implementing a string ``write()`` function. If ``None``, the result is
returned as a string."""
encoding_args = """encoding : str, optional
Character encoding setting for file output (and meta tags if available).
Defaults to ``pandas.options.styler.render.encoding`` value of "utf-8"."""
#
###
class Styler(StylerRenderer):
r"""
Helps style a DataFrame or Series according to the data with HTML and CSS.
Parameters
----------
data : Series or DataFrame
Data to be styled - either a Series or DataFrame.
precision : int, optional
Precision to round floats to. If not given defaults to
``pandas.options.styler.format.precision``.
.. versionchanged:: 1.4.0
table_styles : list-like, default None
List of {selector: (attr, value)} dicts; see Notes.
uuid : str, default None
A unique identifier to avoid CSS collisions; generated automatically.
caption : str, tuple, default None
String caption to attach to the table. Tuple only used for LaTeX dual captions.
table_attributes : str, default None
Items that show up in the opening ``
`` tag
in addition to automatic (by default) id.
cell_ids : bool, default True
If True, each cell will have an ``id`` attribute in their HTML tag.
The ``id`` takes the form ``T__row_col``
where ```` is the unique identifier, ```` is the row
number and ```` is the column number.
na_rep : str, optional
Representation for missing values.
If ``na_rep`` is None, no special formatting is applied, and falls back to
``pandas.options.styler.format.na_rep``.
uuid_len : int, default 5
If ``uuid`` is not specified, the length of the ``uuid`` to randomly generate
expressed in hex characters, in range [0, 32].
decimal : str, optional
Character used as decimal separator for floats, complex and integers. If not
given uses ``pandas.options.styler.format.decimal``.
.. versionadded:: 1.3.0
thousands : str, optional, default None
Character used as thousands separator for floats, complex and integers. If not
given uses ``pandas.options.styler.format.thousands``.
.. versionadded:: 1.3.0
escape : str, optional
Use 'html' to replace the characters ``&``, ``<``, ``>``, ``'``, and ``"``
in cell display string with HTML-safe sequences.
Use 'latex' to replace the characters ``&``, ``%``, ``$``, ``#``, ``_``,
``{``, ``}``, ``~``, ``^``, and ``\`` in the cell display string with
LaTeX-safe sequences. Use 'latex-math' to replace the characters
the same way as in 'latex' mode, except for math substrings,
which either are surrounded by two characters ``$`` or start with
the character ``\(`` and end with ``\)``.
If not given uses ``pandas.options.styler.format.escape``.
.. versionadded:: 1.3.0
formatter : str, callable, dict, optional
Object to define how values are displayed. See ``Styler.format``. If not given
uses ``pandas.options.styler.format.formatter``.
.. versionadded:: 1.4.0
Attributes
----------
env : Jinja2 jinja2.Environment
template_html : Jinja2 Template
template_html_table : Jinja2 Template
template_html_style : Jinja2 Template
template_latex : Jinja2 Template
loader : Jinja2 Loader
See Also
--------
DataFrame.style : Return a Styler object containing methods for building
a styled HTML representation for the DataFrame.
Notes
-----
Most styling will be done by passing style functions into
``Styler.apply`` or ``Styler.map``. Style functions should
return values with strings containing CSS ``'attr: value'`` that will
be applied to the indicated cells.
If using in the Jupyter notebook, Styler has defined a ``_repr_html_``
to automatically render itself. Otherwise call Styler.to_html to get
the generated HTML.
CSS classes are attached to the generated HTML
* Index and Column names include ``index_name`` and ``level``
where `k` is its level in a MultiIndex
* Index label cells include
* ``row_heading``
* ``row`` where `n` is the numeric position of the row
* ``level`` where `k` is the level in a MultiIndex
* Column label cells include
* ``col_heading``
* ``col`` where `n` is the numeric position of the column
* ``level`` where `k` is the level in a MultiIndex
* Blank cells include ``blank``
* Data cells include ``data``
* Trimmed cells include ``col_trim`` or ``row_trim``.
Any, or all, or these classes can be renamed by using the ``css_class_names``
argument in ``Styler.set_table_classes``, giving a value such as
*{"row": "MY_ROW_CLASS", "col_trim": "", "row_trim": ""}*.
Examples
--------
>>> df = pd.DataFrame([[1.0, 2.0, 3.0], [4, 5, 6]], index=['a', 'b'],
... columns=['A', 'B', 'C'])
>>> pd.io.formats.style.Styler(df, precision=2,
... caption="My table") # doctest: +SKIP
Please see:
`Table Visualization <../../user_guide/style.ipynb>`_ for more examples.
"""
def __init__(
self,
data: DataFrame | Series,
precision: int | None = None,
table_styles: CSSStyles | None = None,
uuid: str | None = None,
caption: str | tuple | list | None = None,
table_attributes: str | None = None,
cell_ids: bool = True,
na_rep: str | None = None,
uuid_len: int = 5,
decimal: str | None = None,
thousands: str | None = None,
escape: str | None = None,
formatter: ExtFormatter | None = None,
) -> None:
super().__init__(
data=data,
uuid=uuid,
uuid_len=uuid_len,
table_styles=table_styles,
table_attributes=table_attributes,
caption=caption,
cell_ids=cell_ids,
precision=precision,
)
# validate ordered args
thousands = thousands or get_option("styler.format.thousands")
decimal = decimal or get_option("styler.format.decimal")
na_rep = na_rep or get_option("styler.format.na_rep")
escape = escape or get_option("styler.format.escape")
formatter = formatter or get_option("styler.format.formatter")
# precision is handled by superclass as default for performance
self.format(
formatter=formatter,
precision=precision,
na_rep=na_rep,
escape=escape,
decimal=decimal,
thousands=thousands,
)
def concat(self, other: Styler) -> Styler:
"""
Append another Styler to combine the output into a single table.
.. versionadded:: 1.5.0
Parameters
----------
other : Styler
The other Styler object which has already been styled and formatted. The
data for this Styler must have the same columns as the original, and the
number of index levels must also be the same to render correctly.
Returns
-------
Styler
Notes
-----
The purpose of this method is to extend existing styled dataframes with other
metrics that may be useful but may not conform to the original's structure.
For example adding a sub total row, or displaying metrics such as means,
variance or counts.
Styles that are applied using the ``apply``, ``map``, ``apply_index``
and ``map_index``, and formatting applied with ``format`` and
``format_index`` will be preserved.
.. warning::
Only the output methods ``to_html``, ``to_string`` and ``to_latex``
currently work with concatenated Stylers.
Other output methods, including ``to_excel``, **do not** work with
concatenated Stylers.
The following should be noted:
- ``table_styles``, ``table_attributes``, ``caption`` and ``uuid`` are all
inherited from the original Styler and not ``other``.
- hidden columns and hidden index levels will be inherited from the
original Styler
- ``css`` will be inherited from the original Styler, and the value of
keys ``data``, ``row_heading`` and ``row`` will be prepended with
``foot0_``. If more concats are chained, their styles will be prepended
with ``foot1_``, ''foot_2'', etc., and if a concatenated style have
another concatanated style, the second style will be prepended with
``foot{parent}_foot{child}_``.
A common use case is to concatenate user defined functions with
``DataFrame.agg`` or with described statistics via ``DataFrame.describe``.
See examples.
Examples
--------
A common use case is adding totals rows, or otherwise, via methods calculated
in ``DataFrame.agg``.
>>> df = pd.DataFrame([[4, 6], [1, 9], [3, 4], [5, 5], [9, 6]],
... columns=["Mike", "Jim"],
... index=["Mon", "Tue", "Wed", "Thurs", "Fri"])
>>> styler = df.style.concat(df.agg(["sum"]).style) # doctest: +SKIP
.. figure:: ../../_static/style/footer_simple.png
Since the concatenated object is a Styler the existing functionality can be
used to conditionally format it as well as the original.
>>> descriptors = df.agg(["sum", "mean", lambda s: s.dtype])
>>> descriptors.index = ["Total", "Average", "dtype"]
>>> other = (descriptors.style
... .highlight_max(axis=1, subset=(["Total", "Average"], slice(None)))
... .format(subset=("Average", slice(None)), precision=2, decimal=",")
... .map(lambda v: "font-weight: bold;"))
>>> styler = (df.style
... .highlight_max(color="salmon")
... .set_table_styles([{"selector": ".foot_row0",
... "props": "border-top: 1px solid black;"}]))
>>> styler.concat(other) # doctest: +SKIP
.. figure:: ../../_static/style/footer_extended.png
When ``other`` has fewer index levels than the original Styler it is possible
to extend the index in ``other``, with placeholder levels.
>>> df = pd.DataFrame([[1], [2]],
... index=pd.MultiIndex.from_product([[0], [1, 2]]))
>>> descriptors = df.agg(["sum"])
>>> descriptors.index = pd.MultiIndex.from_product([[""], descriptors.index])
>>> df.style.concat(descriptors.style) # doctest: +SKIP
"""
if not isinstance(other, Styler):
raise TypeError("`other` must be of type `Styler`")
if not self.data.columns.equals(other.data.columns):
raise ValueError("`other.data` must have same columns as `Styler.data`")
if not self.data.index.nlevels == other.data.index.nlevels:
raise ValueError(
"number of index levels must be same in `other` "
"as in `Styler`. See documentation for suggestions."
)
self.concatenated.append(other)
return self
def _repr_html_(self) -> str | None:
"""
Hooks into Jupyter notebook rich display system, which calls _repr_html_ by
default if an object is returned at the end of a cell.
"""
if get_option("styler.render.repr") == "html":
return self.to_html()
return None
def _repr_latex_(self) -> str | None:
if get_option("styler.render.repr") == "latex":
return self.to_latex()
return None
def set_tooltips(
self,
ttips: DataFrame,
props: CSSProperties | None = None,
css_class: str | None = None,
) -> Styler:
"""
Set the DataFrame of strings on ``Styler`` generating ``:hover`` tooltips.
These string based tooltips are only applicable to ``
`` HTML elements,
and cannot be used for column or index headers.
.. versionadded:: 1.3.0
Parameters
----------
ttips : DataFrame
DataFrame containing strings that will be translated to tooltips, mapped
by identical column and index values that must exist on the underlying
Styler data. None, NaN values, and empty strings will be ignored and
not affect the rendered HTML.
props : list-like or str, optional
List of (attr, value) tuples or a valid CSS string. If ``None`` adopts
the internal default values described in notes.
css_class : str, optional
Name of the tooltip class used in CSS, should conform to HTML standards.
Only useful if integrating tooltips with external CSS. If ``None`` uses the
internal default value 'pd-t'.
Returns
-------
Styler
Notes
-----
Tooltips are created by adding `` to each data cell
and then manipulating the table level CSS to attach pseudo hover and pseudo
after selectors to produce the required the results.
The default properties for the tooltip CSS class are:
- visibility: hidden
- position: absolute
- z-index: 1
- background-color: black
- color: white
- transform: translate(-20px, -20px)
The property 'visibility: hidden;' is a key prerequisite to the hover
functionality, and should always be included in any manual properties
specification, using the ``props`` argument.
Tooltips are not designed to be efficient, and can add large amounts of
additional HTML for larger tables, since they also require that ``cell_ids``
is forced to `True`.
Examples
--------
Basic application
>>> df = pd.DataFrame(data=[[0, 1], [2, 3]])
>>> ttips = pd.DataFrame(
... data=[["Min", ""], [np.nan, "Max"]], columns=df.columns, index=df.index
... )
>>> s = df.style.set_tooltips(ttips).to_html()
Optionally controlling the tooltip visual display
>>> df.style.set_tooltips(ttips, css_class='tt-add', props=[
... ('visibility', 'hidden'),
... ('position', 'absolute'),
... ('z-index', 1)]) # doctest: +SKIP
>>> df.style.set_tooltips(ttips, css_class='tt-add',
... props='visibility:hidden; position:absolute; z-index:1;')
... # doctest: +SKIP
"""
if not self.cell_ids:
# tooltips not optimised for individual cell check. requires reasonable
# redesign and more extensive code for a feature that might be rarely used.
raise NotImplementedError(
"Tooltips can only render with 'cell_ids' is True."
)
if not ttips.index.is_unique or not ttips.columns.is_unique:
raise KeyError(
"Tooltips render only if `ttips` has unique index and columns."
)
if self.tooltips is None: # create a default instance if necessary
self.tooltips = Tooltips()
self.tooltips.tt_data = ttips
if props:
self.tooltips.class_properties = props
if css_class:
self.tooltips.class_name = css_class
return self
@doc(
NDFrame.to_excel,
klass="Styler",
storage_options=_shared_docs["storage_options"],
storage_options_versionadded="1.5.0",
)
def to_excel(
self,
excel_writer: FilePath | WriteExcelBuffer | ExcelWriter,
sheet_name: str = "Sheet1",
na_rep: str = "",
float_format: str | None = None,
columns: Sequence[Hashable] | None = None,
header: Sequence[Hashable] | bool = True,
index: bool = True,
index_label: IndexLabel | None = None,
startrow: int = 0,
startcol: int = 0,
engine: str | None = None,
merge_cells: bool = True,
encoding: str | None = None,
inf_rep: str = "inf",
verbose: bool = True,
freeze_panes: tuple[int, int] | None = None,
storage_options: StorageOptions | None = None,
) -> None:
from pandas.io.formats.excel import ExcelFormatter
formatter = ExcelFormatter(
self,
na_rep=na_rep,
cols=columns,
header=header,
float_format=float_format,
index=index,
index_label=index_label,
merge_cells=merge_cells,
inf_rep=inf_rep,
)
formatter.write(
excel_writer,
sheet_name=sheet_name,
startrow=startrow,
startcol=startcol,
freeze_panes=freeze_panes,
engine=engine,
storage_options=storage_options,
)
@overload
def to_latex(
self,
buf: FilePath | WriteBuffer[str],
*,
column_format: str | None = ...,
position: str | None = ...,
position_float: str | None = ...,
hrules: bool | None = ...,
clines: str | None = ...,
label: str | None = ...,
caption: str | tuple | None = ...,
sparse_index: bool | None = ...,
sparse_columns: bool | None = ...,
multirow_align: str | None = ...,
multicol_align: str | None = ...,
siunitx: bool = ...,
environment: str | None = ...,
encoding: str | None = ...,
convert_css: bool = ...,
) -> None:
...
@overload
def to_latex(
self,
buf: None = ...,
*,
column_format: str | None = ...,
position: str | None = ...,
position_float: str | None = ...,
hrules: bool | None = ...,
clines: str | None = ...,
label: str | None = ...,
caption: str | tuple | None = ...,
sparse_index: bool | None = ...,
sparse_columns: bool | None = ...,
multirow_align: str | None = ...,
multicol_align: str | None = ...,
siunitx: bool = ...,
environment: str | None = ...,
encoding: str | None = ...,
convert_css: bool = ...,
) -> str:
...
def to_latex(
self,
buf: FilePath | WriteBuffer[str] | None = None,
*,
column_format: str | None = None,
position: str | None = None,
position_float: str | None = None,
hrules: bool | None = None,
clines: str | None = None,
label: str | None = None,
caption: str | tuple | None = None,
sparse_index: bool | None = None,
sparse_columns: bool | None = None,
multirow_align: str | None = None,
multicol_align: str | None = None,
siunitx: bool = False,
environment: str | None = None,
encoding: str | None = None,
convert_css: bool = False,
) -> str | None:
r"""
Write Styler to a file, buffer or string in LaTeX format.
.. versionadded:: 1.3.0
Parameters
----------
buf : str, path object, file-like object, or None, default None
String, path object (implementing ``os.PathLike[str]``), or file-like
object implementing a string ``write()`` function. If None, the result is
returned as a string.
column_format : str, optional
The LaTeX column specification placed in location:
\\begin{tabular}{}
Defaults to 'l' for index and
non-numeric data columns, and, for numeric data columns,
to 'r' by default, or 'S' if ``siunitx`` is ``True``.
position : str, optional
The LaTeX positional argument (e.g. 'h!') for tables, placed in location:
``\\begin{table}[]``.
position_float : {"centering", "raggedleft", "raggedright"}, optional
The LaTeX float command placed in location:
\\begin{table}[]
\\
Cannot be used if ``environment`` is "longtable".
hrules : bool
Set to `True` to add \\toprule, \\midrule and \\bottomrule from the
{booktabs} LaTeX package.
Defaults to ``pandas.options.styler.latex.hrules``, which is `False`.
.. versionchanged:: 1.4.0
clines : str, optional
Use to control adding \\cline commands for the index labels separation.
Possible values are:
- `None`: no cline commands are added (default).
- `"all;data"`: a cline is added for every index value extending the
width of the table, including data entries.
- `"all;index"`: as above with lines extending only the width of the
index entries.
- `"skip-last;data"`: a cline is added for each index value except the
last level (which is never sparsified), extending the widtn of the
table.
- `"skip-last;index"`: as above with lines extending only the width of the
index entries.
.. versionadded:: 1.4.0
label : str, optional
The LaTeX label included as: \\label{