DOC: Highlighted role of index alignment in DataFrame.dot(other) (#26…

[matsmaiwald]

…480)

• closes pd.DataFrame.dot does not work when column index is set #26480
• tests passed

Added note highlighting that column names of DataFrame and index of other need to same.
Added example showing that reshuffling of objects does not change which elements are multiplied with which.

[matsmaiwald]

Output of doctest:

################################################################################
####################### Docstring (pandas.DataFrame.dot) #######################
################################################################################

Compute the matrix multiplication between the DataFrame and other.

This method computes the matrix product between the DataFrame and the
values of an other Series, DataFrame or a numpy array.

It can also be called using self @ other in Python >= 3.5.

Parameters

other : Series, DataFrame or array-like
The other object to compute the matrix product with.

Returns

Series or DataFrame
If other is a Series, return the matrix product between self and
other as a Serie. If other is a DataFrame or a numpy.array, return
the matrix product of self and other in a DataFrame of a np.array.

See Also

Series.dot: Similar method for Series.

Notes

The dimensions of DataFrame and other must be compatible in order to
compute the matrix multiplication. In addition, the column names of
DataFrame and the index of other must contain the same values, as they
will be aligned prior to the multiplication.

The dot method for Series computes the inner product, instead of the
matrix product here.

Examples

Here we multiply a DataFrame with a Series.

df = pd.DataFrame([[0, 1, -2, -1], [1, 1, 1, 1]])
s = pd.Series([1, 1, 2, 1])
df.dot(s)
0 -4
1 5
dtype: int64

Here we multiply a DataFrame with another DataFrame.

other = pd.DataFrame([[0, 1], [1, 2], [-1, -1], [2, 0]])
df.dot(other)
0 1
0 1 4
1 2 2

Note that the dot method give the same result as @

df @ other
0 1
0 1 4
1 2 2

The dot method works also if other is an np.array.

arr = np.array([[0, 1], [1, 2], [-1, -1], [2, 0]])
df.dot(arr)
0 1
0 1 4
1 2 2

Note how shuffling of the objects does not change the result.

s2 = s.reindex([1, 0, 2, 3])
df.dot(s2)
0 -4
1 5
dtype: int64

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.dot" correct. :)

[codecov]

Codecov Report

Merging #26496 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #26496      +/-   ##
==========================================
- Coverage   91.75%   91.74%   -0.01%     
==========================================
  Files         174      174              
  Lines       50761    50761              
==========================================
- Hits        46575    46571       -4     
- Misses       4186     4190       +4

Flag	Coverage Δ
#multiple	90.25% <ø> (ø)	⬆️
#single	41.71% <ø> (-0.09%)	⬇️

Impacted Files	Coverage Δ
pandas/core/frame.py	97.02% <ø> (-0.12%)	⬇️
pandas/io/gbq.py	78.94% <0%> (-10.53%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6d2398a...c157e82. Read the comment docs.

[TomAugspurger]

Thanks @matsmaiwald!