Skip to content

Commit c9fa159

Browse files
Charlie-XIAOim-vinicius
Charlie-XIAO
authored and
im-vinicius
committed
DOC: EX01 ({Categorical, Interval, Multi, Datetime, Timedelta}-Index) (pandas-dev#53925)
* add examples for CategoricalIndex.equals * add examples for MultiIndex.dtypes * add examples for MultiIndex.drop * add examples for DatetimeIndex.to_pydatetime/std * add examples for TimedeltaIndex * minor modifications * fix docstrings and make up for removed ones * fix doctests
1 parent eff369d commit c9fa159

File tree

10 files changed

+309
-75
lines changed

10 files changed

+309
-75
lines changed

‎ci/code_checks.sh

-18
Original file line numberDiff line numberDiff line change
@@ -138,25 +138,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
138138
pandas.util.hash_pandas_object \
139139
pandas_object \
140140
pandas.api.interchange.from_dataframe \
141-
pandas.CategoricalIndex.codes \
142-
pandas.CategoricalIndex.categories \
143-
pandas.CategoricalIndex.ordered \
144-
pandas.CategoricalIndex.reorder_categories \
145-
pandas.CategoricalIndex.set_categories \
146-
pandas.CategoricalIndex.as_ordered \
147-
pandas.CategoricalIndex.as_unordered \
148-
pandas.CategoricalIndex.equals \
149-
pandas.IntervalIndex.values \
150-
pandas.IntervalIndex.to_tuples \
151-
pandas.MultiIndex.dtypes \
152-
pandas.MultiIndex.drop \
153141
pandas.DatetimeIndex.snap \
154-
pandas.DatetimeIndex.as_unit \
155-
pandas.DatetimeIndex.to_pydatetime \
156-
pandas.DatetimeIndex.to_series \
157-
pandas.DatetimeIndex.mean \
158-
pandas.DatetimeIndex.std \
159-
pandas.TimedeltaIndex \
160142
pandas.core.window.rolling.Rolling.max \
161143
pandas.core.window.rolling.Rolling.cov \
162144
pandas.core.window.rolling.Rolling.skew \

‎pandas/core/arrays/categorical.py

+112-29
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ class Categorical(NDArrayBackedExtensionArray, PandasObject, ObjectStringArrayMi
272272
Attributes
273273
----------
274274
categories : Index
275-
The categories of this categorical
275+
The categories of this categorical.
276276
codes : ndarray
277277
The codes (integer positions, which point to the categories) of this
278278
categorical, read only.
@@ -760,23 +760,32 @@ def categories(self) -> Index:
760760
761761
Examples
762762
--------
763+
For :class:`pandas.Series`:
763764
764-
For Series:
765-
766-
>>> ser = pd.Series(["a", "b", "c", "a"], dtype="category")
765+
>>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
767766
>>> ser.cat.categories
768767
Index(['a', 'b', 'c'], dtype='object')
769768
770-
>>> raw_cat = pd.Categorical(["a", "b", "c", "a"], categories=["b", "c", "d"],)
769+
>>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], categories=['b', 'c', 'd'])
771770
>>> ser = pd.Series(raw_cat)
772771
>>> ser.cat.categories
773772
Index(['b', 'c', 'd'], dtype='object')
774773
775-
For Categorical:
774+
For :class:`pandas.Categorical`:
776775
777776
>>> cat = pd.Categorical(['a', 'b'], ordered=True)
778777
>>> cat.categories
779778
Index(['a', 'b'], dtype='object')
779+
780+
For :class:`pandas.CategoricalIndex`:
781+
782+
>>> ci = pd.CategoricalIndex(['a', 'c', 'b', 'a', 'c', 'b'])
783+
>>> ci.categories
784+
Index(['a', 'b', 'c'], dtype='object')
785+
786+
>>> ci = pd.CategoricalIndex(['a', 'c'], categories=['c', 'b', 'a'])
787+
>>> ci.categories
788+
Index(['c', 'b', 'a'], dtype='object')
780789
"""
781790
return self.dtype.categories
782791

@@ -787,19 +796,18 @@ def ordered(self) -> Ordered:
787796
788797
Examples
789798
--------
799+
For :class:`pandas.Series`:
790800
791-
For Series:
792-
793-
>>> ser = pd.Series(["a", "b", "c", "a"], dtype="category")
801+
>>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
794802
>>> ser.cat.ordered
795803
False
796804
797-
>>> raw_cat = pd.Categorical(["a", "b", "c", "a"], ordered=True)
805+
>>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], ordered=True)
798806
>>> ser = pd.Series(raw_cat)
799807
>>> ser.cat.ordered
800808
True
801809
802-
For Categorical:
810+
For :class:`pandas.Categorical`:
803811
804812
>>> cat = pd.Categorical(['a', 'b'], ordered=True)
805813
>>> cat.ordered
@@ -808,13 +816,23 @@ def ordered(self) -> Ordered:
808816
>>> cat = pd.Categorical(['a', 'b'], ordered=False)
809817
>>> cat.ordered
810818
False
819+
820+
For :class:`pandas.CategoricalIndex`:
821+
822+
>>> ci = pd.CategoricalIndex(['a', 'b'], ordered=True)
823+
>>> ci.ordered
824+
True
825+
826+
>>> ci = pd.CategoricalIndex(['a', 'b'], ordered=False)
827+
>>> ci.ordered
828+
False
811829
"""
812830
return self.dtype.ordered
813831

814832
@property
815833
def codes(self) -> np.ndarray:
816834
"""
817-
The category codes of this categorical.
835+
The category codes of this categorical index.
818836
819837
Codes are an array of integers which are the positions of the actual
820838
values in the categories array.
@@ -825,13 +843,25 @@ def codes(self) -> np.ndarray:
825843
Returns
826844
-------
827845
ndarray[int]
828-
A non-writable view of the `codes` array.
846+
A non-writable view of the ``codes`` array.
829847
830848
Examples
831849
--------
850+
For :class:`pandas.Categorical`:
851+
832852
>>> cat = pd.Categorical(['a', 'b'], ordered=True)
833853
>>> cat.codes
834854
array([0, 1], dtype=int8)
855+
856+
For :class:`pandas.CategoricalIndex`:
857+
858+
>>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
859+
>>> ci.codes
860+
array([0, 1, 2, 0, 1, 2], dtype=int8)
861+
862+
>>> ci = pd.CategoricalIndex(['a', 'c'], categories=['c', 'b', 'a'])
863+
>>> ci.codes
864+
array([2, 0], dtype=int8)
835865
"""
836866
v = self._codes.view()
837867
v.flags.writeable = False
@@ -915,12 +945,23 @@ def as_ordered(self) -> Self:
915945
916946
Examples
917947
--------
918-
>>> ser = pd.Series(["a", "b", "c", "a"], dtype="category")
948+
For :class:`pandas.Series`:
949+
950+
>>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
919951
>>> ser.cat.ordered
920952
False
921953
>>> ser = ser.cat.as_ordered()
922954
>>> ser.cat.ordered
923955
True
956+
957+
For :class:`pandas.CategoricalIndex`:
958+
959+
>>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'])
960+
>>> ci.ordered
961+
False
962+
>>> ci = ci.as_ordered()
963+
>>> ci.ordered
964+
True
924965
"""
925966
return self.set_ordered(True)
926967

@@ -935,24 +976,36 @@ def as_unordered(self) -> Self:
935976
936977
Examples
937978
--------
938-
>>> raw_cate = pd.Categorical(["a", "b", "c"],
939-
... categories=["a", "b", "c"], ordered=True)
940-
>>> ser = pd.Series(raw_cate)
979+
For :class:`pandas.Series`:
980+
981+
>>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], ordered=True)
982+
>>> ser = pd.Series(raw_cat)
983+
>>> ser.cat.ordered
984+
True
941985
>>> ser = ser.cat.as_unordered()
942986
>>> ser.cat.ordered
943987
False
988+
989+
For :class:`pandas.CategoricalIndex`:
990+
991+
>>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'], ordered=True)
992+
>>> ci.ordered
993+
True
994+
>>> ci = ci.as_unordered()
995+
>>> ci.ordered
996+
False
944997
"""
945998
return self.set_ordered(False)
946999

9471000
def set_categories(self, new_categories, ordered=None, rename: bool = False):
9481001
"""
949-
Set the categories to the specified new_categories.
1002+
Set the categories to the specified new categories.
9501003
951-
`new_categories` can include new categories (which will result in
1004+
``new_categories`` can include new categories (which will result in
9521005
unused categories) or remove old categories (which results in values
953-
set to NaN). If `rename==True`, the categories will simple be renamed
1006+
set to ``NaN``). If ``rename=True``, the categories will simply be renamed
9541007
(less or more items than in old categories will result in values set to
955-
NaN or in unused categories respectively).
1008+
``NaN`` or in unused categories respectively).
9561009
9571010
This method can be used to perform more than one action of adding,
9581011
removing, and reordering simultaneously and is therefore faster than
@@ -994,23 +1047,41 @@ def set_categories(self, new_categories, ordered=None, rename: bool = False):
9941047
9951048
Examples
9961049
--------
997-
>>> raw_cate = pd.Categorical(["a", "b", "c", "A"],
998-
... categories=["a", "b", "c"], ordered=True)
999-
>>> ser = pd.Series(raw_cate)
1050+
For :class:`pandas.Series`:
1051+
1052+
>>> raw_cat = pd.Categorical(['a', 'b', 'c', 'A'],
1053+
... categories=['a', 'b', 'c'], ordered=True)
1054+
>>> ser = pd.Series(raw_cat)
10001055
>>> ser
10011056
0 a
10021057
1 b
10031058
2 c
10041059
3 NaN
10051060
dtype: category
10061061
Categories (3, object): ['a' < 'b' < 'c']
1007-
>>> ser.cat.set_categories(["A", "B", "C"], rename=True)
1062+
1063+
>>> ser.cat.set_categories(['A', 'B', 'C'], rename=True)
10081064
0 A
10091065
1 B
10101066
2 C
10111067
3 NaN
10121068
dtype: category
10131069
Categories (3, object): ['A' < 'B' < 'C']
1070+
1071+
For :class:`pandas.CategoricalIndex`:
1072+
1073+
>>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'A'],
1074+
... categories=['a', 'b', 'c'], ordered=True)
1075+
>>> ci
1076+
CategoricalIndex(['a', 'b', 'c', nan], categories=['a', 'b', 'c'],
1077+
ordered=True, dtype='category')
1078+
1079+
>>> ci.set_categories(['A', 'b', 'c'])
1080+
CategoricalIndex([nan, 'b', 'c', nan], categories=['A', 'b', 'c'],
1081+
ordered=True, dtype='category')
1082+
>>> ci.set_categories(['A', 'b', 'c'], rename=True)
1083+
CategoricalIndex(['A', 'b', 'c', nan], categories=['A', 'b', 'c'],
1084+
ordered=True, dtype='category')
10141085
"""
10151086

10161087
if ordered is None:
@@ -1108,7 +1179,7 @@ def reorder_categories(self, new_categories, ordered=None) -> Self:
11081179
"""
11091180
Reorder categories as specified in new_categories.
11101181
1111-
`new_categories` need to include all old categories and no new category
1182+
``new_categories`` need to include all old categories and no new category
11121183
items.
11131184
11141185
Parameters
@@ -1140,7 +1211,9 @@ def reorder_categories(self, new_categories, ordered=None) -> Self:
11401211
11411212
Examples
11421213
--------
1143-
>>> ser = pd.Series(["a", "b", "c", "a"], dtype="category")
1214+
For :class:`pandas.Series`:
1215+
1216+
>>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
11441217
>>> ser = ser.cat.reorder_categories(['c', 'b', 'a'], ordered=True)
11451218
>>> ser
11461219
0 a
@@ -1149,14 +1222,24 @@ def reorder_categories(self, new_categories, ordered=None) -> Self:
11491222
3 a
11501223
dtype: category
11511224
Categories (3, object): ['c' < 'b' < 'a']
1152-
>>> ser = ser.sort_values()
1153-
>>> ser
1225+
1226+
>>> ser.sort_values()
11541227
2 c
11551228
1 b
11561229
0 a
11571230
3 a
11581231
dtype: category
11591232
Categories (3, object): ['c' < 'b' < 'a']
1233+
1234+
For :class:`pandas.CategoricalIndex`:
1235+
1236+
>>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'])
1237+
>>> ci
1238+
CategoricalIndex(['a', 'b', 'c', 'a'], categories=['a', 'b', 'c'],
1239+
ordered=False, dtype='category')
1240+
>>> ci.reorder_categories(['c', 'b', 'a'], ordered=True)
1241+
CategoricalIndex(['a', 'b', 'c', 'a'], categories=['c', 'b', 'a'],
1242+
ordered=True, dtype='category')
11601243
"""
11611244
if (
11621245
len(self.categories) != len(new_categories)

‎pandas/core/arrays/datetimelike.py

+11
Original file line numberDiff line numberDiff line change
@@ -1552,6 +1552,17 @@ def mean(self, *, skipna: bool = True, axis: AxisInt | None = 0):
15521552
15531553
Examples
15541554
--------
1555+
For :class:`pandas.DatetimeIndex`:
1556+
1557+
>>> idx = pd.date_range('2001-01-01 00:00', periods=3)
1558+
>>> idx
1559+
DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'],
1560+
dtype='datetime64[ns]', freq='D')
1561+
>>> idx.mean()
1562+
Timestamp('2001-01-02 00:00:00')
1563+
1564+
For :class:`pandas.TimedeltaIndex`:
1565+
15551566
>>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='D')
15561567
>>> tdelta_idx
15571568
TimedeltaIndex(['1 days', '2 days', '3 days'],

‎pandas/core/arrays/datetimes.py

+34-9
Original file line numberDiff line numberDiff line change
@@ -1090,11 +1090,19 @@ def tz_localize(
10901090

10911091
def to_pydatetime(self) -> npt.NDArray[np.object_]:
10921092
"""
1093-
Return an ndarray of datetime.datetime objects.
1093+
Return an ndarray of ``datetime.datetime`` objects.
10941094
10951095
Returns
10961096
-------
10971097
numpy.ndarray
1098+
1099+
Examples
1100+
--------
1101+
>>> idx = pd.date_range('2018-02-27', periods=3)
1102+
>>> idx.to_pydatetime()
1103+
array([datetime.datetime(2018, 2, 27, 0, 0),
1104+
datetime.datetime(2018, 2, 28, 0, 0),
1105+
datetime.datetime(2018, 3, 1, 0, 0)], dtype=object)
10981106
"""
10991107
return ints_to_pydatetime(self.asi8, tz=self.tz, reso=self._creso)
11001108

@@ -2097,23 +2105,40 @@ def std(
20972105
"""
20982106
Return sample standard deviation over requested axis.
20992107
2100-
Normalized by N-1 by default. This can be changed using the ddof argument
2108+
Normalized by `N-1` by default. This can be changed using ``ddof``.
21012109
21022110
Parameters
21032111
----------
2104-
axis : int optional, default None
2105-
Axis for the function to be applied on.
2106-
For `Series` this parameter is unused and defaults to `None`.
2112+
axis : int, optional
2113+
Axis for the function to be applied on. For :class:`pandas.Series`
2114+
this parameter is unused and defaults to ``None``.
21072115
ddof : int, default 1
2108-
Degrees of Freedom. The divisor used in calculations is N - ddof,
2109-
where N represents the number of elements.
2116+
Degrees of Freedom. The divisor used in calculations is `N - ddof`,
2117+
where `N` represents the number of elements.
21102118
skipna : bool, default True
2111-
Exclude NA/null values. If an entire row/column is NA, the result will be
2112-
NA.
2119+
Exclude NA/null values. If an entire row/column is ``NA``, the result
2120+
will be ``NA``.
21132121
21142122
Returns
21152123
-------
21162124
Timedelta
2125+
2126+
See Also
2127+
--------
2128+
numpy.ndarray.std : Returns the standard deviation of the array elements
2129+
along given axis.
2130+
Series.std : Return sample standard deviation over requested axis.
2131+
2132+
Examples
2133+
--------
2134+
For :class:`pandas.DatetimeIndex`:
2135+
2136+
>>> idx = pd.date_range('2001-01-01 00:00', periods=3)
2137+
>>> idx
2138+
DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'],
2139+
dtype='datetime64[ns]', freq='D')
2140+
>>> idx.std()
2141+
Timedelta('1 days 00:00:00')
21172142
"""
21182143
# Because std is translation-invariant, we can get self.std
21192144
# by calculating (self - Timestamp(0)).std, and we can do it

0 commit comments

Comments
 (0)