diff --git a/pandas/core/algorithms.py b/pandas/core/algorithms.py index 1a4368ee8ea98..3c4fe519e4181 100644 --- a/pandas/core/algorithms.py +++ b/pandas/core/algorithms.py @@ -289,6 +289,11 @@ def unique(values): - If the input is a Categorical dtype, the return is a Categorical - If the input is a Series/ndarray, the return will be an ndarray + See Also + -------- + pandas.Index.unique + pandas.Series.unique + Examples -------- >>> pd.unique(pd.Series([2, 1, 3, 3])) @@ -338,11 +343,6 @@ def unique(values): >>> pd.unique([('a', 'b'), ('b', 'a'), ('a', 'c'), ('b', 'a')]) array([('a', 'b'), ('b', 'a'), ('a', 'c')], dtype=object) - - See Also - -------- - pandas.Index.unique - pandas.Series.unique """ values = _ensure_arraylike(values) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 938ca53b5fdce..6e96fc75daec9 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -273,6 +273,16 @@ class Categorical(ExtensionArray, PandasObject): If an explicit ``ordered=True`` is given but no `categories` and the `values` are not sortable. + See Also + -------- + pandas.api.types.CategoricalDtype : Type for categorical data. + CategoricalIndex : An Index with an underlying ``Categorical``. + + Notes + ----- + See the `user guide + `_ for more. + Examples -------- >>> pd.Categorical([1, 2, 3, 1, 2, 3]) @@ -293,16 +303,6 @@ class Categorical(ExtensionArray, PandasObject): Categories (3, object): [c < b < a] >>> c.min() 'c' - - Notes - ----- - See the `user guide - `_ for more. - - See Also - -------- - pandas.api.types.CategoricalDtype : Type for categorical data. - CategoricalIndex : An Index with an underlying ``Categorical``. """ # For comparisons, so that numpy uses our implementation if the compare @@ -827,11 +827,6 @@ def set_categories(self, new_categories, ordered=None, rename=False, dtypes on python3, which does not considers a S1 string equal to a single char python string. - Raises - ------ - ValueError - If new_categories does not validate as categories - Parameters ---------- new_categories : Index-like @@ -850,6 +845,11 @@ def set_categories(self, new_categories, ordered=None, rename=False, ------- cat : Categorical with reordered categories or None if inplace. + Raises + ------ + ValueError + If new_categories does not validate as categories + See Also -------- rename_categories @@ -882,12 +882,6 @@ def rename_categories(self, new_categories, inplace=False): """ Renames categories. - Raises - ------ - ValueError - If new categories are list-like and do not have the same number of - items than the current categories or do not validate as categories - Parameters ---------- new_categories : list-like, dict-like or callable @@ -922,6 +916,12 @@ def rename_categories(self, new_categories, inplace=False): With ``inplace=False``, the new categorical is returned. With ``inplace=True``, there is no return value. + Raises + ------ + ValueError + If new categories are list-like and do not have the same number of + items than the current categories or do not validate as categories + See Also -------- reorder_categories @@ -979,12 +979,6 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False): `new_categories` need to include all old categories and no new category items. - Raises - ------ - ValueError - If the new categories do not contain all old category items or any - new ones - Parameters ---------- new_categories : Index-like @@ -1000,6 +994,12 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False): ------- cat : Categorical with reordered categories or None if inplace. + Raises + ------ + ValueError + If the new categories do not contain all old category items or any + new ones + See Also -------- rename_categories @@ -1022,12 +1022,6 @@ def add_categories(self, new_categories, inplace=False): `new_categories` will be included at the last/highest place in the categories and will be unused directly after this call. - Raises - ------ - ValueError - If the new categories include old categories or do not validate as - categories - Parameters ---------- new_categories : category or list-like of category @@ -1040,6 +1034,12 @@ def add_categories(self, new_categories, inplace=False): ------- cat : Categorical with new categories added or None if inplace. + Raises + ------ + ValueError + If the new categories include old categories or do not validate as + categories + See Also -------- rename_categories @@ -1072,11 +1072,6 @@ def remove_categories(self, removals, inplace=False): `removals` must be included in the old categories. Values which were in the removed categories will be set to NaN - Raises - ------ - ValueError - If the removals are not contained in the categories - Parameters ---------- removals : category or list of categories @@ -1089,6 +1084,11 @@ def remove_categories(self, removals, inplace=False): ------- cat : Categorical with removed categories or None if inplace. + Raises + ------ + ValueError + If the removals are not contained in the categories + See Also -------- rename_categories diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index a92e2f6157b40..b74ede4547249 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -892,6 +892,11 @@ def to_period(self, freq=None): When converting a DatetimeArray/Index with non-regular values, so that a frequency cannot be inferred. + See Also + -------- + PeriodIndex: Immutable ndarray holding ordinal values. + DatetimeIndex.to_pydatetime: Return DatetimeIndex as object. + Examples -------- >>> df = pd.DataFrame({"y": [1,2,3]}, @@ -908,11 +913,6 @@ def to_period(self, freq=None): >>> idx.to_period() PeriodIndex(['2017-01-01', '2017-01-02'], dtype='period[D]', freq='D') - - See Also - -------- - PeriodIndex: Immutable ndarray holding ordinal values. - DatetimeIndex.to_pydatetime: Return DatetimeIndex as object. """ from pandas.core.arrays import PeriodArray @@ -1087,17 +1087,17 @@ def date(self): by 6. This method is available on both Series with datetime values (using the `dt` accessor) or DatetimeIndex. + Returns + ------- + Series or Index + Containing integers indicating the day number. + See Also -------- Series.dt.dayofweek : Alias. Series.dt.weekday : Alias. Series.dt.day_name : Returns the name of the day of the week. - Returns - ------- - Series or Index - Containing integers indicating the day number. - Examples -------- >>> s = pd.date_range('2016-12-31', '2017-01-08', freq='D').to_series() diff --git a/pandas/core/arrays/interval.py b/pandas/core/arrays/interval.py index 785fb02c4d95d..1a1648a3b8480 100644 --- a/pandas/core/arrays/interval.py +++ b/pandas/core/arrays/interval.py @@ -84,14 +84,6 @@ set_closed %(extra_methods)s\ -%(examples)s\ - -Notes ------- -See the `user guide -`_ -for more. - See Also -------- Index : The base pandas Index type. @@ -99,6 +91,14 @@ interval_range : Function to create a fixed frequency IntervalIndex. cut : Bin values into discrete Intervals. qcut : Bin values into equal-sized Intervals based on rank or sample quantiles. + +Notes +------ +See the `user guide +`_ +for more. + +%(examples)s\ """ @@ -236,18 +236,18 @@ def _from_factorized(cls, values, original): .. versionadded:: 0.23.0 + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex. + %(klass)s.from_arrays : Construct from a left and right array. + %(klass)s.from_tuples : Construct from a sequence of tuples. + Examples -------- >>> pd.%(klass)s.from_breaks([0, 1, 2, 3]) %(klass)s([(0, 1], (1, 2], (2, 3]] closed='right', dtype='interval[int64]') - - See Also - -------- - interval_range : Function to create a fixed frequency IntervalIndex. - %(klass)s.from_arrays : Construct from a left and right array. - %(klass)s.from_tuples : Construct from a sequence of tuples. """ @classmethod @@ -281,14 +281,6 @@ def from_breaks(cls, breaks, closed='right', copy=False, dtype=None): ------- %(klass)s - Notes - ----- - Each element of `left` must be less than or equal to the `right` - element at the same position. If an element is missing, it must be - missing in both `left` and `right`. A TypeError is raised when - using an unsupported type for `left` or `right`. At the moment, - 'category', 'object', and 'string' subtypes are not supported. - Raises ------ ValueError @@ -304,6 +296,13 @@ def from_breaks(cls, breaks, closed='right', copy=False, dtype=None): %(klass)s.from_tuples : Construct an %(klass)s from an array-like of tuples. + Notes + ----- + Each element of `left` must be less than or equal to the `right` + element at the same position. If an element is missing, it must be + missing in both `left` and `right`. A TypeError is raised when + using an unsupported type for `left` or `right`. At the moment, + 'category', 'object', and 'string' subtypes are not supported. Examples -------- @@ -339,6 +338,16 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None): ..versionadded:: 0.23.0 + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex. + %(klass)s.from_arrays : Construct an %(klass)s from a left and + right array. + %(klass)s.from_breaks : Construct an %(klass)s from an array of + splits. + %(klass)s.from_tuples : Construct an %(klass)s from an + array-like of tuples. + Examples -------- >>> pd.%(klass)s.from_intervals([pd.Interval(0, 1), @@ -352,16 +361,6 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None): >>> pd.Index([pd.Interval(0, 1), pd.Interval(1, 2)]) %(klass)s([(0, 1], (1, 2]] closed='right', dtype='interval[int64]') - - See Also - -------- - interval_range : Function to create a fixed frequency IntervalIndex. - %(klass)s.from_arrays : Construct an %(klass)s from a left and - right array. - %(klass)s.from_breaks : Construct an %(klass)s from an array of - splits. - %(klass)s.from_tuples : Construct an %(klass)s from an - array-like of tuples. """ _interval_shared_docs['from_tuples'] = """ @@ -381,13 +380,6 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None): ..versionadded:: 0.23.0 - - Examples - -------- - >>> pd.%(klass)s.from_tuples([(0, 1), (1, 2)]) - %(klass)s([(0, 1], (1, 2]], - closed='right', dtype='interval[int64]') - See Also -------- interval_range : Function to create a fixed frequency IntervalIndex. @@ -395,6 +387,12 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None): right array. %(klass)s.from_breaks : Construct an %(klass)s from an array of splits. + + Examples + -------- + >>> pd.%(klass)s.from_tuples([(0, 1), (1, 2)]) + %(klass)s([(0, 1], (1, 2]], + closed='right', dtype='interval[int64]') """ @classmethod @@ -1052,6 +1050,10 @@ def repeat(self, repeats, **kwargs): ndarray Boolean array positionally indicating where an overlap occurs. + See Also + -------- + Interval.overlaps : Check whether two Interval objects overlap. + Examples -------- >>> intervals = %(constructor)s.from_tuples([(0, 1), (1, 3), (2, 4)]) @@ -1071,10 +1073,6 @@ def repeat(self, repeats, **kwargs): >>> intervals.overlaps(pd.Interval(1, 2, closed='right')) array([False, True, False]) - - See Also - -------- - Interval.overlaps : Check whether two Interval objects overlap. """ @Appender(_interval_shared_docs['overlaps'] % _shared_docs_kwargs) diff --git a/pandas/core/base.py b/pandas/core/base.py index e7c3a45a710e0..e224b6a50d332 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -1298,14 +1298,14 @@ def memory_usage(self, deep=False): ------- bytes used + See Also + -------- + numpy.ndarray.nbytes + Notes ----- Memory usage does not include memory consumed by elements that are not components of the array if deep=False or if used on PyPy - - See Also - -------- - numpy.ndarray.nbytes """ if hasattr(self.values, 'memory_usage'): return self.values.memory_usage(deep=deep) diff --git a/pandas/core/computation/eval.py b/pandas/core/computation/eval.py index 4b9ba02ed85a4..b768ed6df303e 100644 --- a/pandas/core/computation/eval.py +++ b/pandas/core/computation/eval.py @@ -246,6 +246,11 @@ def eval(expr, parser='pandas', engine=None, truediv=True, - Item assignment is provided and `inplace=False`, but the `target` does not support the `.copy()` method + See Also + -------- + pandas.DataFrame.query + pandas.DataFrame.eval + Notes ----- The ``dtype`` of any objects involved in an arithmetic ``%`` operation are @@ -253,11 +258,6 @@ def eval(expr, parser='pandas', engine=None, truediv=True, See the :ref:`enhancing performance ` documentation for more details. - - See Also - -------- - pandas.DataFrame.query - pandas.DataFrame.eval """ from pandas.core.computation.expr import Expr diff --git a/pandas/core/dtypes/base.py b/pandas/core/dtypes/base.py index aa81e88abf28e..ab1cb9cf2499a 100644 --- a/pandas/core/dtypes/base.py +++ b/pandas/core/dtypes/base.py @@ -151,6 +151,11 @@ class ExtensionDtype(_DtypeOpsMixin): .. versionadded:: 0.23.0 + See Also + -------- + pandas.api.extensions.register_extension_dtype + pandas.api.extensions.ExtensionArray + Notes ----- The interface includes the following abstract methods that must @@ -199,11 +204,6 @@ class property**. Methods and properties required by the interface raise ``pandas.errors.AbstractMethodError`` and no ``register`` method is provided for registering virtual subclasses. - - See Also - -------- - pandas.api.extensions.register_extension_dtype - pandas.api.extensions.ExtensionArray """ def __str__(self): diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index 82f931c1469b7..0db76cd934d19 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -186,6 +186,10 @@ class CategoricalDtype(PandasExtensionDtype, ExtensionDtype): ------- None + See Also + -------- + pandas.Categorical + Notes ----- This class is useful for specifying the type of a ``Categorical`` @@ -202,10 +206,6 @@ class CategoricalDtype(PandasExtensionDtype, ExtensionDtype): 3 NaN dtype: category Categories (2, object): [b < a] - - See Also - -------- - pandas.Categorical """ # TODO: Document public vs. private API name = 'category' diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 2a8d58b8867b7..f7f1855a4fabc 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -211,18 +211,18 @@ DataFrame A DataFrame of the two merged objects. -Notes ------ -Support for specifying index levels as the `on`, `left_on`, and -`right_on` parameters was added in version 0.23.0 -Support for merging named Series objects was added in version 0.24.0 - See Also -------- merge_ordered : Merge with optional filling/interpolation. merge_asof : Merge on nearest keys. DataFrame.join : Similar method using indices. +Notes +----- +Support for specifying index levels as the `on`, `left_on`, and +`right_on` parameters was added in version 0.23.0 +Support for merging named Series objects was added in version 0.24.0 + Examples -------- @@ -309,6 +309,13 @@ class DataFrame(NDFrame): copy : boolean, default False Copy data from inputs. Only affects DataFrame / 2d ndarray input + See Also + -------- + DataFrame.from_records : Constructor from tuples, also record arrays. + DataFrame.from_dict : From dicts of Series, arrays, or dicts. + DataFrame.from_items : From sequence of (key, value) pairs + pandas.read_csv, pandas.read_table, pandas.read_clipboard. + Examples -------- Constructing DataFrame from a dictionary. @@ -344,13 +351,6 @@ class DataFrame(NDFrame): 0 1 2 3 1 4 5 6 2 7 8 9 - - See Also - -------- - DataFrame.from_records : Constructor from tuples, also record arrays. - DataFrame.from_dict : From dicts of Series, arrays, or dicts. - DataFrame.from_items : From sequence of (key, value) pairs - pandas.read_csv, pandas.read_table, pandas.read_clipboard. """ @property @@ -786,6 +786,21 @@ def iterrows(self): """ Iterate over DataFrame rows as (index, Series) pairs. + Yields + ------ + index : label or tuple of label + The index of the row. A tuple for a `MultiIndex`. + data : Series + The data of the row as a Series. + + it : generator + A generator that iterates over the rows of the frame. + + See Also + -------- + itertuples : Iterate over DataFrame rows as namedtuples of the values. + iteritems : Iterate over (column name, Series) pairs. + Notes ----- @@ -812,21 +827,6 @@ def iterrows(self): This is not guaranteed to work in all cases. Depending on the data types, the iterator returns a copy and not a view, and writing to it will have no effect. - - Yields - ------ - index : label or tuple of label - The index of the row. A tuple for a `MultiIndex`. - data : Series - The data of the row as a Series. - - it : generator - A generator that iterates over the rows of the frame. - - See Also - -------- - itertuples : Iterate over DataFrame rows as namedtuples of the values. - iteritems : Iterate over (column name, Series) pairs. """ columns = self.columns klass = self._constructor_sliced @@ -853,18 +853,18 @@ def itertuples(self, index=True, name="Pandas"): field possibly being the index and following fields being the column values. - Notes - ----- - The column names will be renamed to positional names if they are - invalid Python identifiers, repeated, or start with an underscore. - With a large number of columns (>255), regular tuples are returned. - See Also -------- DataFrame.iterrows : Iterate over DataFrame rows as (index, Series) pairs. DataFrame.iteritems : Iterate over (column name, Series) pairs. + Notes + ----- + The column names will be renamed to positional names if they are + invalid Python identifiers, repeated, or start with an underscore. + With a large number of columns (>255), regular tuples are returned. + Examples -------- >>> df = pd.DataFrame({'num_legs': [4, 2], 'num_wings': [0, 2]}, @@ -1714,13 +1714,13 @@ def from_csv(cls, path, header=0, sep=',', index_col=0, parse_dates=True, datetime format based on the first datetime string. If the format can be inferred, there often will be a large parsing speed-up. - See Also - -------- - pandas.read_csv - Returns ------- y : DataFrame + + See Also + -------- + pandas.read_csv """ warnings.warn("from_csv is deprecated. Please use read_csv(...) " @@ -2858,6 +2858,11 @@ def query(self, expr, inplace=False, **kwargs): ------- q : DataFrame + See Also + -------- + pandas.eval + DataFrame.eval + Notes ----- The result of the evaluation of this expression is first passed to @@ -2893,11 +2898,6 @@ def query(self, expr, inplace=False, **kwargs): For further details and examples see the ``query`` documentation in :ref:`indexing `. - See Also - -------- - pandas.eval - DataFrame.eval - Examples -------- >>> df = pd.DataFrame(np.random.randn(10, 2), columns=list('ab')) @@ -3037,6 +3037,12 @@ def select_dtypes(self, include=None, exclude=None): A selection of dtypes or strings to be included/excluded. At least one of these parameters must be supplied. + Returns + ------- + subset : DataFrame + The subset of the frame including the dtypes in ``include`` and + excluding the dtypes in ``exclude``. + Raises ------ ValueError @@ -3044,12 +3050,6 @@ def select_dtypes(self, include=None, exclude=None): * If ``include`` and ``exclude`` have overlapping elements * If any kind of string dtype is passed in. - Returns - ------- - subset : DataFrame - The subset of the frame including the dtypes in ``include`` and - excluding the dtypes in ``exclude``. - Notes ----- * To select all *numeric* types, use ``np.number`` or ``'number'`` @@ -3675,6 +3675,11 @@ def drop(self, labels=None, axis=0, index=None, columns=None, ------- dropped : pandas.DataFrame + Raises + ------ + KeyError + If none of the labels are found in the selected axis + See Also -------- DataFrame.loc : Label-location based indexer for selection by label. @@ -3684,11 +3689,6 @@ def drop(self, labels=None, axis=0, index=None, columns=None, removed, optionally only considering certain columns. Series.drop : Return Series with specified index labels removed. - Raises - ------ - KeyError - If none of the labels are found in the selected axis - Examples -------- >>> df = pd.DataFrame(np.arange(12).reshape(3,4), @@ -4960,6 +4960,11 @@ def combine(self, other, func, fill_value=None, overwrite=True): ------- result : DataFrame + See Also + -------- + DataFrame.combine_first : Combine two DataFrame objects and default to + non-null values in frame calling the method. + Examples -------- Combine using a simple function that chooses the smaller column. @@ -5032,11 +5037,6 @@ def combine(self, other, func, fill_value=None, overwrite=True): 0 0.0 NaN NaN 1 0.0 3.0 1.0 2 NaN 3.0 1.0 - - See Also - -------- - DataFrame.combine_first : Combine two DataFrame objects and default to - non-null values in frame calling the method. """ other_idxlen = len(other.index) # save for compare @@ -5118,6 +5118,11 @@ def combine_first(self, other): ------- combined : DataFrame + See Also + -------- + DataFrame.combine : Perform series-wise operation on two DataFrames + using a given function. + Examples -------- @@ -5138,11 +5143,6 @@ def combine_first(self, other): 0 NaN 4.0 NaN 1 0.0 3.0 1.0 2 NaN 3.0 1.0 - - See Also - -------- - DataFrame.combine : Perform series-wise operation on two DataFrames - using a given function. """ import pandas.core.computation.expressions as expressions @@ -5476,6 +5476,15 @@ def pivot(self, index=None, columns=None, values=None): Name of the row / column that will contain the totals when margins is True. + Returns + ------- + table : DataFrame + + See Also + -------- + DataFrame.pivot : Pivot without aggregation that can handle + non-numeric data. + Examples -------- >>> df = pd.DataFrame({"A": ["foo", "foo", "foo", "foo", "foo", @@ -5551,15 +5560,6 @@ def pivot(self, index=None, columns=None, values=None): small 5.500000 9 8.500000 8 foo large 2.000000 5 4.500000 4 small 2.333333 6 4.333333 2 - - Returns - ------- - table : DataFrame - - See Also - -------- - DataFrame.pivot : Pivot without aggregation that can handle - non-numeric data. """ @Substitution('') @@ -5763,6 +5763,10 @@ def unstack(self, level=-1, fill_value=None): .. versionadded:: 0.18.0 + Returns + ------- + unstacked : DataFrame or Series + See Also -------- DataFrame.pivot : Pivot a table based on column values. @@ -5798,10 +5802,6 @@ def unstack(self, level=-1, fill_value=None): two a 3.0 b 4.0 dtype: float64 - - Returns - ------- - unstacked : DataFrame or Series """ from pandas.core.reshape.reshape import unstack return unstack(self, level, fill_value) @@ -5895,7 +5895,6 @@ def unstack(self, level=-1, fill_value=None): 0 a B E 1 1 b B E 3 2 c B E 5 - """) @Appender(_shared_docs['melt'] % @@ -6199,6 +6198,16 @@ def apply(self, func, axis=0, broadcast=None, raw=False, reduce=None, Additional keyword arguments to pass as keywords arguments to `func`. + Returns + ------- + applied : Series or DataFrame + + See Also + -------- + DataFrame.applymap: For elementwise operations. + DataFrame.aggregate: Only perform aggregating type operations. + DataFrame.transform: Only perform transforming type operations. + Notes ----- In the current implementation apply calls `func` twice on the @@ -6207,12 +6216,6 @@ def apply(self, func, axis=0, broadcast=None, raw=False, reduce=None, side-effects, as they will take effect twice for the first column/row. - See Also - -------- - DataFrame.applymap: For elementwise operations. - DataFrame.aggregate: Only perform aggregating type operations. - DataFrame.transform: Only perform transforming type operations. - Examples -------- @@ -6282,10 +6285,6 @@ def apply(self, func, axis=0, broadcast=None, raw=False, reduce=None, 0 1 2 1 1 2 2 1 2 - - Returns - ------- - applied : Series or DataFrame """ from pandas.core.apply import frame_apply op = frame_apply(self, @@ -6388,6 +6387,11 @@ def append(self, other, ignore_index=False, ------- appended : DataFrame + See Also + -------- + pandas.concat : General function to concatenate DataFrame, Series + or Panel objects. + Notes ----- If a list of dict/series is passed and the keys are all contained in @@ -6399,11 +6403,6 @@ def append(self, other, ignore_index=False, those rows to a list and then concatenate the list with the original DataFrame all at once. - See Also - -------- - pandas.concat : General function to concatenate DataFrame, Series - or Panel objects. - Examples -------- @@ -6541,6 +6540,10 @@ def join(self, other, on=None, how='left', lsuffix='', rsuffix='', DataFrame A dataframe containing columns from both the caller and `other`. + See Also + -------- + DataFrame.merge : For column(s)-on-columns(s) operations. + Notes ----- Parameters `on`, `lsuffix`, and `rsuffix` are not supported when @@ -6549,10 +6552,6 @@ def join(self, other, on=None, how='left', lsuffix='', rsuffix='', Support for specifying index levels as the `on` parameter was added in version 0.23.0. - See Also - -------- - DataFrame.merge : For column(s)-on-columns(s) operations. - Examples -------- >>> df = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5'], @@ -7300,22 +7299,22 @@ def idxmin(self, axis=0, skipna=True): Exclude NA/null values. If an entire row/column is NA, the result will be NA. + Returns + ------- + idxmin : Series + Raises ------ ValueError * If the row/column is empty - Returns - ------- - idxmin : Series + See Also + -------- + Series.idxmin Notes ----- This method is the DataFrame version of ``ndarray.argmin``. - - See Also - -------- - Series.idxmin """ axis = self._get_axis_number(axis) indices = nanops.nanargmin(self.values, axis=axis, skipna=skipna) @@ -7336,22 +7335,22 @@ def idxmax(self, axis=0, skipna=True): Exclude NA/null values. If an entire row/column is NA, the result will be NA. + Returns + ------- + idxmax : Series + Raises ------ ValueError * If the row/column is empty - Returns - ------- - idxmax : Series + See Also + -------- + Series.idxmax Notes ----- This method is the DataFrame version of ``ndarray.argmax``. - - See Also - -------- - Series.idxmax """ axis = self._get_axis_number(axis) indices = nanops.nanargmax(self.values, axis=axis, skipna=skipna) @@ -7493,6 +7492,11 @@ def quantile(self, q=0.5, axis=0, numeric_only=True, - If ``q`` is a float, a Series will be returned where the index is the columns of self and the values are the quantiles. + See Also + -------- + pandas.core.window.Rolling.quantile + numpy.percentile + Examples -------- @@ -7520,11 +7524,6 @@ def quantile(self, q=0.5, axis=0, numeric_only=True, B 2010-07-02 12:00:00 C 1 days 12:00:00 Name: 0.5, dtype: object - - See Also - -------- - pandas.core.window.Rolling.quantile - numpy.percentile """ self._check_percentile(q) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b3cb5c3be67f9..0eb0e14c9054e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -638,14 +638,14 @@ def transpose(self, *args, **kwargs): Make a copy of the underlying data. Mixed-dtype data will always result in a copy + Returns + ------- + y : same as input + Examples -------- >>> p.transpose(2, 0, 1) >>> p.transpose(2, 0, 1, copy=True) - - Returns - ------- - y : same as input """ # construct the args @@ -1847,6 +1847,11 @@ def empty(self): bool If DataFrame is empty, return True, if not return False. + See Also + -------- + pandas.Series.dropna + pandas.DataFrame.dropna + Notes ----- If DataFrame contains only NaNs, it is still not considered empty. See @@ -1875,11 +1880,6 @@ def empty(self): False >>> df.dropna().empty True - - See Also - -------- - pandas.Series.dropna - pandas.DataFrame.dropna """ return any(len(self._get_axis(a)) == 0 for a in self._AXIS_ORDERS) @@ -2051,6 +2051,11 @@ def _repr_data_resource_(self): .. versionadded:: 0.20.0. + See Also + -------- + read_excel + ExcelWriter + Notes ----- For compatibility with :meth:`~DataFrame.to_csv`, @@ -2059,11 +2064,6 @@ def _repr_data_resource_(self): Once a workbook has been saved it is not possible write further data without rewriting the whole workbook. - See Also - -------- - read_excel - ExcelWriter - Examples -------- @@ -2640,6 +2640,10 @@ def to_xarray(self): DataFrame.to_hdf : Write DataFrame to an HDF5 file. DataFrame.to_parquet : Write a DataFrame to the binary parquet format. + Notes + ----- + See the `xarray docs `__ + Examples -------- >>> df = pd.DataFrame([('falcon', 'bird', 389.0, 2), @@ -2695,10 +2699,6 @@ class (index) object 'bird' 'bird' 'mammal' 'mammal' * animal (animal) object 'falcon' 'parrot' Data variables: speed (date, animal) int64 350 18 361 15 - - Notes - ----- - See the `xarray docs `__ """ try: @@ -4133,6 +4133,10 @@ def reindex(self, *args, **kwargs): .. versionadded:: 0.21.0 (list-like tolerance) + Returns + ------- + %(klass)s with changed index. + See Also -------- DataFrame.set_index : Set row labels. @@ -4283,10 +4287,6 @@ def reindex(self, *args, **kwargs): in the original dataframe, use the ``fillna()`` method. See the :ref:`user guide ` for more. - - Returns - ------- - %(klass)s with changed index. """ # TODO: Decide if we care about having different examples for different # kinds @@ -4399,6 +4399,10 @@ def _reindex_multi(self, axes, copy, fill_value): .. versionadded:: 0.21.0 (list-like tolerance) + Returns + ------- + %(klass)s + See Also -------- DataFrame.set_index : Set row labels. @@ -4406,10 +4410,6 @@ def _reindex_multi(self, axes, copy, fill_value): DataFrame.reindex : Change to new indices or expand indices. DataFrame.reindex_like : Change to same indices as other DataFrame. - Returns - ------- - %(klass)s - Examples -------- >>> df.reindex_axis(['A', 'B', 'C'], axis=1) @@ -4483,6 +4483,18 @@ def filter(self, items=None, like=None, regex=None, axis=None): ------- same type as input object + See Also + -------- + DataFrame.loc + + Notes + ----- + The ``items``, ``like``, and ``regex`` parameters are + enforced to be mutually exclusive. + + ``axis`` defaults to the info axis that is used when indexing + with ``[]``. + Examples -------- >>> df = pd.DataFrame(np.array(([1,2,3], [4,5,6])), @@ -4505,18 +4517,6 @@ def filter(self, items=None, like=None, regex=None, axis=None): >>> df.filter(like='bbi', axis=0) one two three rabbit 4 5 6 - - See Also - -------- - DataFrame.loc - - Notes - ----- - The ``items``, ``like``, and ``regex`` parameters are - enforced to be mutually exclusive. - - ``axis`` defaults to the info axis that is used when indexing - with ``[]``. """ import re @@ -4850,6 +4850,12 @@ def sample(self, n=None, frac=None, replace=False, weights=None, ------- object : the return type of ``func``. + See Also + -------- + DataFrame.apply + DataFrame.applymap + Series.map + Notes ----- @@ -4873,12 +4879,6 @@ def sample(self, n=None, frac=None, replace=False, weights=None, ... .pipe(g, arg1=a) ... .pipe((f, 'arg2'), arg1=a, arg3=c) ... ) - - See Also - -------- - DataFrame.apply - DataFrame.applymap - Series.map """) @Appender(_shared_docs['pipe'] % _shared_doc_kwargs) @@ -5181,6 +5181,10 @@ def as_matrix(self, columns=None): If the caller is heterogeneous and contains booleans or objects, the result will be of dtype=object. See Notes. + See Also + -------- + DataFrame.values + Notes ----- Return is NOT a Numpy-matrix, rather, a Numpy-array. @@ -5197,10 +5201,6 @@ def as_matrix(self, columns=None): This method is provided for backwards compatibility. Generally, it is recommended to use '.values'. - - See Also - -------- - DataFrame.values """ warnings.warn("Method .as_matrix will be removed in a future version. " "Use .values instead.", FutureWarning, stacklevel=2) @@ -5225,6 +5225,24 @@ def values(self): numpy.ndarray The values of the DataFrame. + See Also + -------- + DataFrame.to_numpy : Recommended alternative to this method. + pandas.DataFrame.index : Retrieve the index labels. + pandas.DataFrame.columns : Retrieving the column names. + + Notes + ----- + The dtype will be a lower-common-denominator dtype (implicit + upcasting); that is to say if the dtypes (even of numeric types) + are mixed, the one that accommodates all will be chosen. Use this + with care if you are not dealing with the blocks. + + e.g. If the dtypes are float16 and float32, dtype will be upcast to + float32. If dtypes are int32 and uint8, dtype will be upcast to + int32. By :func:`numpy.find_common_type` convention, mixing int64 + and uint64 will result in a float64 dtype. + Examples -------- A DataFrame where all columns are the same type (e.g., int64) results @@ -5263,24 +5281,6 @@ def values(self): array([['parrot', 24.0, 'second'], ['lion', 80.5, 1], ['monkey', nan, None]], dtype=object) - - Notes - ----- - The dtype will be a lower-common-denominator dtype (implicit - upcasting); that is to say if the dtypes (even of numeric types) - are mixed, the one that accommodates all will be chosen. Use this - with care if you are not dealing with the blocks. - - e.g. If the dtypes are float16 and float32, dtype will be upcast to - float32. If dtypes are int32 and uint8, dtype will be upcast to - int32. By :func:`numpy.find_common_type` convention, mixing int64 - and uint64 will result in a float64 dtype. - - See Also - -------- - DataFrame.to_numpy : Recommended alternative to this method. - pandas.DataFrame.index : Retrieve the index labels. - pandas.DataFrame.columns : Retrieving the column names. """ self._consolidate_inplace() return self._data.as_array(transpose=self._AXIS_REVERSED) @@ -5568,6 +5568,13 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): ------- casted : same type as caller + See Also + -------- + to_datetime : Convert argument to datetime. + to_timedelta : Convert argument to timedelta. + to_numeric : Convert argument to a numeric type. + numpy.ndarray.astype : Cast a numpy array to a specified type. + Examples -------- >>> ser = pd.Series([1, 2], dtype='int32') @@ -5608,13 +5615,6 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): 0 10 1 2 dtype: int64 - - See Also - -------- - to_datetime : Convert argument to datetime. - to_timedelta : Convert argument to timedelta. - to_numeric : Convert argument to a numeric type. - numpy.ndarray.astype : Cast a numpy array to a specified type. """ if is_dict_like(dtype): if self.ndim == 1: # i.e. Series @@ -5832,15 +5832,15 @@ def convert_objects(self, convert_dates=True, convert_numeric=False, conversion was done). Note: This is meant for internal use, and should not be confused with inplace. + Returns + ------- + converted : same as input object + See Also -------- to_datetime : Convert argument to datetime. to_timedelta : Convert argument to timedelta. to_numeric : Convert argument to numeric type. - - Returns - ------- - converted : same as input object """ msg = ("convert_objects is deprecated. To re-infer data dtypes for " "object columns, use {klass}.infer_objects()\nFor all " @@ -5866,16 +5866,16 @@ def infer_objects(self): .. versionadded:: 0.21.0 + Returns + ------- + converted : same type as input object + See Also -------- to_datetime : Convert argument to datetime. to_timedelta : Convert argument to timedelta. to_numeric : Convert argument to numeric type. - Returns - ------- - converted : same type as input object - Examples -------- >>> df = pd.DataFrame({"A": ["a", 1, 2, 3]}) @@ -5939,15 +5939,15 @@ def fillna(self, value=None, method=None, axis=None, inplace=False, or the string 'infer' which will try to downcast to an appropriate equal type (e.g. float64 to int64 if possible) + Returns + ------- + filled : %(klass)s + See Also -------- interpolate : Fill NaN values using interpolation. reindex, asfreq - Returns - ------- - filled : %(klass)s - Examples -------- >>> df = pd.DataFrame([[np.nan, 2, np.nan, 0], @@ -6829,10 +6829,6 @@ def asof(self, where, subset=None): For DataFrame, if not `None`, only use these columns to check for NaNs. - Notes - ----- - Dates are assumed to be sorted. Raises if this is not the case. - Returns ------- scalar, Series, or DataFrame @@ -6847,6 +6843,10 @@ def asof(self, where, subset=None): -------- merge_asof : Perform an asof merge. Similar to left join. + Notes + ----- + Dates are assumed to be sorted. Raises if this is not the case. + Examples -------- A Series and a scalar `where`. @@ -7188,17 +7188,17 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, Additional keywords have no effect but might be accepted for compatibility with numpy. - See Also - -------- - clip_lower : Clip values below specified threshold(s). - clip_upper : Clip values above specified threshold(s). - Returns ------- Series or DataFrame Same type as calling object with the values outside the clip boundaries replaced + See Also + -------- + clip_lower : Clip values below specified threshold(s). + clip_upper : Clip values above specified threshold(s). + Examples -------- >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_1': [-2, -7, 6, 8, -5]} @@ -7624,6 +7624,15 @@ def asfreq(self, freq, method=None, how=None, normalize=False, ------- converted : same type as caller + See Also + -------- + reindex + + Notes + ----- + To learn more about the frequency strings, please see `this link + `__. + Examples -------- @@ -7674,15 +7683,6 @@ def asfreq(self, freq, method=None, how=None, normalize=False, 2000-01-01 00:02:00 2.0 2000-01-01 00:02:30 3.0 2000-01-01 00:03:00 3.0 - - See Also - -------- - reindex - - Notes - ----- - To learn more about the frequency strings, please see `this link - `__. """ from pandas.core.resample import asfreq return asfreq(self, freq, method=method, how=how, normalize=normalize, @@ -7692,11 +7692,6 @@ def at_time(self, time, asof=False, axis=None): """ Select values at particular time of day (e.g. 9:30AM). - Raises - ------ - TypeError - If the index is not a :class:`DatetimeIndex` - Parameters ---------- time : datetime.time or string @@ -7704,11 +7699,23 @@ def at_time(self, time, asof=False, axis=None): .. versionadded:: 0.24.0 - Returns ------- values_at_time : same type as caller + Raises + ------ + TypeError + If the index is not a :class:`DatetimeIndex` + + See Also + -------- + between_time : Select values between particular times of the day. + first : Select initial periods of time series based on a date offset. + last : Select final periods of time series based on a date offset. + DatetimeIndex.indexer_at_time : Get just the index locations for + values at particular time of the day. + Examples -------- >>> i = pd.date_range('2018-04-09', periods=4, freq='12H') @@ -7724,14 +7731,6 @@ def at_time(self, time, asof=False, axis=None): A 2018-04-09 12:00:00 2 2018-04-10 12:00:00 4 - - See Also - -------- - between_time : Select values between particular times of the day. - first : Select initial periods of time series based on a date offset. - last : Select final periods of time series based on a date offset. - DatetimeIndex.indexer_at_time : Get just the index locations for - values at particular time of the day. """ if axis is None: axis = self._stat_axis_number @@ -7753,11 +7752,6 @@ def between_time(self, start_time, end_time, include_start=True, By setting ``start_time`` to be later than ``end_time``, you can get the times that are *not* between the two times. - Raises - ------ - TypeError - If the index is not a :class:`DatetimeIndex` - Parameters ---------- start_time : datetime.time or string @@ -7772,6 +7766,19 @@ def between_time(self, start_time, end_time, include_start=True, ------- values_between_time : same type as caller + Raises + ------ + TypeError + If the index is not a :class:`DatetimeIndex` + + See Also + -------- + at_time : Select values at a particular time of the day. + first : Select initial periods of time series based on a date offset. + last : Select final periods of time series based on a date offset. + DatetimeIndex.indexer_between_time : Get just the index locations for + values between particular times of the day. + Examples -------- >>> i = pd.date_range('2018-04-09', periods=4, freq='1D20min') @@ -7795,14 +7802,6 @@ def between_time(self, start_time, end_time, include_start=True, A 2018-04-09 00:00:00 1 2018-04-12 01:00:00 4 - - See Also - -------- - at_time : Select values at a particular time of the day. - first : Select initial periods of time series based on a date offset. - last : Select final periods of time series based on a date offset. - DatetimeIndex.indexer_between_time : Get just the index locations for - values between particular times of the day. """ if axis is None: axis = self._stat_axis_number @@ -7890,6 +7889,12 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, ------- Resampler object + See Also + -------- + groupby : Group by mapping, function, label, or list of labels. + Series.resample : Resample a Series. + DataFrame.resample: Resample a DataFrame. + Notes ----- See the `user guide @@ -7899,12 +7904,6 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, To learn more about the offset strings, please see `this link `__. - See Also - -------- - groupby : Group by mapping, function, label, or list of labels. - Series.resample : Resample a Series. - DataFrame.resample: Resample a DataFrame. - Examples -------- @@ -8122,14 +8121,24 @@ def first(self, offset): Convenience method for subsetting initial periods of time series data based on a date offset. + Parameters + ---------- + offset : string, DateOffset, dateutil.relativedelta + + Returns + ------- + subset : same type as caller + Raises ------ TypeError If the index is not a :class:`DatetimeIndex` - Parameters - ---------- - offset : string, DateOffset, dateutil.relativedelta + See Also + -------- + last : Select final periods of time series based on a date offset. + at_time : Select values at a particular time of the day. + between_time : Select values between particular times of the day. Examples -------- @@ -8152,16 +8161,6 @@ def first(self, offset): Notice the data for 3 first calender days were returned, not the first 3 days observed in the dataset, and therefore data for 2018-04-13 was not returned. - - Returns - ------- - subset : same type as caller - - See Also - -------- - last : Select final periods of time series based on a date offset. - at_time : Select values at a particular time of the day. - between_time : Select values between particular times of the day. """ if not isinstance(self.index, DatetimeIndex): raise TypeError("'first' only supports a DatetimeIndex index") @@ -8185,14 +8184,24 @@ def last(self, offset): Convenience method for subsetting final periods of time series data based on a date offset. + Parameters + ---------- + offset : string, DateOffset, dateutil.relativedelta + + Returns + ------- + subset : same type as caller + Raises ------ TypeError If the index is not a :class:`DatetimeIndex` - Parameters - ---------- - offset : string, DateOffset, dateutil.relativedelta + See Also + -------- + first : Select initial periods of time series based on a date offset. + at_time : Select values at a particular time of the day. + between_time : Select values between particular times of the day. Examples -------- @@ -8215,16 +8224,6 @@ def last(self, offset): Notice the data for 3 last calender days were returned, not the last 3 observed days in the dataset, and therefore data for 2018-04-11 was not returned. - - Returns - ------- - subset : same type as caller - - See Also - -------- - first : Select initial periods of time series based on a date offset. - at_time : Select values at a particular time of the day. - between_time : Select values between particular times of the day. """ if not isinstance(self.index, DatetimeIndex): raise TypeError("'last' only supports a DatetimeIndex index") @@ -8691,6 +8690,11 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, ------- wh : same type as caller + See Also + -------- + :func:`DataFrame.%(name_other)s` : Return an object of same shape as + self. + Notes ----- The %(name)s method is an application of the if-then idiom. For each @@ -8705,11 +8709,6 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, For further details and examples see the ``%(name)s`` documentation in :ref:`indexing `. - See Also - -------- - :func:`DataFrame.%(name_other)s` : Return an object of same shape as - self. - Examples -------- >>> s = pd.Series(range(5)) @@ -8891,14 +8890,14 @@ def slice_shift(self, periods=1, axis=0): periods : int Number of periods to move, can be positive or negative + Returns + ------- + shifted : same type as caller + Notes ----- While the `slice_shift` is faster than `shift`, you may pay for it later during alignment. - - Returns - ------- - shifted : same type as caller """ if periods == 0: return self @@ -8929,15 +8928,15 @@ def tshift(self, periods=1, freq=None, axis=0): axis : int or basestring Corresponds to the axis that contains the Index + Returns + ------- + shifted : NDFrame + Notes ----- If freq is not specified then tries to use the freq or inferred_freq attributes of the index. If neither of those attributes exist, a ValueError is thrown - - Returns - ------- - shifted : NDFrame """ index = self._get_axis(axis) @@ -9325,6 +9324,10 @@ def abs(self): abs Series/DataFrame containing the absolute value of each element. + See Also + -------- + numpy.absolute : Calculate the absolute value element-wise. + Notes ----- For ``complex`` inputs, ``1.2 + 1j``, the absolute value is @@ -9376,10 +9379,6 @@ def abs(self): 0 4 10 100 2 6 30 -30 3 7 40 -50 - - See Also - -------- - numpy.absolute : Calculate the absolute value element-wise. """ return np.abs(self) @@ -10085,14 +10084,14 @@ def transform(self, func, *args, **kwargs): _shared_docs['valid_index'] = """ Return index for %(position)s non-NA/null value. + Returns + -------- + scalar : type of index + Notes -------- If all elements are non-NA/null, returns None. Also returns None for empty %(klass)s. - - Returns - -------- - scalar : type of index """ def _find_valid_index(self, how): @@ -10303,7 +10302,6 @@ def _doc_parms(cls): Returns ------- %(outname)s : %(name1)s or %(name2)s\n -%(examples)s See Also -------- core.window.Expanding.%(accum_func_name)s : Similar functionality @@ -10314,6 +10312,8 @@ def _doc_parms(cls): %(name2)s.cummin : Return cumulative minimum over %(name2)s axis. %(name2)s.cumsum : Return cumulative sum over %(name2)s axis. %(name2)s.cumprod : Return cumulative product over %(name2)s axis. + +%(examples)s """ _cummin_examples = """\ diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index 26e437355fa8b..2f54f61818aa6 100644 --- a/pandas/core/groupby/generic.py +++ b/pandas/core/groupby/generic.py @@ -634,6 +634,10 @@ def filter(self, func, dropna=True, *args, **kwargs): # noqa dropna : Drop groups that do not pass the filter. True by default; if False, groups that evaluate False are filled with NaNs. + Returns + ------- + filtered : DataFrame + Notes ----- Each subframe is endowed the attribute 'name' in case you need to know @@ -651,10 +655,6 @@ def filter(self, func, dropna=True, *args, **kwargs): # noqa 1 bar 2 5.0 3 bar 4 1.0 5 bar 6 9.0 - - Returns - ------- - filtered : DataFrame """ indices = [] diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 253860d83f49e..45eaa3efa948a 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -78,18 +78,6 @@ class providing the base-class of operations. ------- applied : Series or DataFrame - Notes - ----- - In the current implementation `apply` calls `func` twice on the - first group to decide whether it can take a fast or slow code - path. This can lead to unexpected behavior if `func` has - side-effects, as they will take effect twice for the first - group. - - Examples - -------- - {examples} - See Also -------- pipe : Apply function to the full GroupBy object instead of to each @@ -165,6 +153,18 @@ class providing the base-class of operations. a 1 b 0 dtype: int64 + + Notes + ----- + In the current implementation `apply` calls `func` twice on the + first group to decide whether it can take a fast or slow code + path. This can lead to unexpected behavior if `func` has + side-effects, as they will take effect twice for the first + group. + + Examples + -------- + {examples} """) _pipe_template = """\ @@ -204,6 +204,13 @@ class providing the base-class of operations. ------- object : the return type of `func`. +See Also +-------- +pandas.Series.pipe : Apply a function with arguments to a series. +pandas.DataFrame.pipe: Apply a function with arguments to a dataframe. +apply : Apply function to each group instead of to the + full %(klass)s object. + Notes ----- See more `here @@ -212,13 +219,6 @@ class providing the base-class of operations. Examples -------- %(examples)s - -See Also --------- -pandas.Series.pipe : Apply a function with arguments to a series. -pandas.DataFrame.pipe: Apply a function with arguments to a dataframe. -apply : Apply function to each group instead of to the - full %(klass)s object. """ _transform_template = """ @@ -231,6 +231,14 @@ class providing the base-class of operations. f : function Function to apply to each group +Returns +------- +%(klass)s + +See Also +-------- +aggregate, transform + Notes ----- Each group is endowed the attribute 'name' in case you need to know @@ -248,14 +256,6 @@ class providing the base-class of operations. * f must not mutate groups. Mutation is not supported and may produce unexpected results. -Returns -------- -%(klass)s - -See Also --------- -aggregate, transform - Examples -------- @@ -285,7 +285,6 @@ class providing the base-class of operations. 3 3 8.0 4 4 6.0 5 3 8.0 - """ @@ -1705,6 +1704,10 @@ def ngroup(self, ascending=True): ascending : bool, default True If False, number in reverse, from number of group - 1 to 0. + See Also + -------- + .cumcount : Number the rows in each group. + Examples -------- @@ -1741,10 +1744,6 @@ def ngroup(self, ascending=True): 4 2 5 0 dtype: int64 - - See Also - -------- - .cumcount : Number the rows in each group. """ with _group_selection_context(self): @@ -1768,6 +1767,10 @@ def cumcount(self, ascending=True): ascending : bool, default True If False, number in reverse, from length of group - 1 to 0. + See Also + -------- + .ngroup : Number the groups themselves. + Examples -------- @@ -1797,10 +1800,6 @@ def cumcount(self, ascending=True): 4 0 5 0 dtype: int64 - - See Also - -------- - .ngroup : Number the groups themselves. """ with _group_selection_context(self): diff --git a/pandas/core/indexes/accessors.py b/pandas/core/indexes/accessors.py index 6138f73726e0a..82b6b22be4a79 100644 --- a/pandas/core/indexes/accessors.py +++ b/pandas/core/indexes/accessors.py @@ -212,6 +212,10 @@ def to_pytimedelta(self): a : numpy.ndarray 1D array containing data with `datetime.timedelta` type. + See Also + -------- + datetime.timedelta + Examples -------- >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit='d')) @@ -227,10 +231,6 @@ def to_pytimedelta(self): array([datetime.timedelta(0), datetime.timedelta(1), datetime.timedelta(2), datetime.timedelta(3), datetime.timedelta(4)], dtype=object) - - See Also - -------- - datetime.timedelta """ return self._get_values().to_pytimedelta() diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 88510e84a29a5..c097694800cd7 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -181,6 +181,15 @@ class Index(IndexOpsMixin, PandasObject): tupleize_cols : bool (default: True) When True, attempt to create a MultiIndex if possible + See Also + --------- + RangeIndex : Index implementing a monotonic integer range. + CategoricalIndex : Index of :class:`Categorical` s. + MultiIndex : A multi-level, or hierarchical, Index. + IntervalIndex : An Index of :class:`Interval` s. + DatetimeIndex, TimedeltaIndex, PeriodIndex + Int64Index, UInt64Index, Float64Index + Notes ----- An Index instance can **only** contain hashable objects @@ -192,15 +201,6 @@ class Index(IndexOpsMixin, PandasObject): >>> pd.Index(list('abc')) Index(['a', 'b', 'c'], dtype='object') - - See Also - --------- - RangeIndex : Index implementing a monotonic integer range. - CategoricalIndex : Index of :class:`Categorical` s. - MultiIndex : A multi-level, or hierarchical, Index. - IntervalIndex : An Index of :class:`Interval` s. - DatetimeIndex, TimedeltaIndex, PeriodIndex - Int64Index, UInt64Index, Float64Index """ # To hand over control to subclasses _join_precedence = 1 @@ -2069,6 +2069,16 @@ def duplicated(self, keep='first'): occurrence. - ``False`` : Mark all duplicates as ``True``. + Returns + ------- + numpy.ndarray + + See Also + -------- + pandas.Series.duplicated : Equivalent method on pandas.Series. + pandas.DataFrame.duplicated : Equivalent method on pandas.DataFrame. + pandas.Index.drop_duplicates : Remove duplicate values from Index. + Examples -------- By default, for each set of duplicated values, the first occurrence is @@ -2093,16 +2103,6 @@ def duplicated(self, keep='first'): >>> idx.duplicated(keep=False) array([ True, False, True, False, True]) - - Returns - ------- - numpy.ndarray - - See Also - -------- - pandas.Series.duplicated : Equivalent method on pandas.Series. - pandas.DataFrame.duplicated : Equivalent method on pandas.DataFrame. - pandas.Index.drop_duplicates : Remove duplicate values from Index. """ return super(Index, self).duplicated(keep=keep) @@ -4187,6 +4187,11 @@ def shift(self, periods=1, freq=None): -------- Series.shift : Shift values of Series. + Notes + ----- + This method is only implemented for datetime-like index classes, + i.e., DatetimeIndex, PeriodIndex and TimedeltaIndex. + Examples -------- Put the first 5 month starts of 2011 into an index. @@ -4211,11 +4216,6 @@ def shift(self, periods=1, freq=None): DatetimeIndex(['2011-11-01', '2011-12-01', '2012-01-01', '2012-02-01', '2012-03-01'], dtype='datetime64[ns]', freq='MS') - - Notes - ----- - This method is only implemented for datetime-like index classes, - i.e., DatetimeIndex, PeriodIndex and TimedeltaIndex. """ raise NotImplementedError("Not supported for type %s" % type(self).__name__) @@ -4768,6 +4768,10 @@ def slice_locs(self, start=None, end=None, step=None, kind=None): ------- start, end : int + See Also + -------- + Index.get_loc : Get location for a single label. + Notes ----- This method only works if the index is monotonic or unique. @@ -4777,10 +4781,6 @@ def slice_locs(self, start=None, end=None, step=None, kind=None): >>> idx = pd.Index(list('abcd')) >>> idx.slice_locs(start='b', end='c') (1, 3) - - See Also - -------- - Index.get_loc : Get location for a single label. """ inc = (step is None or step >= 0) diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index fd4a1527c07b7..c30e64fcf04da 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -1526,6 +1526,10 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None, **kwargs For compatibility. Has no effect on the result. + Returns + ------- + DatetimeIndex + Notes ----- Of the four parameters: ``start``, ``end``, ``periods``, and ``freq``, @@ -1536,10 +1540,6 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None, To learn more about the frequency strings, please see `this link `__. - Returns - ------- - DatetimeIndex - Examples -------- Note how the two weekend days are skipped in the result. diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index 444f9e21b0bdc..e526aa72affee 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -486,6 +486,12 @@ def is_overlapping(self): bool Boolean indicating if the IntervalIndex has overlapping intervals. + See Also + -------- + Interval.overlaps : Check whether two Interval objects overlap. + IntervalIndex.overlaps : Check an IntervalIndex elementwise for + overlaps. + Examples -------- >>> index = pd.IntervalIndex.from_tuples([(0, 2), (1, 3), (4, 5)]) @@ -515,12 +521,6 @@ def is_overlapping(self): dtype='interval[int64]') >>> index.is_overlapping False - - See Also - -------- - Interval.overlaps : Check whether two Interval objects overlap. - IntervalIndex.overlaps : Check an IntervalIndex elementwise for - overlaps. """ # GH 23309 return self._engine.is_overlapping @@ -1180,6 +1180,14 @@ def interval_range(start=None, end=None, periods=None, freq=None, Whether the intervals are closed on the left-side, right-side, both or neither. + Returns + ------- + rng : IntervalIndex + + See Also + -------- + IntervalIndex : An Index of intervals that are all closed on the same side. + Notes ----- Of the four parameters ``start``, ``end``, ``periods``, and ``freq``, @@ -1190,10 +1198,6 @@ def interval_range(start=None, end=None, periods=None, freq=None, To learn more about datetime-like frequency strings, please see `this link `__. - Returns - ------- - rng : IntervalIndex - Examples -------- Numeric ``start`` and ``end`` is supported. @@ -1241,10 +1245,6 @@ def interval_range(start=None, end=None, periods=None, freq=None, >>> pd.interval_range(end=5, periods=4, closed='both') IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]] closed='both', dtype='interval[int64]') - - See Also - -------- - IntervalIndex : An Index of intervals that are all closed on the same side. """ start = com.maybe_box_datetimelike(start) end = com.maybe_box_datetimelike(end) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 5e26a3c6c439e..34fca8fe58449 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -145,34 +145,6 @@ class MultiIndex(Index): verify_integrity : boolean, default True Check that the levels/codes are consistent and valid - Examples - --------- - A new ``MultiIndex`` is typically constructed using one of the helper - methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product` - and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``): - - >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']] - >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color')) - MultiIndex(levels=[[1, 2], ['blue', 'red']], - labels=[[0, 0, 1, 1], [1, 0, 1, 0]], - names=['number', 'color']) - - See further examples for how to construct a MultiIndex in the doc strings - of the mentioned helper methods. - - Notes - ----- - See the `user guide - `_ for more. - - See Also - -------- - MultiIndex.from_arrays : Convert list of arrays to MultiIndex. - MultiIndex.from_product : Create a MultiIndex from the cartesian product - of iterables. - MultiIndex.from_tuples : Convert list of tuples to a MultiIndex. - Index : The base pandas Index type. - Attributes ---------- names @@ -196,6 +168,34 @@ class MultiIndex(Index): swaplevel reorder_levels remove_unused_levels + + See Also + -------- + MultiIndex.from_arrays : Convert list of arrays to MultiIndex. + MultiIndex.from_product : Create a MultiIndex from the cartesian product + of iterables. + MultiIndex.from_tuples : Convert list of tuples to a MultiIndex. + Index : The base pandas Index type. + + Notes + ----- + See the `user guide + `_ for more. + + Examples + --------- + A new ``MultiIndex`` is typically constructed using one of the helper + methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product` + and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``): + + >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']] + >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color')) + MultiIndex(levels=[[1, 2], ['blue', 'red']], + labels=[[0, 0, 1, 1], [1, 0, 1, 0]], + names=['number', 'color']) + + See further examples for how to construct a MultiIndex in the doc strings + of the mentioned helper methods. """ # initialize to zero-length tuples to make everything work @@ -303,16 +303,16 @@ def from_arrays(cls, arrays, sortorder=None, names=None): ------- index : MultiIndex - Examples - -------- - >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']] - >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color')) - See Also -------- MultiIndex.from_tuples : Convert list of tuples to MultiIndex. MultiIndex.from_product : Make a MultiIndex from cartesian product of iterables. + + Examples + -------- + >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']] + >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color')) """ if not is_list_like(arrays): raise TypeError("Input must be a list / sequence of array-likes.") @@ -351,17 +351,17 @@ def from_tuples(cls, tuples, sortorder=None, names=None): ------- index : MultiIndex - Examples - -------- - >>> tuples = [(1, u'red'), (1, u'blue'), - (2, u'red'), (2, u'blue')] - >>> pd.MultiIndex.from_tuples(tuples, names=('number', 'color')) - See Also -------- MultiIndex.from_arrays : Convert list of arrays to MultiIndex MultiIndex.from_product : Make a MultiIndex from cartesian product of iterables + + Examples + -------- + >>> tuples = [(1, u'red'), (1, u'blue'), + (2, u'red'), (2, u'blue')] + >>> pd.MultiIndex.from_tuples(tuples, names=('number', 'color')) """ if not is_list_like(tuples): raise TypeError('Input must be a list / sequence of tuple-likes.') @@ -404,6 +404,11 @@ def from_product(cls, iterables, sortorder=None, names=None): ------- index : MultiIndex + See Also + -------- + MultiIndex.from_arrays : Convert list of arrays to MultiIndex. + MultiIndex.from_tuples : Convert list of tuples to MultiIndex. + Examples -------- >>> numbers = [0, 1, 2] @@ -413,11 +418,6 @@ def from_product(cls, iterables, sortorder=None, names=None): MultiIndex(levels=[[0, 1, 2], [u'green', u'purple']], labels=[[0, 0, 1, 1, 2, 2], [0, 1, 0, 1, 0, 1]], names=[u'number', u'color']) - - See Also - -------- - MultiIndex.from_arrays : Convert list of arrays to MultiIndex. - MultiIndex.from_tuples : Convert list of tuples to MultiIndex. """ from pandas.core.arrays.categorical import _factorize_from_iterables from pandas.core.reshape.util import cartesian_product diff --git a/pandas/core/indexes/numeric.py b/pandas/core/indexes/numeric.py index 491176bc586a8..9d6a56200df6e 100644 --- a/pandas/core/indexes/numeric.py +++ b/pandas/core/indexes/numeric.py @@ -147,13 +147,13 @@ def insert(self, loc, item): ------- None - Notes - ----- - An Index instance can **only** contain hashable objects. - See Also -------- Index : The base pandas Index type. + + Notes + ----- + An Index instance can **only** contain hashable objects. """ _int64_descr_args = dict( diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py index 3d69a0a84f7ae..23a8ab54c4e6d 100644 --- a/pandas/core/indexes/period.py +++ b/pandas/core/indexes/period.py @@ -989,6 +989,10 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None): name : string, default None Name of the resulting PeriodIndex + Returns + ------- + prng : PeriodIndex + Notes ----- Of the three parameters: ``start``, ``end``, and ``periods``, exactly two @@ -997,10 +1001,6 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None): To learn more about the frequency strings, please see `this link `__. - Returns - ------- - prng : PeriodIndex - Examples -------- diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 364aadb9523f0..0da924de244ed 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -46,11 +46,6 @@ class RangeIndex(Int64Index): copy : bool, default False Unused, accepted for homogeneity with other index types. - See Also - -------- - Index : The base pandas Index type. - Int64Index : Index of int64 data. - Attributes ---------- None @@ -58,6 +53,11 @@ class RangeIndex(Int64Index): Methods ------- from_range + + See Also + -------- + Index : The base pandas Index type. + Int64Index : Index of int64 data. """ _typ = 'rangeindex' diff --git a/pandas/core/indexes/timedeltas.py b/pandas/core/indexes/timedeltas.py index 1c84e592d3a0d..5d52696992c30 100644 --- a/pandas/core/indexes/timedeltas.py +++ b/pandas/core/indexes/timedeltas.py @@ -80,19 +80,6 @@ class TimedeltaIndex(TimedeltaArray, DatetimeIndexOpsMixin, name : object Name to be stored in the index - Notes - ----- - - To learn more about the frequency strings, please see `this link - `__. - - See Also - --------- - Index : The base pandas Index type. - Timedelta : Represents a duration between two dates or times. - DatetimeIndex : Index of datetime64 data. - PeriodIndex : Index of Period data. - Attributes ---------- days @@ -110,6 +97,19 @@ class TimedeltaIndex(TimedeltaArray, DatetimeIndexOpsMixin, floor ceil to_frame + + See Also + --------- + Index : The base pandas Index type. + Timedelta : Represents a duration between two dates or times. + DatetimeIndex : Index of datetime64 data. + PeriodIndex : Index of Period data. + + Notes + ----- + + To learn more about the frequency strings, please see `this link + `__. """ _typ = 'timedeltaindex' diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index 0914324a03f84..ab4ad693a462e 100755 --- a/pandas/core/indexing.py +++ b/pandas/core/indexing.py @@ -1559,6 +1559,11 @@ class _LocIndexer(_LocationIndexer): See more at :ref:`Selection by Label ` + Raises + ------ + KeyError: + when any items are not found + See Also -------- DataFrame.at : Access a single value for a row/column label pair. @@ -1765,11 +1770,6 @@ class _LocIndexer(_LocationIndexer): sidewinder mark i 10 20 mark ii 1 4 viper mark ii 7 1 - - Raises - ------ - KeyError: - when any items are not found """ _valid_types = ("labels (MUST BE IN THE INDEX), slices of labels (BOTH " @@ -2291,6 +2291,11 @@ class _AtIndexer(_ScalarAccessIndexer): ``at`` if you only need to get or set a single value in a DataFrame or Series. + Raises + ------ + KeyError + When label does not exist in DataFrame + See Also -------- DataFrame.iat : Access a single value for a row/column pair by integer @@ -2323,11 +2328,6 @@ class _AtIndexer(_ScalarAccessIndexer): >>> df.loc[5].at['B'] 4 - - Raises - ------ - KeyError - When label does not exist in DataFrame """ _takeable = False @@ -2362,6 +2362,11 @@ class _iAtIndexer(_ScalarAccessIndexer): ``iat`` if you only need to get or set a single value in a DataFrame or Series. + Raises + ------ + IndexError + When integer position is out of bounds + See Also -------- DataFrame.at : Access a single value for a row/column label pair. @@ -2393,11 +2398,6 @@ class _iAtIndexer(_ScalarAccessIndexer): >>> df.loc[0].iat[1] 2 - - Raises - ------ - IndexError - When integer position is out of bounds """ _takeable = True diff --git a/pandas/core/ops.py b/pandas/core/ops.py index bd5268808e7b2..41e3f4581587e 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -468,6 +468,10 @@ def _get_op_name(op, special): ------- result : Series +See Also +-------- +Series.{reverse} + Examples -------- >>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd']) @@ -491,10 +495,6 @@ def _get_op_name(op, special): d 1.0 e NaN dtype: float64 - -See Also --------- -Series.{reverse} """ _arith_doc_FRAME = """ @@ -515,13 +515,13 @@ def _get_op_name(op, special): Broadcast across a level, matching Index values on the passed MultiIndex level -Notes ------ -Mismatched indices will be unioned together - Returns ------- result : DataFrame + +Notes +----- +Mismatched indices will be unioned together """ _flex_doc_FRAME = """ @@ -549,10 +549,6 @@ def _get_op_name(op, special): If data in both corresponding DataFrame locations is missing the result will be missing. -Notes ------ -Mismatched indices will be unioned together. - Returns ------- DataFrame @@ -569,6 +565,10 @@ def _get_op_name(op, special): DataFrame.mod : Calculate modulo (remainder after division). DataFrame.pow : Calculate exponential power. +Notes +----- +Mismatched indices will be unioned together. + Examples -------- >>> df = pd.DataFrame({{'angles': [0, 3, 4], diff --git a/pandas/core/panel.py b/pandas/core/panel.py index bb3412a3d7c0c..540192d1a592c 100644 --- a/pandas/core/panel.py +++ b/pandas/core/panel.py @@ -1012,6 +1012,10 @@ def apply(self, func, axis='major', **kwargs): axes Additional keyword arguments will be passed as keywords to the function + Returns + ------- + result : Panel, DataFrame, or Series + Examples -------- @@ -1032,10 +1036,6 @@ def apply(self, func, axis='major', **kwargs): items x major), as a Series >>> p.apply(lambda x: x.shape, axis=(0,1)) # doctest: +SKIP - - Returns - ------- - result : Panel, DataFrame, or Series """ if kwargs and not isinstance(func, np.ufunc): diff --git a/pandas/core/resample.py b/pandas/core/resample.py index f2cf17f8f060d..dc1f94c479a37 100644 --- a/pandas/core/resample.py +++ b/pandas/core/resample.py @@ -212,6 +212,12 @@ def pipe(self, func, *args, **kwargs): return super(Resampler, self).pipe(func, *args, **kwargs) _agg_doc = dedent(""" + See Also + -------- + pandas.DataFrame.groupby.aggregate + pandas.DataFrame.resample.transform + pandas.DataFrame.aggregate + Examples -------- >>> s = pd.Series([1,2,3,4,5], @@ -245,12 +251,6 @@ def pipe(self, func, *args, **kwargs): 2013-01-01 00:00:00 3 2.121320 2013-01-01 00:00:02 7 4.949747 2013-01-01 00:00:04 5 NaN - - See Also - -------- - pandas.DataFrame.groupby.aggregate - pandas.DataFrame.resample.transform - pandas.DataFrame.aggregate """) @Appender(_agg_doc) @@ -286,13 +286,13 @@ def transform(self, arg, *args, **kwargs): func : function To apply to each group. Should return a Series with the same index - Examples - -------- - >>> resampled.transform(lambda x: (x - x.mean()) / x.std()) - Returns ------- transformed : Series + + Examples + -------- + >>> resampled.transform(lambda x: (x - x.mean()) / x.std()) """ return self._selected_obj.groupby(self.groupby).transform( arg, *args, **kwargs) @@ -635,6 +635,10 @@ def fillna(self, method, limit=None): pandas.DataFrame.fillna : Fill NaN values in the DataFrame using the specified method, which can be 'bfill' and 'ffill'. + References + ---------- + .. [1] https://en.wikipedia.org/wiki/Imputation_(statistics) + Examples -------- Resampling a Series: @@ -746,10 +750,6 @@ def fillna(self, method, limit=None): 2018-01-01 01:00:00 NaN 3 2018-01-01 01:30:00 6.0 5 2018-01-01 02:00:00 6.0 5 - - References - ---------- - .. [1] https://en.wikipedia.org/wiki/Imputation_(statistics) """ return self._upsample(method, limit=limit) diff --git a/pandas/core/reshape/concat.py b/pandas/core/reshape/concat.py index b13b22d2e8266..53671e00e88b4 100644 --- a/pandas/core/reshape/concat.py +++ b/pandas/core/reshape/concat.py @@ -87,6 +87,13 @@ def concat(objs, axis=0, join='outer', join_axes=None, ignore_index=False, ``DataFrame``, a ``DataFrame`` is returned. When concatenating along the columns (axis=1), a ``DataFrame`` is returned. + See Also + -------- + Series.append + DataFrame.append + DataFrame.join + DataFrame.merge + Notes ----- The keys, levels, and names arguments are all optional. @@ -95,13 +102,6 @@ def concat(objs, axis=0, join='outer', join_axes=None, ignore_index=False, pandas objects can be found `here `__. - See Also - -------- - Series.append - DataFrame.append - DataFrame.join - DataFrame.merge - Examples -------- Combine two ``Series``. diff --git a/pandas/core/reshape/melt.py b/pandas/core/reshape/melt.py index aafc0de64ee12..312a108ad3380 100644 --- a/pandas/core/reshape/melt.py +++ b/pandas/core/reshape/melt.py @@ -232,6 +232,12 @@ def wide_to_long(df, stubnames, i, j, sep="", suffix=r'\d+'): A DataFrame that contains each stub name as a variable, with new index (i, j) + Notes + ----- + All extra variables are left untouched. This simply uses + `pandas.melt` under the hood, but is hard-coded to "do the right thing" + in a typical case. + Examples -------- >>> np.random.seed(123) @@ -403,12 +409,6 @@ def wide_to_long(df, stubnames, i, j, sep="", suffix=r'\d+'): two 3.4 3 one 2.1 two 2.9 - - Notes - ----- - All extra variables are left untouched. This simply uses - `pandas.melt` under the hood, but is hard-coded to "do the right thing" - in a typical case. """ def get_var_names(df, stub, sep, suffix): regex = r'^{stub}{sep}{suffix}$'.format( diff --git a/pandas/core/reshape/merge.py b/pandas/core/reshape/merge.py index c0c016f9a8caa..e6e6c1c99b509 100644 --- a/pandas/core/reshape/merge.py +++ b/pandas/core/reshape/merge.py @@ -169,6 +169,17 @@ def merge_ordered(left, right, on=None, .. versionadded:: 0.19.0 + Returns + ------- + merged : DataFrame + The output type will the be same as 'left', if it is a subclass + of DataFrame. + + See Also + -------- + merge + merge_asof + Examples -------- >>> A >>> B @@ -192,17 +203,6 @@ def merge_ordered(left, right, on=None, 7 b c 2 2.0 8 b d 2 3.0 9 b e 3 3.0 - - Returns - ------- - merged : DataFrame - The output type will the be same as 'left', if it is a subclass - of DataFrame. - - See Also - -------- - merge - merge_asof """ def _merger(x, y): # perform the ordered merge operation @@ -315,6 +315,11 @@ def merge_asof(left, right, on=None, ------- merged : DataFrame + See Also + -------- + merge + merge_ordered + Examples -------- >>> left = pd.DataFrame({'a': [1, 5, 10], 'left_val': ['a', 'b', 'c']}) @@ -444,11 +449,6 @@ def merge_asof(left, right, on=None, 2 2016-05-25 13:30:00.048 GOOG 720.77 100 NaN NaN 3 2016-05-25 13:30:00.048 GOOG 720.92 100 NaN NaN 4 2016-05-25 13:30:00.048 AAPL 98.00 100 NaN NaN - - See Also - -------- - merge - merge_ordered """ op = _AsOfMerge(left, right, on=on, left_on=left_on, right_on=right_on, diff --git a/pandas/core/reshape/pivot.py b/pandas/core/reshape/pivot.py index 84faab017163f..61ac5d9ed6a2e 100644 --- a/pandas/core/reshape/pivot.py +++ b/pandas/core/reshape/pivot.py @@ -433,6 +433,10 @@ def crosstab(index, columns, values=None, rownames=None, colnames=None, .. versionadded:: 0.18.1 + Returns + ------- + crosstab : DataFrame + Notes ----- Any Series passed will have their name attributes used unless row or column @@ -484,10 +488,6 @@ def crosstab(index, columns, values=None, rownames=None, colnames=None, a 1 0 0 b 0 1 0 c 0 0 0 - - Returns - ------- - crosstab : DataFrame """ index = com.maybe_make_list(index) diff --git a/pandas/core/reshape/reshape.py b/pandas/core/reshape/reshape.py index ba86d3d9ba25f..ff4f9b7847019 100644 --- a/pandas/core/reshape/reshape.py +++ b/pandas/core/reshape/reshape.py @@ -724,6 +724,10 @@ def get_dummies(data, prefix=None, prefix_sep='_', dummy_na=False, ------- dummies : DataFrame or SparseDataFrame + See Also + -------- + Series.str.get_dummies + Examples -------- >>> s = pd.Series(list('abca')) @@ -779,10 +783,6 @@ def get_dummies(data, prefix=None, prefix_sep='_', dummy_na=False, 0 1.0 0.0 0.0 1 0.0 1.0 0.0 2 0.0 0.0 1.0 - - See Also - -------- - Series.str.get_dummies """ from pandas.core.reshape.concat import concat from itertools import cycle diff --git a/pandas/core/series.py b/pandas/core/series.py index 6d951a7a5228a..4f9465354a47b 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -542,6 +542,10 @@ def nonzero(self): but it will always be a one-item tuple because series only have one dimension. + See Also + -------- + numpy.nonzero + Examples -------- >>> s = pd.Series([0, 3, 0, 4]) @@ -560,10 +564,6 @@ def nonzero(self): b 3 d 4 dtype: int64 - - See Also - -------- - numpy.nonzero """ return self._values.nonzero() @@ -1646,6 +1646,16 @@ def duplicated(self, keep='first'): occurrence. - ``False`` : Mark all duplicates as ``True``. + Returns + ------- + pandas.core.series.Series + + See Also + -------- + Index.duplicated : Equivalent method on pandas.Index. + DataFrame.duplicated : Equivalent method on pandas.DataFrame. + Series.drop_duplicates : Remove duplicate values from Series. + Examples -------- By default, for each set of duplicated values, the first occurrence is @@ -1690,16 +1700,6 @@ def duplicated(self, keep='first'): 3 False 4 True dtype: bool - - Returns - ------- - pandas.core.series.Series - - See Also - -------- - Index.duplicated : Equivalent method on pandas.Index. - DataFrame.duplicated : Equivalent method on pandas.DataFrame. - Series.drop_duplicates : Remove duplicate values from Series. """ return super(Series, self).duplicated(keep=keep) @@ -1731,12 +1731,6 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): ValueError If the Series is empty. - Notes - ----- - This method is the Series version of ``ndarray.argmin``. This method - returns the label of the minimum, while ``ndarray.argmin`` returns - the position. To get the position, use ``series.values.argmin()``. - See Also -------- numpy.argmin : Return indices of the minimum values @@ -1746,6 +1740,12 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): Series.idxmax : Return index *label* of the first occurrence of maximum of values. + Notes + ----- + This method is the Series version of ``ndarray.argmin``. This method + returns the label of the minimum, while ``ndarray.argmin`` returns + the position. To get the position, use ``series.values.argmin()``. + Examples -------- >>> s = pd.Series(data=[1, None, 4, 1], @@ -1800,12 +1800,6 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): ValueError If the Series is empty. - Notes - ----- - This method is the Series version of ``ndarray.argmax``. This method - returns the label of the maximum, while ``ndarray.argmax`` returns - the position. To get the position, use ``series.values.argmax()``. - See Also -------- numpy.argmax : Return indices of the maximum values @@ -1815,6 +1809,12 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Series.idxmin : Return index *label* of the first occurrence of minimum of values. + Notes + ----- + This method is the Series version of ``ndarray.argmax``. This method + returns the label of the maximum, while ``ndarray.argmax`` returns + the position. To get the position, use ``series.values.argmax()``. + Examples -------- >>> s = pd.Series(data=[1, None, 4, 3, 4], @@ -1917,6 +1917,11 @@ def quantile(self, q=0.5, interpolation='linear'): if ``q`` is an array, a Series will be returned where the index is ``q`` and the values are the quantiles. + See Also + -------- + core.window.Rolling.quantile + numpy.percentile + Examples -------- >>> s = pd.Series([1, 2, 3, 4]) @@ -1927,11 +1932,6 @@ def quantile(self, q=0.5, interpolation='linear'): 0.50 2.50 0.75 3.25 dtype: float64 - - See Also - -------- - core.window.Rolling.quantile - numpy.percentile """ self._check_percentile(q) @@ -2235,21 +2235,21 @@ def append(self, to_append, ignore_index=False, verify_integrity=False): verify_integrity : boolean, default False If True, raise Exception on creating index with duplicates - Notes - ----- - Iteratively appending to a Series can be more computationally intensive - than a single concatenate. A better solution is to append values to a - list and then concatenate the list with the original Series all at - once. + Returns + ------- + appended : Series See Also -------- concat : General function to concatenate DataFrame, Series or Panel objects. - Returns - ------- - appended : Series + Notes + ----- + Iteratively appending to a Series can be more computationally intensive + than a single concatenate. A better solution is to append values to a + list and then concatenate the list with the original Series all at + once. Examples -------- @@ -2922,17 +2922,17 @@ def nlargest(self, n=5, keep='first'): Series The `n` largest values in the Series, sorted in decreasing order. - Notes - ----- - Faster than ``.sort_values(ascending=False).head(n)`` for small `n` - relative to the size of the ``Series`` object. - See Also -------- Series.nsmallest: Get the `n` smallest elements. Series.sort_values: Sort Series by values. Series.head: Return the first `n` rows. + Notes + ----- + Faster than ``.sort_values(ascending=False).head(n)`` for small `n` + relative to the size of the ``Series`` object. + Examples -------- >>> countries_population = {"Italy": 59000000, "France": 65000000, @@ -3018,17 +3018,17 @@ def nsmallest(self, n=5, keep='first'): Series The `n` smallest values in the Series, sorted in increasing order. - Notes - ----- - Faster than ``.sort_values().head(n)`` for small `n` relative to - the size of the ``Series`` object. - See Also -------- Series.nlargest: Get the `n` largest elements. Series.sort_values: Sort Series by values. Series.head: Return the first `n` rows. + Notes + ----- + Faster than ``.sort_values().head(n)`` for small `n` relative to + the size of the ``Series`` object. + Examples -------- >>> countries_population = {"Italy": 59000000, "France": 65000000, @@ -3149,6 +3149,10 @@ def unstack(self, level=-1, fill_value=None): .. versionadded:: 0.18.0 + Returns + ------- + unstacked : DataFrame + Examples -------- >>> s = pd.Series([1, 2, 3, 4], @@ -3169,10 +3173,6 @@ def unstack(self, level=-1, fill_value=None): one two a 1 3 b 2 4 - - Returns - ------- - unstacked : DataFrame """ from pandas.core.reshape.reshape import unstack return unstack(self, level, fill_value) @@ -3275,6 +3275,12 @@ def _gotitem(self, key, ndim, subset=None): return self _agg_doc = dedent(""" + See Also + -------- + Series.apply : Invoke function on a Series. + Series.transform : Transform function producing + a Series with like indexes. + Examples -------- @@ -3293,12 +3299,6 @@ def _gotitem(self, key, ndim, subset=None): min 1 max 4 dtype: int64 - - See Also - -------- - Series.apply : Invoke function on a Series. - Series.transform : Transform function producing - a Series with like indexes. """) @Appender(_agg_doc) @@ -3637,6 +3637,11 @@ def drop(self, labels=None, axis=0, index=None, columns=None, ------- dropped : pandas.Series + Raises + ------ + KeyError + If none of the labels are found in the index. + See Also -------- Series.reindex : Return only specified index labels of Series. @@ -3644,11 +3649,6 @@ def drop(self, labels=None, axis=0, index=None, columns=None, Series.drop_duplicates : Return Series with duplicate values removed. DataFrame.drop : Drop specified labels from rows or columns. - Raises - ------ - KeyError - If none of the labels are found in the index. - Examples -------- >>> s = pd.Series(data=np.arange(3), index=['A','B','C']) @@ -3893,15 +3893,15 @@ def between(self, left, right, inclusive=True): Series Each element will be a boolean. - Notes - ----- - This function is equivalent to ``(left <= ser) & (ser <= right)`` - See Also -------- Series.gt : Greater than of series and other. Series.lt : Less than of series and other. + Notes + ----- + This function is equivalent to ``(left <= ser) & (ser <= right)`` + Examples -------- >>> s = pd.Series([2, 0, 4, 8, np.nan]) @@ -3991,13 +3991,13 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None, datetime format based on the first datetime string. If the format can be inferred, there often will be a large parsing speed-up. - See Also - -------- - read_csv - Returns ------- y : Series + + See Also + -------- + read_csv """ # We're calling `DataFrame.from_csv` in the implementation, diff --git a/pandas/core/strings.py b/pandas/core/strings.py index d3d38d26ee86b..20ac13ed0ef71 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -123,17 +123,17 @@ def str_count(arr, pat, flags=0): counts : Series or Index Same type as the calling object containing the integer counts. + See Also + -------- + re : Standard library module for regular expressions. + str.count : Standard library version, without regular expression support. + Notes ----- Some characters need to be escaped when passing in `pat`. eg. ``'$'`` has a special meaning in regex and must be escaped when finding this literal character. - See Also - -------- - re : Standard library module for regular expressions. - str.count : Standard library version, without regular expression support. - Examples -------- >>> s = pd.Series(['A', 'B', 'Aaba', 'Baca', np.nan, 'CABA', 'cat']) @@ -978,6 +978,10 @@ def str_get_dummies(arr, sep='|'): ------- dummies : DataFrame + See Also + -------- + get_dummies + Examples -------- >>> pd.Series(['a|b', 'a', 'a|c']).str.get_dummies() @@ -991,10 +995,6 @@ def str_get_dummies(arr, sep='|'): 0 1 1 0 1 0 0 0 2 1 0 1 - - See Also - -------- - get_dummies """ arr = arr.fillna('') try: @@ -1039,16 +1039,16 @@ def str_join(arr, sep): AttributeError If the supplied Series contains neither strings nor lists. - Notes - ----- - If any of the list items is not a string object, the result of the join - will be `NaN`. - See Also -------- str.join : Standard library version of this method. Series.str.split : Split strings around given separator/delimiter. + Notes + ----- + If any of the list items is not a string object, the result of the join + will be `NaN`. + Examples -------- Example with a list that contains non-string elements. diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py index 86bb4e4b94382..4fca5216e24f3 100644 --- a/pandas/core/tools/datetimes.py +++ b/pandas/core/tools/datetimes.py @@ -479,6 +479,11 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, return will have datetime.datetime type (or corresponding array/Series). + See Also + -------- + pandas.DataFrame.astype : Cast argument to a specified dtype. + pandas.to_timedelta : Convert argument to timedelta. + Examples -------- Assembling a datetime from multiple columns of a DataFrame. The keys can be @@ -542,11 +547,6 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, 0 1960-01-02 1 1960-01-03 2 1960-01-04 - - See Also - -------- - pandas.DataFrame.astype : Cast argument to a specified dtype. - pandas.to_timedelta : Convert argument to timedelta. """ if arg is None: return None diff --git a/pandas/core/tools/numeric.py b/pandas/core/tools/numeric.py index 1d4973de92b99..803723dab46ff 100644 --- a/pandas/core/tools/numeric.py +++ b/pandas/core/tools/numeric.py @@ -53,6 +53,13 @@ def to_numeric(arg, errors='raise', downcast=None): ret : numeric if parsing succeeded. Return type depends on input. Series if Series, otherwise ndarray + See Also + -------- + pandas.DataFrame.astype : Cast argument to a specified dtype. + pandas.to_datetime : Convert argument to datetime. + pandas.to_timedelta : Convert argument to timedelta. + numpy.ndarray.astype : Cast a numpy array to a specified type. + Examples -------- Take separate series and convert to numeric, coercing when told to @@ -86,13 +93,6 @@ def to_numeric(arg, errors='raise', downcast=None): 2 2.0 3 -3.0 dtype: float64 - - See Also - -------- - pandas.DataFrame.astype : Cast argument to a specified dtype. - pandas.to_datetime : Convert argument to datetime. - pandas.to_timedelta : Convert argument to timedelta. - numpy.ndarray.astype : Cast a numpy array to a specified type. """ if downcast not in (None, 'integer', 'signed', 'unsigned', 'float'): raise ValueError('invalid downcasting method provided') diff --git a/pandas/core/window.py b/pandas/core/window.py index 6c4dde54bd061..8c4803a732dd8 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -478,6 +478,40 @@ class Window(_Window): ------- a Window or Rolling sub-classed for the particular operation + See Also + -------- + expanding : Provides expanding transformations. + ewm : Provides exponential weighted functions. + + Notes + ----- + By default, the result is set to the right edge of the window. This can be + changed to the center of the window by setting ``center=True``. + + To learn more about the offsets & frequency strings, please see `this link + `__. + + The recognized win_types are: + + * ``boxcar`` + * ``triang`` + * ``blackman`` + * ``hamming`` + * ``bartlett`` + * ``parzen`` + * ``bohman`` + * ``blackmanharris`` + * ``nuttall`` + * ``barthann`` + * ``kaiser`` (needs beta) + * ``gaussian`` (needs std) + * ``general_gaussian`` (needs power, width) + * ``slepian`` (needs width). + + If ``win_type=None`` all points are evenly weighted. To learn more about + different window types see `scipy.signal window functions + `__. + Examples -------- @@ -550,40 +584,6 @@ class Window(_Window): 2013-01-01 09:00:03 3.0 2013-01-01 09:00:05 NaN 2013-01-01 09:00:06 4.0 - - Notes - ----- - By default, the result is set to the right edge of the window. This can be - changed to the center of the window by setting ``center=True``. - - To learn more about the offsets & frequency strings, please see `this link - `__. - - The recognized win_types are: - - * ``boxcar`` - * ``triang`` - * ``blackman`` - * ``hamming`` - * ``bartlett`` - * ``parzen`` - * ``bohman`` - * ``blackmanharris`` - * ``nuttall`` - * ``barthann`` - * ``kaiser`` (needs beta) - * ``gaussian`` (needs std) - * ``general_gaussian`` (needs power, width) - * ``slepian`` (needs width). - - If ``win_type=None`` all points are evenly weighted. To learn more about - different window types see `scipy.signal window functions - `__. - - See Also - -------- - expanding : Provides expanding transformations. - ewm : Provides exponential weighted functions. """ def validate(self): @@ -1596,6 +1596,11 @@ def _validate_freq(self): "index".format(self.window)) _agg_doc = dedent(""" + See Also + -------- + pandas.Series.rolling + pandas.DataFrame.rolling + Examples -------- @@ -1638,11 +1643,6 @@ def _validate_freq(self): 7 2.718061 -1.647453 8 -0.289082 -1.647453 9 0.212668 -1.647453 - - See Also - -------- - pandas.Series.rolling - pandas.DataFrame.rolling """) @Appender(_agg_doc) @@ -1821,6 +1821,16 @@ class Expanding(_Rolling_and_Expanding): ------- a Window sub-classed for the particular operation + See Also + -------- + rolling : Provides rolling window calculations. + ewm : Provides exponential weighted functions. + + Notes + ----- + By default, the result is set to the right edge of the window. This can be + changed to the center of the window by setting ``center=True``. + Examples -------- @@ -1839,16 +1849,6 @@ class Expanding(_Rolling_and_Expanding): 2 3.0 3 3.0 4 7.0 - - Notes - ----- - By default, the result is set to the right edge of the window. This can be - changed to the center of the window by setting ``center=True``. - - See Also - -------- - rolling : Provides rolling window calculations. - ewm : Provides exponential weighted functions. """ _attributes = ['min_periods', 'center', 'axis'] @@ -2116,24 +2116,10 @@ class EWM(_Rolling): ------- a Window sub-classed for the particular operation - Examples + See Also -------- - - >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]}) - B - 0 0.0 - 1 1.0 - 2 2.0 - 3 NaN - 4 4.0 - - >>> df.ewm(com=0.5).mean() - B - 0 0.000000 - 1 0.750000 - 2 1.615385 - 3 1.615385 - 4 3.670213 + rolling : Provides rolling window calculations. + expanding : Provides expanding transformations. Notes ----- @@ -2162,10 +2148,24 @@ class EWM(_Rolling): More details can be found at http://pandas.pydata.org/pandas-docs/stable/computation.html#exponentially-weighted-windows - See Also + Examples -------- - rolling : Provides rolling window calculations. - expanding : Provides expanding transformations. + + >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]}) + B + 0 0.0 + 1 1.0 + 2 2.0 + 3 NaN + 4 4.0 + + >>> df.ewm(com=0.5).mean() + B + 0 0.000000 + 1 0.750000 + 2 1.615385 + 3 1.615385 + 4 3.670213 """ _attributes = ['com', 'min_periods', 'adjust', 'ignore_na', 'axis'] diff --git a/pandas/io/excel.py b/pandas/io/excel.py index 03d873467dc10..c2c9a688f3f0a 100644 --- a/pandas/io/excel.py +++ b/pandas/io/excel.py @@ -930,6 +930,14 @@ class ExcelWriter(object): .. versionadded:: 0.24.0 + Attributes + ---------- + None + + Methods + ------- + None + Notes ----- None of the methods and properties are considered public. @@ -961,14 +969,6 @@ class ExcelWriter(object): >>> with ExcelWriter('path_to_file.xlsx', mode='a') as writer: ... df.to_excel(writer, sheet_name='Sheet3') - - Attributes - ---------- - None - - Methods - ------- - None """ # Defining an ExcelWriter implementation (see abstract methods for more...) diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 4fdcb978b4695..e83220a476f9b 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -78,6 +78,10 @@ class Styler(object): template : Jinja2 Template loader : Jinja2 Loader + See Also + -------- + pandas.DataFrame.style + Notes ----- Most styling will be done by passing style functions into @@ -106,10 +110,6 @@ class Styler(object): * Blank cells include ``blank`` * Data cells include ``data`` - - See Also - -------- - pandas.DataFrame.style """ loader = PackageLoader("pandas", "io/formats/templates") env = Environment( @@ -906,17 +906,17 @@ def background_gradient(self, cmap='PuBu', low=0, high=0, axis=0, ------- self : Styler + Raises + ------ + ValueError + If ``text_color_threshold`` is not a value from 0 to 1. + Notes ----- Set ``text_color_threshold`` or tune ``low`` and ``high`` to keep the text legible by not using the entire range of the color map. The range of the data is extended by ``low * (x.max() - x.min())`` and ``high * (x.max() - x.min())`` before normalizing. - - Raises - ------ - ValueError - If ``text_color_threshold`` is not a value from 0 to 1. """ subset = _maybe_numeric_slice(self.data, subset) subset = _non_reducing_slice(subset) diff --git a/pandas/io/html.py b/pandas/io/html.py index c967bdd29df1f..74934740a6957 100644 --- a/pandas/io/html.py +++ b/pandas/io/html.py @@ -1041,6 +1041,10 @@ def read_html(io, match='.+', flavor=None, header=None, index_col=None, ------- dfs : list of DataFrames + See Also + -------- + pandas.read_csv + Notes ----- Before using this function you should read the :ref:`gotchas about the @@ -1072,10 +1076,6 @@ def read_html(io, match='.+', flavor=None, header=None, index_col=None, -------- See the :ref:`read_html documentation in the IO section of the docs ` for some examples of reading in HTML tables. - - See Also - -------- - pandas.read_csv """ _importers() diff --git a/pandas/io/json/json.py b/pandas/io/json/json.py index 21c8064ebcac5..4bbccc8339d7c 100644 --- a/pandas/io/json/json.py +++ b/pandas/io/json/json.py @@ -344,6 +344,10 @@ def read_json(path_or_buf=None, orient=None, typ='frame', dtype=True, ------- result : Series or DataFrame, depending on the value of `typ`. + See Also + -------- + DataFrame.to_json + Notes ----- Specific to ``orient='table'``, if a :class:`DataFrame` with a literal @@ -355,10 +359,6 @@ def read_json(path_or_buf=None, orient=None, typ='frame', dtype=True, limitation is encountered with a :class:`MultiIndex` and any names beginning with ``'level_'``. - See Also - -------- - DataFrame.to_json - Examples -------- diff --git a/pandas/io/json/table_schema.py b/pandas/io/json/table_schema.py index 2c2ecf75bbe7b..2bd93b19d4225 100644 --- a/pandas/io/json/table_schema.py +++ b/pandas/io/json/table_schema.py @@ -201,6 +201,16 @@ def build_table_schema(data, index=True, primary_key=None, version=True): ------- schema : dict + Notes + ----- + See `_as_json_table_type` for conversion types. + Timedeltas as converted to ISO8601 duration format with + 9 decimal places after the seconds field for nanosecond precision. + + Categoricals are converted to the `any` dtype, and use the `enum` field + constraint to list the allowed values. The `ordered` attribute is included + in an `ordered` field. + Examples -------- >>> df = pd.DataFrame( @@ -215,16 +225,6 @@ def build_table_schema(data, index=True, primary_key=None, version=True): {'name': 'C', 'type': 'datetime'}], 'pandas_version': '0.20.0', 'primaryKey': ['idx']} - - Notes - ----- - See `_as_json_table_type` for conversion types. - Timedeltas as converted to ISO8601 duration format with - 9 decimal places after the seconds field for nanosecond precision. - - Categoricals are converted to the `any` dtype, and use the `enum` field - constraint to list the allowed values. The `ordered` attribute is included - in an `ordered` field. """ if index is True: data = set_default_names(data) diff --git a/pandas/io/sql.py b/pandas/io/sql.py index e65e3dff1936a..e54d29148c6d0 100644 --- a/pandas/io/sql.py +++ b/pandas/io/sql.py @@ -218,14 +218,14 @@ def read_sql_table(table_name, con, schema=None, index_col=None, ------- DataFrame - Notes - ----- - Any datetime values with time zone information will be converted to UTC. - See Also -------- read_sql_query : Read SQL query into a DataFrame. read_sql + + Notes + ----- + Any datetime values with time zone information will be converted to UTC. """ con = _engine_builder(con) @@ -296,15 +296,15 @@ def read_sql_query(sql, con, index_col=None, coerce_float=True, params=None, ------- DataFrame - Notes - ----- - Any datetime values with time zone information parsed via the `parse_dates` - parameter will be converted to UTC. - See Also -------- read_sql_table : Read SQL database table into a DataFrame. read_sql + + Notes + ----- + Any datetime values with time zone information parsed via the `parse_dates` + parameter will be converted to UTC. """ pandas_sql = pandasSQL_builder(con) return pandas_sql.read_query(