From 679192369f0ac0b43d00e6fdc382b49680990402 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Fri, 25 Jan 2019 19:41:47 -0600 Subject: [PATCH 01/27] DOC/CLN: Fix errors in Series docstrings --- pandas/core/series.py | 48 +++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 0c8e697c572e8..e8b3ec213d2b3 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -513,6 +513,10 @@ def ravel(self, order='C'): """ Return the flattened underlying data as an ndarray. + Returns + ------- + arr : numpy.ndarray or ndarray-like + See Also -------- numpy.ndarray.ravel @@ -1394,29 +1398,30 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None, header=True, Parameters ---------- buf : StringIO-like, optional - buffer to write to - na_rep : string, optional - string representation of NAN to use, default 'NaN' + Buffer to write to. + na_rep : str, optional + String representation of NaN to use, default 'NaN'. float_format : one-parameter function, optional - formatter function to apply to columns' elements if they are floats - default None - header : boolean, default True - Add the Series header (index name) + Formatter function to apply to columns' elements if they are floats, + default None. + header : bool, default True + Add the Series header (index name). index : bool, optional - Add index (row) labels, default True - length : boolean, default False - Add the Series length - dtype : boolean, default False - Add the Series dtype - name : boolean, default False - Add the Series name if not None + Add index (row) labels, default True. + length : bool, default False + Add the Series length. + dtype : bool, default False + Add the Series dtype. + name : bool, default False + Add the Series name if not None. max_rows : int, optional Maximum number of rows to show before truncating. If None, show all. Returns ------- - formatted : string (if not buffer passed) + formatted : str or None + String representation of Series if buf=None, otherwise None. """ formatter = fmt.SeriesFormatter(self, name=name, length=length, @@ -1488,7 +1493,7 @@ def to_dict(self, into=dict): OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)]) >>> dd = defaultdict(list) >>> s.to_dict(dd) - defaultdict(, {0: 1, 1: 2, 2: 3, 3: 4}) + defaultdict(, {0: 1, 1: 2, 2: 3, 3: 4}) """ # GH16122 into_c = com.standardize_mapping(into) @@ -1507,6 +1512,7 @@ def to_frame(self, name=None): Returns ------- data_frame : DataFrame + DataFrame representation of Series. """ if name is None: df = self._constructor_expanddim(self) @@ -1564,11 +1570,12 @@ def count(self, level=None): ---------- level : int or level name, default None If the axis is a MultiIndex (hierarchical), count along a - particular level, collapsing into a smaller Series + particular level, collapsing into a smaller Series. Returns ------- nobs : int or Series (if level specified) + Number of non-null values in the Series. """ if level is None: return notna(com.values_from_object(self)).sum() @@ -1597,7 +1604,7 @@ def mode(self, dropna=True): Parameters ---------- - dropna : boolean, default True + dropna : bool, default True Don't consider counts of NaN/NaT. .. versionadded:: 0.24.0 @@ -1605,6 +1612,7 @@ def mode(self, dropna=True): Returns ------- modes : Series (sorted) + Mode of the Series. """ # TODO: Add option for bins like value_counts() return algorithms.mode(self, dropna=dropna) @@ -1823,7 +1831,7 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): Parameters ---------- - skipna : boolean, default True + skipna : bool, default True Exclude NA/null values. If the entire Series is NA, the result will be NA. axis : int, default 0 @@ -1860,7 +1868,7 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): Examples -------- >>> s = pd.Series(data=[1, None, 4, 1], - ... index=['A' ,'B' ,'C' ,'D']) + ... index=['A', 'B', 'C', 'D']) >>> s A 1.0 B NaN From da2cbff22e901383ba4f9ec9ea9d7b5d0b6f1c24 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 09:16:20 -0600 Subject: [PATCH 02/27] Make more docstring fixes --- pandas/core/series.py | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index e8b3ec213d2b3..6ebf886e8da56 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -4109,8 +4109,8 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None, Parameters ---------- - path : string file path or file handle / StringIO - sep : string, default ',' + path : str, file path, or file handle / StringIO + sep : str, default ',' Field delimiter parse_dates : boolean, default True Parse dates. Different default from read_table @@ -4119,9 +4119,9 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None, index_col : int or sequence, default 0 Column to use for index. If a sequence is given, a MultiIndex is used. Different default from read_table - encoding : string, optional - a string representing the encoding to use if the contents are - non-ascii, for python versions prior to 3 + encoding : str, optional + A string representing the encoding to use if the contents are + non-ascii, for python versions prior to 3. infer_datetime_format : boolean, default False If True and `parse_dates` is True for a column, try to infer the datetime format based on the first datetime string. If the format @@ -4334,11 +4334,13 @@ def to_timestamp(self, freq=None, how='start', copy=True): Parameters ---------- - freq : string, default frequency of PeriodIndex - Desired frequency + freq : str, default frequency of PeriodIndex + Desired frequency. how : {'s', 'e', 'start', 'end'} Convention for converting period to timestamp; start of period - vs. end + vs. end. + copy : bool, default True + Whether or not to return a copy. Returns ------- @@ -4359,7 +4361,8 @@ def to_period(self, freq=None, copy=True): Parameters ---------- - freq : string, default + freq : str, default None + Frequency associated with the PeriodIndex. Returns ------- From c6ccf3a6fe066236fbec7d9c805e707663e992d8 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 09:20:03 -0600 Subject: [PATCH 03/27] Fix PEP8 --- pandas/core/series.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 6ebf886e8da56..b319530f3e91d 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1402,8 +1402,8 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None, header=True, na_rep : str, optional String representation of NaN to use, default 'NaN'. float_format : one-parameter function, optional - Formatter function to apply to columns' elements if they are floats, - default None. + Formatter function to apply to columns' elements if they are + floats, default None. header : bool, default True Add the Series header (index name). index : bool, optional From e2ce6019e903ed7f63b37bef25f75e8dc7576a23 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 18:37:34 -0600 Subject: [PATCH 04/27] Update Series docstrings --- pandas/core/series.py | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index b319530f3e91d..0b04076389ea1 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -515,7 +515,8 @@ def ravel(self, order='C'): Returns ------- - arr : numpy.ndarray or ndarray-like + numpy.ndarray or ndarray-like + Flattened data of the Series. See Also -------- @@ -1420,7 +1421,7 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None, header=True, Returns ------- - formatted : str or None + str or None String representation of Series if buf=None, otherwise None. """ @@ -1481,7 +1482,8 @@ def to_dict(self, into=dict): Returns ------- - value_dict : collections.Mapping + collections.Mapping + Key-value representation of Series. Examples -------- @@ -1511,7 +1513,7 @@ def to_frame(self, name=None): Returns ------- - data_frame : DataFrame + DataFrame DataFrame representation of Series. """ if name is None: @@ -1574,7 +1576,7 @@ def count(self, level=None): Returns ------- - nobs : int or Series (if level specified) + int or Series (if level specified) Number of non-null values in the Series. """ if level is None: @@ -1611,8 +1613,8 @@ def mode(self, dropna=True): Returns ------- - modes : Series (sorted) - Mode of the Series. + Series (sorted) + Modes of the Series. """ # TODO: Add option for bins like value_counts() return algorithms.mode(self, dropna=dropna) @@ -4366,7 +4368,8 @@ def to_period(self, freq=None, copy=True): Returns ------- - ts : Series with PeriodIndex + Series + Series with index converted to PeriodIndex. """ new_values = self._values if copy: From 5716d8c793e986afda8b0a1debf0f60fbb05c191 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 19:52:12 -0600 Subject: [PATCH 05/27] Edit some returns sections --- pandas/core/series.py | 48 +++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 0b04076389ea1..c7041cf46e438 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -444,7 +444,7 @@ def values(self): Returns ------- - arr : numpy.ndarray or ndarray-like + numpy.ndarray or ndarray-like See Also -------- @@ -835,7 +835,7 @@ def _ixs(self, i, axis=0): Returns ------- - value : scalar (int) or Series (slice, sequence) + scalar (int) or Series (slice, sequence) """ try: @@ -1125,7 +1125,7 @@ def repeat(self, repeats, axis=None): Returns ------- - repeated_series : Series + Series Newly created Series with repeated elements. See Also @@ -1178,7 +1178,7 @@ def get_value(self, label, takeable=False): Returns ------- - value : scalar value + scalar value """ warnings.warn("get_value is deprecated and will be removed " "in a future release. Please use " @@ -1212,7 +1212,7 @@ def set_value(self, label, value, takeable=False): Returns ------- - series : Series + Series If label is contained, will be reference to calling Series, otherwise a new object """ @@ -1534,7 +1534,7 @@ def to_sparse(self, kind='block', fill_value=None): Returns ------- - sp : SparseSeries + SparseSeries """ # TODO: deprecate from pandas.core.sparse.series import SparseSeries @@ -1692,7 +1692,7 @@ def drop_duplicates(self, keep='first', inplace=False): Returns ------- - deduplicated : Series + Series See Also -------- @@ -1769,7 +1769,7 @@ def duplicated(self, keep='first'): Returns ------- - pandas.core.series.Series + Series See Also -------- @@ -1998,7 +1998,7 @@ def round(self, decimals=0, *args, **kwargs): Returns ------- - Series object + Series See Also -------- @@ -2034,7 +2034,7 @@ def quantile(self, q=0.5, interpolation='linear'): Returns ------- - quantile : float or Series + float or Series if ``q`` is an array, a Series will be returned where the index is ``q`` and the values are the quantiles. @@ -2095,7 +2095,7 @@ def corr(self, other, method='pearson', min_periods=None): Returns ------- - correlation : float + float Examples -------- @@ -2130,7 +2130,7 @@ def cov(self, other, min_periods=None): Returns ------- - covariance : float + float Normalized by N-1 (unbiased estimator). """ @@ -2155,7 +2155,7 @@ def diff(self, periods=1): Returns ------- - diffed : Series + Series See Also -------- @@ -2368,7 +2368,7 @@ def append(self, to_append, ignore_index=False, verify_integrity=False): Returns ------- - appended : Series + Series See Also -------- @@ -2449,7 +2449,7 @@ def _binop(self, other, func, level=None, fill_value=None): Returns ------- - combined : Series + Series """ if not isinstance(other, Series): raise AssertionError('Other operand must be Series') @@ -2872,7 +2872,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- - pandas.Series + Series The original Series sorted by the labels See Also @@ -3012,7 +3012,7 @@ def argsort(self, axis=0, kind='quicksort', order=None): Returns ------- - argsorted : Series, with -1 indicated where nan values are present + Series, with -1 indicated where nan values are present See Also -------- @@ -3235,7 +3235,7 @@ def swaplevel(self, i=-2, j=-1, copy=True): Returns ------- - swapped : Series + Series .. versionchanged:: 0.18.1 @@ -3284,7 +3284,7 @@ def unstack(self, level=-1, fill_value=None): Returns ------- - unstacked : DataFrame + DataFrame Examples -------- @@ -3699,7 +3699,7 @@ def rename(self, index=None, **kwargs): Returns ------- - renamed : Series (new object) + Series (new object) See Also -------- @@ -3772,7 +3772,7 @@ def drop(self, labels=None, axis=0, index=None, columns=None, Returns ------- - dropped : pandas.Series + Series Raises ------ @@ -3970,7 +3970,7 @@ def isin(self, values): Returns ------- - isin : Series (bool dtype) + Series (bool dtype) Raises ------ @@ -4131,7 +4131,7 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None, Returns ------- - y : Series + Series See Also -------- @@ -4346,7 +4346,7 @@ def to_timestamp(self, freq=None, how='start', copy=True): Returns ------- - ts : Series with DatetimeIndex + Series with DatetimeIndex """ new_values = self._values if copy: From 3bd2a45819988a758d4e99d208e320bd4e63a78a Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 20:15:30 -0600 Subject: [PATCH 06/27] Update series.py --- pandas/core/series.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index c7041cf46e438..a32b68c07ce9a 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -129,7 +129,7 @@ class Series(base.IndexOpsMixin, generic.NDFrame): sequence are used, the index will override the keys found in the dict. dtype : str, numpy.dtype, or ExtensionDtype, optional - dtype for the output Series. If not specified, this will be + Data type for the output Series. If not specified, this will be inferred from `data`. See the :ref:`user guide ` for more usages. copy : bool, default False @@ -3970,7 +3970,8 @@ def isin(self, values): Returns ------- - Series (bool dtype) + Series + Series of booleans indicating if each element is in values. Raises ------ @@ -4029,7 +4030,8 @@ def between(self, left, right, inclusive=True): Returns ------- Series - Each element will be a boolean. + Series representing whether each element is between left and + right (inclusive). See Also -------- @@ -4332,7 +4334,7 @@ def valid(self, inplace=False, **kwargs): def to_timestamp(self, freq=None, how='start', copy=True): """ - Cast to datetimeindex of timestamps, at *beginning* of period. + Cast to DatetimeIndex of Timestamps, at *beginning* of period. Parameters ---------- From 2fba35b3b2e7e58b992c9c4afa39673b3f8bbafb Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 26 Jan 2019 20:19:29 -0600 Subject: [PATCH 07/27] Tweak mode docstring --- pandas/core/series.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index a32b68c07ce9a..1180ed1599113 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1613,8 +1613,8 @@ def mode(self, dropna=True): Returns ------- - Series (sorted) - Modes of the Series. + Series + Modes of the Series in sorted order. """ # TODO: Add option for bins like value_counts() return algorithms.mode(self, dropna=dropna) From b1dfb6420c471425c705949839c2fb2adc08cf6a Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 08:41:33 -0600 Subject: [PATCH 08/27] Update docs --- pandas/core/series.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 1180ed1599113..b7d4a022b9ab2 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1422,7 +1422,7 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None, header=True, Returns ------- str or None - String representation of Series if buf=None, otherwise None. + String representation of Series if ``buf=None``, otherwise None. """ formatter = fmt.SeriesFormatter(self, name=name, length=length, @@ -3012,7 +3012,9 @@ def argsort(self, axis=0, kind='quicksort', order=None): Returns ------- - Series, with -1 indicated where nan values are present + Series + Positions of values within the sort order with -1 indicating + nan values. See Also -------- From 120f5d9e9ef7c09459c5b6476c468523ccc4e31d Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:03:04 -0600 Subject: [PATCH 09/27] Add to to_sparse docstring --- pandas/core/series.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index b7d4a022b9ab2..3d1497bee4dcd 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1529,12 +1529,14 @@ def to_sparse(self, kind='block', fill_value=None): Parameters ---------- - kind : {'block', 'integer'} + kind : {'block', 'integer'}, default 'block' fill_value : float, defaults to NaN (missing) + Value to use for filling NaN values. Returns ------- SparseSeries + Sparse representation of the Series. """ # TODO: deprecate from pandas.core.sparse.series import SparseSeries From 44dbfbb82def0cab5847b588fb3b29699ccbc213 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:05:19 -0600 Subject: [PATCH 10/27] Fix drop_duplicates doc --- pandas/core/series.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 3d1497bee4dcd..5e380225d5b1e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1689,12 +1689,13 @@ def drop_duplicates(self, keep='first', inplace=False): - 'first' : Drop duplicates except for the first occurrence. - 'last' : Drop duplicates except for the last occurrence. - ``False`` : Drop all duplicates. - inplace : boolean, default ``False`` + inplace : bool, default ``False`` If ``True``, performs operation inplace and returns None. Returns ------- Series + Series with duplicates dropped. See Also -------- From 0c31b4b207c6015e26e3bb9975c5ba26aa449434 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:09:21 -0600 Subject: [PATCH 11/27] Add duplicated return description --- pandas/core/series.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 5e380225d5b1e..ac7abb19548fa 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1773,6 +1773,8 @@ def duplicated(self, keep='first'): Returns ------- Series + Series indicating whether each value has occurred in the + preceding values. See Also -------- From 411dcce9bb82fc795c356f0ad80174bf461c48e8 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:13:45 -0600 Subject: [PATCH 12/27] Fix idxmin and idxmax --- pandas/core/series.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index ac7abb19548fa..081df69d927b4 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1850,7 +1850,8 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): Returns ------- - idxmin : Index of minimum of values. + Index + Label of the minimum value. Raises ------ @@ -1907,7 +1908,7 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Parameters ---------- - skipna : boolean, default True + skipna : bool, default True Exclude NA/null values. If the entire Series is NA, the result will be NA. axis : int, default 0 @@ -1919,7 +1920,8 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Returns ------- - idxmax : Index of maximum of values. + Index + Label of the maximum value. Raises ------ From 8690c74c305260c555f7dd6dc2a64e20b72246c8 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:16:41 -0600 Subject: [PATCH 13/27] Fix round --- pandas/core/series.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 081df69d927b4..54e58475926f0 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2006,11 +2006,12 @@ def round(self, decimals=0, *args, **kwargs): Returns ------- Series + Rounded values of the Series. See Also -------- - numpy.around - DataFrame.round + numpy.around : Round values of an np.array. + DataFrame.round : Round values of a DataFrame. """ nv.validate_round(args, kwargs) result = com.values_from_object(self).round(decimals) From 18af89f7b6078c7f732a2dc7af4bc20f4f86295a Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:20:14 -0600 Subject: [PATCH 14/27] Add diff return description --- pandas/core/series.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 54e58475926f0..2cba0d347df59 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2164,6 +2164,7 @@ def diff(self, periods=1): Returns ------- Series + First differences of the Series. See Also -------- From a7752124021c8d1e89968a90fcc0d7cf51872099 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 09:32:45 -0600 Subject: [PATCH 15/27] Fix docs --- pandas/core/series.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 2cba0d347df59..cc7011a5c784e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2882,7 +2882,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, Returns ------- Series - The original Series sorted by the labels + The original Series sorted by the labels. See Also -------- @@ -4126,18 +4126,18 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None, ---------- path : str, file path, or file handle / StringIO sep : str, default ',' - Field delimiter - parse_dates : boolean, default True - Parse dates. Different default from read_table + Field delimiter. + parse_dates : bool, default True + Parse dates. Different default from read_table. header : int, default None - Row to use as header (skip prior rows) + Row to use as header (skip prior rows). index_col : int or sequence, default 0 Column to use for index. If a sequence is given, a MultiIndex - is used. Different default from read_table + is used. Different default from read_table. encoding : str, optional A string representing the encoding to use if the contents are non-ascii, for python versions prior to 3. - infer_datetime_format : boolean, default False + infer_datetime_format : bool, default False If True and `parse_dates` is True for a column, try to infer the datetime format based on the first datetime string. If the format can be inferred, there often will be a large parsing speed-up. From eb7543a348d9df30562255dce3649f097ab06a3e Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 12:33:52 -0600 Subject: [PATCH 16/27] Make some more fixes --- pandas/core/series.py | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index cc7011a5c784e..982b2e2761735 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2026,7 +2026,7 @@ def quantile(self, q=0.5, interpolation='linear'): Parameters ---------- q : float or array-like, default 0.5 (50% quantile) - 0 <= q <= 1, the quantile(s) to compute + 0 <= q <= 1, the quantile(s) to compute. interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} .. versionadded:: 0.18.0 @@ -2043,8 +2043,9 @@ def quantile(self, q=0.5, interpolation='linear'): Returns ------- float or Series - if ``q`` is an array, a Series will be returned where the - index is ``q`` and the values are the quantiles. + If ``q`` is an array, a Series will be returned where the + index is ``q`` and the values are the quantiles, otherwise + a float will be returned. See Also -------- @@ -2134,13 +2135,13 @@ def cov(self, other, min_periods=None): ---------- other : Series min_periods : int, optional - Minimum number of observations needed to have a valid result + Minimum number of observations needed to have a valid result. Returns ------- float - - Normalized by N-1 (unbiased estimator). + Covariance between Series and other normalized by N-1 + (unbiased estimator). """ this, other = self.align(other, join='inner', copy=False) if len(this) == 0: @@ -2367,17 +2368,18 @@ def append(self, to_append, ignore_index=False, verify_integrity=False): Parameters ---------- to_append : Series or list/tuple of Series - ignore_index : boolean, default False + ignore_index : bool, default False If True, do not use the index labels. .. versionadded:: 0.19.0 - verify_integrity : boolean, default False - If True, raise Exception on creating index with duplicates + verify_integrity : bool, default False + If True, raise Exception on creating index with duplicates. Returns ------- Series + Concatenated Series. See Also -------- @@ -2395,7 +2397,7 @@ def append(self, to_append, ignore_index=False, verify_integrity=False): -------- >>> s1 = pd.Series([1, 2, 3]) >>> s2 = pd.Series([4, 5, 6]) - >>> s3 = pd.Series([4, 5, 6], index=[3,4,5]) + >>> s3 = pd.Series([4, 5, 6], index=[3, 4, 5]) >>> s1.append(s2) 0 1 1 2 @@ -3241,12 +3243,13 @@ def swaplevel(self, i=-2, j=-1, copy=True): Parameters ---------- - i, j : int, string (can be mixed) + i, j : int, str (can be mixed) Level of index to be swapped. Can pass level name as string. Returns ------- Series + Series with levels swapped in MultiIndex. .. versionchanged:: 0.18.1 @@ -3286,8 +3289,8 @@ def unstack(self, level=-1, fill_value=None): Parameters ---------- - level : int, string, or list of these, default last level - Level(s) to unstack, can pass level name + level : int, str, or list of these, default last level + Level(s) to unstack, can pass level name. fill_value : replace NaN with this value if the unstack produces missing values @@ -3296,6 +3299,7 @@ def unstack(self, level=-1, fill_value=None): Returns ------- DataFrame + Unstacked Series. Examples -------- @@ -3799,7 +3803,7 @@ def drop(self, labels=None, axis=0, index=None, columns=None, Examples -------- - >>> s = pd.Series(data=np.arange(3), index=['A','B','C']) + >>> s = pd.Series(data=np.arange(3), index=['A', 'B', 'C']) >>> s A 0 B 1 @@ -3808,7 +3812,7 @@ def drop(self, labels=None, axis=0, index=None, columns=None, Drop labels B en C - >>> s.drop(labels=['B','C']) + >>> s.drop(labels=['B', 'C']) A 0 dtype: int64 From f29365ed37dbbc8d53f79557acd225a7212c3b75 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Thu, 31 Jan 2019 19:01:46 -0600 Subject: [PATCH 17/27] Remove unnecessary comment --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 080ff09867d11..f96ea03499946 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3714,7 +3714,7 @@ def rename(self, index=None, **kwargs): Returns ------- - Series (new object) + Series See Also -------- From e496f9202ed5bd5846efbb92af3c660aceae3079 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 2 Feb 2019 15:56:26 -0600 Subject: [PATCH 18/27] Fix PEP8 --- pandas/core/series.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index f96ea03499946..7f6b431385de8 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3304,7 +3304,8 @@ def unstack(self, level=-1, fill_value=None): Examples -------- >>> s = pd.Series([1, 2, 3, 4], - ... index=pd.MultiIndex.from_product([['one', 'two'], ['a', 'b']])) + ... index=pd.MultiIndex.from_product([['one', 'two'], + ... ['a', 'b']])) >>> s one a 1 b 2 From bc77485c4faf7364198a896bb74ce75e9ff80495 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 2 Feb 2019 15:59:10 -0600 Subject: [PATCH 19/27] Fix PEP8 in corr example --- pandas/core/series.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 7f6b431385de8..4901e264a3e8e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2105,11 +2105,12 @@ def corr(self, other, method='pearson', min_periods=None): Returns ------- float + Correlation with other. Examples - -------- - >>> histogram_intersection = lambda a, b: np.minimum(a, b - ... ).sum().round(decimals=1) + >>> def histogram_intersection(a, b): + ... v = np.minimum(a, b).sum().round(decimals=1) + ... return v >>> s1 = pd.Series([.2, .0, .6, .2]) >>> s2 = pd.Series([.3, .6, .0, .1]) >>> s1.corr(s2, method=histogram_intersection) From 50cd6d436478c60ed671258cec1379e432c1892f Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sat, 2 Feb 2019 16:05:58 -0600 Subject: [PATCH 20/27] Add some descriptions --- pandas/core/series.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 4901e264a3e8e..041295f664b51 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2091,6 +2091,7 @@ def corr(self, other, method='pearson', min_periods=None): Parameters ---------- other : Series + Series with which to compute the correlation. method : {'pearson', 'kendall', 'spearman'} or callable * pearson : standard correlation coefficient * kendall : Kendall Tau correlation coefficient @@ -2135,6 +2136,7 @@ def cov(self, other, min_periods=None): Parameters ---------- other : Series + Series with which to compute the covariance. min_periods : int, optional Minimum number of observations needed to have a valid result. @@ -2300,7 +2302,7 @@ def dot(self, other): 8 >>> s @ other 8 - >>> df = pd.DataFrame([[0 ,1], [-2, 3], [4, -5], [6, 7]]) + >>> df = pd.DataFrame([[0, 1], [-2, 3], [4, -5], [6, 7]]) >>> s.dot(df) 0 24 1 14 @@ -2369,6 +2371,7 @@ def append(self, to_append, ignore_index=False, verify_integrity=False): Parameters ---------- to_append : Series or list/tuple of Series + Series to append with self. ignore_index : bool, default False If True, do not use the index labels. From a52afd90b5a170697cb8342d2c2e4de933547147 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sun, 3 Feb 2019 09:38:18 -0600 Subject: [PATCH 21/27] Document copy in to_period --- pandas/core/series.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 041295f664b51..906cf88f2aa6d 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -4387,6 +4387,8 @@ def to_period(self, freq=None, copy=True): ---------- freq : str, default None Frequency associated with the PeriodIndex. + copy : bool, default True + Whether or not to return a copy. Returns ------- From ee25c1e1c895bd5ddfed79ac5bfa6e94452af5bc Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Sun, 3 Feb 2019 10:06:45 -0600 Subject: [PATCH 22/27] Fix more stuff --- pandas/core/series.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 906cf88f2aa6d..7a991cd2a99e9 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3295,8 +3295,8 @@ def unstack(self, level=-1, fill_value=None): ---------- level : int, str, or list of these, default last level Level(s) to unstack, can pass level name. - fill_value : replace NaN with this value if the unstack produces - missing values + fill_value : scalar value, default None + Value to use when replacing NaN values. .. versionadded:: 0.18.0 @@ -3709,7 +3709,7 @@ def rename(self, index=None, **kwargs): Scalar or hashable sequence-like will alter the ``Series.name`` attribute. copy : bool, default True - Also copy underlying data + Whether to copy underlying data. inplace : bool, default False Whether to return a new Series. If True then value of copy is ignored. @@ -3720,10 +3720,11 @@ def rename(self, index=None, **kwargs): Returns ------- Series + Series with index labels or name altered. See Also -------- - Series.rename_axis + Series.rename_axis : Set the name of the axis. Examples -------- @@ -3733,7 +3734,7 @@ def rename(self, index=None, **kwargs): 1 2 2 3 dtype: int64 - >>> s.rename("my_name") # scalar, changes Series.name + >>> s.rename("my_name") # scalar, changes Series.name 0 1 1 2 2 3 @@ -3793,6 +3794,7 @@ def drop(self, labels=None, axis=0, index=None, columns=None, Returns ------- Series + Series with specified index labels removed. Raises ------ From bd622ed3c808753ec2abb6961d2fea0b59c90ce4 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Mon, 4 Feb 2019 20:09:26 -0600 Subject: [PATCH 23/27] Add round example --- pandas/core/series.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 7a991cd2a99e9..fe790ef84546d 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2012,6 +2012,15 @@ def round(self, decimals=0, *args, **kwargs): -------- numpy.around : Round values of an np.array. DataFrame.round : Round values of a DataFrame. + + Examples + -------- + >>> s = pd.Series([0.1, 1.3, 2.7]) + >>> s.round() + 0 0.0 + 1 1.0 + 2 3.0 + dtype: float64 """ nv.validate_round(args, kwargs) result = com.values_from_object(self).round(decimals) From ac895060328478bbd2a04c96805aa0dd32574953 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Mon, 4 Feb 2019 20:12:16 -0600 Subject: [PATCH 24/27] Add two more examples --- pandas/core/series.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index fe790ef84546d..4168345a2ac29 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1515,6 +1515,16 @@ def to_frame(self, name=None): ------- DataFrame DataFrame representation of Series. + + Examples + -------- + >>> s = pd.Series(["a", "b", "c"], + ... name="vals") + >>> s.to_frame() + vals + 0 a + 1 b + 2 c """ if name is None: df = self._constructor_expanddim(self) @@ -1580,6 +1590,12 @@ def count(self, level=None): ------- int or Series (if level specified) Number of non-null values in the Series. + + Examples + -------- + >>> s = pd.Series([0.0, 1.0, np.nan]) + >>> s.count() + 2 """ if level is None: return notna(com.values_from_object(self)).sum() From 8c45dfce60b29a6d606110a96ae85aa0c28caa62 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Mon, 4 Feb 2019 21:50:17 -0600 Subject: [PATCH 25/27] Add another example --- pandas/core/series.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 4168345a2ac29..36af34ac8d6d7 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2170,6 +2170,13 @@ def cov(self, other, min_periods=None): float Covariance between Series and other normalized by N-1 (unbiased estimator). + + Examples + -------- + >>> s1 = pd.Series([0.90010907, 0.13484424, 0.62036035]) + >>> s2 = pd.Series([0.12528585, 0.26962463, 0.51111198]) + >>> s1.cov(s2) + -0.01685762652715874 """ this, other = self.align(other, join='inner', copy=False) if len(this) == 0: From 55350c05042e2dd6e2f4364087ec88351bfbe15b Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Tue, 5 Feb 2019 19:30:53 -0600 Subject: [PATCH 26/27] Add missing dashes --- pandas/core/series.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index 36af34ac8d6d7..84a8ac376c7d2 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2134,6 +2134,7 @@ def corr(self, other, method='pearson', min_periods=None): Correlation with other. Examples + -------- >>> def histogram_intersection(a, b): ... v = np.minimum(a, b).sum().round(decimals=1) ... return v From 120540448036a6eb64a80393f575bb31c38d8cc4 Mon Sep 17 00:00:00 2001 From: Daniel Saxton Date: Wed, 6 Feb 2019 19:56:20 -0600 Subject: [PATCH 27/27] Add a period --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 84a8ac376c7d2..db8a15932106a 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2126,7 +2126,7 @@ def corr(self, other, method='pearson', min_periods=None): .. versionadded:: 0.24.0 min_periods : int, optional - Minimum number of observations needed to have a valid result + Minimum number of observations needed to have a valid result. Returns -------