Styler Object and Customising the Display#

Styling and output display customisation should be performedafter the data in a DataFrame has been processed. The Styler isnot dynamically updated if further changes to the DataFrame are made. TheDataFrame.style attribute is a property that returns aStyler object. It has a_repr_html_ method defined on it so it is rendered automatically in Jupyter Notebook.

The Styler, which can be used for large data but is primarily designed for small data, currently has the ability to output to these formats:

• HTML

• LaTeX

• String (and CSV by extension)

• Excel

• (JSON is not currently available)

The first three of these have display customisation methods designed to format and customise the output. These include:

• Formatting values, the index and columns headers, using.format() and.format_index(),

• Renaming the index or column header labels, using.relabel_index()

• Hiding certain columns, the index and/or column headers, or index names, using.hide()

• Concatenating similar DataFrames, using.concat()

Formatting the Display#

[2]:

importpandasaspdimportnumpyasnpimportmatplotlibasmpldf=pd.DataFrame({"strings":["Adam","Mike"],"ints":[1,3],"floats":[1.123,1000.23]})df.style \.format(precision=3,thousands=".",decimal=",") \.format_index(str.upper,axis=1) \.relabel_index(["row 1","row 2"],axis=0)

[2]:

[3]:

weather_df=pd.DataFrame(np.random.rand(10,2)*5,index=pd.date_range(start="2021-01-01",periods=10),columns=["Tokyo","Beijing"])defrain_condition(v):ifv<1.75:return"Dry"elifv<2.75:return"Rain"return"Heavy Rain"defmake_pretty(styler):styler.set_caption("Weather Conditions")styler.format(rain_condition)styler.format_index(lambdav:v.strftime("%A"))styler.background_gradient(axis=None,vmin=1,vmax=5,cmap="YlGnBu")returnstylerweather_df

[3]:

[4]:

weather_df.loc["2021-01-04":"2021-01-08"].style.pipe(make_pretty)

[4]:

[5]:

df=pd.DataFrame(np.random.randn(5,5))df.style \.hide(subset=[0,2,4],axis=0) \.hide(subset=[0,2,4],axis=1)

[5]:

[6]:

show=[0,2,4]df.style \.hide([rowforrowindf.indexifrownotinshow],axis=0) \.hide([colforcolindf.columnsifcolnotinshow],axis=1)

[6]:

[7]:

summary_styler=df.agg(["sum","mean"]).style \.format(precision=3) \.relabel_index(["Sum","Average"])df.style.format(precision=1).concat(summary_styler)

[7]:

Styler Object and HTML#

TheStyler was originally constructed to support the wide array of HTML formatting options. Its HTML output creates an HTML<table> and leverages CSS styling language to manipulate many parameters including colors, fonts, borders, background, etc. Seehere for more information on styling HTML tables. This allows a lot of flexibility out of the box, and even enables web developers tointegrate DataFrames into their exiting user interface designs.

Below we demonstrate the default output, which looks very similar to the standard DataFrame HTML representation. But the HTML here has already attached some CSS classes to each cell, even if we haven’t yet created any styles. We can view these by calling the.to_html() method, which returns the raw HTML as string, which is useful for further processing or adding to a file - read on inMore about CSS andHTML. This section will also provide a walkthrough for how to convert this default output to represent a DataFrame output that is more communicative. For example how we can builds:

[8]:

df=pd.DataFrame([[38.0,2.0,18.0,22.0,21,np.nan],[19,439,6,452,226,232]],index=pd.Index(['Tumour (Positive)','Non-Tumour (Negative)'],name='Actual Label:'),columns=pd.MultiIndex.from_product([['Decision Tree','Regression','Random'],['Tumour','Non-Tumour']],names=['Model:','Predicted:']))df.style

[8]:

[10]:

s

[10]:

The first step we have taken is the create the Styler object from the DataFrame and then select the range of interest by hiding unwanted columns with.hide().

[11]:

s=df.style.format('{:.0f}').hide([('Random','Tumour'),('Random','Non-Tumour')],axis="columns")s

[11]:

Methods to Add Styles#

There are3 primary methods of adding custom CSS styles toStyler:

• Using.set_table_styles() to control broader areas of the table with specified internal CSS. Although table styles allow the flexibility to add CSS selectors and properties controlling all individual parts of the table, they are unwieldy for individual cell specifications. Also, note that table styles cannot be exported to Excel.

• Using.set_td_classes() to directly link either external CSS classes to your data cells or link the internal CSS classes created by.set_table_styles(). Seehere. These cannot be used on column header rows or indexes, and also won’t export to Excel.

• Using the.apply() and.map() functions to add direct internal CSS to specific data cells. Seehere. As of v1.4.0 there are also methods that work directly on column header rows or indexes;.apply_index() and.map_index(). Note that only these methods add styles that will export to Excel. These methods work in a similar way toDataFrame.apply() andDataFrame.map().

Table Styles#

Table styles are flexible enough to control all individual parts of the table, including column headers and indexes. However, they can be unwieldy to type for individual data cells or for any kind of conditional formatting, so we recommend that table styles are used for broad styling, such as entire rows or columns at a time.

Table styles are also used to control features which can apply to the whole table at once such as creating a generic hover functionality. The:hover pseudo-selector, as well as other pseudo-selectors, can only be used this way.

To replicate the normal format of CSS selectors and properties (attribute value pairs), e.g.

tr:hover {  background-color: #ffff99;}

the necessary format to pass styles to.set_table_styles() is as a list of dicts, each with a CSS-selector tag and CSS-properties. Properties can either be a list of 2-tuples, or a regular CSS-string, for example:

[13]:

cell_hover={# for row hover use <tr> instead of <td>'selector':'td:hover','props':[('background-color','#ffffb3')]}index_names={'selector':'.index_name','props':'font-style: italic; color: darkgrey; font-weight:normal;'}headers={'selector':'th:not(.index_name)','props':'background-color: #000066; color: white;'}s.set_table_styles([cell_hover,index_names,headers])

[13]:

Next we just add a couple more styling artifacts targeting specific parts of the table. Be careful here, since we arechaining methods we need to explicitly instruct the methodnot tooverwrite the existing styles.

[15]:

s.set_table_styles([{'selector':'th.col_heading','props':'text-align: center;'},{'selector':'th.col_heading.level0','props':'font-size: 1.5em;'},{'selector':'td','props':'text-align: center; font-weight: bold;'},],overwrite=False)

[15]:

As a convenience method (since version 1.2.0) we can also pass adict to.set_table_styles() which contains row or column keys. Behind the scenes Styler just indexes the keys and adds relevant.col<m> or.row<n> classes as necessary to the given CSS selectors.

[17]:

s.set_table_styles({('Regression','Tumour'):[{'selector':'th','props':'border-left: 1px solid white'},{'selector':'td','props':'border-left: 1px solid #000066'}]},overwrite=False,axis=0)

[17]:

Setting Classes and Linking to External CSS#

If you have designed a website then it is likely you will already have an external CSS file that controls the styling of table and cell objects within it. You may want to use these native files rather than duplicate all the CSS in python (and duplicate any maintenance work).

[19]:

out=s.set_table_attributes('class="my-table-cls"').to_html()print(out[out.find('<table'):][:109])

<table id="T_xyz01" class="my-table-cls">  <thead>    <tr>      <th class="index_name level0" >Model:</th>

[20]:

s.set_table_styles([# create internal CSS classes{'selector':'.true','props':'background-color: #e6ffe6;'},{'selector':'.false','props':'background-color: #ffe6e6;'},],overwrite=False)cell_color=pd.DataFrame([['true ','false ','true ','false '],['false ','true ','false ','true ']],index=df.index,columns=df.columns[:4])s.set_td_classes(cell_color)

[20]:

Styler Functions#

[22]:

np.random.seed(0)df2=pd.DataFrame(np.random.randn(10,4),columns=['A','B','C','D'])df2.style

[22]:

[23]:

defstyle_negative(v,props=''):returnpropsifv<0elseNones2=df2.style.map(style_negative,props='color:red;')\.map(lambdav:'opacity: 20%;'if(v<0.3)and(v>-0.3)elseNone)s2

[23]:

[25]:

defhighlight_max(s,props=''):returnnp.where(s==np.nanmax(s.values),props,'')s2.apply(highlight_max,props='color:white;background-color:darkblue',axis=0)

[25]:

[27]:

s2.apply(highlight_max,props='color:white;background-color:pink;',axis=1)\.apply(highlight_max,props='color:white;background-color:purple',axis=None)

[27]:

[29]:

s2.map_index(lambdav:"color:pink;"ifv>4else"color:darkblue;",axis=0)s2.apply_index(lambdas:np.where(s.isin(["A","B"]),"color:pink;","color:darkblue;"),axis=1)

[29]:

Tooltips and Captions#

Table captions can be added with the.set_caption() method. You can use table styles to control the CSS relevant to the caption.

[30]:

s.set_caption("Confusion matrix for multiple cancer prediction models.")\.set_table_styles([{'selector':'caption','props':'caption-side: bottom; font-size:1.25em;'}],overwrite=False)

[30]:

Adding tooltips (since version 1.3.0) can be done using the.set_tooltips() method in the same way you can add CSS classes to data cells by providing a string based DataFrame with intersecting indices and columns. You don’t have to specify acss_class name or any cssprops for the tooltips, since there are standard defaults, but the option is there if you want more visual control.

[32]:

tt=pd.DataFrame([['This model has a very strong true positive rate',"This model's total number of false negatives is too high"]],index=['Tumour (Positive)'],columns=df.columns[[0,3]])s.set_tooltips(tt,props='visibility: hidden; position: absolute; z-index: 1; border: 1px solid #000066;''background-color: white; color: #000066; font-size: 0.8em;''transform: translate(0px, -24px); padding: 0.6em; border-radius: 0.5em;')

[32]:

The only thing left to do for our table is to add the highlighting borders to draw the audience attention to the tooltips. We will create internal CSS classes as before using table styles.Setting classes always overwrites so we need to make sure we add the previous classes.

[34]:

s.set_table_styles([# create internal CSS classes{'selector':'.border-red','props':'border: 2px dashed red;'},{'selector':'.border-green','props':'border: 2px dashed green;'},],overwrite=False)cell_border=pd.DataFrame([['border-green ',' ',' ','border-red '],[' ',' ',' ',' ']],index=df.index,columns=df.columns[:4])s.set_td_classes(cell_color+cell_border)

[34]:

Finer Control with Slicing#

The examples we have shown so far for theStyler.apply andStyler.map functions have not demonstrated the use of thesubset argument. This is a useful argument which permits a lot of flexibility: it allows you to apply styles to specific rows or columns, without having to code that logic into yourstyle function.

The value passed tosubset behaves similar to slicing a DataFrame;

• A scalar is treated as a column label

• A list (or Series or NumPy array) is treated as multiple column labels

• A tuple is treated as(row_indexer,column_indexer)

Consider usingpd.IndexSlice to construct the tuple for the last one. We will create a MultiIndexed DataFrame to demonstrate the functionality.

[36]:

df3=pd.DataFrame(np.random.randn(4,4),pd.MultiIndex.from_product([['A','B'],['r1','r2']]),columns=['c1','c2','c3','c4'])df3

[36]:

We will use subset to highlight the maximum in the third and fourth columns with red text. We will highlight the subset sliced region in yellow.

[37]:

slice_=['c3','c4']df3.style.apply(highlight_max,props='color:red;',axis=0,subset=slice_)\.set_properties(**{'background-color':'#ffffb3'},subset=slice_)

[37]:

If combined with theIndexSlice as suggested then it can index across both dimensions with greater flexibility.

[38]:

idx=pd.IndexSliceslice_=idx[idx[:,'r1'],idx['c2':'c4']]df3.style.apply(highlight_max,props='color:red;',axis=0,subset=slice_)\.set_properties(**{'background-color':'#ffffb3'},subset=slice_)

[38]:

This also provides the flexibility to sub select rows when used with theaxis=1.

[39]:

slice_=idx[idx[:,'r2'],:]df3.style.apply(highlight_max,props='color:red;',axis=1,subset=slice_)\.set_properties(**{'background-color':'#ffffb3'},subset=slice_)

[39]:

There is also scope to provideconditional filtering.

Suppose we want to highlight the maximum across columns 2 and 4 only in the case that the sum of columns 1 and 3 is less than -2.0(essentially excluding rows(:,'r2')).

[40]:

slice_=idx[idx[(df3['c1']+df3['c3'])<-2.0],['c2','c4']]df3.style.apply(highlight_max,props='color:red;',axis=1,subset=slice_)\.set_properties(**{'background-color':'#ffffb3'},subset=slice_)

[40]:

Only label-based slicing is supported right now, not positional, and not callables.

If your style function uses asubset oraxis keyword argument, consider wrapping your function in afunctools.partial, partialing out that keyword.

my_func2=functools.partial(my_func,subset=42)

Optimization#

Generally, for smaller tables and most cases, the rendered HTML does not need to be optimized, and we don’t really recommend it. There are two cases where it is worth considering:

• If you are rendering and styling a very large HTML table, certain browsers have performance issues.

• If you are usingStyler to dynamically create part of online user interfaces and want to improve network performance.

Here we recommend the following steps to implement:

[41]:

df4=pd.DataFrame([[1,2],[3,4]])s4=df4.style

[42]:

frompandas.io.formats.styleimportStylers4=Styler(df4,uuid_len=0,cell_ids=False)

[43]:

props='font-family: "Times New Roman", Times, serif; color: #e83e8c; font-size:1.3em;'df4.style.map(lambdax:props,subset=[1])

[43]:

[44]:

df4.style.set_table_styles([{'selector':'td.col1','props':props}])

[44]:

[45]:

df2.style.apply(highlight_max,props='color:white;background-color:darkblue;',axis=0)\.apply(highlight_max,props='color:white;background-color:pink;',axis=1)\.apply(highlight_max,props='color:white;background-color:purple',axis=None)

[45]:

[46]:

build=lambdax:pd.DataFrame(x,index=df2.index,columns=df2.columns)cls1=build(df2.apply(highlight_max,props='cls-1 ',axis=0))cls2=build(df2.apply(highlight_max,props='cls-2 ',axis=1,result_type='expand').values)cls3=build(highlight_max(df2,props='cls-3 '))df2.style.set_table_styles([{'selector':'.cls-1','props':'color:white;background-color:darkblue;'},{'selector':'.cls-2','props':'color:white;background-color:pink;'},{'selector':'.cls-3','props':'color:white;background-color:purple;'}]).set_td_classes(cls1+cls2+cls3)

[46]:

[47]:

my_css={"row_heading":"","col_heading":"","index_name":"","col":"c","row":"r","col_trim":"","row_trim":"","level":"l","data":"","blank":"",}html=Styler(df4,uuid_len=0,cell_ids=False)html.set_table_styles([{'selector':'td','props':props},{'selector':'.c1','props':'color:green;'},{'selector':'.l0','props':'color:blue;'}],css_class_names=my_css)print(html.to_html())

<style type="text/css">#T_ td {  font-family: "Times New Roman", Times, serif;  color: #e83e8c;  font-size: 1.3em;}#T_ .c1 {  color: green;}#T_ .l0 {  color: blue;}</style><table id="T_">  <thead>    <tr>      <th class=" l0" >&nbsp;</th>      <th class=" l0 c0" >0</th>      <th class=" l0 c1" >1</th>    </tr>  </thead>  <tbody>    <tr>      <th class=" l0 r0" >0</th>      <td class=" r0 c0" >1</td>      <td class=" r0 c1" >2</td>    </tr>    <tr>      <th class=" l0 r1" >1</th>      <td class=" r1 c0" >3</td>      <td class=" r1 c1" >4</td>    </tr>  </tbody></table>

[48]:

html

[48]:

Builtin Styles#

Some styling functions are common enough that we’ve “built them in” to theStyler, so you don’t have to write them and apply them yourself. The current list of such functions is:

• .highlight_null: for use with identifying missing data.

• .highlight_min and.highlight_max: for use with identifying extremeties in data.

• .highlight_between and.highlight_quantile: for use with identifying classes within data.

• .background_gradient: a flexible method for highlighting cells based on their, or other, values on a numeric scale.

• .text_gradient: similar method for highlighting text based on their, or other, values on a numeric scale.

• .bar: to display mini-charts within cell backgrounds.

The individual documentation on each function often gives more examples of their arguments.

[49]:

df2.iloc[0,2]=np.nandf2.iloc[4,3]=np.nandf2.loc[:4].style.highlight_null(color='yellow')

[49]:

[50]:

df2.loc[:4].style.highlight_max(axis=1,props='color:white; font-weight:bold; background-color:darkblue;')

[50]:

[51]:

left=pd.Series([1.0,0.0,1.0],index=["A","B","D"])df2.loc[:4].style.highlight_between(left=left,right=1.5,axis=1,props='color:white; background-color:purple;')

[51]:

[52]:

df2.loc[:4].style.highlight_quantile(q_left=0.85,axis=None,color='yellow')

[52]:

[53]:

importseabornassnscm=sns.light_palette("green",as_cmap=True)df2.style.background_gradient(cmap=cm)

[53]:

[54]:

df2.style.text_gradient(cmap=cm)

[54]:

[55]:

df2.loc[:4].style.set_properties(**{'background-color':'black','color':'lawngreen','border-color':'white'})

[55]:

[56]:

df2.style.bar(subset=['A','B'],color='#d65f5f')

[56]:

[57]:

df2.style.format('{:.3f}',na_rep="")\.bar(align=0,vmin=-2.5,vmax=2.5,cmap="bwr",height=50,width=60,props="width: 120px; border-right: 1px solid black;")\.text_gradient(cmap="bwr",vmin=-2.5,vmax=2.5)

[57]:

[59]:

HTML(head)

[59]:

Sharing styles#

Say you have a lovely style built up for a DataFrame, and now you want to apply the same style to a second DataFrame. Export the style withdf1.style.export, and import it on the second DataFrame withdf1.style.set

[60]:

style1=df2.style\.map(style_negative,props='color:red;')\.map(lambdav:'opacity: 20%;'if(v<0.3)and(v>-0.3)elseNone)\.set_table_styles([{"selector":"th","props":"color: blue;"}])\.hide(axis="index")style1

[60]:

[61]:

style2=df3.stylestyle2.use(style1.export())style2

[61]:

Notice that you’re able to share the styles even though they’re data aware. The styles are re-evaluated on the new DataFrame they’ve beenused upon.

Limitations#

• DataFrame only (useSeries.to_frame().style)

• The index and columns do not need to be unique, but certain styling functions can only work with unique indexes.

• No large repr, and construction performance isn’t great; although we have someHTML optimizations

• You can only apply styles, you can’t insert new HTML entities, except via subclassing.

Other Fun and Useful Stuff#

Here are a few interesting examples.

[62]:

fromipywidgetsimportwidgets@widgets.interactdeff(h_neg=(0,359,1),h_pos=(0,359),s=(0.,99.9),l=(0.,99.9)):returndf2.style.background_gradient(cmap=sns.palettes.diverging_palette(h_neg=h_neg,h_pos=h_pos,s=s,l=l,as_cmap=True))

[63]:

defmagnify():return[dict(selector="th",props=[("font-size","4pt")]),dict(selector="td",props=[('padding',"0em 0em")]),dict(selector="th:hover",props=[("font-size","12pt")]),dict(selector="tr:hover td:hover",props=[('max-width','200px'),('font-size','12pt')])]

[64]:

np.random.seed(25)cmap=cmap=sns.diverging_palette(5,250,as_cmap=True)bigdf=pd.DataFrame(np.random.randn(20,25)).cumsum()bigdf.style.background_gradient(cmap,axis=1)\.set_properties(**{'max-width':'80px','font-size':'1pt'})\.set_caption("Hover to magnify")\.format(precision=2)\.set_table_styles(magnify())

[64]:

[65]:

bigdf=pd.DataFrame(np.random.randn(16,100))bigdf.style.set_sticky(axis="index")

[65]:

[66]:

bigdf.index=pd.MultiIndex.from_product([["A","B"],[0,1],[0,1,2,3]])bigdf.style.set_sticky(axis="index",pixel_size=18,levels=[1,2])