Skip to content

Commit 77e97d2

Browse files
DOC: Add documentation to __add__ (#50527)
* Add documentation to __add__ * Update examples for consistency with other docs * Minor clean-up * Update docs * Clean up indentation * Additional indentation fixing * Indentation * Indentation * Column reference consistency
1 parent 852518e commit 77e97d2

File tree

2 files changed

+87
-0
lines changed

2 files changed

+87
-0
lines changed

doc/source/reference/frame.rst

+1
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ Binary operator functions
8383
.. autosummary::
8484
:toctree: api/
8585

86+
DataFrame.__add__
8687
DataFrame.add
8788
DataFrame.sub
8889
DataFrame.mul

pandas/core/arraylike.py

+86
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,92 @@ def _arith_method(self, other, op):
9797

9898
@unpack_zerodim_and_defer("__add__")
9999
def __add__(self, other):
100+
"""
101+
Get Addition of DataFrame and other, column-wise.
102+
103+
Equivalent to ``DataFrame.add(other)``.
104+
105+
Parameters
106+
----------
107+
other : scalar, sequence, Series, dict or DataFrame
108+
Object to be added to the DataFrame.
109+
110+
Returns
111+
-------
112+
DataFrame
113+
The result of adding ``other`` to DataFrame.
114+
115+
See Also
116+
--------
117+
DataFrame.add : Add a DataFrame and another object, with option for index-
118+
or column-oriented addition.
119+
120+
Examples
121+
--------
122+
>>> df = pd.DataFrame({'height': [1.5, 2.6], 'weight': [500, 800]},
123+
... index=['elk', 'moose'])
124+
>>> df
125+
height weight
126+
elk 1.5 500
127+
moose 2.6 800
128+
129+
Adding a scalar affects all rows and columns.
130+
131+
>>> df[['height', 'weight']] + 1.5
132+
height weight
133+
elk 3.0 501.5
134+
moose 4.1 801.5
135+
136+
Each element of a list is added to a column of the DataFrame, in order.
137+
138+
>>> df[['height', 'weight']] + [0.5, 1.5]
139+
height weight
140+
elk 2.0 501.5
141+
moose 3.1 801.5
142+
143+
Keys of a dictionary are aligned to the DataFrame, based on column names;
144+
each value in the dictionary is added to the corresponding column.
145+
146+
>>> df[['height', 'weight']] + {'height': 0.5, 'weight': 1.5}
147+
height weight
148+
elk 2.0 501.5
149+
moose 3.1 801.5
150+
151+
When `other` is a :class:`Series`, the index of `other` is aligned with the
152+
columns of the DataFrame.
153+
154+
>>> s1 = pd.Series([0.5, 1.5], index=['weight', 'height'])
155+
>>> df[['height', 'weight']] + s1
156+
height weight
157+
elk 3.0 500.5
158+
moose 4.1 800.5
159+
160+
Even when the index of `other` is the same as the index of the DataFrame,
161+
the :class:`Series` will not be reoriented. If index-wise alignment is desired,
162+
:meth:`DataFrame.add` should be used with `axis='index'`.
163+
164+
>>> s2 = pd.Series([0.5, 1.5], index=['elk', 'moose'])
165+
>>> df[['height', 'weight']] + s2
166+
elk height moose weight
167+
elk NaN NaN NaN NaN
168+
moose NaN NaN NaN NaN
169+
170+
>>> df[['height', 'weight']].add(s2, axis='index')
171+
height weight
172+
elk 2.0 500.5
173+
moose 4.1 801.5
174+
175+
When `other` is a :class:`DataFrame`, both columns names and the
176+
index are aligned.
177+
178+
>>> other = pd.DataFrame({'height': [0.2, 0.4, 0.6]},
179+
... index=['elk', 'moose', 'deer'])
180+
>>> df[['height', 'weight']] + other
181+
height weight
182+
deer NaN NaN
183+
elk 1.7 NaN
184+
moose 3.0 NaN
185+
"""
100186
return self._arith_method(other, operator.add)
101187

102188
@unpack_zerodim_and_defer("__radd__")

0 commit comments

Comments
 (0)