Skip to content

Commit 8bb2cc1

Browse files
math-and-dataWillAyd
math-and-data
authored and
WillAyd
committed
DOC: update the pandas.Series/DataFrame.interpolate docstring (#20270)
1 parent f2302d6 commit 8bb2cc1

File tree

1 file changed

+152
-50
lines changed

1 file changed

+152
-50
lines changed

‎pandas/core/generic.py

+152-50
Original file line numberDiff line numberDiff line change
@@ -6081,89 +6081,191 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
60816081

60826082
_shared_docs['interpolate'] = """
60836083
Please note that only ``method='linear'`` is supported for
6084-
DataFrames/Series with a MultiIndex.
6084+
DataFrame/Series with a MultiIndex.
60856085
60866086
Parameters
60876087
----------
6088-
method : {'linear', 'time', 'index', 'values', 'nearest', 'zero',
6089-
'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh',
6090-
'polynomial', 'spline', 'piecewise_polynomial',
6091-
'from_derivatives', 'pchip', 'akima'}
6088+
method : str, default 'linear'
6089+
Interpolation technique to use. One of:
60926090
6093-
* 'linear': ignore the index and treat the values as equally
6091+
* 'linear': Ignore the index and treat the values as equally
60946092
spaced. This is the only method supported on MultiIndexes.
6095-
default
6096-
* 'time': interpolation works on daily and higher resolution
6097-
data to interpolate given length of interval
6098-
* 'index', 'values': use the actual numerical values of the index
6099-
* 'nearest', 'zero', 'slinear', 'quadratic', 'cubic',
6100-
'barycentric', 'polynomial' is passed to
6101-
:class:`scipy.interpolate.interp1d`. Both 'polynomial' and
6102-
'spline' require that you also specify an `order` (int),
6093+
* 'time': Works on daily and higher resolution data to interpolate
6094+
given length of interval.
6095+
* 'index', 'values': use the actual numerical values of the index.
6096+
* 'pad': Fill in NaNs using existing values.
6097+
* 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'spline',
6098+
'barycentric', 'polynomial': Passed to
6099+
`scipy.interpolate.interp1d`. Both 'polynomial' and 'spline'
6100+
require that you also specify an `order` (int),
61036101
e.g. ``df.interpolate(method='polynomial', order=4)``.
6104-
These use the actual numerical values of the index.
6105-
* 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima'
6106-
are all wrappers around the scipy interpolation methods of
6107-
similar names. These use the actual numerical values of the
6108-
index. For more information on their behavior, see the
6109-
`scipy documentation
6110-
<http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
6111-
and `tutorial documentation
6112-
<http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__
6113-
* 'from_derivatives' refers to
6114-
:meth:`scipy.interpolate.BPoly.from_derivatives` which
6102+
These use the numerical values of the index.
6103+
* 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima':
6104+
Wrappers around the SciPy interpolation methods of similar
6105+
names. See `Notes`.
6106+
* 'from_derivatives': Refers to
6107+
`scipy.interpolate.BPoly.from_derivatives` which
61156108
replaces 'piecewise_polynomial' interpolation method in
6116-
scipy 0.18
6109+
scipy 0.18.
61176110
61186111
.. versionadded:: 0.18.1
61196112
61206113
Added support for the 'akima' method.
61216114
Added interpolate method 'from_derivatives' which replaces
6122-
'piecewise_polynomial' in scipy 0.18; backwards-compatible with
6123-
scipy < 0.18
6124-
6125-
axis : {0, 1}, default 0
6126-
* 0: fill column-by-column
6127-
* 1: fill row-by-row
6128-
limit : int, default None.
6129-
Maximum number of consecutive NaNs to fill. Must be greater than 0.
6130-
limit_direction : {'forward', 'backward', 'both'}, default 'forward'
6131-
limit_area : {'inside', 'outside'}, default None
6132-
* None: (default) no fill restriction
6133-
* 'inside' Only fill NaNs surrounded by valid values (interpolate).
6134-
* 'outside' Only fill NaNs outside valid values (extrapolate).
6115+
'piecewise_polynomial' in SciPy 0.18; backwards-compatible with
6116+
SciPy < 0.18
61356117
6118+
axis : {0 or 'index', 1 or 'columns', None}, default None
6119+
Axis to interpolate along.
6120+
limit : int, optional
6121+
Maximum number of consecutive NaNs to fill. Must be greater than
6122+
0.
6123+
inplace : bool, default False
6124+
Update the data in place if possible.
6125+
limit_direction : {'forward', 'backward', 'both'}, default 'forward'
61366126
If limit is specified, consecutive NaNs will be filled in this
61376127
direction.
6128+
limit_area : {`None`, 'inside', 'outside'}, default None
6129+
If limit is specified, consecutive NaNs will be filled with this
6130+
restriction.
6131+
6132+
* ``None``: No fill restriction.
6133+
* 'inside': Only fill NaNs surrounded by valid values
6134+
(interpolate).
6135+
* 'outside': Only fill NaNs outside valid values (extrapolate).
61386136
61396137
.. versionadded:: 0.21.0
6140-
inplace : bool, default False
6141-
Update the NDFrame in place if possible.
6138+
61426139
downcast : optional, 'infer' or None, defaults to None
61436140
Downcast dtypes if possible.
6144-
kwargs : keyword arguments to pass on to the interpolating function.
6141+
**kwargs
6142+
Keyword arguments to pass on to the interpolating function.
61456143
61466144
Returns
61476145
-------
6148-
Series or DataFrame of same shape interpolated at the NaNs
6146+
Series or DataFrame
6147+
Returns the same object type as the caller, interpolated at
6148+
some or all ``NaN`` values
61496149
61506150
See Also
61516151
--------
6152-
reindex, replace, fillna
6152+
fillna : Fill missing values using different methods.
6153+
scipy.interpolate.Akima1DInterpolator : Piecewise cubic polynomials
6154+
(Akima interpolator).
6155+
scipy.interpolate.BPoly.from_derivatives : Piecewise polynomial in the
6156+
Bernstein basis.
6157+
scipy.interpolate.interp1d : Interpolate a 1-D function.
6158+
scipy.interpolate.KroghInterpolator : Interpolate polynomial (Krogh
6159+
interpolator).
6160+
scipy.interpolate.PchipInterpolator : PCHIP 1-d monotonic cubic
6161+
interpolation.
6162+
scipy.interpolate.CubicSpline : Cubic spline data interpolator.
6163+
6164+
Notes
6165+
-----
6166+
The 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima'
6167+
methods are wrappers around the respective SciPy implementations of
6168+
similar names. These use the actual numerical values of the index.
6169+
For more information on their behavior, see the
6170+
`SciPy documentation
6171+
<http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
6172+
and `SciPy tutorial
6173+
<http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__.
61536174
61546175
Examples
61556176
--------
6156-
6157-
Filling in NaNs
6177+
Filling in ``NaN`` in a :class:`~pandas.Series` via linear
6178+
interpolation.
61586179
61596180
>>> s = pd.Series([0, 1, np.nan, 3])
6181+
>>> s
6182+
0 0.0
6183+
1 1.0
6184+
2 NaN
6185+
3 3.0
6186+
dtype: float64
61606187
>>> s.interpolate()
6161-
0 0
6162-
1 1
6163-
2 2
6164-
3 3
6188+
0 0.0
6189+
1 1.0
6190+
2 2.0
6191+
3 3.0
61656192
dtype: float64
61666193
6194+
Filling in ``NaN`` in a Series by padding, but filling at most two
6195+
consecutive ``NaN`` at a time.
6196+
6197+
>>> s = pd.Series([np.nan, "single_one", np.nan,
6198+
... "fill_two_more", np.nan, np.nan, np.nan,
6199+
... 4.71, np.nan])
6200+
>>> s
6201+
0 NaN
6202+
1 single_one
6203+
2 NaN
6204+
3 fill_two_more
6205+
4 NaN
6206+
5 NaN
6207+
6 NaN
6208+
7 4.71
6209+
8 NaN
6210+
dtype: object
6211+
>>> s.interpolate(method='pad', limit=2)
6212+
0 NaN
6213+
1 single_one
6214+
2 single_one
6215+
3 fill_two_more
6216+
4 fill_two_more
6217+
5 fill_two_more
6218+
6 NaN
6219+
7 4.71
6220+
8 4.71
6221+
dtype: object
6222+
6223+
Filling in ``NaN`` in a Series via polynomial interpolation or splines:
6224+
Both 'polynomial' and 'spline' methods require that you also specify
6225+
an ``order`` (int).
6226+
6227+
>>> s = pd.Series([0, 2, np.nan, 8])
6228+
>>> s.interpolate(method='polynomial', order=2)
6229+
0 0.000000
6230+
1 2.000000
6231+
2 4.666667
6232+
3 8.000000
6233+
dtype: float64
6234+
6235+
Fill the DataFrame forward (that is, going down) along each column
6236+
using linear interpolation.
6237+
6238+
Note how the last entry in column 'a' is interpolated differently,
6239+
because there is no entry after it to use for interpolation.
6240+
Note how the first entry in column 'b' remains ``NaN``, because there
6241+
is no entry befofe it to use for interpolation.
6242+
6243+
>>> df = pd.DataFrame([(0.0, np.nan, -1.0, 1.0),
6244+
... (np.nan, 2.0, np.nan, np.nan),
6245+
... (2.0, 3.0, np.nan, 9.0),
6246+
... (np.nan, 4.0, -4.0, 16.0)],
6247+
... columns=list('abcd'))
6248+
>>> df
6249+
a b c d
6250+
0 0.0 NaN -1.0 1.0
6251+
1 NaN 2.0 NaN NaN
6252+
2 2.0 3.0 NaN 9.0
6253+
3 NaN 4.0 -4.0 16.0
6254+
>>> df.interpolate(method='linear', limit_direction='forward', axis=0)
6255+
a b c d
6256+
0 0.0 NaN -1.0 1.0
6257+
1 1.0 2.0 -2.0 5.0
6258+
2 2.0 3.0 -3.0 9.0
6259+
3 2.0 4.0 -4.0 16.0
6260+
6261+
Using polynomial interpolation.
6262+
6263+
>>> df['d'].interpolate(method='polynomial', order=2)
6264+
0 1.0
6265+
1 4.0
6266+
2 9.0
6267+
3 16.0
6268+
Name: d, dtype: float64
61676269
"""
61686270

61696271
@Appender(_shared_docs['interpolate'] % _shared_doc_kwargs)

0 commit comments

Comments
 (0)