DOC: operator methods accept dicts

[mkp-gebensleben]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.mul.html

Documentation problem

The operator methods such as DataFrame.mul seem to work fine with dicts, but this is not documented. An example follows.

Setup:

>>> import pandas as pd
>>> import numpy as np
>>> df = pd.DataFrame(columns=['A', 'B', 'C'], data=np.arange(3*3).reshape(3,3))
>>> df 
   A  B  C
0  0  1  2
1  3  4  5
2  6  7  8

Multiplication with Series or dict produces the same result:

factors = {'A':0, 'B': 1, 'C': 2}
factors_s = pd.Series(factors)
>>> df.mul(factors_s)
   A  B   C
0  0  1   4
1  0  4  10
2  0  7  16
>>> df.mul(factors) 
   A  B   C
0  0  1   4
1  0  4  10
2  0  7  16

However, the operation seems to be faster with a Series. (IPython %timeit)

>>> %timeit df.mul(factors)
329 µs ± 26.8 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
>>> %timeit df.mul(factors_s)
129 µs ± 1.48 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)

Suggested fix for documentation

If dicts can safely be used for the other parameter of the operator-methods, mention it in the documentation. If dicts only work coincidentally because of implementation details, leave documentation as is.

[BarkotBeyene]

I'm taking this issue. Would be great if you assigned it to me.