From 93b5e04865490988fc28f334ad35937214f8c69d Mon Sep 17 00:00:00 2001 From: fwx Date: Sun, 25 Nov 2018 02:27:58 +0530 Subject: [PATCH 01/10] Editing docstring summaries. --- pandas/core/frame.py | 6 +-- pandas/core/groupby/base.py | 8 +-- pandas/core/groupby/groupby.py | 32 ++++++------ pandas/core/indexes/base.py | 77 ++++++++++++++++------------- pandas/core/indexes/datetimelike.py | 4 +- pandas/core/indexes/multi.py | 6 +-- pandas/core/indexes/range.py | 2 +- pandas/core/panel.py | 33 +++++++------ pandas/core/resample.py | 26 +++++----- pandas/core/window.py | 35 ++++++------- pandas/io/formats/style.py | 6 ++- pandas/io/json/normalize.py | 6 +-- pandas/io/pytables.py | 4 +- 13 files changed, 128 insertions(+), 117 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 8d089ab3a1949..9683ea0e69584 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -1953,7 +1953,7 @@ def to_stata(self, fname, convert_dates=None, write_index=True, def to_feather(self, fname): """ - write out the binary feather-format for DataFrames + Write out the binary feather-format for DataFrames. .. versionadded:: 0.20.0 @@ -5839,7 +5839,7 @@ def unstack(self, level=-1, fill_value=None): return unstack(self, level, fill_value) _shared_docs['melt'] = (""" - "Unpivots" a DataFrame from wide format to long format, optionally + 'Unpivots' a DataFrame from wide format to long format, optionally leaving identifier variables set. This function is useful to massage a DataFrame into a format where one @@ -6045,7 +6045,7 @@ def _gotitem(self, ): # type: (...) -> Union[Series, DataFrame] """ - sub-classes to define + Sub-classes to define return a sliced object Parameters diff --git a/pandas/core/groupby/base.py b/pandas/core/groupby/base.py index 1bf97690a84ed..60ce08b9a6da5 100644 --- a/pandas/core/groupby/base.py +++ b/pandas/core/groupby/base.py @@ -12,11 +12,11 @@ class GroupByMixin(object): - """ provide the groupby facilities to the mixed object """ + """ Provide the groupby facilities to the mixed object. """ @staticmethod def _dispatch(name, *args, **kwargs): - """ dispatch to apply """ + """ Dispatch to apply. """ def outer(self, *args, **kwargs): def f(x): @@ -28,8 +28,8 @@ def f(x): def _gotitem(self, key, ndim, subset=None): """ - sub-classes to define - return a sliced object + Sub-classes to define + return a sliced object. Parameters ---------- diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index b68fdf853ab19..30eb6d24443c2 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -291,7 +291,7 @@ class providing the base-class of operations. class GroupByPlot(PandasObject): """ - Class implementing the .plot attribute for groupby objects + Class implementing the .plot attribute for groupby objects. """ def __init__(self, groupby): @@ -314,7 +314,7 @@ def f(self): @contextmanager def _group_selection_context(groupby): """ - set / reset the _group_selection_context + Set / reset the _group_selection_context. """ groupby._set_group_selection() yield groupby @@ -377,14 +377,14 @@ def __unicode__(self): def _assure_grouper(self): """ - we create the grouper on instantiation - sub-classes may have a different policy + We create the grouper on instantiation + sub-classes may have a different policy. """ pass @property def groups(self): - """ dict {group name -> group labels} """ + """ Dict {group name -> group labels} """ self._assure_grouper() return self.grouper.groups @@ -395,14 +395,14 @@ def ngroups(self): @property def indices(self): - """ dict {group name -> group indices} """ + """ Dict {group name -> group indices} """ self._assure_grouper() return self.grouper.indices def _get_indices(self, names): """ - safe get multiple indices, translate keys for - datelike to underlying repr + Safe get multiple indices, translate keys for + datelike to underlying repr. """ def get_converter(s): @@ -450,7 +450,7 @@ def get_converter(s): return [self.indices.get(name, []) for name in names] def _get_index(self, name): - """ safe get index, translate keys for datelike to underlying repr """ + """ Safe get index, translate keys for datelike to underlying repr .""" return self._get_indices([name])[0] @cache_readonly @@ -1127,7 +1127,7 @@ def mean(self, *args, **kwargs): @Appender(_doc_template) def median(self, **kwargs): """ - Compute median of groups, excluding missing values + Compute median of groups, excluding missing values. For multiple groupings, the result index will be a MultiIndex """ @@ -1148,9 +1148,9 @@ def f(x): @Appender(_doc_template) def std(self, ddof=1, *args, **kwargs): """ - Compute standard deviation of groups, excluding missing values + Compute standard deviation of groups, excluding missing values. - For multiple groupings, the result index will be a MultiIndex + For multiple groupings, the result index will be a MultiIndex. Parameters ---------- @@ -1166,9 +1166,9 @@ def std(self, ddof=1, *args, **kwargs): @Appender(_doc_template) def var(self, ddof=1, *args, **kwargs): """ - Compute variance of groups, excluding missing values + Compute variance of groups, excluding missing values. - For multiple groupings, the result index will be a MultiIndex + For multiple groupings, the result index will be a MultiIndex. Parameters ---------- @@ -1192,9 +1192,9 @@ def var(self, ddof=1, *args, **kwargs): @Appender(_doc_template) def sem(self, ddof=1): """ - Compute standard error of the mean of groups, excluding missing values + Compute standard error of the mean of groups, excluding missing values. - For multiple groupings, the result index will be a MultiIndex + For multiple groupings, the result index will be a MultiIndex. Parameters ---------- diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 28aefb652adb0..28934c6159c9f 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -690,17 +690,17 @@ def __array_wrap__(self, result, context=None): @cache_readonly def dtype(self): - """ return the dtype object of the underlying data """ + """ Return the dtype object of the underlying data. """ return self._data.dtype @cache_readonly def dtype_str(self): - """ return the dtype str of the underlying data """ + """ Return the dtype str of the underlying data. """ return str(self.dtype) @property def values(self): - """ return the underlying data as an ndarray """ + """ Return the underlying data as an ndarray. """ return self._data.view(np.ndarray) @property @@ -824,12 +824,12 @@ def repeat(self, repeats, *args, **kwargs): nv.validate_repeat(args, kwargs) return self._shallow_copy(self._values.repeat(repeats)) - _index_shared_docs['where'] = """ - .. versionadded:: 0.19.0 - + _index_shared_docs['where'] = """ Return an Index of same shape as self and whose corresponding entries are from self where cond is True and otherwise are from other. + + .. versionadded:: 0.19.0 Parameters ---------- @@ -862,7 +862,7 @@ def where(self, cond, other=None): def ravel(self, order='C'): """ - return an ndarray of the flattened values of the underlying data + Return an ndarray of the flattened values of the underlying data. See Also -------- @@ -1493,13 +1493,14 @@ def _mpl_repr(self): # introspection @property def is_monotonic(self): - """ alias for is_monotonic_increasing (deprecated) """ + """ Alias for is_monotonic_increasing. + .. deprecated :: """ return self.is_monotonic_increasing @property def is_monotonic_increasing(self): """ - return if the index is monotonic increasing (only equal or + Return if the index is monotonic increasing (only equal or increasing) values. Examples @@ -1516,7 +1517,7 @@ def is_monotonic_increasing(self): @property def is_monotonic_decreasing(self): """ - return if the index is monotonic decreasing (only equal or + Return if the index is monotonic decreasing (only equal or decreasing) values. Examples @@ -1532,8 +1533,8 @@ def is_monotonic_decreasing(self): @property def _is_strictly_monotonic_increasing(self): - """return if the index is strictly monotonic increasing - (only increasing) values + """Return if the index is strictly monotonic increasing + (only increasing) values. Examples -------- @@ -1548,8 +1549,8 @@ def _is_strictly_monotonic_increasing(self): @property def _is_strictly_monotonic_decreasing(self): - """return if the index is strictly monotonic decreasing - (only decreasing) values + """Return if the index is strictly monotonic decreasing + (only decreasing) values. Examples -------- @@ -1567,7 +1568,7 @@ def is_lexsorted_for_tuple(self, tup): @cache_readonly def is_unique(self): - """ return if the index has unique values """ + """ Return if the index has unique values. """ return self._engine.is_unique @property @@ -1958,11 +1959,11 @@ def _get_level_number(self, level): @cache_readonly def inferred_type(self): - """ return a string of the type inferred from the values """ + """ Return a string of the type inferred from the values, """ return lib.infer_dtype(self) def _is_memory_usage_qualified(self): - """ return a boolean if we need a qualified .info display """ + """ Return a boolean if we need a qualified .info display. """ return self.is_object() def is_type_compatible(self, kind): @@ -1980,7 +1981,7 @@ def __reduce__(self): return _new_Index, (self.__class__, d), None def __setstate__(self, state): - """Necessary for making this object picklable""" + """ Necessary for making this object picklable. """ if isinstance(state, dict): self._data = state.pop('data') @@ -2014,7 +2015,7 @@ def __nonzero__(self): __bool__ = __nonzero__ _index_shared_docs['__contains__'] = """ - return a boolean if this key is IN the index + Return a boolean if this key is IN the index. Parameters ---------- @@ -2034,7 +2035,7 @@ def __contains__(self, key): return False _index_shared_docs['contains'] = """ - return a boolean if this key is IN the index + Return a boolean if this key is IN the index. Parameters ---------- @@ -2152,7 +2153,7 @@ def _concat_same_dtype(self, to_concat, name): return _concat._concat_index_asobject(to_concat, name) _index_shared_docs['take'] = """ - return a new %(klass)s of the values selected by the indices + Return a new %(klass)s of the values selected by the indices. For internal compatibility with numpy arrays. @@ -2345,7 +2346,7 @@ def notna(self): def putmask(self, mask, value): """ - return a new Index of the values set with the mask + Return a new Index of the values set with the mask. See Also -------- @@ -2536,12 +2537,17 @@ def asof(self, label): def asof_locs(self, where, mask): """ - where : array of timestamps - mask : array of booleans where data is not NA + Parameters + ---------- + where : array + Array of timestamps. + mask : array-like + Array of booleans denoting where values in the original + data are not NA. """ locs = self.values[mask].searchsorted(where.values, side='right') - locs = np.where(locs > 0, locs - 1, 0) + result = np.arange(len(self))[mask].take(locs) first = mask.argmax() @@ -3501,8 +3507,9 @@ def get_indexer_non_unique(self, target): def get_indexer_for(self, target, **kwargs): """ - guaranteed return of an indexer even when non-unique - This dispatches to get_indexer or get_indexer_nonunique as appropriate + Guaranteed return of an indexer even when non-unique. + This dispatches to get_indexer or get_indexer_nonunique + as appropriate. """ if self.is_unique: return self.get_indexer(target, **kwargs) @@ -3817,11 +3824,11 @@ def _reindex_non_unique(self, target): new_index = self._shallow_copy_with_infer(new_labels, freq=None) return new_index, indexer, new_indexer - _index_shared_docs['join'] = """ - *this is an internal non-public method* - + _index_shared_docs['join'] = """ Compute join_index and indexers to conform data structures to the new index. + + *This is an internal non-public method* Parameters ---------- @@ -4281,9 +4288,9 @@ def _maybe_cast_indexer(self, key): def _validate_indexer(self, form, key, kind): """ - if we are positional indexer + If we are positional indexer validate that we have appropriate typed bounds - must be an integer + must be an integer. """ assert kind in ['ix', 'loc', 'getitem', 'iloc'] @@ -4493,7 +4500,7 @@ def slice_locs(self, start=None, end=None, step=None, kind=None): def delete(self, loc): """ - Make new Index with passed location(-s) deleted + Make new Index with passed location(-s) deleted. Returns ------- @@ -4504,7 +4511,7 @@ def delete(self, loc): def insert(self, loc, item): """ Make new Index inserting new item at location. Follows - Python list.append semantics for negative values + Python list.append semantics for negative values. Parameters ---------- @@ -4522,7 +4529,7 @@ def insert(self, loc, item): def drop(self, labels, errors='raise'): """ - Make new Index with passed list of labels deleted + Make new Index with passed list of labels deleted. Parameters ---------- diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 1179f6f39d06c..cb09998331832 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -34,7 +34,7 @@ class DatelikeOps(object): - """ common ops for DatetimeIndex/PeriodIndex, but not TimedeltaIndex """ + """ Common ops for DatetimeIndex/PeriodIndex, but not TimedeltaIndex. """ def strftime(self, date_format): return Index(self.format(date_format=date_format), @@ -76,7 +76,7 @@ def strftime(self, date_format): class TimelikeOps(object): - """ common ops for TimedeltaIndex/DatetimeIndex, but not PeriodIndex """ + """ Common ops for TimedeltaIndex/DatetimeIndex, but not PeriodIndex. """ _round_doc = ( """ diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index f9483b48b5261..ea6dfa6a3a6af 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -121,7 +121,7 @@ def _codes_to_ints(self, codes): class MultiIndex(Index): """ - A multi-level, or hierarchical, index object for pandas objects + A multi-level, or hierarchical, index object for pandas objects. Parameters ---------- @@ -1195,14 +1195,14 @@ def to_frame(self, index=True, name=None): def to_hierarchical(self, n_repeat, n_shuffle=1): """ - .. deprecated:: 0.24.0 - Return a MultiIndex reshaped to conform to the shapes given by n_repeat and n_shuffle. Useful to replicate and rearrange a MultiIndex for combination with another Index with n_repeat items. + .. deprecated:: 0.24.0 + Parameters ---------- n_repeat : int diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 0d4e7aaebeca5..d6286244fcb7e 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -122,7 +122,7 @@ def ensure_int(value, field): @classmethod def from_range(cls, data, name=None, dtype=None, **kwargs): - """ create RangeIndex from a range (py3), or xrange (py2) object """ + """ Create RangeIndex from a range (py3), or xrange (py2) object. """ if not isinstance(data, range): raise TypeError( '{0}(...) must be called with object coercible to a ' diff --git a/pandas/core/panel.py b/pandas/core/panel.py index 90016f599addc..cd3cb192e4588 100644 --- a/pandas/core/panel.py +++ b/pandas/core/panel.py @@ -157,7 +157,7 @@ def __init__(self, data=None, items=None, major_axis=None, minor_axis=None, def _init_data(self, data, copy, dtype, **kwargs): """ Generate ND initialization; axes are passed - as required objects to __init__ + as required objects to __init__. """ if data is None: data = {} @@ -242,7 +242,7 @@ def _init_arrays(self, arrays, arr_names, axes): @classmethod def from_dict(cls, data, intersect=False, orient='items', dtype=None): """ - Construct Panel from dict of DataFrame objects + Construct Panel from dict of DataFrame objects. Parameters ---------- @@ -348,7 +348,7 @@ def _compare_constructor(self, other, func): def __unicode__(self): """ - Return a string representation for a particular Panel + Return a string representation for a particular Panel. Invoked by unicode(df) in py2 only. Yields a Unicode String in both py2/py3. @@ -377,7 +377,7 @@ def _get_plane_axes_index(self, axis): """ Get my plane axes indexes: these are already (as compared with higher level planes), - as we are returning a DataFrame axes indexes + as we are returning a DataFrame axes indexes. """ axis_name = self._get_axis_name(axis) @@ -397,7 +397,7 @@ def _get_plane_axes(self, axis): """ Get my plane axes indexes: these are already (as compared with higher level planes), - as we are returning a DataFrame axes + as we are returning a DataFrame axes. """ return [self._get_axis(axi) for axi in self._get_plane_axes_index(axis)] @@ -473,7 +473,8 @@ def as_matrix(self): # Getting and setting elements def get_value(self, *args, **kwargs): - """Quickly retrieve single value at (item, major, minor) location + """ + Quickly retrieve single value at (item, major, minor) location. .. deprecated:: 0.21.0 @@ -787,7 +788,7 @@ def _combine_panel(self, other, func): def major_xs(self, key): """ - Return slice of panel along major axis + Return slice of panel along major axis. Parameters ---------- @@ -811,7 +812,7 @@ def major_xs(self, key): def minor_xs(self, key): """ - Return slice of panel along minor axis + Return slice of panel along minor axis. Parameters ---------- @@ -835,7 +836,7 @@ def minor_xs(self, key): def xs(self, key, axis=1): """ - Return slice of panel along selected axis + Return slice of panel along selected axis. Parameters ---------- @@ -898,7 +899,7 @@ def _ixs(self, i, axis=0): def groupby(self, function, axis='major'): """ - Group data on given axis, returning GroupBy object + Group data on given axis, returning GroupBy object. Parameters ---------- @@ -993,7 +994,7 @@ def construct_index_parts(idx, major=True): def apply(self, func, axis='major', **kwargs): """ - Applies function along axis (or axes) of the Panel + Applies function along axis (or axes) of the Panel. Parameters ---------- @@ -1115,7 +1116,7 @@ def _apply_1d(self, func, axis): return self._construct_return_type(results, planes) def _apply_2d(self, func, axis): - """ handle 2-d slices, equiv to iterating over the other axis """ + """ Handle 2-d slices, equiv to iterating over the other axis. """ ndim = self.ndim axis = [self._get_axis_number(a) for a in axis] @@ -1172,7 +1173,7 @@ def _reduce(self, op, name, axis=0, skipna=True, numeric_only=None, return self._construct_return_type(result, axes) def _construct_return_type(self, result, axes=None): - """ return the type for the ndim of the result """ + """ Return the type for the ndim of the result. """ ndim = getattr(result, 'ndim', None) # need to assume they are the same @@ -1333,7 +1334,7 @@ def tshift(self, periods=1, freq=None, axis='major'): def join(self, other, how='left', lsuffix='', rsuffix=''): """ - Join items with other Panel either on major and minor axes column + Join items with other Panel either on major and minor axes column. Parameters ---------- @@ -1440,13 +1441,13 @@ def _get_join_index(self, other, how): # miscellaneous data creation @staticmethod def _extract_axes(self, data, axes, **kwargs): - """ return a list of the axis indices """ + """ Return a list of the axis indices. """ return [self._extract_axis(self, data, axis=i, **kwargs) for i, a in enumerate(axes)] @staticmethod def _extract_axes_for_slice(self, axes): - """ return the slice dictionary for these axes """ + """ Return the slice dictionary for these axes. """ return {self._AXIS_SLICEMAP[i]: a for i, a in zip(self._AXIS_ORDERS[self._AXIS_LEN - len(axes):], axes)} diff --git a/pandas/core/resample.py b/pandas/core/resample.py index 125b441e5558a..1193d932edf86 100644 --- a/pandas/core/resample.py +++ b/pandas/core/resample.py @@ -757,8 +757,8 @@ def interpolate(self, method='linear', axis=0, limit=None, inplace=False, def asfreq(self, fill_value=None): """ - return the values at the new freq, - essentially a reindex + Return the values at the new freq, + essentially a reindex. Parameters ---------- @@ -777,7 +777,7 @@ def asfreq(self, fill_value=None): def std(self, ddof=1, *args, **kwargs): """ - Compute standard deviation of groups, excluding missing values + Compute standard deviation of groups, excluding missing values. Parameters ---------- @@ -789,7 +789,7 @@ def std(self, ddof=1, *args, **kwargs): def var(self, ddof=1, *args, **kwargs): """ - Compute variance of groups, excluding missing values + Compute variance of groups, excluding missing values. Parameters ---------- @@ -909,7 +909,7 @@ def _maybe_process_deprecations(r, how=None, fill_method=None, limit=None): class _GroupByMixin(GroupByMixin): - """ provide the groupby facilities """ + """ Provide the groupby facilities. """ def __init__(self, obj, *args, **kwargs): @@ -931,8 +931,8 @@ def __init__(self, obj, *args, **kwargs): def _apply(self, f, grouper=None, *args, **kwargs): """ - dispatch to _upsample; we are stripping all of the _upsample kwargs and - performing the original function call on the grouped object + Dispatch to _upsample; we are stripping all of the _upsample kwargs and + performing the original function call on the grouped object. """ def func(x): @@ -966,7 +966,7 @@ def _get_binner_for_time(self): def _downsample(self, how, **kwargs): """ - Downsample the cython defined function + Downsample the cython defined function. Parameters ---------- @@ -1106,7 +1106,7 @@ def _convert_obj(self, obj): def _downsample(self, how, **kwargs): """ - Downsample the cython defined function + Downsample the cython defined function. Parameters ---------- @@ -1177,7 +1177,7 @@ def _upsample(self, method, limit=None, fill_value=None): class PeriodIndexResamplerGroupby(_GroupByMixin, PeriodIndexResampler): """ - Provides a resample of a groupby implementation + Provides a resample of a groupby implementation. .. versionadded:: 0.18.1 @@ -1207,7 +1207,7 @@ def _adjust_binner_for_upsample(self, binner): class TimedeltaIndexResamplerGroupby(_GroupByMixin, TimedeltaIndexResampler): """ - Provides a resample of a groupby implementation + Provides a resample of a groupby implementation. .. versionadded:: 0.18.1 @@ -1218,7 +1218,7 @@ def _constructor(self): def resample(obj, kind=None, **kwds): - """ create a TimeGrouper and return our resampler """ + """ Create a TimeGrouper and return our resampler. """ tg = TimeGrouper(**kwds) return tg._get_resampler(obj, kind=kind) @@ -1244,7 +1244,7 @@ def get_resampler_for_grouping(groupby, rule, how=None, fill_method=None, class TimeGrouper(Grouper): """ - Custom groupby class for time-interval grouping + Custom groupby class for time-interval grouping. Parameters ---------- diff --git a/pandas/core/window.py b/pandas/core/window.py index 4c67b04e89ba8..47914cd40ec85 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -161,7 +161,7 @@ def _window_type(self): return self.__class__.__name__ def __unicode__(self): - """ provide a nice str repr of our rolling object """ + """ Provide a nice str repr of our rolling object. """ attrs = ["{k}={v}".format(k=k, v=getattr(self, k)) for k in self._attributes @@ -175,7 +175,7 @@ def __iter__(self): def _get_index(self, index=None): """ - Return index as ndarrays + Return index as ndarrays. Returns ------- @@ -776,8 +776,8 @@ def __init__(self, obj, *args, **kwargs): def _apply(self, func, name, window=None, center=None, check_minp=None, **kwargs): """ - dispatch to apply; we are stripping all of the _apply kwargs and - performing the original function call on the grouped object + Dispatch to apply; we are stripping all of the _apply kwargs and + performing the original function call on the grouped object. """ def f(x, name=name, *args): @@ -995,7 +995,7 @@ def sum(self, *args, **kwargs): return self._apply('roll_sum', 'sum', **kwargs) _shared_docs['max'] = dedent(""" - %(name)s maximum + Calculate the %(name)s maximum """) def max(self, *args, **kwargs): @@ -1259,7 +1259,7 @@ def kurt(self, **kwargs): check_minp=_require_min_periods(4), **kwargs) _shared_docs['quantile'] = dedent(""" - %(name)s quantile. + Calculate the %(name)s quantile. Parameters ---------- @@ -1333,7 +1333,7 @@ def f(arg, *args, **kwargs): **kwargs) _shared_docs['cov'] = dedent(""" - %(name)s sample covariance + Calculate the %(name)s sample covariance Parameters ---------- @@ -1760,7 +1760,7 @@ def corr(self, other=None, pairwise=None, **kwargs): class RollingGroupby(_GroupByMixin, Rolling): """ - Provides a rolling groupby implementation + Provides a rolling groupby implementation. .. versionadded:: 0.18.1 @@ -1781,7 +1781,7 @@ def _gotitem(self, key, ndim, subset=None): def _validate_monotonic(self): """ - validate that on is monotonic; + Validate that on is monotonic; we don't care for groupby.rolling because we have already validated at a higher level @@ -2031,7 +2031,7 @@ def corr(self, other=None, pairwise=None, **kwargs): class ExpandingGroupby(_GroupByMixin, Expanding): """ - Provides a expanding groupby implementation + Provides a expanding groupby implementation. .. versionadded:: 0.18.1 @@ -2069,7 +2069,7 @@ def _constructor(self): class EWM(_Rolling): r""" - Provides exponential weighted functions + Provides exponential weighted functions. .. versionadded:: 0.18.0 @@ -2219,7 +2219,8 @@ def aggregate(self, arg, *args, **kwargs): agg = aggregate def _apply(self, func, **kwargs): - """Rolling statistical measure using supplied function. Designed to be + """ + Rolling statistical measure using supplied function. Designed to be used with passed-in Cython array-based functions. Parameters @@ -2261,7 +2262,7 @@ def func(arg): @Substitution(name='ewm') @Appender(_doc_template) def mean(self, *args, **kwargs): - """exponential weighted moving average""" + """ Exponential weighted moving average. """ nv.validate_window_func('mean', args, kwargs) return self._apply('ewma', **kwargs) @@ -2269,7 +2270,7 @@ def mean(self, *args, **kwargs): @Appender(_doc_template) @Appender(_bias_template) def std(self, bias=False, *args, **kwargs): - """exponential weighted moving stddev""" + """ Exponential weighted moving stddev. """ nv.validate_window_func('std', args, kwargs) return _zsqrt(self.var(bias=bias, **kwargs)) @@ -2279,7 +2280,7 @@ def std(self, bias=False, *args, **kwargs): @Appender(_doc_template) @Appender(_bias_template) def var(self, bias=False, *args, **kwargs): - """exponential weighted moving variance""" + """ Exponential weighted moving variance. """ nv.validate_window_func('var', args, kwargs) def f(arg): @@ -2293,7 +2294,7 @@ def f(arg): @Appender(_doc_template) @Appender(_pairwise_template) def cov(self, other=None, pairwise=None, bias=False, **kwargs): - """exponential weighted sample covariance""" + """ Exponential weighted sample covariance. """ if other is None: other = self._selected_obj # only default unset @@ -2316,7 +2317,7 @@ def _get_cov(X, Y): @Appender(_doc_template) @Appender(_pairwise_template) def corr(self, other=None, pairwise=None, **kwargs): - """exponential weighted sample correlation""" + """ Exponential weighted sample correlation. """ if other is None: other = self._selected_obj # only default unset diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 2c018598a6a6e..4cb372525ce10 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -417,7 +417,8 @@ def format(self, formatter, subset=None): return self def render(self, **kwargs): - """Render the built up styles to HTML + """ + Render the built up styles to HTML. Parameters ---------- @@ -504,7 +505,8 @@ def __deepcopy__(self, memo): return self._copy(deepcopy=True) def clear(self): - """"Reset" the styler, removing any previously applied styles. + """ + 'Reset' the styler, removing any previously applied styles. Returns None. """ self.ctx.clear() diff --git a/pandas/io/json/normalize.py b/pandas/io/json/normalize.py index 3e3f125b56d88..4cabbe614a0a7 100644 --- a/pandas/io/json/normalize.py +++ b/pandas/io/json/normalize.py @@ -24,9 +24,9 @@ def _convert_to_line_delimits(s): def nested_to_record(ds, prefix="", sep=".", level=0): - """a simplified json_normalize + """A simplified json_normalize. - converts a nested dict into a flat dict ("record"), unlike json_normalize, + Converts a nested dict into a flat dict ("record"), unlike json_normalize, it does not attempt to extract a subset of the data. Parameters @@ -99,7 +99,7 @@ def json_normalize(data, record_path=None, meta=None, errors='raise', sep='.'): """ - "Normalize" semi-structured JSON data into a flat table + 'Normalize' semi-structured JSON data into a flat table. Parameters ---------- diff --git a/pandas/io/pytables.py b/pandas/io/pytables.py index ab1c89ef828d0..640034cb49d25 100644 --- a/pandas/io/pytables.py +++ b/pandas/io/pytables.py @@ -414,7 +414,7 @@ def _is_metadata_of(group, parent_group): class HDFStore(StringMixin): """ - dict-like IO interface for storing pandas objects in PyTables + Dict-like IO interface for storing pandas objects in PyTables either Fixed or Table format. Parameters @@ -1217,7 +1217,7 @@ def copy(self, file, mode='w', propindexes=True, keys=None, complib=None, def info(self): """ - print detailed information on the store + Print detailed information on the store. .. versionadded:: 0.21.0 """ From 751ebc9e5995a62ce34082f6446af24f65676285 Mon Sep 17 00:00:00 2001 From: fwx Date: Sun, 25 Nov 2018 02:40:37 +0530 Subject: [PATCH 02/10] Fixing a PEP8 issue --- pandas/core/indexes/base.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 28934c6159c9f..02b7fc762e8be 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -824,11 +824,11 @@ def repeat(self, repeats, *args, **kwargs): nv.validate_repeat(args, kwargs) return self._shallow_copy(self._values.repeat(repeats)) - _index_shared_docs['where'] = """ + _index_shared_docs['where'] = """ Return an Index of same shape as self and whose corresponding entries are from self where cond is True and otherwise are from other. - + .. versionadded:: 0.19.0 Parameters @@ -3824,10 +3824,10 @@ def _reindex_non_unique(self, target): new_index = self._shallow_copy_with_infer(new_labels, freq=None) return new_index, indexer, new_indexer - _index_shared_docs['join'] = """ + _index_shared_docs['join'] = """ Compute join_index and indexers to conform data structures to the new index. - + *This is an internal non-public method* Parameters From d6a2d5bc016f52cbbb6370f555f8541adc5eff86 Mon Sep 17 00:00:00 2001 From: fwx Date: Sun, 25 Nov 2018 03:14:00 +0530 Subject: [PATCH 03/10] Another missed PEP8 issue fixed. --- pandas/core/indexes/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 02b7fc762e8be..73db22e20c5f0 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -824,7 +824,7 @@ def repeat(self, repeats, *args, **kwargs): nv.validate_repeat(args, kwargs) return self._shallow_copy(self._values.repeat(repeats)) - _index_shared_docs['where'] = """ + _index_shared_docs['where'] = """ Return an Index of same shape as self and whose corresponding entries are from self where cond is True and otherwise are from other. From 55f5a2292b559173c7bb5297be49f868844c52dd Mon Sep 17 00:00:00 2001 From: fwx Date: Mon, 26 Nov 2018 13:09:46 +0530 Subject: [PATCH 04/10] Adding in changes requested by @datapythonista --- pandas/core/frame.py | 2 +- pandas/core/groupby/base.py | 11 +- pandas/core/groupby/groupby.py | 108 ++++++++----- pandas/core/indexes/base.py | 284 ++++++++++++++++++++++----------- pandas/core/window.py | 84 ++++++---- pandas/io/formats/style.py | 54 ++++--- pandas/io/json/json.py | 60 ++++--- pandas/io/json/normalize.py | 9 +- 8 files changed, 397 insertions(+), 215 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 9683ea0e69584..751f9648e2180 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -5839,7 +5839,7 @@ def unstack(self, level=-1, fill_value=None): return unstack(self, level, fill_value) _shared_docs['melt'] = (""" - 'Unpivots' a DataFrame from wide format to long format, optionally + Unpivots a DataFrame from wide format to long format, optionally leaving identifier variables set. This function is useful to massage a DataFrame into a format where one diff --git a/pandas/core/groupby/base.py b/pandas/core/groupby/base.py index 60ce08b9a6da5..a148f7e0cab87 100644 --- a/pandas/core/groupby/base.py +++ b/pandas/core/groupby/base.py @@ -12,11 +12,15 @@ class GroupByMixin(object): - """ Provide the groupby facilities to the mixed object. """ + """ + Provide the groupby facilities to the mixed object. + """ @staticmethod def _dispatch(name, *args, **kwargs): - """ Dispatch to apply. """ + """ + Dispatch to apply. + """ def outer(self, *args, **kwargs): def f(x): @@ -28,8 +32,7 @@ def f(x): def _gotitem(self, key, ndim, subset=None): """ - Sub-classes to define - return a sliced object. + Sub-classes to define. Return a sliced object. Parameters ---------- diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 30eb6d24443c2..292d4207cf2c5 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -377,14 +377,16 @@ def __unicode__(self): def _assure_grouper(self): """ - We create the grouper on instantiation - sub-classes may have a different policy. + We create the grouper on instantiation sub-classes may have a + different policy. """ pass @property def groups(self): - """ Dict {group name -> group labels} """ + """ + Dict {group name -> group labels}. + """ self._assure_grouper() return self.grouper.groups @@ -395,7 +397,9 @@ def ngroups(self): @property def indices(self): - """ Dict {group name -> group indices} """ + """ + Dict {group name -> group indices}. + """ self._assure_grouper() return self.grouper.indices @@ -450,7 +454,9 @@ def get_converter(s): return [self.indices.get(name, []) for name in names] def _get_index(self, name): - """ Safe get index, translate keys for datelike to underlying repr .""" + """ + Safe get index, translate keys for datelike to underlying repr. + """ return self._get_indices([name])[0] @cache_readonly @@ -465,8 +471,10 @@ def _selected_obj(self): def _reset_group_selection(self): """ - Clear group based selection. Used for methods needing to return info on - each group regardless of whether a group selection was previously set. + Clear group based selection. + + Used for methods needing to return info on each group regardless of + whether a group selection was previously set. """ if self._group_selection is not None: # GH12839 clear cached selection too when changing group selection @@ -475,8 +483,9 @@ def _reset_group_selection(self): def _set_group_selection(self): """ - Create group based selection. Used when selection is not passed - directly but instead via a grouper. + Create group based selection. + + Used when selection is not passed directly but instead via a grouper. NOTE: this should be paired with a call to _reset_group_selection """ @@ -617,7 +626,7 @@ def curried(x): def get_group(self, name, obj=None): """ - Constructs NDFrame from group with provided name + Constructs NDFrame from group with provided name. Parameters ---------- @@ -643,7 +652,7 @@ def get_group(self, name, obj=None): def __iter__(self): """ - Groupby iterator + Groupby iterator. Returns ------- @@ -743,11 +752,11 @@ def _cumcount_array(self, ascending=True): def _try_cast(self, result, obj, numeric_only=False): """ - try to cast the result to our obj original type, - we may have roundtripped thru object in the mean-time + Try to cast the result to our obj original type, + we may have roundtripped through object in the mean-time. - if numeric_only is True, then only try to cast numerics - and not datetimelikes + If numeric_only is True, then only try to cast numerics + and not datetimelikes. """ if obj.ndim > 1: @@ -945,8 +954,9 @@ def _apply_filter(self, indices, dropna): class GroupBy(_GroupBy): """ - Class for grouping and aggregating relational data. See aggregate, - transform, and apply functions on this object. + Class for grouping and aggregating relational data. + + See aggregate, transform, and apply functions on this object. It's easiest to use obj.groupby(...) to use GroupBy, but you can also do: @@ -1010,7 +1020,9 @@ class GroupBy(_GroupBy): Number of groups """ def _bool_agg(self, val_test, skipna): - """Shared func to call any / all Cython GroupBy implementations""" + """ + Shared func to call any / all Cython GroupBy implementations. + """ def objs_to_bool(vals): try: @@ -1036,7 +1048,7 @@ def result_to_bool(result): @Appender(_doc_template) def any(self, skipna=True): """ - Returns True if any value in the group is truthful, else False + Returns True if any value in the group is truthful, else False. Parameters ---------- @@ -1049,7 +1061,7 @@ def any(self, skipna=True): @Appender(_doc_template) def all(self, skipna=True): """ - Returns True if all values in the group are truthful, else False + Returns True if all values in the group are truthful, else False. Parameters ---------- @@ -1061,7 +1073,9 @@ def all(self, skipna=True): @Substitution(name='groupby') @Appender(_doc_template) def count(self): - """Compute count of group, excluding missing values""" + """ + Compute count of group, excluding missing values. + """ # defined here for API doc raise NotImplementedError @@ -1207,7 +1221,9 @@ def sem(self, ddof=1): @Substitution(name='groupby') @Appender(_doc_template) def size(self): - """Compute group sizes""" + """ + Compute group sizes. + """ result = self.grouper.size() if isinstance(self.obj, Series): @@ -1216,7 +1232,9 @@ def size(self): @classmethod def _add_numeric_operations(cls): - """ add numeric operations to the GroupBy generically """ + """ + Add numeric operations to the GroupBy generically. + """ def groupby_function(name, alias, npfunc, numeric_only=True, _convert=False, @@ -1293,7 +1311,8 @@ def last(x): @Appender(_doc_template) def ohlc(self): """ - Compute sum of values, excluding missing values + Compute sum of values, excluding missing values. + For multiple groupings, the result index will be a MultiIndex """ @@ -1421,9 +1440,7 @@ def resample(self, rule, *args, **kwargs): @Appender(_doc_template) def rolling(self, *args, **kwargs): """ - Return a rolling grouper, providing rolling - functionality per group - + Return a rolling grouper, providing rolling functionality per group. """ from pandas.core.window import RollingGroupby return RollingGroupby(self, *args, **kwargs) @@ -1433,14 +1450,14 @@ def rolling(self, *args, **kwargs): def expanding(self, *args, **kwargs): """ Return an expanding grouper, providing expanding - functionality per group - + functionality per group. """ from pandas.core.window import ExpandingGroupby return ExpandingGroupby(self, *args, **kwargs) def _fill(self, direction, limit=None): - """Shared function for `pad` and `backfill` to call Cython method + """ + Shared function for `pad` and `backfill` to call Cython method. Parameters ---------- @@ -1474,7 +1491,7 @@ def _fill(self, direction, limit=None): @Substitution(name='groupby') def pad(self, limit=None): """ - Forward fill the values + Forward fill the values. Parameters ---------- @@ -1494,7 +1511,7 @@ def pad(self, limit=None): @Substitution(name='groupby') def backfill(self, limit=None): """ - Backward fill the values + Backward fill the values. Parameters ---------- @@ -1830,7 +1847,9 @@ def rank(self, method='average', ascending=True, na_option='keep', @Substitution(name='groupby') @Appender(_doc_template) def cumprod(self, axis=0, *args, **kwargs): - """Cumulative product for each group""" + """ + Cumulative product for each group. + """ nv.validate_groupby_func('cumprod', args, kwargs, ['numeric_only', 'skipna']) if axis != 0: @@ -1841,7 +1860,9 @@ def cumprod(self, axis=0, *args, **kwargs): @Substitution(name='groupby') @Appender(_doc_template) def cumsum(self, axis=0, *args, **kwargs): - """Cumulative sum for each group""" + """ + Cumulative sum for each group. + """ nv.validate_groupby_func('cumsum', args, kwargs, ['numeric_only', 'skipna']) if axis != 0: @@ -1852,7 +1873,9 @@ def cumsum(self, axis=0, *args, **kwargs): @Substitution(name='groupby') @Appender(_doc_template) def cummin(self, axis=0, **kwargs): - """Cumulative min for each group""" + """ + Cumulative min for each group. + """ if axis != 0: return self.apply(lambda x: np.minimum.accumulate(x, axis)) @@ -1861,7 +1884,9 @@ def cummin(self, axis=0, **kwargs): @Substitution(name='groupby') @Appender(_doc_template) def cummax(self, axis=0, **kwargs): - """Cumulative max for each group""" + """ + Cumulative max for each group. + """ if axis != 0: return self.apply(lambda x: np.maximum.accumulate(x, axis)) @@ -1873,7 +1898,8 @@ def _get_cythonized_result(self, how, grouper, aggregate=False, result_is_index=False, pre_processing=None, post_processing=None, **kwargs): - """Get result for Cythonized functions + """ + Get result for Cythonized functions. Parameters ---------- @@ -1968,7 +1994,7 @@ def _get_cythonized_result(self, how, grouper, aggregate=False, @Appender(_doc_template) def shift(self, periods=1, freq=None, axis=0): """ - Shift each group by periods observations + Shift each group by periods observations. Parameters ---------- @@ -1991,7 +2017,9 @@ def shift(self, periods=1, freq=None, axis=0): @Appender(_doc_template) def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None, axis=0): - """Calculate pct_change of each value to previous entry in group""" + """ + Calculate pct_change of each value to previous entry in group. + """ if freq is not None or axis != 0: return self.apply(lambda x: x.pct_change(periods=periods, fill_method=fill_method, @@ -2035,7 +2063,7 @@ def head(self, n=5): @Appender(_doc_template) def tail(self, n=5): """ - Returns last n rows of each group + Returns last n rows of each group. Essentially equivalent to ``.apply(lambda x: x.tail(n))``, except ignores as_index flag. diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 73db22e20c5f0..53ce9d44b3921 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -150,8 +150,9 @@ class InvalidIndexError(Exception): def _new_Index(cls, d): - """ This is called upon unpickling, rather than the default which doesn't - have arguments and breaks __new__ + """ + This is called upon unpickling, rather than the default which doesn't + have arguments and breaks __new__. """ # required for backward compat, because PI can't be instantiated with # ordinals through __new__ GH #13277 @@ -164,7 +165,7 @@ def _new_Index(cls, d): class Index(IndexOpsMixin, PandasObject): """ Immutable ndarray implementing an ordered, sliceable set. The basic object - storing axis labels for all pandas objects + storing axis labels for all pandas objects. Parameters ---------- @@ -490,8 +491,8 @@ def __new__(cls, data=None, dtype=None, copy=False, name=None, @classmethod def _simple_new(cls, values, name=None, dtype=None, **kwargs): """ - we require the we have a dtype compat for the values - if we are passed a non-dtype compat, then coerce using the constructor + We require that we have a dtype compat for the values. If we are passed + a non-dtype compat, then coerce using the constructor. Must be careful not to recurse. """ @@ -518,9 +519,9 @@ def _simple_new(cls, values, name=None, dtype=None, **kwargs): return result._reset_identity() _index_shared_docs['_shallow_copy'] = """ - create a new Index with the same class as the caller, don't copy the + Create a new Index with the same class as the caller, don't copy the data, use the same object attributes with passed in attributes taking - precedence + precedence. *this is an internal non-public method* @@ -550,9 +551,9 @@ def _shallow_copy(self, values=None, **kwargs): def _shallow_copy_with_infer(self, values, **kwargs): """ - create a new Index inferring the class with passed value, don't copy + Create a new Index inferring the class with passed value, don't copy the data, use the same object attributes with passed in attributes - taking precedence + taking precedence. *this is an internal non-public method* @@ -575,11 +576,11 @@ def _shallow_copy_with_infer(self, values, **kwargs): def _deepcopy_if_needed(self, orig, copy=False): """ - .. versionadded:: 0.19.0 - Make a copy of self if data coincides (in memory) with orig. Subclasses should override this if self._base is not an ndarray. + .. versionadded:: 0.19.0 + Parameters ---------- orig : ndarray @@ -608,7 +609,9 @@ def _update_inplace(self, result, **kwargs): raise TypeError("Index can't be updated inplace") def _sort_levels_monotonic(self): - """ compat with MultiIndex """ + """ + Compat with MultiIndex. + """ return self _index_shared_docs['_get_grouper_for_level'] = """ @@ -643,7 +646,7 @@ def _get_grouper_for_level(self, mapper, level=None): def is_(self, other): """ - More flexible, faster check like ``is`` but that works through views + More flexible, faster check like ``is`` but that works through views. Note: this is *not* the same as ``Index.identical()``, which checks that metadata is also the same. @@ -662,24 +665,28 @@ def is_(self, other): other, '_id', Ellipsis) and self._id is not None def _reset_identity(self): - """Initializes or resets ``_id`` attribute with new object""" + """ + Initializes or resets ``_id`` attribute with new object. + """ self._id = _Identity() return self # ndarray compat def __len__(self): """ - return the length of the Index + Return the length of the Index. """ return len(self._data) def __array__(self, dtype=None): - """ the array interface, return my values """ + """ + The array interface, return my values. + """ return self._data.view(np.ndarray) def __array_wrap__(self, result, context=None): """ - Gets called after a ufunc + Gets called after a ufunc. """ if is_bool_dtype(result): return result @@ -690,24 +697,31 @@ def __array_wrap__(self, result, context=None): @cache_readonly def dtype(self): - """ Return the dtype object of the underlying data. """ + """ + Return the dtype object of the underlying data. + """ return self._data.dtype @cache_readonly def dtype_str(self): - """ Return the dtype str of the underlying data. """ + """ + Return the dtype str of the underlying data. + """ return str(self.dtype) @property def values(self): - """ Return the underlying data as an ndarray. """ + """ + Return the underlying data as an ndarray. + """ return self._data.view(np.ndarray) @property def _values(self): # type: () -> Union[ExtensionArray, Index, np.ndarray] # TODO(EA): remove index types as they become extension arrays - """The best array representation. + """ + The best array representation. This is an ndarray, ExtensionArray, or Index subclass. This differs from ``_ndarray_values``, which always returns an ndarray. @@ -927,8 +941,16 @@ def _string_data_error(cls, data): @classmethod def _coerce_to_ndarray(cls, data): - """coerces data to ndarray, raises on scalar data. Converts other - iterables to list first and then to array. Does not touch ndarrays. + """ + Coerces data to ndarray. + + Converts other iterables to list first and then to array. + Does not touch ndarrays. + + Raises + ------ + TypeError + When the data passed in is a scalar. """ if not isinstance(data, (np.ndarray, Index)): @@ -942,7 +964,9 @@ def _coerce_to_ndarray(cls, data): return data def _get_attributes_dict(self): - """ return an attributes dict for my class """ + """ + Return an attributes dict for my class. + """ return {k: getattr(self, k, None) for k in self._attributes} def view(self, cls=None): @@ -959,7 +983,7 @@ def view(self, cls=None): def _coerce_scalar_to_index(self, item): """ - we need to coerce a scalar to a compat for our index type + We need to coerce a scalar to a compat for our index type. Parameters ---------- @@ -1078,13 +1102,13 @@ def _format_space(self): @property def _formatter_func(self): """ - Return the formatter function + Return the formatter function. """ return default_pprint def _format_data(self, name=None): """ - Return the formatted data as a unicode string + Return the formatted data as a unicode string. """ # do we want to justify (only do so for non-objects) @@ -1097,7 +1121,7 @@ def _format_data(self, name=None): def _format_attrs(self): """ - Return a list of tuples of the (attr,formatted_value) + Return a list of tuples of the (attr,formatted_value). """ return format_object_attrs(self) @@ -1124,7 +1148,7 @@ def to_flat_index(self): def to_series(self, index=None, name=None): """ Create a Series with both index and values equal to the index keys - useful with map for returning an indexer based on an index + useful with map for returning an indexer based on an index. Parameters ---------- @@ -1251,7 +1275,9 @@ def astype(self, dtype, copy=True): raise TypeError(msg.format(name=type(self).__name__, dtype=dtype)) def _to_safe_for_reshape(self): - """ convert to object if we are a categorical """ + """ + Convert to object if we are a categorical. + """ return self def _assert_can_do_setop(self, other): @@ -1268,11 +1294,15 @@ def _convert_can_do_setop(self, other): return other, result_name def _convert_for_op(self, value): - """ Convert value to be insertable to ndarray """ + """ + Convert value to be insertable to ndarray. + """ return value def _assert_can_do_op(self, value): - """ Check value is valid for scalar op """ + """ + Check value is valid for scalar op. + """ if not is_scalar(value): msg = "'value' must be a scalar, passed: {0}" raise TypeError(msg.format(type(value).__name__)) @@ -1445,7 +1475,7 @@ def _has_complex_internals(self): def _summary(self, name=None): """ - Return a summarized representation + Return a summarized representation. Parameters ---------- @@ -1477,6 +1507,7 @@ def _summary(self, name=None): def summary(self, name=None): """ Return a summarized representation + .. deprecated:: 0.23.0 """ warnings.warn("'summary' is deprecated and will be removed in a " @@ -1493,7 +1524,9 @@ def _mpl_repr(self): # introspection @property def is_monotonic(self): - """ Alias for is_monotonic_increasing. + """ + Alias for is_monotonic_increasing. + .. deprecated :: """ return self.is_monotonic_increasing @@ -1549,7 +1582,8 @@ def _is_strictly_monotonic_increasing(self): @property def _is_strictly_monotonic_decreasing(self): - """Return if the index is strictly monotonic decreasing + """ + Return if the index is strictly monotonic decreasing (only decreasing) values. Examples @@ -1568,7 +1602,9 @@ def is_lexsorted_for_tuple(self, tup): @cache_readonly def is_unique(self): - """ Return if the index has unique values. """ + """ + Return if the index has unique values. + """ return self._engine.is_unique @property @@ -1856,7 +1892,9 @@ def _convert_list_indexer(self, keyarr, kind=None): return None def _invalid_indexer(self, form, key): - """ consistent invalid indexer message """ + """ + Consistent invalid indexer message. + """ raise TypeError("cannot do {form} indexing on {klass} with these " "indexers [{key}] of {kind}".format( form=form, klass=type(self), key=key, @@ -1959,11 +1997,15 @@ def _get_level_number(self, level): @cache_readonly def inferred_type(self): - """ Return a string of the type inferred from the values, """ + """ + Return a string of the type inferred from the values. + """ return lib.infer_dtype(self) def _is_memory_usage_qualified(self): - """ Return a boolean if we need a qualified .info display. """ + """ + Return a boolean if we need a qualified .info display. + """ return self.is_object() def is_type_compatible(self, kind): @@ -1981,7 +2023,9 @@ def __reduce__(self): return _new_Index, (self.__class__, d), None def __setstate__(self, state): - """ Necessary for making this object picklable. """ + """ + Necessary for making this object picklable. + """ if isinstance(state, dict): self._data = state.pop('data') @@ -2110,7 +2154,7 @@ def _can_hold_identifiers_and_holds_name(self, name): def append(self, other): """ - Append a collection of Index options together + Append a collection of Index options together. Parameters ---------- @@ -2147,7 +2191,7 @@ def _concat(self, to_concat, name): def _concat_same_dtype(self, to_concat, name): """ - Concatenate to_concat which has the same class + Concatenate to_concat which has the same class. """ # must be overridden in specific classes return _concat._concat_index_asobject(to_concat, name) @@ -2193,7 +2237,9 @@ def take(self, indices, axis=0, allow_fill=True, def _assert_take_fillable(self, values, indices, allow_fill=True, fill_value=None, na_value=np.nan): - """ Internal method to handle NA filling of take """ + """ + Internal method to handle NA filling of take. + """ indices = ensure_platform_int(indices) # only fill if we are passing a non-None fill_value @@ -2212,7 +2258,9 @@ def _assert_take_fillable(self, values, indices, allow_fill=True, @cache_readonly def _isnan(self): - """ return if each value is nan""" + """ + Return if each value is NaN. + """ if self._can_hold_na: return isna(self) else: @@ -2232,7 +2280,7 @@ def _nan_idxs(self): @cache_readonly def hasnans(self): """ - Return if I have any nans; enables various perf speedups. + Return if the index has any nans; enables various perf speedups. """ if self._can_hold_na: return bool(self._isnan.any()) @@ -2365,7 +2413,7 @@ def putmask(self, mask, value): def format(self, name=False, formatter=None, **kwargs): """ - Render a string representation of the Index + Render a string representation of the Index. """ header = [] if name: @@ -2431,7 +2479,9 @@ def to_native_types(self, slicer=None, **kwargs): return values._format_native_types(**kwargs) def _format_native_types(self, na_rep='', quoting=None, **kwargs): - """ actually format my specific types """ + """ + Actually format specific types of the index. + """ mask = isna(self) if not self.is_object() and not quoting: values = np.asarray(self).astype(str) @@ -2462,8 +2512,9 @@ def equals(self, other): return False def identical(self, other): - """Similar to equals, but check that other comparable attributes are - also equal + """ + Similar to equals, but check that other comparable attributes are + also equal. """ return (self.equals(other) and all((getattr(self, c, None) == getattr(other, c, None) @@ -2537,13 +2588,32 @@ def asof(self, label): def asof_locs(self, where, mask): """ + Finds the locations (indices) of the labels from the index for + every entry in the `where` argument. + + As in the `asof` function, if the label (a particular entry in + `where`) is not in the index, the latest index label upto the + passed label is chosen and its index returned. + + If all of the labels in the index are later than a label in `where`, + -1 is returned. + + `mask` is used to ignore NA values in the index during calculation. + Parameters ---------- - where : array - Array of timestamps. + where : Index + An Index consisting of an array of timestamps. mask : array-like Array of booleans denoting where values in the original data are not NA. + + Returns + ------- + result: array + An array of locations (indices) of the labels from the Index + which correspond to the return values of the `asof` function + for every element in `where`. """ locs = self.values[mask].searchsorted(where.values, side='right') locs = np.where(locs > 0, locs - 1, 0) @@ -2615,8 +2685,7 @@ def sort(self, *args, **kwargs): def sortlevel(self, level=None, ascending=True, sort_remaining=None): """ - - For internal compatibility with with the Index API + For internal compatibility with with the Index API. Sort the Index. This is for compat with MultiIndex @@ -2986,6 +3055,7 @@ def difference(self, other, sort=True): def symmetric_difference(self, other, result_name=None): """ Compute the symmetric difference of two Index objects. + It's sorted if sorting is possible. Parameters @@ -3142,7 +3212,7 @@ def get_loc(self, key, method=None, tolerance=None): def get_value(self, series, key): """ Fast lookup of value from 1-dimensional ndarray. Only use this if you - know what you're doing + know what you're doing. """ # if we have something that is Index-like, then @@ -3197,7 +3267,7 @@ def get_value(self, series, key): def set_value(self, arr, key, value): """ Fast lookup of value from 1-dimensional ndarray. Only use this if you - know what you're doing + know what you're doing. """ self._engine.set_value(com.values_from_object(arr), com.values_from_object(key), value) @@ -3246,8 +3316,10 @@ def _get_level_values(self, level): def droplevel(self, level=0): """ - Return index with requested level(s) removed. If resulting index has - only 1 level left, the result will be of Index type, not MultiIndex. + Return index with requested level(s) removed. + + If resulting index has only 1 level left, the result will be + of Index type, not MultiIndex. .. versionadded:: 0.23.1 (support for non-MultiIndex) @@ -3414,7 +3486,7 @@ def _get_fill_indexer(self, target, method, limit=None, tolerance=None): def _get_fill_indexer_searchsorted(self, target, method, limit=None): """ Fallback pad/backfill get_indexer that works for monotonic decreasing - indexes and non-monotonic targets + indexes and non-monotonic targets. """ if limit is not None: raise ValueError('limit argument for %r method only well-defined ' @@ -3508,6 +3580,7 @@ def get_indexer_non_unique(self, target): def get_indexer_for(self, target, **kwargs): """ Guaranteed return of an indexer even when non-unique. + This dispatches to get_indexer or get_indexer_nonunique as appropriate. """ @@ -3688,9 +3761,9 @@ def isin(self, values, level=None): def _can_reindex(self, indexer): """ - *this is an internal non-public method* + Check if we are allowing reindexing with this particular indexer. - Check if we are allowing reindexing with this particular indexer + *this is an internal non-public method* Parameters ---------- @@ -3708,7 +3781,8 @@ def _can_reindex(self, indexer): def reindex(self, target, method=None, level=None, limit=None, tolerance=None): """ - Create index with target's values (move/add/delete values as necessary) + Create index with target's values (move/add/delete values + as necessary). Parameters ---------- @@ -3765,10 +3839,10 @@ def reindex(self, target, method=None, level=None, limit=None, def _reindex_non_unique(self, target): """ - *this is an internal non-public method* - Create a new index with target's values (move/add/delete values as - necessary) use with non-unique Index and a possibly non-unique target + necessary) use with non-unique Index and a possibly non-unique target. + + *this is an internal non-public method* Parameters ---------- @@ -4042,16 +4116,18 @@ def _join_level(self, other, level, how='left', return_indexers=False, """ The join method *only* affects the level of the resulting MultiIndex. Otherwise it just exactly aligns the Index data to the - labels of the level in the MultiIndex. If `keep_order` == True, the - order of the data indexed by the MultiIndex will not be changed; - otherwise, it will tie out with `other`. + labels of the level in the MultiIndex. + + If `keep_order` == True, the order of the data indexed by the + MultiIndex will not be changed; otherwise, it will tie out + with `other`. """ from .multi import MultiIndex def _get_leaf_sorter(labels): """ - returns sorter for the inner most level while preserving the - order of higher levels + Returns sorter for the inner most level while preserving the + order of higher levels. """ if labels[0].size == 0: return np.empty(0, dtype='int64') @@ -4273,8 +4349,8 @@ def slice_indexer(self, start=None, end=None, step=None, kind=None): def _maybe_cast_indexer(self, key): """ - If we have a float key and are not a floating index - then try to cast to an int if equivalent + If we have a float key and are not a floating index, then try to cast + to an int if equivalent. """ if is_float(key) and not self.is_floating(): @@ -4288,9 +4364,8 @@ def _maybe_cast_indexer(self, key): def _validate_indexer(self, form, key, kind): """ - If we are positional indexer - validate that we have appropriate typed bounds - must be an integer. + If we are positional indexer, validate that we have appropriate + typed bounds must be an integer. """ assert kind in ['ix', 'loc', 'getitem', 'iloc'] @@ -4510,8 +4585,9 @@ def delete(self, loc): def insert(self, loc, item): """ - Make new Index inserting new item at location. Follows - Python list.append semantics for negative values. + Make new Index inserting new item at location. + + Follows Python list.append semantics for negative values. Parameters ---------- @@ -4769,7 +4845,9 @@ def _evaluate_with_datetime_like(self, other, op): @classmethod def _add_comparison_methods(cls): - """ add in comparison methods """ + """ + Add in comparison methods. + """ cls.__eq__ = _make_comparison_op(operator.eq, cls) cls.__ne__ = _make_comparison_op(operator.ne, cls) cls.__lt__ = _make_comparison_op(operator.lt, cls) @@ -4779,7 +4857,9 @@ def _add_comparison_methods(cls): @classmethod def _add_numeric_methods_add_sub_disabled(cls): - """ add in the numeric add/sub methods to disable """ + """ + Add in the numeric add/sub methods to disable. + """ cls.__add__ = make_invalid_op('__add__') cls.__radd__ = make_invalid_op('__radd__') cls.__iadd__ = make_invalid_op('__iadd__') @@ -4789,7 +4869,9 @@ def _add_numeric_methods_add_sub_disabled(cls): @classmethod def _add_numeric_methods_disabled(cls): - """ add in numeric methods to disable other than add/sub """ + """ + Add in numeric methods to disable other than add/sub. + """ cls.__pow__ = make_invalid_op('__pow__') cls.__rpow__ = make_invalid_op('__rpow__') cls.__mul__ = make_invalid_op('__mul__') @@ -4809,12 +4891,15 @@ def _add_numeric_methods_disabled(cls): cls.__inv__ = make_invalid_op('__inv__') def _maybe_update_attributes(self, attrs): - """ Update Index attributes (e.g. freq) depending on op """ + """ + Update Index attributes (e.g. freq) depending on op. + """ return attrs def _validate_for_numeric_unaryop(self, op, opstr): - """ validate if we can perform a numeric unary operation """ - + """ + Validate if we can perform a numeric unary operation. + """ if not self._is_numeric_dtype: raise TypeError("cannot evaluate a numeric op " "{opstr} for type: {typ}" @@ -4822,10 +4907,10 @@ def _validate_for_numeric_unaryop(self, op, opstr): def _validate_for_numeric_binop(self, other, op): """ - return valid other, evaluate or raise TypeError - if we are not of the appropriate type + Return valid other; evaluate or raise TypeError if we are not of + the appropriate type. - internal method called by ops + *this is an internal method called by ops* """ opstr = '__{opname}__'.format(opname=op.__name__) # if we are an inheritor of numeric, @@ -4865,7 +4950,9 @@ def _validate_for_numeric_binop(self, other, op): @classmethod def _add_numeric_methods_binary(cls): - """ add in numeric methods """ + """ + Add in numeric methods. + """ cls.__add__ = _make_arithmetic_op(operator.add, cls) cls.__radd__ = _make_arithmetic_op(ops.radd, cls) cls.__sub__ = _make_arithmetic_op(operator.sub, cls) @@ -4887,8 +4974,9 @@ def _add_numeric_methods_binary(cls): @classmethod def _add_numeric_methods_unary(cls): - """ add in numeric unary methods """ - + """ + Add in numeric unary methods. + """ def _make_evaluate_unary(op, opstr): def _evaluate_numeric_unary(self): @@ -4912,8 +5000,9 @@ def _add_numeric_methods(cls): @classmethod def _add_logical_methods(cls): - """ add in logical methods """ - + """ + Add in logical methods. + """ _doc = """ %(desc)s @@ -5017,7 +5106,9 @@ def logical_func(self, *args, **kwargs): @classmethod def _add_logical_methods_disabled(cls): - """ add in logical methods to disable """ + """ + Add in logical methods to disable. + """ cls.all = make_invalid_op('all') cls.any = make_invalid_op('any') @@ -5028,7 +5119,8 @@ def _add_logical_methods_disabled(cls): def ensure_index_from_sequences(sequences, names=None): - """Construct an index from sequences of data. + """ + Construct an index from sequences of data. A single sequence returns an Index. Many sequences returns a MultiIndex. @@ -5069,7 +5161,7 @@ def ensure_index_from_sequences(sequences, names=None): def ensure_index(index_like, copy=False): """ - Ensure that we have an index from some index-like object + Ensure that we have an index from some index-like object. Parameters ---------- @@ -5131,7 +5223,9 @@ def ensure_index(index_like, copy=False): def _ensure_has_len(seq): - """If seq is an iterator, put its values into a list.""" + """ + If seq is an iterator, put its values into a list. + """ try: len(seq) except TypeError: @@ -5142,7 +5236,7 @@ def _ensure_has_len(seq): def _trim_front(strings): """ - Trims zeros and decimal points + Trims zeros and decimal points. """ trimmed = strings while len(strings) > 0 and all(x[0] == ' ' for x in trimmed): diff --git a/pandas/core/window.py b/pandas/core/window.py index 47914cd40ec85..a079cea0fabd1 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -1,9 +1,6 @@ """ - -provide a generic structure to support window functions, -similar to how we have a Groupby object - - +Provide a generic structure to support window functions, +similar to how we have a Groupby object. """ from __future__ import division @@ -95,14 +92,17 @@ def validate(self): "'neither'") def _convert_freq(self): - """ resample according to the how, return a new object """ - + """ + Resample according to the how, return a new object. + """ obj = self._selected_obj index = None return obj, index def _create_blocks(self): - """ split data into blocks & return conformed data """ + """ + Split data into blocks & return conformed data. + """ obj, index = self._convert_freq() if index is not None: @@ -119,8 +119,7 @@ def _create_blocks(self): def _gotitem(self, key, ndim, subset=None): """ - sub-classes to define - return a sliced object + Sub-classes to define. Return a sliced object. Parameters ---------- @@ -161,7 +160,9 @@ def _window_type(self): return self.__class__.__name__ def __unicode__(self): - """ Provide a nice str repr of our rolling object. """ + """ + Provide a nice str repr of our rolling object. + """ attrs = ["{k}={v}".format(k=k, v=getattr(self, k)) for k in self._attributes @@ -219,7 +220,9 @@ def _prep_values(self, values=None, kill_inf=True): return values def _wrap_result(self, result, block=None, obj=None): - """ wrap a single result """ + """ + Wrap a single result. + """ if obj is None: obj = self._selected_obj @@ -243,7 +246,7 @@ def _wrap_result(self, result, block=None, obj=None): def _wrap_results(self, results, blocks, obj): """ - wrap the results + Wrap the results. Parameters ---------- @@ -288,7 +291,9 @@ def _wrap_results(self, results, blocks, obj): return concat(final, axis=1).reindex(columns=columns, copy=False) def _center_window(self, result, window): - """ center the result in the window """ + """ + Center the result in the window. + """ if self.axis > result.ndim - 1: raise ValueError("Requested axis is larger then no. of argument " "dimensions") @@ -606,8 +611,8 @@ def validate(self): def _prep_window(self, **kwargs): """ - provide validation for our window type, return the window - we have already been validated + Provide validation for our window type, return the window + we have already been validated. """ window = self._get_window() @@ -757,7 +762,9 @@ def mean(self, *args, **kwargs): class _GroupByMixin(GroupByMixin): - """ provide the groupby facilities """ + """ + Provide the groupby facilities. + """ def __init__(self, obj, *args, **kwargs): parent = kwargs.pop('parent', None) # noqa @@ -800,8 +807,9 @@ def _constructor(self): def _apply(self, func, name=None, window=None, center=None, check_minp=None, **kwargs): """ - Rolling statistical measure using supplied function. Designed to be - used with passed-in Cython array-based functions. + Rolling statistical measure using supplied function. + + Designed to be used with passed-in Cython array-based functions. Parameters ---------- @@ -937,7 +945,7 @@ def count(self): return self._wrap_results(results, blocks, obj) _shared_docs['apply'] = dedent(r""" - %(name)s function apply + %(name)s function apply. Parameters ---------- @@ -995,7 +1003,7 @@ def sum(self, *args, **kwargs): return self._apply('roll_sum', 'sum', **kwargs) _shared_docs['max'] = dedent(""" - Calculate the %(name)s maximum + Calculate the %(name)s maximum. """) def max(self, *args, **kwargs): @@ -1333,7 +1341,7 @@ def f(arg, *args, **kwargs): **kwargs) _shared_docs['cov'] = dedent(""" - Calculate the %(name)s sample covariance + Calculate the %(name)s sample covariance. Parameters ---------- @@ -1485,7 +1493,7 @@ def _get_cov(X, Y): Y 0.626300 1.000000 4 X 1.000000 0.555368 Y 0.555368 1.000000 -""") + """) def corr(self, other=None, pairwise=None, **kwargs): if other is None: @@ -1566,14 +1574,18 @@ def validate(self): "and offset based windows") def _validate_monotonic(self): - """ validate on is monotonic """ + """ + Validate on is_monotonic. + """ if not self._on.is_monotonic: formatted = self.on or 'index' raise ValueError("{0} must be " "monotonic".format(formatted)) def _validate_freq(self): - """ validate & return window frequency """ + """ + Validate & return window frequency. + """ from pandas.tseries.frequencies import to_offset try: return to_offset(self.window) @@ -1784,7 +1796,7 @@ def _validate_monotonic(self): Validate that on is monotonic; we don't care for groupby.rolling because we have already validated at a higher - level + level. """ pass @@ -2262,7 +2274,9 @@ def func(arg): @Substitution(name='ewm') @Appender(_doc_template) def mean(self, *args, **kwargs): - """ Exponential weighted moving average. """ + """ + Exponential weighted moving average. + """ nv.validate_window_func('mean', args, kwargs) return self._apply('ewma', **kwargs) @@ -2270,7 +2284,9 @@ def mean(self, *args, **kwargs): @Appender(_doc_template) @Appender(_bias_template) def std(self, bias=False, *args, **kwargs): - """ Exponential weighted moving stddev. """ + """ + Exponential weighted moving stddev. + """ nv.validate_window_func('std', args, kwargs) return _zsqrt(self.var(bias=bias, **kwargs)) @@ -2280,7 +2296,9 @@ def std(self, bias=False, *args, **kwargs): @Appender(_doc_template) @Appender(_bias_template) def var(self, bias=False, *args, **kwargs): - """ Exponential weighted moving variance. """ + """ + Exponential weighted moving variance. + """ nv.validate_window_func('var', args, kwargs) def f(arg): @@ -2294,7 +2312,9 @@ def f(arg): @Appender(_doc_template) @Appender(_pairwise_template) def cov(self, other=None, pairwise=None, bias=False, **kwargs): - """ Exponential weighted sample covariance. """ + """ + Exponential weighted sample covariance. + """ if other is None: other = self._selected_obj # only default unset @@ -2317,7 +2337,9 @@ def _get_cov(X, Y): @Appender(_doc_template) @Appender(_pairwise_template) def corr(self, other=None, pairwise=None, **kwargs): - """ Exponential weighted sample correlation. """ + """ + Exponential weighted sample correlation. + """ if other is None: other = self._selected_obj # only default unset diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 4cb372525ce10..dda50b6a0e7f8 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -53,8 +53,7 @@ def _mpl(func): class Styler(object): """ - Helps style a DataFrame or Series according to the - data with HTML and CSS. + Helps style a DataFrame or Series according to the data with HTML and CSS. Parameters ---------- @@ -157,7 +156,9 @@ def default_display_func(x): self._display_funcs = defaultdict(lambda: default_display_func) def _repr_html_(self): - """Hooks into Jupyter notebook rich display system.""" + """ + Hooks into Jupyter notebook rich display system. + """ return self.render() @Appender(_shared_docs['to_excel'] % dict( @@ -187,7 +188,7 @@ def to_excel(self, excel_writer, sheet_name='Sheet1', na_rep='', def _translate(self): """ Convert the DataFrame in `self.data` and the attrs from `_build_styles` - into a dictionary of {head, body, uuid, cellstyle} + into a dictionary of {head, body, uuid, cellstyle}. """ table_styles = self.table_styles or [] caption = self.caption @@ -468,8 +469,9 @@ def render(self, **kwargs): def _update_ctx(self, attrs): """ - update the state of the Styler. Collects a mapping - of {index_label: [': ']} + Update the state of the Styler. + + Collects a mapping of {index_label: [': ']}. attrs : Series or DataFrame should contain strings of ': ;: ' @@ -506,7 +508,7 @@ def __deepcopy__(self, memo): def clear(self): """ - 'Reset' the styler, removing any previously applied styles. + Reset the styler, removing any previously applied styles. Returns None. """ self.ctx.clear() @@ -698,9 +700,10 @@ def set_precision(self, precision): def set_table_attributes(self, attributes): """ - Set the table attributes. These are the items - that show up in the opening ```` tag in addition - to to automatic (by default) id. + Set the table attributes. + + These are the items that show up in the opening ``
`` tag + in addition to to automatic (by default) id. Parameters ---------- @@ -722,6 +725,7 @@ def set_table_attributes(self, attributes): def export(self): """ Export the styles to applied to the current Styler. + Can be applied to a second style with ``Styler.use``. Returns @@ -787,8 +791,9 @@ def set_caption(self, caption): def set_table_styles(self, table_styles): """ - Set the table styles on a Styler. These are placed in a - ``