Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC/CLN: Fix various docstring errors #25295

Merged
merged 4 commits into from
Feb 16, 2019
Merged

DOC/CLN: Fix various docstring errors #25295

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4a8206b
DOC/CLN: Fix various docstring errors
Jan 27, 2019
293227b
Fix some PEP8
Feb 13, 2019
1e104b5
Merge branch 'master' into doc-fix
Feb 16, 2019
292b64d
Remove comments from crosstab docstring
Feb 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 36 additions & 36 deletions pandas/core/arrays/categorical.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ def contains(cat, key, container):

class Categorical(ExtensionArray, PandasObject):
"""
Represent a categorical variable in classic R / S-plus fashion
Represent a categorical variable in classic R / S-plus fashion.

`Categoricals` can only take on only a limited, and usually fixed, number
of possible values (`categories`). In contrast to statistical categorical
Expand All @@ -235,7 +235,7 @@ class Categorical(ExtensionArray, PandasObject):
The unique categories for this categorical. If not given, the
categories are assumed to be the unique values of `values` (sorted, if
possible, otherwise in the order in which they appear).
ordered : boolean, (default False)
ordered : bool, default False
Whether or not this categorical is treated as a ordered categorical.
If True, the resulting categorical will be ordered.
An ordered categorical respects, when sorted, the order of its
Expand All @@ -253,7 +253,7 @@ class Categorical(ExtensionArray, PandasObject):
codes : ndarray
The codes (integer positions, which point to the categories) of this
categorical, read only.
ordered : boolean
ordered : bool
Whether or not this Categorical is ordered.
dtype : CategoricalDtype
The instance of ``CategoricalDtype`` storing the ``categories``
Expand Down Expand Up @@ -297,7 +297,7 @@ class Categorical(ExtensionArray, PandasObject):
Ordered `Categoricals` can be sorted according to the custom order
of the categories and can have a min and max value.

>>> c = pd.Categorical(['a','b','c','a','b','c'], ordered=True,
>>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'], ordered=True,
... categories=['c', 'b', 'a'])
>>> c
[a, b, c, a, b, c]
Expand Down Expand Up @@ -618,7 +618,7 @@ def from_codes(cls, codes, categories=None, ordered=None, dtype=None):
----------
codes : array-like, integers
An integer array, where each integer points to a category in
categories or dtype.categories, or else is -1 for NaN
categories or dtype.categories, or else is -1 for NaN.
categories : index-like, optional
The categories for the categorical. Items need to be unique.
If the categories are not given here, then they must be provided
Expand Down Expand Up @@ -700,7 +700,7 @@ def _set_categories(self, categories, fastpath=False):

Parameters
----------
fastpath : boolean (default: False)
fastpath : bool, default False
Don't perform validation of the categories for uniqueness or nulls

Examples
Expand Down Expand Up @@ -747,15 +747,15 @@ def _set_dtype(self, dtype):

def set_ordered(self, value, inplace=False):
"""
Set the ordered attribute to the boolean value
Set the ordered attribute to the boolean value.

Parameters
----------
value : boolean to set whether this categorical is ordered (True) or
not (False)
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to the value
value : bool
Set whether this categorical is ordered (True) or not (False).
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to the value.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
new_dtype = CategoricalDtype(self.categories, ordered=value)
Expand All @@ -770,9 +770,9 @@ def as_ordered(self, inplace=False):

Parameters
----------
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to True
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to True.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
return self.set_ordered(True, inplace=inplace)
Expand All @@ -783,9 +783,9 @@ def as_unordered(self, inplace=False):

Parameters
----------
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to False
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to False.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
return self.set_ordered(False, inplace=inplace)
Expand Down Expand Up @@ -815,19 +815,19 @@ def set_categories(self, new_categories, ordered=None, rename=False,
----------
new_categories : Index-like
The categories in new order.
ordered : boolean, (default: False)
ordered : bool, default False
Whether or not the categorical is treated as a ordered categorical.
If not given, do not change the ordered information.
rename : boolean (default: False)
rename : bool, default False
Whether or not the new_categories should be considered as a rename
of the old categories or as reordered categories.
inplace : boolean (default: False)
Whether or not to reorder the categories inplace or return a copy of
this categorical with reordered categories.
inplace : bool, default False
Whether or not to reorder the categories in-place or return a copy
of this categorical with reordered categories.

Returns
-------
cat : Categorical with reordered categories or None if inplace.
Categorical with reordered categories or None if inplace.

Raises
------
Expand Down Expand Up @@ -890,7 +890,7 @@ def rename_categories(self, new_categories, inplace=False):
Currently, Series are considered list like. In a future version
of pandas they'll be considered dict-like.

inplace : boolean (default: False)
inplace : bool, default False
Whether or not to rename the categories inplace or return a copy of
this categorical with renamed categories.

Expand Down Expand Up @@ -967,10 +967,10 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
----------
new_categories : Index-like
The categories in new order.
ordered : boolean, optional
ordered : bool, optional
Whether or not the categorical is treated as a ordered categorical.
If not given, do not change the ordered information.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to reorder the categories inplace or return a copy of
this categorical with reordered categories.

Expand Down Expand Up @@ -1010,7 +1010,7 @@ def add_categories(self, new_categories, inplace=False):
----------
new_categories : category or list-like of category
The new categories to be included.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to add the categories inplace or return a copy of
this categorical with added categories.

Expand Down Expand Up @@ -1060,7 +1060,7 @@ def remove_categories(self, removals, inplace=False):
----------
removals : category or list of categories
The categories which should be removed.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to remove the categories inplace or return a copy of
this categorical with removed categories.

Expand Down Expand Up @@ -1108,7 +1108,7 @@ def remove_unused_categories(self, inplace=False):

Parameters
----------
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to drop unused categories inplace or return a copy of
this categorical with unused categories dropped.

Expand Down Expand Up @@ -1460,7 +1460,7 @@ def value_counts(self, dropna=True):

Parameters
----------
dropna : boolean, default True
dropna : bool, default True
Don't include counts of NaN.

Returns
Expand Down Expand Up @@ -1581,9 +1581,9 @@ def sort_values(self, inplace=False, ascending=True, na_position='last'):

Parameters
----------
inplace : boolean, default False
inplace : bool, default False
Do operation in place.
ascending : boolean, default True
ascending : bool, default True
Order ascending. Passing False orders descending. The
ordering parameter provides the method by which the
category values are organized.
Expand Down Expand Up @@ -2239,7 +2239,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
Expand Down Expand Up @@ -2332,7 +2332,7 @@ def equals(self, other):

Returns
-------
are_equal : boolean
bool
"""
if self.is_dtype_equal(other):
if self.categories.equals(other.categories):
Expand All @@ -2356,7 +2356,7 @@ def is_dtype_equal(self, other):

Returns
-------
are_equal : boolean
bool
"""

try:
Expand Down
64 changes: 30 additions & 34 deletions pandas/core/arrays/datetimes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -799,14 +799,14 @@ def tz_convert(self, tz):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time. Corresponding timestamps would be converted
to this time zone of the Datetime Array/Index. A `tz` of None will
convert to UTC and remove the timezone information.

Returns
-------
normalized : same type as self
Array or Index

Raises
------
Expand Down Expand Up @@ -842,7 +842,7 @@ def tz_convert(self, tz):
With the ``tz=None``, we can remove the timezone (after converting
to UTC if necessary):

>>> dti = pd.date_range(start='2014-08-01 09:00',freq='H',
>>> dti = pd.date_range(start='2014-08-01 09:00', freq='H',
... periods=3, tz='Europe/Berlin')

>>> dti
Expand Down Expand Up @@ -882,7 +882,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone to convert timestamps to. Passing ``None`` will
remove the time zone information preserving local time.
ambiguous : 'infer', 'NaT', bool array, default 'raise'
Expand Down Expand Up @@ -930,7 +930,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',

Returns
-------
result : same type as self
Same type as self
Array/Index converted to the specified time zone.

Raises
Expand Down Expand Up @@ -970,43 +970,39 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',

Be careful with DST changes. When there is sequential data, pandas can
infer the DST time:
>>> s = pd.to_datetime(pd.Series([
... '2018-10-28 01:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 03:00:00',
... '2018-10-28 03:30:00']))
>>> s = pd.to_datetime(pd.Series(['2018-10-28 01:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 03:00:00',
... '2018-10-28 03:30:00']))
>>> s.dt.tz_localize('CET', ambiguous='infer')
2018-10-28 01:30:00+02:00 0
2018-10-28 02:00:00+02:00 1
2018-10-28 02:30:00+02:00 2
2018-10-28 02:00:00+01:00 3
2018-10-28 02:30:00+01:00 4
2018-10-28 03:00:00+01:00 5
2018-10-28 03:30:00+01:00 6
dtype: int64
0 2018-10-28 01:30:00+02:00
1 2018-10-28 02:00:00+02:00
2 2018-10-28 02:30:00+02:00
3 2018-10-28 02:00:00+01:00
4 2018-10-28 02:30:00+01:00
5 2018-10-28 03:00:00+01:00
6 2018-10-28 03:30:00+01:00
dtype: datetime64[ns, CET]

In some cases, inferring the DST is impossible. In such cases, you can
pass an ndarray to the ambiguous parameter to set the DST explicitly

>>> s = pd.to_datetime(pd.Series([
... '2018-10-28 01:20:00',
... '2018-10-28 02:36:00',
... '2018-10-28 03:46:00']))
>>> s = pd.to_datetime(pd.Series(['2018-10-28 01:20:00',
... '2018-10-28 02:36:00',
... '2018-10-28 03:46:00']))
>>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False]))
0 2018-10-28 01:20:00+02:00
1 2018-10-28 02:36:00+02:00
2 2018-10-28 03:46:00+01:00
dtype: datetime64[ns, CET]
0 2015-03-29 03:00:00+02:00
1 2015-03-29 03:30:00+02:00
dtype: datetime64[ns, Europe/Warsaw]

If the DST transition causes nonexistent times, you can shift these
dates forward or backwards with a timedelta object or `'shift_forward'`
or `'shift_backwards'`.
>>> s = pd.to_datetime(pd.Series([
... '2015-03-29 02:30:00',
... '2015-03-29 03:30:00']))
>>> s = pd.to_datetime(pd.Series(['2015-03-29 02:30:00',
... '2015-03-29 03:30:00']))
>>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')
0 2015-03-29 03:00:00+02:00
1 2015-03-29 03:30:00+02:00
Expand Down Expand Up @@ -1129,7 +1125,7 @@ def to_period(self, freq=None):

Parameters
----------
freq : string or Offset, optional
freq : str or Offset, optional
One of pandas' :ref:`offset strings <timeseries.offset_aliases>`
or an Offset object. Will be inferred by default.

Expand All @@ -1150,7 +1146,7 @@ def to_period(self, freq=None):

Examples
--------
>>> df = pd.DataFrame({"y": [1,2,3]},
>>> df = pd.DataFrame({"y": [1, 2, 3]},
... index=pd.to_datetime(["2000-03-31 00:00:00",
... "2000-05-31 00:00:00",
... "2000-08-31 00:00:00"]))
Expand Down
Loading