diff --git a/pandas/core/frame.py b/pandas/core/frame.py index f7f1855a4fabc..46651ee83d6f2 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -931,16 +931,70 @@ def __len__(self): def dot(self, other): """ - Matrix multiplication with DataFrame or Series objects. Can also be - called using `self @ other` in Python >= 3.5. + Compute the matrix mutiplication 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 : DataFrame or Series + other : Series, DataFrame or array-like + The other object to compute the matrix product with. Returns ------- - dot_product : DataFrame or Series + 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. + + 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 """ if isinstance(other, (Series, DataFrame)): common = self.columns.union(other.index)