enh: support `DataFrame.plot.hist`

[fonnesbeck]

Checks

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of Polars.

Reproducible example

import polars as pl
import numpy as np

# Simulated DataFrame
np.random.seed(0)
data = {
    "shotRebound": np.random.randint(0, 2, size=1000)  # Simulating shot rebounds (0 or 1)
}
simulated_df = pl.DataFrame(data)

# Plotting the histogram
simulated_df.select(pl.col("shotRebound")).plot.hist(bins=30, title="Histogram of Shot Rebounds", xlabel="Shot Rebound", ylabel="Frequency")

Log output

AttributeError                            Traceback (most recent call last)
Cell In[26], line 12
      9 simulated_df = pl.DataFrame(data)
     11 # Plotting the histogram
---> 12 simulated_df.select(pl.col("shotRebound")).plot.hist(bins=30, title="Histogram of Shot Rebounds", xlabel="Shot Rebound", ylabel="Frequency")

File ~/repos/xg_model/.pixi/envs/default/lib/python3.12/site-packages/polars/dataframe/plotting.py:255, in DataFramePlot.__getattr__(self, attr)
    253 if method is None:
    254     msg = "Altair has no method 'mark_{attr}'"
--> 255     raise AttributeError(msg)
    256 return lambda **kwargs: method().encode(**kwargs).interactive()

AttributeError: Altair has no method 'mark_{attr}'

Issue description

Despite up-to-date versions of polars and altair being installed, plotting a histogram fails, apparently due to incompatibility between the two libraries.

Expected behavior

Plotted histogram

Installed versions

Details

--------Version info---------
Polars:              1.6.0
Index type:          UInt32
Platform:            Linux-6.9.12-200.fc40.x86_64-x86_64-with-glibc2.39
Python:              3.12.5 | packaged by conda-forge | (main, Aug  8 2024, 18:36:51) [GCC 12.4.0]

----Optional dependencies----
adbc_driver_manager  <not installed>
altair               5.4.1
cloudpickle          3.0.0
connectorx           <not installed>
deltalake            <not installed>
fastexcel            <not installed>
fsspec               <not installed>
gevent               <not installed>
great_tables         <not installed>
matplotlib           3.9.2
nest_asyncio         1.6.0
numpy                1.26.4
openpyxl             <not installed>
pandas               2.2.2
pyarrow              17.0.0
pydantic             <not installed>
pyiceberg            <not installed>
sqlalchemy           <not installed>
torch                <not installed>
xlsx2csv             <not installed>
xlsxwriter           <not installed>

[MarcoGorelli]

hey @fonnesbeck

the plotting methods in Polars are shorthand for some Altair ones, e.g.:

• df.plot.line(x='x', y='y') is shorthand for alt.Chart(df).mark_line().encode(x='x', y='y')
• df.plot.bar(x='x', y='y') is shorthand for alt.Chart(df).mark_bar().encode(x='x', y='y')

It's not meant to be perfectly backwards-compatible with the hvplot API

If you want to keep your plot working as before, you can add import hvplot.polars to the top of your script, and then do simulated_df.select(pl.col("shotRebound")).plot.hist(bins=30, title="Histogram of Shot Rebounds", xlabel="Shot Rebound", ylabel="Frequency")

will post an Altair solution soon

[MarcoGorelli]

Altair solution (requires an explicit import altair as alt - though I'd suggest trying df['shotRebound'].hist() in case the default is good enough)

import altair as alt

simulated_df.plot.bar(
    x=alt.X("shotRebound", bin=alt.Bin(maxbins=30), title="Shot Rebound"),
    y=alt.Y("count()", title="Frequency"),
).properties(title="Histogram of Shot Rebounds", width=600)

---

this may be common enough that max_bins could be added to Series.hist 🤔

[fonnesbeck]

Yikes, that's pretty verbose for a simple histogram!

[MarcoGorelli]

yup - some substantial improvements are on their way, just give it another week or so

[albertotb]

I've just hit the same issue. It is specially confusing because according to the docs here https://docs.pola.rs/api/python/stable/reference/series/plot.html it says that

s.plot.hist(**kwargs) is shorthand for alt.Chart(s.to_frame()).mark_bar(tooltip=True).encode(x=alt.X(f'{s.name}:Q', bin=True), y='count()', **kwargs).interactive()

However, when doing

size.plot.hist("len", bins=50, title="histogram")

the error is AttributeError: Altair has no method 'mark_hist'. So it seems that .plot.hist is not being mapped to mark_bar as the documentation suggests, but to mark_hist, which does not exists.

Note: I'm on polars 1.32

[MarcoGorelli]

hi @albertotb - what's size? If it's a dataframe, then the docs you've linked to are for Series.plot

[albertotb]

hi @albertotb - what's size? If it's a dataframe, then the docs you've linked to are for Series.plot

You are right, size is a Dataframe. Ok, then there is nothing confusing here because the DataFrame docs do not suggest that plot.hist() works. Just the same problem as reported by op, plot.hist not working for DataFrames.