diff --git a/pandas/core/generic.py b/pandas/core/generic.py index fd372ce2fd78e..9bdf34113ccf0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6081,89 +6081,191 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None, _shared_docs['interpolate'] = """ Please note that only ``method='linear'`` is supported for - DataFrames/Series with a MultiIndex. + DataFrame/Series with a MultiIndex. Parameters ---------- - method : {'linear', 'time', 'index', 'values', 'nearest', 'zero', - 'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh', - 'polynomial', 'spline', 'piecewise_polynomial', - 'from_derivatives', 'pchip', 'akima'} + method : str, default 'linear' + Interpolation technique to use. One of: - * 'linear': ignore the index and treat the values as equally + * 'linear': Ignore the index and treat the values as equally spaced. This is the only method supported on MultiIndexes. - default - * 'time': interpolation works on daily and higher resolution - data to interpolate given length of interval - * 'index', 'values': use the actual numerical values of the index - * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', - 'barycentric', 'polynomial' is passed to - :class:`scipy.interpolate.interp1d`. Both 'polynomial' and - 'spline' require that you also specify an `order` (int), + * 'time': Works on daily and higher resolution data to interpolate + given length of interval. + * 'index', 'values': use the actual numerical values of the index. + * 'pad': Fill in NaNs using existing values. + * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'spline', + 'barycentric', 'polynomial': Passed to + `scipy.interpolate.interp1d`. Both 'polynomial' and 'spline' + require that you also specify an `order` (int), e.g. ``df.interpolate(method='polynomial', order=4)``. - These use the actual numerical values of the index. - * 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima' - are all wrappers around the scipy interpolation methods of - similar names. These use the actual numerical values of the - index. For more information on their behavior, see the - `scipy documentation - `__ - and `tutorial documentation - `__ - * 'from_derivatives' refers to - :meth:`scipy.interpolate.BPoly.from_derivatives` which + These use the numerical values of the index. + * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima': + Wrappers around the SciPy interpolation methods of similar + names. See `Notes`. + * 'from_derivatives': Refers to + `scipy.interpolate.BPoly.from_derivatives` which replaces 'piecewise_polynomial' interpolation method in - scipy 0.18 + scipy 0.18. .. versionadded:: 0.18.1 Added support for the 'akima' method. Added interpolate method 'from_derivatives' which replaces - 'piecewise_polynomial' in scipy 0.18; backwards-compatible with - scipy < 0.18 - - axis : {0, 1}, default 0 - * 0: fill column-by-column - * 1: fill row-by-row - limit : int, default None. - Maximum number of consecutive NaNs to fill. Must be greater than 0. - limit_direction : {'forward', 'backward', 'both'}, default 'forward' - limit_area : {'inside', 'outside'}, default None - * None: (default) no fill restriction - * 'inside' Only fill NaNs surrounded by valid values (interpolate). - * 'outside' Only fill NaNs outside valid values (extrapolate). + 'piecewise_polynomial' in SciPy 0.18; backwards-compatible with + SciPy < 0.18 + axis : {0 or 'index', 1 or 'columns', None}, default None + Axis to interpolate along. + limit : int, optional + Maximum number of consecutive NaNs to fill. Must be greater than + 0. + inplace : bool, default False + Update the data in place if possible. + limit_direction : {'forward', 'backward', 'both'}, default 'forward' If limit is specified, consecutive NaNs will be filled in this direction. + limit_area : {`None`, 'inside', 'outside'}, default None + If limit is specified, consecutive NaNs will be filled with this + restriction. + + * ``None``: No fill restriction. + * 'inside': Only fill NaNs surrounded by valid values + (interpolate). + * 'outside': Only fill NaNs outside valid values (extrapolate). .. versionadded:: 0.21.0 - inplace : bool, default False - Update the NDFrame in place if possible. + downcast : optional, 'infer' or None, defaults to None Downcast dtypes if possible. - kwargs : keyword arguments to pass on to the interpolating function. + **kwargs + Keyword arguments to pass on to the interpolating function. Returns ------- - Series or DataFrame of same shape interpolated at the NaNs + Series or DataFrame + Returns the same object type as the caller, interpolated at + some or all ``NaN`` values See Also -------- - reindex, replace, fillna + fillna : Fill missing values using different methods. + scipy.interpolate.Akima1DInterpolator : Piecewise cubic polynomials + (Akima interpolator). + scipy.interpolate.BPoly.from_derivatives : Piecewise polynomial in the + Bernstein basis. + scipy.interpolate.interp1d : Interpolate a 1-D function. + scipy.interpolate.KroghInterpolator : Interpolate polynomial (Krogh + interpolator). + scipy.interpolate.PchipInterpolator : PCHIP 1-d monotonic cubic + interpolation. + scipy.interpolate.CubicSpline : Cubic spline data interpolator. + + Notes + ----- + The 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima' + methods are wrappers around the respective SciPy implementations of + similar names. These use the actual numerical values of the index. + For more information on their behavior, see the + `SciPy documentation + `__ + and `SciPy tutorial + `__. Examples -------- - - Filling in NaNs + Filling in ``NaN`` in a :class:`~pandas.Series` via linear + interpolation. >>> s = pd.Series([0, 1, np.nan, 3]) + >>> s + 0 0.0 + 1 1.0 + 2 NaN + 3 3.0 + dtype: float64 >>> s.interpolate() - 0 0 - 1 1 - 2 2 - 3 3 + 0 0.0 + 1 1.0 + 2 2.0 + 3 3.0 dtype: float64 + Filling in ``NaN`` in a Series by padding, but filling at most two + consecutive ``NaN`` at a time. + + >>> s = pd.Series([np.nan, "single_one", np.nan, + ... "fill_two_more", np.nan, np.nan, np.nan, + ... 4.71, np.nan]) + >>> s + 0 NaN + 1 single_one + 2 NaN + 3 fill_two_more + 4 NaN + 5 NaN + 6 NaN + 7 4.71 + 8 NaN + dtype: object + >>> s.interpolate(method='pad', limit=2) + 0 NaN + 1 single_one + 2 single_one + 3 fill_two_more + 4 fill_two_more + 5 fill_two_more + 6 NaN + 7 4.71 + 8 4.71 + dtype: object + + Filling in ``NaN`` in a Series via polynomial interpolation or splines: + Both 'polynomial' and 'spline' methods require that you also specify + an ``order`` (int). + + >>> s = pd.Series([0, 2, np.nan, 8]) + >>> s.interpolate(method='polynomial', order=2) + 0 0.000000 + 1 2.000000 + 2 4.666667 + 3 8.000000 + dtype: float64 + + Fill the DataFrame forward (that is, going down) along each column + using linear interpolation. + + Note how the last entry in column 'a' is interpolated differently, + because there is no entry after it to use for interpolation. + Note how the first entry in column 'b' remains ``NaN``, because there + is no entry befofe it to use for interpolation. + + >>> df = pd.DataFrame([(0.0, np.nan, -1.0, 1.0), + ... (np.nan, 2.0, np.nan, np.nan), + ... (2.0, 3.0, np.nan, 9.0), + ... (np.nan, 4.0, -4.0, 16.0)], + ... columns=list('abcd')) + >>> df + a b c d + 0 0.0 NaN -1.0 1.0 + 1 NaN 2.0 NaN NaN + 2 2.0 3.0 NaN 9.0 + 3 NaN 4.0 -4.0 16.0 + >>> df.interpolate(method='linear', limit_direction='forward', axis=0) + a b c d + 0 0.0 NaN -1.0 1.0 + 1 1.0 2.0 -2.0 5.0 + 2 2.0 3.0 -3.0 9.0 + 3 2.0 4.0 -4.0 16.0 + + Using polynomial interpolation. + + >>> df['d'].interpolate(method='polynomial', order=2) + 0 1.0 + 1 4.0 + 2 9.0 + 3 16.0 + Name: d, dtype: float64 """ @Appender(_shared_docs['interpolate'] % _shared_doc_kwargs)