diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 4962469dbf429..d23e1c912ebf4 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -82,15 +82,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \ pandas.Series.backfill \ pandas.Series.pad \ - pandas.Series.sparse \ pandas.DataFrame.sparse \ - pandas.Series.cat.codes \ - pandas.Series.cat.reorder_categories \ - pandas.Series.cat.set_categories \ - pandas.Series.cat.as_ordered \ - pandas.Series.cat.as_unordered \ - pandas.Series.sparse.fill_value \ - pandas.Flags \ pandas.Series.attrs \ pandas.Series.plot \ pandas.Series.hist \ @@ -242,7 +234,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.IntervalIndex.to_tuples \ pandas.MultiIndex.dtypes \ pandas.MultiIndex.drop \ - pandas.DatetimeIndex.indexer_between_time \ pandas.DatetimeIndex.snap \ pandas.DatetimeIndex.as_unit \ pandas.DatetimeIndex.to_pydatetime \ diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 4cc7236ff1083..97ed64856fe3b 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -875,6 +875,15 @@ def as_ordered(self) -> Self: ------- Categorical Ordered Categorical. + + Examples + -------- + >>> ser = pd.Series(["a", "b", "c", "a"], dtype="category") + >>> ser.cat.ordered + False + >>> ser = ser.cat.as_ordered() + >>> ser.cat.ordered + True """ return self.set_ordered(True) @@ -886,6 +895,15 @@ def as_unordered(self) -> Self: ------- Categorical Unordered Categorical. + + Examples + -------- + >>> raw_cate = pd.Categorical(["a", "b", "c"], + ... categories=["a", "b", "c"], ordered=True) + >>> ser = pd.Series(raw_cate) + >>> ser = ser.cat.as_unordered() + >>> ser.cat.ordered + False """ return self.set_ordered(False) @@ -936,6 +954,26 @@ def set_categories(self, new_categories, ordered=None, rename: bool = False): add_categories : Add new categories. remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. + + Examples + -------- + >>> raw_cate = pd.Categorical(["a", "b", "c", "A"], + ... categories=["a", "b", "c"], ordered=True) + >>> ser = pd.Series(raw_cate) + >>> ser + 0 a + 1 b + 2 c + 3 NaN + dtype: category + Categories (3, object): ['a' < 'b' < 'c'] + >>> ser.cat.set_categories(["A", "B", "C"], rename=True) + 0 A + 1 B + 2 C + 3 NaN + dtype: category + Categories (3, object): ['A' < 'B' < 'C'] """ if ordered is None: @@ -1062,6 +1100,26 @@ def reorder_categories(self, new_categories, ordered=None) -> Self: remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. set_categories : Set the categories to the specified ones. + + Examples + -------- + >>> ser = pd.Series(["a", "b", "c", "a"], dtype="category") + >>> ser = ser.cat.reorder_categories(['c', 'b', 'a'], ordered=True) + >>> ser + 0 a + 1 b + 2 c + 3 a + dtype: category + Categories (3, object): ['c' < 'b' < 'a'] + >>> ser = ser.sort_values() + >>> ser + 2 c + 1 b + 0 a + 3 a + dtype: category + Categories (3, object): ['c' < 'b' < 'a'] """ if ( len(self.categories) != len(new_categories) @@ -2663,6 +2721,17 @@ def _delegate_property_set(self, name: str, new_values): # type: ignore[overrid def codes(self) -> Series: """ Return Series of codes as well as the index. + + Examples + -------- + >>> raw_cate = pd.Categorical(["a", "b", "c", "a"], categories=["a", "b"]) + >>> ser = pd.Series(raw_cate) + >>> ser.cat.codes + 0 0 + 1 1 + 2 -1 + 3 0 + dtype: int8 """ from pandas import Series diff --git a/pandas/core/arrays/sparse/accessor.py b/pandas/core/arrays/sparse/accessor.py index eeff44cfa3c9c..ede58c86aa78d 100644 --- a/pandas/core/arrays/sparse/accessor.py +++ b/pandas/core/arrays/sparse/accessor.py @@ -40,6 +40,14 @@ def _validate(self, data): class SparseAccessor(BaseAccessor, PandasDelegate): """ Accessor for SparseSparse from other sparse matrix data types. + + Examples + -------- + >>> ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]") + >>> ser.sparse.density + 0.6 + >>> ser.sparse.sp_values + array([2, 2, 2]) """ def _validate(self, data): diff --git a/pandas/core/arrays/sparse/array.py b/pandas/core/arrays/sparse/array.py index 4f5505015ef76..16e7835a7183d 100644 --- a/pandas/core/arrays/sparse/array.py +++ b/pandas/core/arrays/sparse/array.py @@ -629,6 +629,16 @@ def fill_value(self): Elements in `data` that are `fill_value` are not stored. For memory savings, this should be the most common value in the array. + + Examples + -------- + >>> ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]") + >>> ser.sparse.fill_value + 0 + >>> spa_dtype = pd.SparseDtype(dtype=np.int32, fill_value=2) + >>> ser = pd.Series([0, 0, 2, 2, 2], dtype=spa_dtype) + >>> ser.sparse.fill_value + 2 """ return self.dtype.fill_value diff --git a/pandas/core/flags.py b/pandas/core/flags.py index c4d92bcb4e994..038132f99c82e 100644 --- a/pandas/core/flags.py +++ b/pandas/core/flags.py @@ -32,9 +32,9 @@ class Flags: it is expected that every method taking or returning one or more DataFrame or Series objects will propagate ``allows_duplicate_labels``. - Notes - ----- - Attributes can be set in two ways + Examples + -------- + Attributes can be set in two ways: >>> df = pd.DataFrame() >>> df.flags diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 85dd0d6165eec..1500bcef5d4d9 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -764,6 +764,16 @@ def indexer_between_time( -------- indexer_at_time : Get index locations of values at particular time of day. DataFrame.between_time : Select values between particular times of day. + + Examples + -------- + >>> idx = pd.date_range("2023-01-01", periods=4, freq="H") + >>> idx + DatetimeIndex(['2023-01-01 00:00:00', '2023-01-01 01:00:00', + '2023-01-01 02:00:00', '2023-01-01 03:00:00'], + dtype='datetime64[ns]', freq='H') + >>> idx.indexer_between_time("00:00", "2:00", include_end=False) + array([0, 1]) """ start_time = to_time(start_time) end_time = to_time(end_time)