""" 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 ( Any, Callable, Hashable, Sequence, overload, ) import warnings import numpy as np from pandas._config import get_option from pandas._libs import lib from pandas._typing import ( Axis, FilePath, IndexLabel, Level, QuantileInterpolation, Scalar, StorageOptions, WriteBuffer, ) 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, ) try: import matplotlib as mpl import matplotlib.pyplot as plt has_mpl = True except ImportError: has_mpl = False no_mpl_message = "{0} requires matplotlib." @contextmanager def _mpl(func: Callable): if has_mpl: yield plt, mpl else: raise ImportError(no_mpl_message.format(func.__name__)) #### # Shared Doc Strings subset = """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.""" props = """props : str, default None CSS properties to use for highlighting. If ``props`` is given, ``color`` is not used.""" color = """color : str, default 'yellow' Background color to use for highlighting.""" buf = """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 = """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``. .. versionadded:: 1.0.0 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]. .. versionadded:: 1.2.0 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. 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.applymap``. 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": ""}*. """ def __init__( self, data: DataFrame | Series, precision: int | None = None, table_styles: CSSStyles | None = None, uuid: str | None = None, caption: str | tuple | 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.precision = precision # can be removed on set_precision depr cycle self.na_rep = na_rep # can be removed on set_na_rep depr cycle 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 ------- self : 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``, ``applymap``, ``apply_index`` and ``applymap_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 = 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=",") ... .applymap(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 = 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 render( self, sparse_index: bool | None = None, sparse_columns: bool | None = None, **kwargs, ) -> str: """ Render the ``Styler`` including all applied styles to HTML. .. deprecated:: 1.4.0 Parameters ---------- sparse_index : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each row. Defaults to ``pandas.options.styler.sparse.index`` value. sparse_columns : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each row. Defaults to ``pandas.options.styler.sparse.columns`` value. **kwargs Any additional keyword arguments are passed through to ``self.template.render``. This is useful when you need to provide additional variables for a custom template. Returns ------- rendered : str The rendered HTML. Notes ----- This method is deprecated in favour of ``Styler.to_html``. Styler objects have defined the ``_repr_html_`` method which automatically calls ``self.to_html()`` when it's the last item in a Notebook cell. When calling ``Styler.render()`` directly, wrap the result in ``IPython.display.HTML`` to view the rendered HTML in the notebook. Pandas uses the following keys in render. Arguments passed in ``**kwargs`` take precedence, so think carefully if you want to override them: * head * cellstyle * body * uuid * table_styles * caption * table_attributes """ warnings.warn( "this method is deprecated in favour of `Styler.to_html()`", FutureWarning, stacklevel=find_stack_level(), ) if sparse_index is None: sparse_index = get_option("styler.sparse.index") if sparse_columns is None: sparse_columns = get_option("styler.sparse.columns") return self._render_html(sparse_index, sparse_columns, **kwargs) 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 ------- self : 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, 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: 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{
}. If tuple, i.e ("full caption", "short caption"), the caption included as: \\caption[]{}. sparse_index : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each row. Defaults to ``pandas.options.styler.sparse.index``, which is `True`. sparse_columns : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each column. Defaults to ``pandas.options.styler.sparse.columns``, which is `True`. multirow_align : {"c", "t", "b", "naive"}, optional If sparsifying hierarchical MultiIndexes whether to align text centrally, at the top or bottom using the multirow package. If not given defaults to ``pandas.options.styler.latex.multirow_align``, which is `"c"`. If "naive" is given renders without multirow. .. versionchanged:: 1.4.0 multicol_align : {"r", "c", "l", "naive-l", "naive-r"}, optional If sparsifying hierarchical MultiIndex columns whether to align text at the left, centrally, or at the right. If not given defaults to ``pandas.options.styler.latex.multicol_align``, which is "r". If a naive option is given renders without multicol. Pipe decorators can also be added to non-naive values to draw vertical rules, e.g. "\|r" will draw a rule on the left side of right aligned merged cells. .. versionchanged:: 1.4.0 siunitx : bool, default False Set to ``True`` to structure LaTeX compatible with the {siunitx} package. environment : str, optional If given, the environment that will replace 'table' in ``\\begin{table}``. If 'longtable' is specified then a more suitable template is rendered. If not given defaults to ``pandas.options.styler.latex.environment``, which is `None`. .. versionadded:: 1.4.0 encoding : str, optional Character encoding setting. Defaults to ``pandas.options.styler.render.encoding``, which is "utf-8". convert_css : bool, default False Convert simple cell-styles from CSS to LaTeX format. Any CSS not found in conversion table is dropped. A style can be forced by adding option `--latex`. See notes. Returns ------- str or None If `buf` is None, returns the result as a string. Otherwise returns `None`. See Also -------- Styler.format: Format the text display value of cells. Notes ----- **Latex Packages** For the following features we recommend the following LaTeX inclusions: ===================== ========================================================== Feature Inclusion ===================== ========================================================== sparse columns none: included within default {tabular} environment sparse rows \\usepackage{multirow} hrules \\usepackage{booktabs} colors \\usepackage[table]{xcolor} siunitx \\usepackage{siunitx} bold (with siunitx) | \\usepackage{etoolbox} | \\robustify\\bfseries | \\sisetup{detect-all = true} *(within {document})* italic (with siunitx) | \\usepackage{etoolbox} | \\robustify\\itshape | \\sisetup{detect-all = true} *(within {document})* environment \\usepackage{longtable} if arg is "longtable" | or any other relevant environment package hyperlinks \\usepackage{hyperref} ===================== ========================================================== **Cell Styles** LaTeX styling can only be rendered if the accompanying styling functions have been constructed with appropriate LaTeX commands. All styling functionality is built around the concept of a CSS ``(, )`` pair (see `Table Visualization <../../user_guide/style.ipynb>`_), and this should be replaced by a LaTeX ``(, )`` approach. Each cell will be styled individually using nested LaTeX commands with their accompanied options. For example the following code will highlight and bold a cell in HTML-CSS: >>> df = pd.DataFrame([[1,2], [3,4]]) >>> s = df.style.highlight_max(axis=None, ... props='background-color:red; font-weight:bold;') >>> s.to_html() # doctest: +SKIP The equivalent using LaTeX only commands is the following: >>> s = df.style.highlight_max(axis=None, ... props='cellcolor:{red}; bfseries: ;') >>> s.to_latex() # doctest: +SKIP Internally these structured LaTeX ``(, )`` pairs are translated to the ``display_value`` with the default structure: ``\ ``. Where there are multiple commands the latter is nested recursively, so that the above example highlighed cell is rendered as ``\cellcolor{red} \bfseries 4``. Occasionally this format does not suit the applied command, or combination of LaTeX packages that is in use, so additional flags can be added to the ````, within the tuple, to result in different positions of required braces (the **default** being the same as ``--nowrap``): =================================== ============================================ Tuple Format Output Structure =================================== ============================================ (,) \\ (, ``--nowrap``) \\ (, ``--rwrap``) \\{} (, ``--wrap``) {\\ } (, ``--lwrap``) {\\} (, ``--dwrap``) {\\}{} =================================== ============================================ For example the `textbf` command for font-weight should always be used with `--rwrap` so ``('textbf', '--rwrap')`` will render a working cell, wrapped with braces, as ``\textbf{}``. A more comprehensive example is as follows: >>> df = pd.DataFrame([[1, 2.2, "dogs"], [3, 4.4, "cats"], [2, 6.6, "cows"]], ... index=["ix1", "ix2", "ix3"], ... columns=["Integers", "Floats", "Strings"]) >>> s = df.style.highlight_max( ... props='cellcolor:[HTML]{FFFF00}; color:{red};' ... 'textit:--rwrap; textbf:--rwrap;' ... ) >>> s.to_latex() # doctest: +SKIP .. figure:: ../../_static/style/latex_1.png **Table Styles** Internally Styler uses its ``table_styles`` object to parse the ``column_format``, ``position``, ``position_float``, and ``label`` input arguments. These arguments are added to table styles in the format: .. code-block:: python set_table_styles([ {"selector": "column_format", "props": f":{column_format};"}, {"selector": "position", "props": f":{position};"}, {"selector": "position_float", "props": f":{position_float};"}, {"selector": "label", "props": f":{{{label.replace(':','§')}}};"} ], overwrite=False) Exception is made for the ``hrules`` argument which, in fact, controls all three commands: ``toprule``, ``bottomrule`` and ``midrule`` simultaneously. Instead of setting ``hrules`` to ``True``, it is also possible to set each individual rule definition, by manually setting the ``table_styles``, for example below we set a regular ``toprule``, set an ``hline`` for ``bottomrule`` and exclude the ``midrule``: .. code-block:: python set_table_styles([ {'selector': 'toprule', 'props': ':toprule;'}, {'selector': 'bottomrule', 'props': ':hline;'}, ], overwrite=False) If other ``commands`` are added to table styles they will be detected, and positioned immediately above the '\\begin{tabular}' command. For example to add odd and even row coloring, from the {colortbl} package, in format ``\rowcolors{1}{pink}{red}``, use: .. code-block:: python set_table_styles([ {'selector': 'rowcolors', 'props': ':{1}{pink}{red};'} ], overwrite=False) A more comprehensive example using these arguments is as follows: >>> df.columns = pd.MultiIndex.from_tuples([ ... ("Numeric", "Integers"), ... ("Numeric", "Floats"), ... ("Non-Numeric", "Strings") ... ]) >>> df.index = pd.MultiIndex.from_tuples([ ... ("L0", "ix1"), ("L0", "ix2"), ("L1", "ix3") ... ]) >>> s = df.style.highlight_max( ... props='cellcolor:[HTML]{FFFF00}; color:{red}; itshape:; bfseries:;' ... ) >>> s.to_latex( ... column_format="rrrrr", position="h", position_float="centering", ... hrules=True, label="table:5", caption="Styled LaTeX Table", ... multirow_align="t", multicol_align="r" ... ) # doctest: +SKIP .. figure:: ../../_static/style/latex_2.png **Formatting** To format values :meth:`Styler.format` should be used prior to calling `Styler.to_latex`, as well as other methods such as :meth:`Styler.hide` for example: >>> s.clear() >>> s.table_styles = [] >>> s.caption = None >>> s.format({ ... ("Numeric", "Integers"): '\${}', ... ("Numeric", "Floats"): '{:.3f}', ... ("Non-Numeric", "Strings"): str.upper ... }) # doctest: +SKIP Numeric Non-Numeric Integers Floats Strings L0 ix1 $1 2.200 DOGS ix2 $3 4.400 CATS L1 ix3 $2 6.600 COWS >>> s.to_latex() # doctest: +SKIP \begin{tabular}{llrrl} {} & {} & \multicolumn{2}{r}{Numeric} & {Non-Numeric} \\ {} & {} & {Integers} & {Floats} & {Strings} \\ \multirow[c]{2}{*}{L0} & ix1 & \\$1 & 2.200 & DOGS \\ & ix2 & \$3 & 4.400 & CATS \\ L1 & ix3 & \$2 & 6.600 & COWS \\ \end{tabular} **CSS Conversion** This method can convert a Styler constructured with HTML-CSS to LaTeX using the following limited conversions. ================== ==================== ============= ========================== CSS Attribute CSS value LaTeX Command LaTeX Options ================== ==================== ============= ========================== font-weight | bold | bfseries | bolder | bfseries font-style | italic | itshape | oblique | slshape background-color | red cellcolor | {red}--lwrap | #fe01ea | [HTML]{FE01EA}--lwrap | #f0e | [HTML]{FF00EE}--lwrap | rgb(128,255,0) | [rgb]{0.5,1,0}--lwrap | rgba(128,0,0,0.5) | [rgb]{0.5,0,0}--lwrap | rgb(25%,255,50%) | [rgb]{0.25,1,0.5}--lwrap color | red color | {red} | #fe01ea | [HTML]{FE01EA} | #f0e | [HTML]{FF00EE} | rgb(128,255,0) | [rgb]{0.5,1,0} | rgba(128,0,0,0.5) | [rgb]{0.5,0,0} | rgb(25%,255,50%) | [rgb]{0.25,1,0.5} ================== ==================== ============= ========================== It is also possible to add user-defined LaTeX only styles to a HTML-CSS Styler using the ``--latex`` flag, and to add LaTeX parsing options that the converter will detect within a CSS-comment. >>> df = pd.DataFrame([[1]]) >>> df.style.set_properties( ... **{"font-weight": "bold /* --dwrap */", "Huge": "--latex--rwrap"} ... ).to_latex(convert_css=True) # doctest: +SKIP \begin{tabular}{lr} {} & {0} \\ 0 & {\bfseries}{\Huge{1}} \\ \end{tabular} Examples -------- Below we give a complete step by step example adding some advanced features and noting some common gotchas. First we create the DataFrame and Styler as usual, including MultiIndex rows and columns, which allow for more advanced formatting options: >>> cidx = pd.MultiIndex.from_arrays([ ... ["Equity", "Equity", "Equity", "Equity", ... "Stats", "Stats", "Stats", "Stats", "Rating"], ... ["Energy", "Energy", "Consumer", "Consumer", "", "", "", "", ""], ... ["BP", "Shell", "H&M", "Unilever", ... "Std Dev", "Variance", "52w High", "52w Low", ""] ... ]) >>> iidx = pd.MultiIndex.from_arrays([ ... ["Equity", "Equity", "Equity", "Equity"], ... ["Energy", "Energy", "Consumer", "Consumer"], ... ["BP", "Shell", "H&M", "Unilever"] ... ]) >>> styler = pd.DataFrame([ ... [1, 0.8, 0.66, 0.72, 32.1678, 32.1678**2, 335.12, 240.89, "Buy"], ... [0.8, 1.0, 0.69, 0.79, 1.876, 1.876**2, 14.12, 19.78, "Hold"], ... [0.66, 0.69, 1.0, 0.86, 7, 7**2, 210.9, 140.6, "Buy"], ... [0.72, 0.79, 0.86, 1.0, 213.76, 213.76**2, 2807, 3678, "Sell"], ... ], columns=cidx, index=iidx).style Second we will format the display and, since our table is quite wide, will hide the repeated level-0 of the index: >>> styler.format(subset="Equity", precision=2) ... .format(subset="Stats", precision=1, thousands=",") ... .format(subset="Rating", formatter=str.upper) ... .format_index(escape="latex", axis=1) ... .format_index(escape="latex", axis=0) ... .hide(level=0, axis=0) # doctest: +SKIP Note that one of the string entries of the index and column headers is "H&M". Without applying the `escape="latex"` option to the `format_index` method the resultant LaTeX will fail to render, and the error returned is quite difficult to debug. Using the appropriate escape the "&" is converted to "\\&". Thirdly we will apply some (CSS-HTML) styles to our object. We will use a builtin method and also define our own method to highlight the stock recommendation: >>> def rating_color(v): ... if v == "Buy": color = "#33ff85" ... elif v == "Sell": color = "#ff5933" ... else: color = "#ffdd33" ... return f"color: {color}; font-weight: bold;" >>> styler.background_gradient(cmap="inferno", subset="Equity", vmin=0, vmax=1) ... .applymap(rating_color, subset="Rating") # doctest: +SKIP All the above styles will work with HTML (see below) and LaTeX upon conversion: .. figure:: ../../_static/style/latex_stocks_html.png However, we finally want to add one LaTeX only style (from the {graphicx} package), that is not easy to convert from CSS and pandas does not support it. Notice the `--latex` flag used here, as well as `--rwrap` to ensure this is formatted correctly and not ignored upon conversion. >>> styler.applymap_index( ... lambda v: "rotatebox:{45}--rwrap--latex;", level=2, axis=1 ... ) # doctest: +SKIP Finally we render our LaTeX adding in other options as required: >>> styler.to_latex( ... caption="Selected stock correlation and simple statistics.", ... clines="skip-last;data", ... convert_css=True, ... position_float="centering", ... multicol_align="|c|", ... hrules=True, ... ) # doctest: +SKIP \begin{table} \centering \caption{Selected stock correlation and simple statistics.} \begin{tabular}{llrrrrrrrrl} \toprule & & \multicolumn{4}{|c|}{Equity} & \multicolumn{4}{|c|}{Stats} & Rating \\ & & \multicolumn{2}{|c|}{Energy} & \multicolumn{2}{|c|}{Consumer} & \multicolumn{4}{|c|}{} & \\ & & \rotatebox{45}{BP} & \rotatebox{45}{Shell} & \rotatebox{45}{H\&M} & \rotatebox{45}{Unilever} & \rotatebox{45}{Std Dev} & \rotatebox{45}{Variance} & \rotatebox{45}{52w High} & \rotatebox{45}{52w Low} & \rotatebox{45}{} \\ \midrule \multirow[c]{2}{*}{Energy} & BP & {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 & {\cellcolor[HTML]{FCA50A}} \color[HTML]{000000} 0.80 & {\cellcolor[HTML]{EB6628}} \color[HTML]{F1F1F1} 0.66 & {\cellcolor[HTML]{F68013}} \color[HTML]{F1F1F1} 0.72 & 32.2 & 1,034.8 & 335.1 & 240.9 & \color[HTML]{33FF85} \bfseries BUY \\ & Shell & {\cellcolor[HTML]{FCA50A}} \color[HTML]{000000} 0.80 & {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 & {\cellcolor[HTML]{F1731D}} \color[HTML]{F1F1F1} 0.69 & {\cellcolor[HTML]{FCA108}} \color[HTML]{000000} 0.79 & 1.9 & 3.5 & 14.1 & 19.8 & \color[HTML]{FFDD33} \bfseries HOLD \\ \cline{1-11} \multirow[c]{2}{*}{Consumer} & H\&M & {\cellcolor[HTML]{EB6628}} \color[HTML]{F1F1F1} 0.66 & {\cellcolor[HTML]{F1731D}} \color[HTML]{F1F1F1} 0.69 & {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 & {\cellcolor[HTML]{FAC42A}} \color[HTML]{000000} 0.86 & 7.0 & 49.0 & 210.9 & 140.6 & \color[HTML]{33FF85} \bfseries BUY \\ & Unilever & {\cellcolor[HTML]{F68013}} \color[HTML]{F1F1F1} 0.72 & {\cellcolor[HTML]{FCA108}} \color[HTML]{000000} 0.79 & {\cellcolor[HTML]{FAC42A}} \color[HTML]{000000} 0.86 & {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 & 213.8 & 45,693.3 & 2,807.0 & 3,678.0 & \color[HTML]{FF5933} \bfseries SELL \\ \cline{1-11} \bottomrule \end{tabular} \end{table} .. figure:: ../../_static/style/latex_stocks.png """ obj = self._copy(deepcopy=True) # manipulate table_styles on obj, not self table_selectors = ( [style["selector"] for style in self.table_styles] if self.table_styles is not None else [] ) if column_format is not None: # add more recent setting to table_styles obj.set_table_styles( [{"selector": "column_format", "props": f":{column_format}"}], overwrite=False, ) elif "column_format" in table_selectors: pass # adopt what has been previously set in table_styles else: # create a default: set float, complex, int cols to 'r' ('S'), index to 'l' _original_columns = self.data.columns self.data.columns = RangeIndex(stop=len(self.data.columns)) numeric_cols = self.data._get_numeric_data().columns.to_list() self.data.columns = _original_columns column_format = "" for level in range(self.index.nlevels): column_format += "" if self.hide_index_[level] else "l" for ci, _ in enumerate(self.data.columns): if ci not in self.hidden_columns: column_format += ( ("r" if not siunitx else "S") if ci in numeric_cols else "l" ) obj.set_table_styles( [{"selector": "column_format", "props": f":{column_format}"}], overwrite=False, ) if position: obj.set_table_styles( [{"selector": "position", "props": f":{position}"}], overwrite=False, ) if position_float: if environment == "longtable": raise ValueError( "`position_float` cannot be used in 'longtable' `environment`" ) if position_float not in ["raggedright", "raggedleft", "centering"]: raise ValueError( f"`position_float` should be one of " f"'raggedright', 'raggedleft', 'centering', " f"got: '{position_float}'" ) obj.set_table_styles( [{"selector": "position_float", "props": f":{position_float}"}], overwrite=False, ) hrules = get_option("styler.latex.hrules") if hrules is None else hrules if hrules: obj.set_table_styles( [ {"selector": "toprule", "props": ":toprule"}, {"selector": "midrule", "props": ":midrule"}, {"selector": "bottomrule", "props": ":bottomrule"}, ], overwrite=False, ) if label: obj.set_table_styles( [{"selector": "label", "props": f":{{{label.replace(':', '§')}}}"}], overwrite=False, ) if caption: obj.set_caption(caption) if sparse_index is None: sparse_index = get_option("styler.sparse.index") if sparse_columns is None: sparse_columns = get_option("styler.sparse.columns") environment = environment or get_option("styler.latex.environment") multicol_align = multicol_align or get_option("styler.latex.multicol_align") multirow_align = multirow_align or get_option("styler.latex.multirow_align") latex = obj._render_latex( sparse_index=sparse_index, sparse_columns=sparse_columns, multirow_align=multirow_align, multicol_align=multicol_align, environment=environment, convert_css=convert_css, siunitx=siunitx, clines=clines, ) encoding = ( (encoding or get_option("styler.render.encoding")) if isinstance(buf, str) # i.e. a filepath else encoding ) return save_to_buffer(latex, buf=buf, encoding=encoding) @overload def to_html( self, buf: FilePath | WriteBuffer[str], *, table_uuid: str | None = ..., table_attributes: str | None = ..., sparse_index: bool | None = ..., sparse_columns: bool | None = ..., bold_headers: bool = ..., caption: str | None = ..., max_rows: int | None = ..., max_columns: int | None = ..., encoding: str | None = ..., doctype_html: bool = ..., exclude_styles: bool = ..., **kwargs, ) -> None: ... @overload def to_html( self, buf: None = ..., *, table_uuid: str | None = ..., table_attributes: str | None = ..., sparse_index: bool | None = ..., sparse_columns: bool | None = ..., bold_headers: bool = ..., caption: str | None = ..., max_rows: int | None = ..., max_columns: int | None = ..., encoding: str | None = ..., doctype_html: bool = ..., exclude_styles: bool = ..., **kwargs, ) -> str: ... @Substitution(buf=buf, encoding=encoding) def to_html( self, buf: FilePath | WriteBuffer[str] | None = None, *, table_uuid: str | None = None, table_attributes: str | None = None, sparse_index: bool | None = None, sparse_columns: bool | None = None, bold_headers: bool = False, caption: str | None = None, max_rows: int | None = None, max_columns: int | None = None, encoding: str | None = None, doctype_html: bool = False, exclude_styles: bool = False, **kwargs, ) -> str | None: """ Write Styler to a file, buffer or string in HTML-CSS format. .. versionadded:: 1.3.0 Parameters ---------- %(buf)s table_uuid : str, optional Id attribute assigned to the HTML element in the format: ``
`` If not given uses Styler's initially assigned value. table_attributes : str, optional Attributes to assign within the `
` HTML element in the format: ``
>`` If not given defaults to Styler's preexisting value. sparse_index : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each row. Defaults to ``pandas.options.styler.sparse.index`` value. .. versionadded:: 1.4.0 sparse_columns : bool, optional Whether to sparsify the display of a hierarchical index. Setting to False will display each explicit level element in a hierarchical key for each column. Defaults to ``pandas.options.styler.sparse.columns`` value. .. versionadded:: 1.4.0 bold_headers : bool, optional Adds "font-weight: bold;" as a CSS property to table style header cells. .. versionadded:: 1.4.0 caption : str, optional Set, or overwrite, the caption on Styler before rendering. .. versionadded:: 1.4.0 max_rows : int, optional The maximum number of rows that will be rendered. Defaults to ``pandas.options.styler.render.max_rows/max_columns``. .. versionadded:: 1.4.0 max_columns : int, optional The maximum number of columns that will be rendered. Defaults to ``pandas.options.styler.render.max_columns``, which is None. Rows and columns may be reduced if the number of total elements is large. This value is set to ``pandas.options.styler.render.max_elements``, which is 262144 (18 bit browser rendering). .. versionadded:: 1.4.0 %(encoding)s doctype_html : bool, default False Whether to output a fully structured HTML file including all HTML elements, or just the core ``' '
' ' ' ' ' ' ' ' ' ' ' ' ' '
0
1
' """ if not classes.index.is_unique or not classes.columns.is_unique: raise KeyError( "Classes render only if `classes` has unique index and columns." ) classes = classes.reindex_like(self.data) for r, row_tup in enumerate(classes.itertuples()): for c, value in enumerate(row_tup[1:]): if not (pd.isna(value) or value == ""): self.cell_context[(r, c)] = str(value) return self def _update_ctx(self, attrs: DataFrame) -> None: """ Update the state of the ``Styler`` for data cells. Collects a mapping of {index_label: [('', ''), ..]}. Parameters ---------- attrs : DataFrame should contain strings of ': ;: ' Whitespace shouldn't matter and the final trailing ';' shouldn't matter. """ if not self.index.is_unique or not self.columns.is_unique: raise KeyError( "`Styler.apply` and `.applymap` are not compatible " "with non-unique index or columns." ) for cn in attrs.columns: j = self.columns.get_loc(cn) ser = attrs[cn] for rn, c in ser.items(): if not c or pd.isna(c): continue css_list = maybe_convert_css_to_tuples(c) i = self.index.get_loc(rn) self.ctx[(i, j)].extend(css_list) def _update_ctx_header(self, attrs: DataFrame, axis: int) -> None: """ Update the state of the ``Styler`` for header cells. Collects a mapping of {index_label: [('', ''), ..]}. Parameters ---------- attrs : Series Should contain strings of ': ;: ', and an integer index. Whitespace shouldn't matter and the final trailing ';' shouldn't matter. axis : int Identifies whether the ctx object being updated is the index or columns """ for j in attrs.columns: ser = attrs[j] for i, c in ser.items(): if not c: continue css_list = maybe_convert_css_to_tuples(c) if axis == 0: self.ctx_index[(i, j)].extend(css_list) else: self.ctx_columns[(j, i)].extend(css_list) def _copy(self, deepcopy: bool = False) -> Styler: """ Copies a Styler, allowing for deepcopy or shallow copy Copying a Styler aims to recreate a new Styler object which contains the same data and styles as the original. Data dependent attributes [copied and NOT exported]: - formatting (._display_funcs) - hidden index values or column values (.hidden_rows, .hidden_columns) - tooltips - cell_context (cell css classes) - ctx (cell css styles) - caption - concatenated stylers Non-data dependent attributes [copied and exported]: - css - hidden index state and hidden columns state (.hide_index_, .hide_columns_) - table_attributes - table_styles - applied styles (_todo) """ # GH 40675 styler = Styler( self.data, # populates attributes 'data', 'columns', 'index' as shallow ) shallow = [ # simple string or boolean immutables "hide_index_", "hide_columns_", "hide_column_names", "hide_index_names", "table_attributes", "cell_ids", "caption", "uuid", "uuid_len", "template_latex", # also copy templates if these have been customised "template_html_style", "template_html_table", "template_html", ] deep = [ # nested lists or dicts "css", "concatenated", "_display_funcs", "_display_funcs_index", "_display_funcs_columns", "hidden_rows", "hidden_columns", "ctx", "ctx_index", "ctx_columns", "cell_context", "_todo", "table_styles", "tooltips", ] for attr in shallow: setattr(styler, attr, getattr(self, attr)) for attr in deep: val = getattr(self, attr) setattr(styler, attr, copy.deepcopy(val) if deepcopy else val) return styler def __copy__(self) -> Styler: return self._copy(deepcopy=False) def __deepcopy__(self, memo) -> Styler: return self._copy(deepcopy=True) def clear(self) -> None: """ Reset the ``Styler``, removing any previously applied styles. Returns None. """ # create default GH 40675 clean_copy = Styler(self.data, uuid=self.uuid) clean_attrs = [a for a in clean_copy.__dict__ if not callable(a)] self_attrs = [a for a in self.__dict__ if not callable(a)] # maybe more attrs for attr in clean_attrs: setattr(self, attr, getattr(clean_copy, attr)) for attr in set(self_attrs).difference(clean_attrs): delattr(self, attr) def _apply( self, func: Callable, axis: Axis | None = 0, subset: Subset | None = None, **kwargs, ) -> Styler: subset = slice(None) if subset is None else subset subset = non_reducing_slice(subset) data = self.data.loc[subset] if data.empty: result = DataFrame() elif axis is None: result = func(data, **kwargs) if not isinstance(result, DataFrame): if not isinstance(result, np.ndarray): raise TypeError( f"Function {repr(func)} must return a DataFrame or ndarray " f"when passed to `Styler.apply` with axis=None" ) if not (data.shape == result.shape): raise ValueError( f"Function {repr(func)} returned ndarray with wrong shape.\n" f"Result has shape: {result.shape}\n" f"Expected shape: {data.shape}" ) result = DataFrame(result, index=data.index, columns=data.columns) else: axis = self.data._get_axis_number(axis) if axis == 0: result = data.apply(func, axis=0, **kwargs) else: result = data.T.apply(func, axis=0, **kwargs).T # see GH 42005 if isinstance(result, Series): raise ValueError( f"Function {repr(func)} resulted in the apply method collapsing to a " f"Series.\nUsually, this is the result of the function returning a " f"single value, instead of list-like." ) msg = ( f"Function {repr(func)} created invalid {{0}} labels.\nUsually, this is " f"the result of the function returning a " f"{'Series' if axis is not None else 'DataFrame'} which contains invalid " f"labels, or returning an incorrectly shaped, list-like object which " f"cannot be mapped to labels, possibly due to applying the function along " f"the wrong axis.\n" f"Result {{0}} has shape: {{1}}\n" f"Expected {{0}} shape: {{2}}" ) if not all(result.index.isin(data.index)): raise ValueError(msg.format("index", result.index.shape, data.index.shape)) if not all(result.columns.isin(data.columns)): raise ValueError( msg.format("columns", result.columns.shape, data.columns.shape) ) self._update_ctx(result) return self @Substitution(subset=subset) def apply( self, func: Callable, axis: Axis | None = 0, subset: Subset | None = None, **kwargs, ) -> Styler: """ Apply a CSS-styling function column-wise, row-wise, or table-wise. Updates the HTML representation with the result. Parameters ---------- func : function ``func`` should take a Series if ``axis`` in [0,1] and return a list-like object of same length, or a Series, not necessarily of same length, with valid index labels considering ``subset``. ``func`` should take a DataFrame if ``axis`` is ``None`` and return either an ndarray with the same shape or a DataFrame, not necessarily of the same shape, with valid index and columns labels considering ``subset``. .. versionchanged:: 1.3.0 .. versionchanged:: 1.4.0 axis : {0 or 'index', 1 or 'columns', None}, default 0 Apply to each column (``axis=0`` or ``'index'``), to each row (``axis=1`` or ``'columns'``), or to the entire DataFrame at once with ``axis=None``. %(subset)s **kwargs : dict Pass along to ``func``. Returns ------- self : Styler See Also -------- Styler.applymap_index: Apply a CSS-styling function to headers elementwise. Styler.apply_index: Apply a CSS-styling function to headers level-wise. Styler.applymap: Apply a CSS-styling function elementwise. Notes ----- The elements of the output of ``func`` should be CSS styles as strings, in the format 'attribute: value; attribute2: value2; ...' or, if nothing is to be applied to that element, an empty string or ``None``. This is similar to ``DataFrame.apply``, except that ``axis=None`` applies the function to the entire DataFrame at once, rather than column-wise or row-wise. Examples -------- >>> def highlight_max(x, color): ... return np.where(x == np.nanmax(x.to_numpy()), f"color: {color};", None) >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"]) >>> df.style.apply(highlight_max, color='red') # doctest: +SKIP >>> df.style.apply(highlight_max, color='blue', axis=1) # doctest: +SKIP >>> df.style.apply(highlight_max, color='green', axis=None) # doctest: +SKIP Using ``subset`` to restrict application to a single column or multiple columns >>> df.style.apply(highlight_max, color='red', subset="A") ... # doctest: +SKIP >>> df.style.apply(highlight_max, color='red', subset=["A", "B"]) ... # doctest: +SKIP Using a 2d input to ``subset`` to select rows in addition to columns >>> df.style.apply(highlight_max, color='red', subset=([0,1,2], slice(None))) ... # doctest: +SKIP >>> df.style.apply(highlight_max, color='red', subset=(slice(0,5,2), "A")) ... # doctest: +SKIP Using a function which returns a Series / DataFrame of unequal length but containing valid index labels >>> df = pd.DataFrame([[1, 2], [3, 4], [4, 6]], index=["A1", "A2", "Total"]) >>> total_style = pd.Series("font-weight: bold;", index=["Total"]) >>> df.style.apply(lambda s: total_style) # doctest: +SKIP See `Table Visualization <../../user_guide/style.ipynb>`_ user guide for more details. """ self._todo.append( (lambda instance: getattr(instance, "_apply"), (func, axis, subset), kwargs) ) return self def _apply_index( self, func: Callable, axis: int | str = 0, level: Level | list[Level] | None = None, method: str = "apply", **kwargs, ) -> Styler: axis = self.data._get_axis_number(axis) obj = self.index if axis == 0 else self.columns levels_ = refactor_levels(level, obj) data = DataFrame(obj.to_list()).loc[:, levels_] if method == "apply": result = data.apply(func, axis=0, **kwargs) elif method == "applymap": result = data.applymap(func, **kwargs) self._update_ctx_header(result, axis) return self @doc( this="apply", wise="level-wise", alt="applymap", altwise="elementwise", func="take a Series and return a string array of the same length", input_note="the index as a Series, if an Index, or a level of a MultiIndex", output_note="an identically sized array of CSS styles as strings", var="s", ret='np.where(s == "B", "background-color: yellow;", "")', ret2='["background-color: yellow;" if "x" in v else "" for v in s]', ) def apply_index( self, func: Callable, axis: int | str = 0, level: Level | list[Level] | None = None, **kwargs, ) -> Styler: """ Apply a CSS-styling function to the index or column headers, {wise}. Updates the HTML representation with the result. .. versionadded:: 1.4.0 Parameters ---------- func : function ``func`` should {func}. axis : {{0, 1, "index", "columns"}} The headers over which to apply the function. level : int, str, list, optional If index is MultiIndex the level(s) over which to apply the function. **kwargs : dict Pass along to ``func``. Returns ------- self : Styler See Also -------- Styler.{alt}_index: Apply a CSS-styling function to headers {altwise}. Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise. Styler.applymap: Apply a CSS-styling function elementwise. Notes ----- Each input to ``func`` will be {input_note}. The output of ``func`` should be {output_note}, in the format 'attribute: value; attribute2: value2; ...' or, if nothing is to be applied to that element, an empty string or ``None``. Examples -------- Basic usage to conditionally highlight values in the index. >>> df = pd.DataFrame([[1,2], [3,4]], index=["A", "B"]) >>> def color_b(s): ... return {ret} >>> df.style.{this}_index(color_b) # doctest: +SKIP .. figure:: ../../_static/style/appmaphead1.png Selectively applying to specific levels of MultiIndex columns. >>> midx = pd.MultiIndex.from_product([['ix', 'jy'], [0, 1], ['x3', 'z4']]) >>> df = pd.DataFrame([np.arange(8)], columns=midx) >>> def highlight_x({var}): ... return {ret2} >>> df.style.{this}_index(highlight_x, axis="columns", level=[0, 2]) ... # doctest: +SKIP .. figure:: ../../_static/style/appmaphead2.png """ self._todo.append( ( lambda instance: getattr(instance, "_apply_index"), (func, axis, level, "apply"), kwargs, ) ) return self @doc( apply_index, this="applymap", wise="elementwise", alt="apply", altwise="level-wise", func="take a scalar and return a string", input_note="an index value, if an Index, or a level value of a MultiIndex", output_note="CSS styles as a string", var="v", ret='"background-color: yellow;" if v == "B" else None', ret2='"background-color: yellow;" if "x" in v else None', ) def applymap_index( self, func: Callable, axis: int | str = 0, level: Level | list[Level] | None = None, **kwargs, ) -> Styler: self._todo.append( ( lambda instance: getattr(instance, "_apply_index"), (func, axis, level, "applymap"), kwargs, ) ) return self def _applymap( self, func: Callable, subset: Subset | None = None, **kwargs ) -> Styler: func = partial(func, **kwargs) # applymap doesn't take kwargs? if subset is None: subset = IndexSlice[:] subset = non_reducing_slice(subset) result = self.data.loc[subset].applymap(func) self._update_ctx(result) return self @Substitution(subset=subset) def applymap( self, func: Callable, subset: Subset | None = None, **kwargs ) -> Styler: """ Apply a CSS-styling function elementwise. Updates the HTML representation with the result. Parameters ---------- func : function ``func`` should take a scalar and return a string. %(subset)s **kwargs : dict Pass along to ``func``. Returns ------- self : Styler See Also -------- Styler.applymap_index: Apply a CSS-styling function to headers elementwise. Styler.apply_index: Apply a CSS-styling function to headers level-wise. Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise. Notes ----- The elements of the output of ``func`` should be CSS styles as strings, in the format 'attribute: value; attribute2: value2; ...' or, if nothing is to be applied to that element, an empty string or ``None``. Examples -------- >>> def color_negative(v, color): ... return f"color: {color};" if v < 0 else None >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"]) >>> df.style.applymap(color_negative, color='red') # doctest: +SKIP Using ``subset`` to restrict application to a single column or multiple columns >>> df.style.applymap(color_negative, color='red', subset="A") ... # doctest: +SKIP >>> df.style.applymap(color_negative, color='red', subset=["A", "B"]) ... # doctest: +SKIP Using a 2d input to ``subset`` to select rows in addition to columns >>> df.style.applymap(color_negative, color='red', ... subset=([0,1,2], slice(None))) # doctest: +SKIP >>> df.style.applymap(color_negative, color='red', subset=(slice(0,5,2), "A")) ... # doctest: +SKIP See `Table Visualization <../../user_guide/style.ipynb>`_ user guide for more details. """ self._todo.append( (lambda instance: getattr(instance, "_applymap"), (func, subset), kwargs) ) return self @Substitution(subset=subset) def where( self, cond: Callable, value: str, other: str | None = None, subset: Subset | None = None, **kwargs, ) -> Styler: """ Apply CSS-styles based on a conditional function elementwise. .. deprecated:: 1.3.0 Updates the HTML representation with a style which is selected in accordance with the return value of a function. Parameters ---------- cond : callable ``cond`` should take a scalar, and optional keyword arguments, and return a boolean. value : str Applied when ``cond`` returns true. other : str Applied when ``cond`` returns false. %(subset)s **kwargs : dict Pass along to ``cond``. Returns ------- self : Styler See Also -------- Styler.applymap: Apply a CSS-styling function elementwise. Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise. Notes ----- This method is deprecated. This method is a convenience wrapper for :meth:`Styler.applymap`, which we recommend using instead. The example: >>> df = pd.DataFrame([[1, 2], [3, 4]]) >>> def cond(v, limit=4): ... return v > 1 and v != limit >>> df.style.where(cond, value='color:green;', other='color:red;') ... # doctest: +SKIP should be refactored to: >>> def style_func(v, value, other, limit=4): ... cond = v > 1 and v != limit ... return value if cond else other >>> df.style.applymap(style_func, value='color:green;', other='color:red;') ... # doctest: +SKIP """ warnings.warn( "this method is deprecated in favour of `Styler.applymap()`", FutureWarning, stacklevel=find_stack_level(), ) if other is None: other = "" return self.applymap( lambda val: value if cond(val, **kwargs) else other, subset=subset, ) def set_precision(self, precision: int) -> StylerRenderer: """ Set the precision used to display values. .. deprecated:: 1.3.0 Parameters ---------- precision : int Returns ------- self : Styler Notes ----- This method is deprecated see `Styler.format`. """ warnings.warn( "this method is deprecated in favour of `Styler.format(precision=..)`", FutureWarning, stacklevel=find_stack_level(), ) self.precision = precision return self.format(precision=precision, na_rep=self.na_rep) def set_table_attributes(self, attributes: str) -> Styler: """ Set the table attributes added to the ```` HTML element. These are items in addition to automatic (by default) ``id`` attribute. Parameters ---------- attributes : str Returns ------- self : Styler See Also -------- Styler.set_table_styles: Set the table styles included within the ``