From 500ab71bda109327cf191a11fcf514eaffd70167 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 9 Nov 2017 13:34:08 -0600 Subject: [PATCH 01/30] DOC: Remove numpydoc hack, list methods explicitly --- doc/source/api.rst | 29 ++++++++++++++++++++++++++++ doc/source/conf.py | 1 + doc/sphinxext/numpydoc/numpydoc.py | 7 ------- pandas/core/dtypes/dtypes.py | 5 +++++ pandas/core/indexes/category.py | 19 ++++++++++++++++++ pandas/core/indexes/interval.py | 18 +++++++++++++++++ pandas/core/indexes/period.py | 31 ++++++++++++++++++++++++++++++ pandas/core/indexes/range.py | 4 ++++ 8 files changed, 107 insertions(+), 7 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index b5cf593ac0d1f..7682c25f293d1 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -653,6 +653,12 @@ The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.Ca api.types.CategoricalDtype +.. autosummary:: + :toctree: generated/ + + api.types.CategoricalDtype.categories + api.types.CategoricalDtype.ordered + If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the following usable methods and properties: @@ -692,6 +698,9 @@ adding ordering information or special categories is need at creation time of th .. autosummary:: :toctree: generated/ + Categorical.categories + Categorical.ordered + Categorical.codes Categorical.from_codes ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts @@ -1438,6 +1447,15 @@ Numeric Index UInt64Index Float64Index +.. We need this autosummary so that the methods are generated. +.. Separate block, since they aren't classes. + +.. autosummary:: + :toctree: generated/ + + RangeIndex.from_range + + .. _api.categoricalindex: CategoricalIndex @@ -1466,6 +1484,8 @@ Categorical Components CategoricalIndex.set_categories CategoricalIndex.as_ordered CategoricalIndex.as_unordered + CategoricalIndex.get_loc + CategoricalIndex.map .. _api.intervalindex: @@ -1488,6 +1508,15 @@ IntervalIndex Components IntervalIndex.from_tuples IntervalIndex.from_breaks IntervalIndex.from_intervals + IntervalIndex.contains + IntervalIndex.get_loc + IntervalIndex.left + IntervalIndex.right + IntervalIndex.mid + IntervalIndex.closed + IntervalIndex.values + IntervalIndex.is_non_overlapping_monotonic + .. _api.multiindex: diff --git a/doc/source/conf.py b/doc/source/conf.py index e006f1809da5a..2c35073a60bb3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -68,6 +68,7 @@ ] exclude_patterns = ['**.ipynb_checkpoints'] +numpydoc_show_class_members = False with open("index.rst") as f: index_rst_lines = f.readlines() diff --git a/doc/sphinxext/numpydoc/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py index 09e31f9efd217..2bc2d1e91ed3f 100755 --- a/doc/sphinxext/numpydoc/numpydoc.py +++ b/doc/sphinxext/numpydoc/numpydoc.py @@ -42,13 +42,6 @@ def mangle_docstrings(app, what, name, obj, options, lines, class_members_toctree=app.config.numpydoc_class_members_toctree, ) - # PANDAS HACK (to remove the list of methods/attributes for Categorical) - no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex", - "RangeIndex", "Int64Index", "UInt64Index", - "Float64Index", "PeriodIndex", "CategoricalDtype"] - if what == "class" and any(name.endswith(n) for n in no_autosummary): - cfg['class_members_list'] = False - if what == 'module': # Strip top title title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'), diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index b4467f0f9733b..1cd269c05cf7c 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -120,6 +120,11 @@ class CategoricalDtype(ExtensionDtype): Must be unique, and must not contain any nulls. ordered : bool, default False + Attributes + ---------- + categories + ordered + Notes ----- This class is useful for specifying the type of a ``Categorical`` diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 70b531ffb0ec4..e1c8b9523839a 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -49,6 +49,25 @@ class CategoricalIndex(Index, accessor.PandasDelegate): See Also -------- Categorical, Index + + Methods + ------- + rename_categories + reorder_categories + add_categories + remove_categories + remove_unused_categories + set_categories + as_ordered + as_unordered + get_loc + map + + Attributes + ---------- + codes + categories + ordered """ _typ = 'categoricalindex' diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index 7bf7cfce515a1..afd6bf4e11cc9 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -154,6 +154,24 @@ class IntervalIndex(IntervalMixin, Index): IntervalIndex.from_intervals, IntervalIndex.from_tuples cut, qcut : convert arrays of continuous data into categoricals/series of ``Interval``. + + Methods + ------- + from_arrays + from_tuples + from_breaks + from_intervals + contains + get_loc + + Attributes + ---------- + left + right + mid + closed + values + is_non_overlapping_monotonic """ _typ = 'intervalindex' _comparables = ['name'] diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py index a6d5690767c10..bd410126b2fa8 100644 --- a/pandas/core/indexes/period.py +++ b/pandas/core/indexes/period.py @@ -160,6 +160,37 @@ class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index): Timezone for converting datetime64 data to Periods dtype : str or PeriodDtype, default None + Attributes + ---------- + day + dayofweek + dayofyear + days_in_month + daysinmonth + end_time + freq + freqstr + hour + is_leap_year + minute + month + quarter + qyear + second + start_time + week + weekday + weekofyear + year + + Methods + ------- + asfreq + strftime + to_timestamp + tz_convert + tz_localize + Examples -------- >>> idx = PeriodIndex(year=year_arr, quarter=q_arr) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 9cb01896424f7..c8f1c26f532a7 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -48,6 +48,10 @@ class RangeIndex(Int64Index): -------- Index : The base pandas Index type Int64Index : Index of int64 data + + Methods + ------- + from_range """ _typ = 'rangeindex' From 257fc8a0af7de854d0f5e2f0bbc9380320760c69 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 9 Nov 2017 14:28:00 -0600 Subject: [PATCH 02/30] [WIP]: API doc --- doc/source/api.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 7682c25f293d1..0c36cc412f2bb 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -701,6 +701,7 @@ adding ordering information or special categories is need at creation time of th Categorical.categories Categorical.ordered Categorical.codes + Categorical.dtype Categorical.from_codes ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts @@ -801,11 +802,14 @@ Attributes and underlying data DataFrame.get_ftype_counts DataFrame.select_dtypes DataFrame.values + DataFrame.get_values DataFrame.axes DataFrame.ndim DataFrame.size DataFrame.shape DataFrame.memory_usage + DataFrame.empty + DataFrame.is_copy Conversion ~~~~~~~~~~ @@ -818,6 +822,7 @@ Conversion DataFrame.copy DataFrame.isna DataFrame.notna + DataFrame.bool Indexing, iteration ~~~~~~~~~~~~~~~~~~~ @@ -830,7 +835,10 @@ Indexing, iteration DataFrame.loc DataFrame.iloc DataFrame.insert + DataFrame.insert DataFrame.__iter__ + DataFrame.items + DataFrame.keys DataFrame.iteritems DataFrame.iterrows DataFrame.itertuples @@ -838,6 +846,7 @@ Indexing, iteration DataFrame.pop DataFrame.tail DataFrame.xs + DataFrame.get DataFrame.isin DataFrame.where DataFrame.mask @@ -854,12 +863,16 @@ Binary operator functions DataFrame.add DataFrame.sub + DataFrame.subtract DataFrame.mul + DataFrame.multiply DataFrame.div + DataFrame.divide DataFrame.truediv DataFrame.floordiv DataFrame.mod DataFrame.pow + DataFrame.dot DataFrame.radd DataFrame.rsub DataFrame.rmul @@ -884,6 +897,8 @@ Function application, GroupBy & Window DataFrame.apply DataFrame.applymap + DataFrame.pipe + DataFrame.agg DataFrame.aggregate DataFrame.transform DataFrame.groupby @@ -904,6 +919,7 @@ Computations / Descriptive Stats DataFrame.clip DataFrame.clip_lower DataFrame.clip_upper + DataFrame.compound DataFrame.corr DataFrame.corrwith DataFrame.count @@ -916,6 +932,7 @@ Computations / Descriptive Stats DataFrame.diff DataFrame.eval DataFrame.kurt + DataFrame.kurtosis DataFrame.mad DataFrame.max DataFrame.mean @@ -924,6 +941,7 @@ Computations / Descriptive Stats DataFrame.mode DataFrame.pct_change DataFrame.prod + DataFrame.product DataFrame.quantile DataFrame.rank DataFrame.round @@ -932,6 +950,7 @@ Computations / Descriptive Stats DataFrame.sum DataFrame.std DataFrame.var + DataFrame.nunique Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -941,6 +960,8 @@ Reindexing / Selection / Label manipulation DataFrame.add_prefix DataFrame.add_suffix DataFrame.align + DataFrame.at_time + DataFrame.between_time DataFrame.drop DataFrame.drop_duplicates DataFrame.duplicated @@ -959,6 +980,7 @@ Reindexing / Selection / Label manipulation DataFrame.reset_index DataFrame.sample DataFrame.select + DataFrame.set_axis DataFrame.set_index DataFrame.tail DataFrame.take @@ -974,6 +996,9 @@ Missing data handling DataFrame.dropna DataFrame.fillna DataFrame.replace + DataFrame.interpolate + DataFrame.isnull + DataFrame.notnull Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -981,6 +1006,7 @@ Reshaping, sorting, transposing :toctree: generated/ DataFrame.pivot + DataFrame.pivot_table DataFrame.reorder_levels DataFrame.sort_values DataFrame.sort_index @@ -989,10 +1015,12 @@ Reshaping, sorting, transposing DataFrame.swaplevel DataFrame.stack DataFrame.unstack + DataFrame.swapaxes DataFrame.melt - DataFrame.T + DataFrame.squeeze DataFrame.to_panel DataFrame.to_xarray + DataFrame.T DataFrame.transpose Combining / joining / merging @@ -1014,6 +1042,8 @@ Time series-related DataFrame.asfreq DataFrame.asof DataFrame.shift + DataFrame.slice_shift + DataFrame.tshift DataFrame.first_valid_index DataFrame.last_valid_index DataFrame.resample @@ -1068,6 +1098,7 @@ Serialization / IO / Conversion DataFrame.from_items DataFrame.from_records DataFrame.info + DataFrame.to_parquet DataFrame.to_pickle DataFrame.to_csv DataFrame.to_hdf @@ -1086,6 +1117,7 @@ Serialization / IO / Conversion DataFrame.to_dense DataFrame.to_string DataFrame.to_clipboard + DataFrame.style Sparse ~~~~~~ @@ -2313,3 +2345,26 @@ Scalar introspection api.types.is_re api.types.is_re_compilable api.types.is_scalar + + +.. This is to prevent warnings in the doc build. We don't want to encourage +.. these methods. + +.. toctree:: + :hidden: + + generated/pandas.DataFrame.as_blocks + generated/pandas.DataFrame.ffill + generated/pandas.DataFrame.bfill + generated/pandas.DataFrame.blocks + generated/pandas.DataFrame.sortlevel + generated/pandas.DataFrame.consolidate + generated/pandas.DataFrame.set_value + generated/pandas.DataFrame.get_value + + generated/pandas.Series.as_blocks + generated/pandas.Series.ffill + generated/pandas.Series.bfill + generated/pandas.Series.set_value + generated/pandas.Series.get_value + generated/pandas.Series.blocks From d59c0b574202aa0ba07d8caa78a8e4bf3a79909d Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Fri, 10 Nov 2017 07:45:28 -0600 Subject: [PATCH 03/30] More explicit methods --- doc/source/api.rst | 21 ++++++++++++-- pandas/core/indexes/datetimes.py | 48 +++++++++++++++++++++++++++++++ pandas/core/indexes/multi.py | 15 ++++++++++ pandas/core/indexes/timedeltas.py | 18 ++++++++++++ 4 files changed, 100 insertions(+), 2 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 0c36cc412f2bb..578318b580f65 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -1557,12 +1557,17 @@ MultiIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst MultiIndex + +.. autosummary:: + :toctree: generated/ + IndexSlice -MultiIndex Components -~~~~~~~~~~~~~~~~~~~~~~ +MultiIndex Constructors +~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ @@ -1570,6 +1575,13 @@ MultiIndex Components MultiIndex.from_arrays MultiIndex.from_tuples MultiIndex.from_product + +MultiIndex Components +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + MultiIndex.set_levels MultiIndex.set_labels MultiIndex.to_hierarchical @@ -1587,6 +1599,7 @@ DatetimeIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst DatetimeIndex @@ -1665,6 +1678,7 @@ TimedeltaIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst TimedeltaIndex @@ -2196,6 +2210,7 @@ Constructor :toctree: generated/ Styler + Styler.from_custom_template Style Application ~~~~~~~~~~~~~~~~~ @@ -2208,6 +2223,7 @@ Style Application Styler.format Styler.set_precision Styler.set_table_styles + Styler.set_table_attributes Styler.set_caption Styler.set_properties Styler.set_uuid @@ -2234,6 +2250,7 @@ Style Export and Import Styler.render Styler.export Styler.use + Styler.to_excel .. currentmodule:: pandas diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 78869de318dce..c944dbddf63fa 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -214,6 +214,54 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin, Index : The base pandas Index type TimedeltaIndex : Index of timedelta64 data PeriodIndex : Index of Period data + + Methods + ------- + normalize + strftime + snap + tz_convert + tz_localize + round + floor + ceil + to_datetime + to_period + to_perioddelta + to_pydatetime + to_series + to_frame + + Attributes + ---------- + year + month + day + hour + minute + second + microsecond + nanosecond + date + time + dayofyear + weekofyear + week + dayofweek + weekday + weekday_name + quarter + tz + freq + freqstr + is_month_start + is_month_end + is_quarter_start + is_quarter_end + is_year_start + is_year_end + is_leap_year + inferred_freq """ _typ = 'datetimeindex' diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 4cc59f5297058..32b160aba02b8 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -97,6 +97,21 @@ class MultiIndex(Index): of iterables MultiIndex.from_tuples : Convert list of tuples to a MultiIndex Index : The base pandas Index type + + Methods + ------- + from_arrays + from_tuples + from_product + set_levels + set_labels + to_hierarchical + to_frame + is_lexsorted + droplevel + swaplevel + reorder_levels + remove_unused_levels """ # initialize to zero-length tuples to make everything work diff --git a/pandas/core/indexes/timedeltas.py b/pandas/core/indexes/timedeltas.py index a4a5f7df9aa0f..6176521dc014b 100644 --- a/pandas/core/indexes/timedeltas.py +++ b/pandas/core/indexes/timedeltas.py @@ -142,6 +142,24 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, TimelikeOps, Int64Index): Timedelta : Represents a duration between two dates or times. DatetimeIndex : Index of datetime64 data PeriodIndex : Index of Period data + + Attributes + ---------- + days + seconds + microseconds + nanoseconds + components + inferred_freq + + Methods + ------- + to_pytimedelta + to_series + round + floor + ceil + to_frame """ _typ = 'timedeltaindex' From cb57504b6b8d5059f386131137e8ebfd19fecaa8 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Fri, 10 Nov 2017 10:20:57 -0600 Subject: [PATCH 04/30] More updates --- doc/source/api.rst | 76 +++++++++++++++++++++++++++++++++--- pandas/core/indexes/multi.py | 11 ++++++ 2 files changed, 82 insertions(+), 5 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 578318b580f65..ab20484cfa6f0 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -635,10 +635,6 @@ strings and apply several methods to it. These can be accessed like Series.cat Series.dt Index.str - MultiIndex.str - DatetimeIndex.str - TimedeltaIndex.str - .. _api.categorical: @@ -1321,7 +1317,7 @@ Time series-related Serialization / IO / Conversion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. autosummary:: +.. /eautosummary:: :toctree: generated/ Panel.from_dict @@ -1359,10 +1355,14 @@ Attributes Index.is_monotonic_decreasing Index.is_unique Index.has_duplicates + Index.has_nans Index.dtype + Index.dtype_str Index.inferred_type Index.is_all_dates Index.shape + Index.name + Index.names Index.nbytes Index.ndim Index.size @@ -1389,11 +1389,26 @@ Modifying and Computations Index.duplicated Index.equals Index.factorize + Index.format + Index.groupby + Index.holds_integer Index.identical Index.insert + Index.is_ + Index.is_boolean + Index.is_categorical + Index.is_floating + Index.is_integer + Index.is_interval + Index.is_lexsorted_for_tuple + Index.is_mixed + Index.is_numeric + Index.is_object + Index.is_type_compatible Index.min Index.max Index.reindex + Index.rename Index.repeat Index.where Index.take @@ -1402,6 +1417,8 @@ Modifying and Computations Index.unique Index.nunique Index.value_counts + Index.T + Index.transpose Missing Values ~~~~~~~~~~~~~~ @@ -1419,8 +1436,12 @@ Conversion :toctree: generated/ Index.astype + Index.item + Index.map + Index.ravel Index.tolist Index.to_datetime + Index.to_native_types Index.to_series Index.to_frame @@ -1430,6 +1451,7 @@ Sorting :toctree: generated/ Index.argsort + Index.searchsorted Index.sort_values Time-specific operations @@ -1456,11 +1478,18 @@ Selecting .. autosummary:: :toctree: generated/ + Index.asof + Index.asof_locs + Index.contains + Index.get_duplicates Index.get_indexer + Index.get_indexer_for Index.get_indexer_non_unique Index.get_level_values Index.get_loc + Index.get_slice_bound Index.get_value + Index.get_values Index.isin Index.slice_indexer Index.slice_locs @@ -1576,6 +1605,18 @@ MultiIndex Constructors MultiIndex.from_tuples MultiIndex.from_product +MultiIndex Attributes +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MultiIndex.names + MultiIndex.levels + MultiIndex.labels + MultiIndex.nlevels + MultiIndex.levshape + MultiIndex Components ~~~~~~~~~~~~~~~~~~~~~ @@ -1587,6 +1628,7 @@ MultiIndex Components MultiIndex.to_hierarchical MultiIndex.to_frame MultiIndex.is_lexsorted + MultiIndex.sortlevel MultiIndex.droplevel MultiIndex.swaplevel MultiIndex.reorder_levels @@ -1820,6 +1862,7 @@ Properties Timestamp.dayofyear Timestamp.days_in_month Timestamp.daysinmonth + Timestamp.fold Timestamp.hour Timestamp.is_leap_year Timestamp.is_month_end @@ -1831,6 +1874,7 @@ Properties Timestamp.max Timestamp.microsecond Timestamp.min + Timestamp.minute Timestamp.month Timestamp.nanosecond Timestamp.quarter @@ -1839,6 +1883,7 @@ Properties Timestamp.tz Timestamp.tzinfo Timestamp.value + Timestamp.week Timestamp.weekday_name Timestamp.weekofyear Timestamp.year @@ -1923,7 +1968,9 @@ Properties Timedelta.asm8 Timedelta.components Timedelta.days + Timedelta.delta Timedelta.freq + Timedetla.is_populated Timedelta.max Timedelta.microseconds Timedelta.min @@ -1931,6 +1978,7 @@ Properties Timedelta.resolution Timedelta.seconds Timedelta.value + Timedelta.view Methods ~~~~~~~ @@ -2037,6 +2085,7 @@ Indexing, iteration .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst Grouper @@ -2370,6 +2419,8 @@ Scalar introspection .. toctree:: :hidden: + generated/pandas.DataFrame.index + generated/pandas.DataFrame.columns generated/pandas.DataFrame.as_blocks generated/pandas.DataFrame.ffill generated/pandas.DataFrame.bfill @@ -2378,10 +2429,25 @@ Scalar introspection generated/pandas.DataFrame.consolidate generated/pandas.DataFrame.set_value generated/pandas.DataFrame.get_value + generated/pandas.DataFrame.ix + generated/pandas.Series.index generated/pandas.Series.as_blocks generated/pandas.Series.ffill generated/pandas.Series.bfill generated/pandas.Series.set_value generated/pandas.Series.get_value generated/pandas.Series.blocks + generated/pandas.Series.ix + + generated/pandas.Index.flags + generated/pandas.Index.isnull + generated/pandas.Index.notnull + generated/pandas.Index.names + generated/pandas.Index.nlevels + generated/pandas.Index.reshape + generated/pandas.Index.sortlevel + generated/pandas.Index.sort + + generated/pandas.Timestamp.offset + generated/pandas.Timestamp.to_datetime \ No newline at end of file diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 32b160aba02b8..2aac74b3d695b 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -98,6 +98,14 @@ class MultiIndex(Index): MultiIndex.from_tuples : Convert list of tuples to a MultiIndex Index : The base pandas Index type + Attributes + ---------- + names + levels + labels + nlevels + levshape + Methods ------- from_arrays @@ -108,6 +116,7 @@ class MultiIndex(Index): to_hierarchical to_frame is_lexsorted + sortlevel droplevel swaplevel reorder_levels @@ -1379,10 +1388,12 @@ def remove_unused_levels(self): @property def nlevels(self): + """Integer number of levels in this MultiIndex.""" return len(self.levels) @property def levshape(self): + """A tuple with the length of each level.""" return tuple(len(x) for x in self.levels) @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs) From 5e4cf6d5803224c430dc5ffc456e2fe27cf4fd69 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Fri, 10 Nov 2017 10:50:10 -0600 Subject: [PATCH 05/30] typos --- doc/source/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index ab20484cfa6f0..b3a6ef19f691c 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -1355,7 +1355,7 @@ Attributes Index.is_monotonic_decreasing Index.is_unique Index.has_duplicates - Index.has_nans + Index.hasnans Index.dtype Index.dtype_str Index.inferred_type @@ -1970,7 +1970,7 @@ Properties Timedelta.days Timedelta.delta Timedelta.freq - Timedetla.is_populated + Timedelta.is_populated Timedelta.max Timedelta.microseconds Timedelta.min From b5902ff34a7a3071951564c869e3a8fd678a25a4 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 07:11:07 -0600 Subject: [PATCH 06/30] more --- doc/source/api.rst | 175 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 154 insertions(+), 21 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index b3a6ef19f691c..cc97415ab227c 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -278,9 +278,25 @@ Attributes Series.size Series.strides Series.itemsize + Series.axes Series.base Series.T Series.memory_usage + Series.hasnans + Series.flags + Series.empty + Series.dtypes + Series.ftypes + Series.as_matrix + Series.data + Series.get_dtype_counts + Series.get_ftype_counts + Series.get_values + Series.is_copy + Series.imag + Series.real + Series.name + Series.put Conversion ~~~~~~~~~~ @@ -289,9 +305,15 @@ Conversion Series.astype Series.infer_objects + Series.convert_objects Series.copy Series.isna Series.notna + Series.bool + Series.to_period + Series.to_timestamp + Series.tolist + Indexing, iteration ~~~~~~~~~~~~~~~~~~~ @@ -305,6 +327,12 @@ Indexing, iteration Series.iloc Series.__iter__ Series.iteritems + Series.items + Series.keys + Series.pop + Series.compress + Series.item + Series.xs For more information on ``.at``, ``.iat``, ``.loc``, and ``.iloc``, see the :ref:`indexing documentation `. @@ -316,6 +344,7 @@ Binary operator functions Series.add Series.sub + Series.subtract Series.mul Series.div Series.truediv @@ -339,6 +368,9 @@ Binary operator functions Series.ge Series.ne Series.eq + Series.divide + Series.product + Series.dot Function application, GroupBy & Window ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -346,6 +378,7 @@ Function application, GroupBy & Window :toctree: generated/ Series.apply + Series.agg Series.aggregate Series.transform Series.map @@ -353,6 +386,7 @@ Function application, GroupBy & Window Series.rolling Series.expanding Series.ewm + Series.pipe .. _api.series.stats: @@ -404,6 +438,12 @@ Computations / Descriptive Stats Series.is_monotonic_increasing Series.is_monotonic_decreasing Series.value_counts + Series.compound + Series.nonzero + Series.ptp + Series.kurtosis + Series.multiply + Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -434,6 +474,9 @@ Reindexing / Selection / Label manipulation Series.truncate Series.where Series.mask + Series.add_prefix + Series.add_suffix + Series.filter Missing data handling ~~~~~~~~~~~~~~~~~~~~~ @@ -443,6 +486,7 @@ Missing data handling Series.dropna Series.fillna Series.interpolate + Series.valid Reshaping, sorting ~~~~~~~~~~~~~~~~~~ @@ -450,12 +494,24 @@ Reshaping, sorting :toctree: generated/ Series.argsort + Series.argmin + Series.argmax Series.reorder_levels Series.sort_values Series.sort_index Series.swaplevel Series.unstack Series.searchsorted + Series.ravel + Series.reindex_axis + Series.repeat + Series.reshape + Series.squeeze + Series.view + Series.sortlevel + Series.swapaxes + Series.transpose + Combining / joining / merging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -479,6 +535,10 @@ Time series-related Series.resample Series.tz_convert Series.tz_localize + Series.at_time + Series.between_time + Series.tshift + Series.slice_shift Datetimelike Properties ~~~~~~~~~~~~~~~~~~~~~~~ @@ -745,6 +805,7 @@ Serialization / IO / Conversion :toctree: generated/ Series.from_csv + Series.from_array Series.to_pickle Series.to_csv Series.to_dict @@ -1133,6 +1194,7 @@ Constructor :toctree: generated/ Panel + Panel.from_dict Attributes and underlying data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1154,6 +1216,8 @@ Attributes and underlying data Panel.ftypes Panel.get_dtype_counts Panel.get_ftype_counts + Panel.empty + Panel.is_copy Conversion ~~~~~~~~~~ @@ -1164,6 +1228,9 @@ Conversion Panel.copy Panel.isna Panel.notna + Panel.as_matrix + Panel.convert_objects + Panel.infer_objects Getting and setting ~~~~~~~~~~~~~~~~~~~ @@ -1172,6 +1239,8 @@ Getting and setting Panel.get_value Panel.set_value + Panel.get + Panel.get_values Indexing, iteration, slicing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1188,6 +1257,11 @@ Indexing, iteration, slicing Panel.xs Panel.major_xs Panel.minor_xs + Panel.keys + Panel.major_axis + Panel.items + Panel.minor_axis + Panel.slice_shift For more information on ``.at``, ``.iat``, ``.loc``, and ``.iloc``, see the :ref:`indexing documentation `. @@ -1227,6 +1301,7 @@ Function application, GroupBy Panel.apply Panel.groupby + Panel.pipe .. _api.panel.stats: @@ -1255,6 +1330,27 @@ Computations / Descriptive Stats Panel.sum Panel.std Panel.var + Panel.agg + Panel.aggregate + Panel.all + Panel.any + Panel.bool + Panel.divide + Panel.kurt + Panel.kurtosis + Panel.mad + Panel.product + Panel.rank + Panel.head + Panel.tail + Panel.where + Panel.mask + Panel.compound + Panel.describe + Panel.multiply + Panel.subtract + Panel.round + Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1276,6 +1372,13 @@ Reindexing / Selection / Label manipulation Panel.select Panel.take Panel.truncate + Panel.align + Panel.at_time + Panel.asof + Panel.between_time + Panel.rename_axis + Panel.set_axis + Missing data handling ~~~~~~~~~~~~~~~~~~~~~ @@ -1284,6 +1387,10 @@ Missing data handling Panel.dropna Panel.fillna + Panel.ffill + Panel.bfill + Panel.interpolate + Panel.replace Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1295,6 +1402,8 @@ Reshaping, sorting, transposing Panel.transpose Panel.swapaxes Panel.conform + Panel.sort_values + Panel.squeeze Combining / joining / merging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1312,22 +1421,31 @@ Time series-related Panel.asfreq Panel.shift Panel.resample + Panel.tshift Panel.tz_convert Panel.tz_localize Serialization / IO / Conversion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. /eautosummary:: +.. autosummary:: :toctree: generated/ Panel.from_dict - Panel.to_pickle + Panel.toLong + Panel.to_clipboard + Panel.to_dense Panel.to_excel + Panel.to_frame Panel.to_hdf + Panel.to_json + Panel.to_latex + Panel.to_long + Panel.to_msgpack + Panel.to_pickle Panel.to_sparse - Panel.to_frame + Panel.to_sql Panel.to_xarray - Panel.to_clipboard + .. _api.index: @@ -1417,6 +1535,7 @@ Modifying and Computations Index.unique Index.nunique Index.value_counts + Index.summary Index.T Index.transpose @@ -1444,6 +1563,7 @@ Conversion Index.to_native_types Index.to_series Index.to_frame + Index.view Sorting ~~~~~~~ @@ -1490,6 +1610,7 @@ Selecting Index.get_slice_bound Index.get_value Index.get_values + Index.set_value Index.isin Index.slice_indexer Index.slice_locs @@ -2419,35 +2540,47 @@ Scalar introspection .. toctree:: :hidden: - generated/pandas.DataFrame.index - generated/pandas.DataFrame.columns generated/pandas.DataFrame.as_blocks - generated/pandas.DataFrame.ffill generated/pandas.DataFrame.bfill generated/pandas.DataFrame.blocks - generated/pandas.DataFrame.sortlevel + generated/pandas.DataFrame.columns generated/pandas.DataFrame.consolidate - generated/pandas.DataFrame.set_value + generated/pandas.DataFrame.ffill generated/pandas.DataFrame.get_value + generated/pandas.DataFrame.index generated/pandas.DataFrame.ix + generated/pandas.DataFrame.set_value + generated/pandas.DataFrame.sortlevel - generated/pandas.Series.index - generated/pandas.Series.as_blocks - generated/pandas.Series.ffill - generated/pandas.Series.bfill - generated/pandas.Series.set_value - generated/pandas.Series.get_value - generated/pandas.Series.blocks - generated/pandas.Series.ix - + generated/pandas.Index.data.rst generated/pandas.Index.flags generated/pandas.Index.isnull - generated/pandas.Index.notnull generated/pandas.Index.names generated/pandas.Index.nlevels + generated/pandas.Index.notnull generated/pandas.Index.reshape - generated/pandas.Index.sortlevel generated/pandas.Index.sort + generated/pandas.Index.sortlevel + + generated/pandas.Panel.as_blocks.rst + generated/pandas.Panel.blocks.rst + generated/pandas.Panel.consolidate.rst + generated/pandas.Panel.fromDict.rst + generated/pandas.Panel.isnull.rst + generated/pandas.Panel.ix.rst + generated/pandas.Panel.notnull.rst + generated/pandas.Series.as_blocks + generated/pandas.Series.asobject.rst + generated/pandas.Series.bfill + generated/pandas.Series.blocks + generated/pandas.Series.consolidate.rst + generated/pandas.Series.ffill + generated/pandas.Series.get_value + generated/pandas.Series.index + generated/pandas.Series.isnull.rst + generated/pandas.Series.ix + generated/pandas.Series.notnull.rst + generated/pandas.Series.set_value generated/pandas.Timestamp.offset - generated/pandas.Timestamp.to_datetime \ No newline at end of file + generated/pandas.Timestamp.to_datetime From 874aefe8eab257a60089d7e2bde5161c95687c86 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 10:18:14 -0600 Subject: [PATCH 07/30] Add accessors to hidden --- doc/source/api.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/source/api.rst b/doc/source/api.rst index 2ad98a205c45f..d8e5541f0b710 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2606,6 +2606,8 @@ Scalar introspection generated/pandas.Index.sort generated/pandas.Index.sortlevel + generated/pandas.Index.str + generated/pandas.Panel.as_blocks.rst generated/pandas.Panel.blocks.rst generated/pandas.Panel.consolidate.rst @@ -2626,5 +2628,9 @@ Scalar introspection generated/pandas.Series.notnull.rst generated/pandas.Series.set_value + generated/pandas.Series.cat + generated/pandas.Series.dt + generated/pandas.Series.str + generated/pandas.Timestamp.offset generated/pandas.Timestamp.to_datetime From 32c2816cf3b859111c75951b2640da0d427a7d8f Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 14:45:31 -0600 Subject: [PATCH 08/30] Remove dupe section --- pandas/core/indexes/interval.py | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index afd6bf4e11cc9..a22b8aa8ca405 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -121,6 +121,9 @@ class IntervalIndex(IntervalMixin, Index): Name to be stored in the index. copy : boolean, default False Copy the meta-data + mid + values + is_non_overlapping_monotonic Examples --------- @@ -164,14 +167,6 @@ class IntervalIndex(IntervalMixin, Index): contains get_loc - Attributes - ---------- - left - right - mid - closed - values - is_non_overlapping_monotonic """ _typ = 'intervalindex' _comparables = ['name'] From 38673bdd8a7cce10640fe04d8dbe49b02ed9ae8f Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 14:45:44 -0600 Subject: [PATCH 09/30] Added Categorical --- doc/source/api.rst | 59 ++++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index d8e5541f0b710..3f84bcbed5f91 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -701,7 +701,9 @@ strings and apply several methods to it. These can be accessed like Categorical ~~~~~~~~~~~ -The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.CategoricalDtype`. +Pandas defines a custom data type for representing data that can take only a +limited, fixed set of values. The dtype of a ``Categorical`` can be described by +a :class:`pandas.api.types.CategoricalDtype`. .. autosummary:: :toctree: generated/ @@ -715,6 +717,31 @@ The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.Ca api.types.CategoricalDtype.categories api.types.CategoricalDtype.ordered +Categorical data can be stored in a :class:``pandas.Categorical`` + +.. autosummary:: + :toctree: generated/ + + Categorical + +The following two ``Categorical`` constructors are considered API but should only be used when +adding ordering information or special categories is need at creation time of the categorical data: + +.. autosummary:: + :toctree: generated/ + + Categorical.categories + Categorical.from_codes + +``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts +the Categorical back to a numpy array, so categories and order information is not preserved! + +.. autosummary:: + :toctree: generated/ + + Categorical.__array__ + +A ``Categorical`` can be stored in a ``Series`` or ``DataFrame``. If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the following usable methods and properties: @@ -740,33 +767,9 @@ following usable methods and properties: Series.cat.as_ordered Series.cat.as_unordered -To create a Series of dtype ``category``, use ``cat = s.astype("category")``. - -The following two ``Categorical`` constructors are considered API but should only be used when -adding ordering information or special categories is need at creation time of the categorical data: - -.. autosummary:: - :toctree: generated/ - :template: autosummary/class_without_autosummary.rst - - Categorical - -.. autosummary:: - :toctree: generated/ - - Categorical.categories - Categorical.ordered - Categorical.codes - Categorical.dtype - Categorical.from_codes - -``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts -the Categorical back to a numpy array, so categories and order information is not preserved! - -.. autosummary:: - :toctree: generated/ - - Categorical.__array__ +To create a Series of dtype ``category``, use ``cat = s.astype("category")`` or +``s.astype(categorical_dtype)`` where ``categorical_dtype`` is an instance of +:class:`~pandas.api.types.CategoricalDtype`. Plotting ~~~~~~~~ From e30335e5014b4be53993cc34fb0f75953f103799 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 20:28:29 -0600 Subject: [PATCH 10/30] More fixups --- doc/source/api.rst | 65 +++++++++++++++++----------------- doc/source/conf.py | 3 +- pandas/core/dtypes/dtypes.py | 4 +++ pandas/core/indexes/numeric.py | 11 ++++++ pandas/core/reshape/reshape.py | 1 + pandas/io/formats/style.py | 5 ++- pandas/plotting/_core.py | 46 ++++++++++++------------ 7 files changed, 75 insertions(+), 60 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 3f84bcbed5f91..664aac300d735 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -733,6 +733,16 @@ adding ordering information or special categories is need at creation time of th Categorical.categories Categorical.from_codes +The dtype information is available on the ``Categorical`` + +.. autosummary:: + :toctree: generated/ + + Categorical.dtype + Categorical.categories + Categorical.ordered + Categorical.codes + ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts the Categorical back to a numpy array, so categories and order information is not preserved! @@ -2124,41 +2134,13 @@ Frequencies .. currentmodule:: pandas.tseries.frequencies - -.. autosummary:: - :toctree: generated/ - - to_offset - .. _api.offsets: -Offsets -------- - -.. currentmodule:: pandas.tseries.offsets - .. autosummary:: :toctree: generated/ - DateOffset - Week - Day - Hour - Minute - Second - Milli - Micro - Nano - -.. autosummary:: - :toctree: generated/ + to_offset - MonthBegin - MonthEnd - QuarterBegin - QuarterEnd - YearBegin - YearEnd Window ------ @@ -2420,15 +2402,24 @@ Style ``Styler`` objects are returned by :attr:`pandas.DataFrame.style`. - -Constructor -~~~~~~~~~~~ +Styler Constructor +~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ Styler Styler.from_custom_template + +Styler Attributes +~~~~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: generated/ + + Styler.env + Styler.template + Styler.loader + Style Application ~~~~~~~~~~~~~~~~~ .. autosummary:: @@ -2600,6 +2591,7 @@ Scalar introspection generated/pandas.DataFrame.sortlevel generated/pandas.Index.data.rst + generated/pandas.Index.asi8.rst generated/pandas.Index.flags generated/pandas.Index.isnull generated/pandas.Index.names @@ -2637,3 +2629,12 @@ Scalar introspection generated/pandas.Timestamp.offset generated/pandas.Timestamp.to_datetime + + generated/pandas.Categorical.base.rst + generated/pandas.Categorical.itemsize.rst + generated/pandas.Categorical.labels.rst + generated/pandas.Categorical.nbytes.rst + generated/pandas.Categorical.ndim.rst + generated/pandas.Categorical.shape.rst + generated/pandas.Categorical.size.rst + generated/pandas.Categorical.T.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 53c255af0d34e..3ac41b0e7e0c9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -55,7 +55,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'sphinx.ext.todo', - 'numpydoc', # used to parse numpy-style docstrings for autodoc + 'numpydoc', 'IPython.sphinxext.ipython_directive', 'IPython.sphinxext.ipython_console_highlighting', 'sphinx.ext.intersphinx', @@ -67,7 +67,6 @@ ] exclude_patterns = ['**.ipynb_checkpoints'] -numpydoc_show_class_members = False with open("index.rst") as f: index_rst_lines = f.readlines() diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index 1cd269c05cf7c..040b735f8de2c 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -125,6 +125,10 @@ class CategoricalDtype(ExtensionDtype): categories ordered + Methods + ------- + None + Notes ----- This class is useful for specifying the type of a ``Categorical`` diff --git a/pandas/core/indexes/numeric.py b/pandas/core/indexes/numeric.py index b0703869948c2..362e4bf861653 100644 --- a/pandas/core/indexes/numeric.py +++ b/pandas/core/indexes/numeric.py @@ -122,6 +122,14 @@ def is_all_dates(self): name : object Name to be stored in the index + Attributes + ---------- + inferred_type + + Methods + ------- + None + Notes ----- An Index instance can **only** contain hashable objects. @@ -154,6 +162,7 @@ class Int64Index(NumericIndex): @property def inferred_type(self): + """Always 'integer' for ``Int64Index``""" return 'integer' @property @@ -213,6 +222,7 @@ class UInt64Index(NumericIndex): @property def inferred_type(self): + """Always 'integer' for ``UInt64Index``""" return 'integer' @property @@ -290,6 +300,7 @@ class Float64Index(NumericIndex): @property def inferred_type(self): + """Always 'floating' for ``Float64Index""" return 'floating' @Appender(_index_shared_docs['astype']) diff --git a/pandas/core/reshape/reshape.py b/pandas/core/reshape/reshape.py index b8885820f4a49..cf9bcc4b30551 100644 --- a/pandas/core/reshape/reshape.py +++ b/pandas/core/reshape/reshape.py @@ -1100,6 +1100,7 @@ def get_dummies(data, prefix=None, prefix_sep='_', dummy_na=False, first level. .. versionadded:: 0.18.0 + Returns ------- dummies : DataFrame or SparseDataFrame diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 776669d6d28db..6a99b798a123d 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -386,12 +386,11 @@ def format(self, formatter, subset=None): return self def render(self, **kwargs): - r""" - Render the built up styles to HTML + """Render the built up styles to HTML Parameters ---------- - **kwargs: + `**kwargs`: Any additional keyword arguments are passed through to ``self.template.render``. This is useful when you need to provide additional variables for a custom diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 62b2899f49413..e38daa07c1a8f 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1859,7 +1859,7 @@ def _plot(data, x=None, y=None, subplots=False, mark_right : boolean, default True When using a secondary_y axis, automatically mark the column labels with "(right)" in the legend - kwds : keywords + `**kwds` keywords Options to pass to matplotlib plotting method Returns @@ -1955,7 +1955,7 @@ def plot_series(data, kind='line', ax=None, # Series unique array of axes is returned with the same shape as ``layout``. See the prose documentation for more. - kwds : other plotting keyword arguments to be passed to matplotlib boxplot + `**kwds` other plotting keyword arguments to be passed to matplotlib boxplot function Returns @@ -2152,7 +2152,7 @@ def hist_frame(data, column=None, by=None, grid=True, xlabelsize=None, Tuple of (rows, columns) for the layout of the histograms bins : integer, default 10 Number of histogram bins to be used - kwds : other plotting keyword arguments + `**kwds` other plotting keyword arguments To be passed to hist function """ _setup() @@ -2215,7 +2215,7 @@ def hist_series(self, by=None, ax=None, grid=True, xlabelsize=None, figure size in inches by default bins: integer, default 10 Number of histogram bins to be used - kwds : keywords + `**kwds` keywords To be passed to the actual plotting function Notes @@ -2327,7 +2327,7 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None, figsize : A tuple (width, height) in inches layout : tuple (optional) (rows, columns) for the layout of the plot - kwds : other plotting keyword arguments to be passed to matplotlib boxplot + `**kwds` other plotting keyword arguments to be passed to matplotlib boxplot function Returns @@ -2505,7 +2505,7 @@ def line(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2520,7 +2520,7 @@ def bar(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2535,7 +2535,7 @@ def barh(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2550,7 +2550,7 @@ def box(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2567,7 +2567,7 @@ def hist(self, bins=10, **kwds): ---------- bins: integer, default 10 Number of histogram bins to be used - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2582,7 +2582,7 @@ def kde(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2599,7 +2599,7 @@ def area(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2614,7 +2614,7 @@ def pie(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2665,7 +2665,7 @@ def line(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2682,7 +2682,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2699,7 +2699,7 @@ def barh(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2716,7 +2716,7 @@ def box(self, by=None, **kwds): ---------- by : string or sequence Column in the DataFrame to group by. - \*\*kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2735,7 +2735,7 @@ def hist(self, by=None, bins=10, **kwds): Column in the DataFrame to group by. bins: integer, default 10 Number of histogram bins to be used - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2750,7 +2750,7 @@ def kde(self, **kwds): Parameters ---------- - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2769,7 +2769,7 @@ def area(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2786,7 +2786,7 @@ def pie(self, y=None, **kwds): ---------- y : label or position, optional Column to plot. - **kwds : optional + \*\`**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2807,7 +2807,7 @@ def scatter(self, x, y, s=None, c=None, **kwds): Size of each point. c : label or position, optional Color of each point. - **kwds : optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2832,7 +2832,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, a single number (e.g. `mean`, `max`, `sum`, `std`). gridsize : int, optional Number of bins. - **kwds : optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns From 38efdcb5b17968375f929d88fc5bbf5f98dd0701 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 21:04:42 -0600 Subject: [PATCH 11/30] More cleanups --- pandas/_libs/tslib.pyx | 30 ++++++++++++++++++++++++++++-- pandas/core/categorical.py | 2 +- pandas/io/gbq.py | 2 +- 3 files changed, 30 insertions(+), 4 deletions(-) diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index bf22a3a528259..df73bde5d5a15 100644 --- a/pandas/_libs/tslib.pyx +++ b/pandas/_libs/tslib.pyx @@ -288,6 +288,8 @@ class Timestamp(_Timestamp): @classmethod def fromordinal(cls, ordinal, freq=None, tz=None, offset=None): """ + Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None) + passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself @@ -308,8 +310,10 @@ class Timestamp(_Timestamp): @classmethod def now(cls, tz=None): """ - Return the current time in the local timezone. Equivalent - to datetime.now([tz]) + Timestamp.now(tz=None) + + Returns new Timestamp object representing current time local to + tz. Parameters ---------- @@ -323,6 +327,8 @@ class Timestamp(_Timestamp): @classmethod def today(cls, tz=None): """ + Timestamp.today(cls, tz=None) + Return the current time in the local timezone. This differs from datetime.today() in that it can be localized to a passed timezone. @@ -336,18 +342,38 @@ class Timestamp(_Timestamp): @classmethod def utcnow(cls): + """ + Timestamp.utcnow + + Return a new Timestamp representing UTC day and time. + """ return cls.now('UTC') @classmethod def utcfromtimestamp(cls, ts): + """ + Timestamp.utcfromtimestamp(ts) + + Construct a naive UTC datetime from a POSIX timestamp. + """ return cls(datetime.utcfromtimestamp(ts)) @classmethod def fromtimestamp(cls, ts): + """ + Timestamp.fromtimsetamp(ts) + + timestamp[, tz] -> tz's local time from POSIX timestamp. + """ return cls(datetime.fromtimestamp(ts)) @classmethod def combine(cls, date, time): + """ + Timsetamp.combine(date, time) + + date, time -> datetime with same date and time fields + """ return cls(datetime.combine(date, time)) def __new__(cls, object ts_input=_no_input, diff --git a/pandas/core/categorical.py b/pandas/core/categorical.py index 1e3c8f89c0e05..4385dc7421bcd 100644 --- a/pandas/core/categorical.py +++ b/pandas/core/categorical.py @@ -430,7 +430,7 @@ def ordered(self): @property def dtype(self): - """The :ref:`~pandas.api.types.CategoricalDtype` for this instance""" + """The :class:`~pandas.api.types.CategoricalDtype` for this instance""" return self._dtype @property diff --git a/pandas/io/gbq.py b/pandas/io/gbq.py index b4dc9173f11ba..12e52123064e2 100644 --- a/pandas/io/gbq.py +++ b/pandas/io/gbq.py @@ -75,7 +75,7 @@ def read_gbq(query, project_id=None, index_col=None, col_order=None, see `BigQuery SQL Reference `__ - **kwargs : Arbitrary keyword arguments + `**kwargs` : Arbitrary keyword arguments configuration (dict): query config parameters for job processing. For example: From 5e8bcbe5fb7d4073a9bcc145679455d41464e86b Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 21:07:52 -0600 Subject: [PATCH 12/30] PEP8 --- pandas/plotting/_core.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index e38daa07c1a8f..538dc2c14b80a 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1955,8 +1955,9 @@ def plot_series(data, kind='line', ax=None, # Series unique array of axes is returned with the same shape as ``layout``. See the prose documentation for more. - `**kwds` other plotting keyword arguments to be passed to matplotlib boxplot - function + `**kwds` : Keyword Arguments + All other plotting keyword arguments to be passed to + matplotlib's boxplot function Returns ------- @@ -2327,8 +2328,9 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None, figsize : A tuple (width, height) in inches layout : tuple (optional) (rows, columns) for the layout of the plot - `**kwds` other plotting keyword arguments to be passed to matplotlib boxplot - function + `**kwds` : Keyword Arguments + All other plotting keyword arguments to be passed to + matplotlib's boxplot function Returns ------- From 86957276efbde62825d2c63fccd9c8d14e6f2556 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 12 Nov 2017 21:15:08 -0600 Subject: [PATCH 13/30] Hide more items --- doc/source/api.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 664aac300d735..263df61f7d21f 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -368,7 +368,6 @@ Binary operator functions Series.ge Series.ne Series.eq - Series.divide Series.product Series.dot @@ -431,6 +430,7 @@ Computations / Descriptive Stats Series.std Series.sum Series.var + Series.kurtosis Series.unique Series.nunique Series.is_unique @@ -441,8 +441,6 @@ Computations / Descriptive Stats Series.compound Series.nonzero Series.ptp - Series.kurtosis - Series.multiply Reindexing / Selection / Label manipulation @@ -933,11 +931,8 @@ Binary operator functions DataFrame.add DataFrame.sub - DataFrame.subtract DataFrame.mul - DataFrame.multiply DataFrame.div - DataFrame.divide DataFrame.truediv DataFrame.floordiv DataFrame.mod @@ -2638,3 +2633,9 @@ Scalar introspection generated/pandas.Categorical.shape.rst generated/pandas.Categorical.size.rst generated/pandas.Categorical.T.rst + + generated/pandas.DataFrame.subtract + generated/pandas.DataFrame.multiply + generated/pandas.DataFrame.divide + generated/pandas.Series.divide + generated/pandas.Series.multiply From 4476a5f6f51239194616b9fb25c71bf36cc6cffb Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 13 Nov 2017 06:04:36 -0600 Subject: [PATCH 14/30] Fixups --- pandas/_libs/tslib.pyx | 2 +- pandas/core/tools/datetimes.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index df73bde5d5a15..ba96eba1c649d 100644 --- a/pandas/_libs/tslib.pyx +++ b/pandas/_libs/tslib.pyx @@ -361,7 +361,7 @@ class Timestamp(_Timestamp): @classmethod def fromtimestamp(cls, ts): """ - Timestamp.fromtimsetamp(ts) + Timestamp.fromtimestamp(ts) timestamp[, tz] -> tz's local time from POSIX timestamp. """ diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py index 19f7e459d0725..cbf393046907f 100644 --- a/pandas/core/tools/datetimes.py +++ b/pandas/core/tools/datetimes.py @@ -185,6 +185,7 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, strings, especially ones with timezone offsets. .. versionadded: 0.22.0 + Returns ------- ret : datetime if parsing succeeded. @@ -200,7 +201,6 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, Examples -------- - Assembling a datetime from multiple columns of a DataFrame. The keys can be common abbreviations like ['year', 'month', 'day', 'minute', 'second', 'ms', 'us', 'ns']) or plurals of the same From a5005e1b2f71423cbf89c258d562df95f036fd35 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 13 Nov 2017 06:16:01 -0600 Subject: [PATCH 15/30] Matching NaT --- pandas/_libs/tslib.pyx | 2 +- pandas/_libs/tslibs/nattype.pyx | 45 +++++++++++++++++++++++++++------ 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index ba96eba1c649d..43eafda4f7b55 100644 --- a/pandas/_libs/tslib.pyx +++ b/pandas/_libs/tslib.pyx @@ -343,7 +343,7 @@ class Timestamp(_Timestamp): @classmethod def utcnow(cls): """ - Timestamp.utcnow + Timestamp.utcnow() Return a new Timestamp representing UTC day and time. """ diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index a5861f5865a39..3910ffd60e15a 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -336,16 +336,39 @@ class NaTType(_NaT): tzname = _make_error_func('tzname', datetime) utcoffset = _make_error_func('utcoffset', datetime) - # Timestamp has empty docstring for some methods. - utcfromtimestamp = _make_error_func('utcfromtimestamp', None) - fromtimestamp = _make_error_func('fromtimestamp', None) - combine = _make_error_func('combine', None) - utcnow = _make_error_func('utcnow', None) - # ---------------------------------------------------------------------- # The remaining methods have docstrings copy/pasted from the analogous # Timestamp methods. + utcfromtimestamp = _make_error_func('utcfromtimestamp', + """ + Timestamp.utcfromtimestamp(ts) + + Construct a naive UTC datetime from a POSIX timestamp. + """ + ) + fromtimestamp = _make_error_func('fromtimestamp', + """ + Timestamp.fromtimestamp(ts) + + timestamp[, tz] -> tz's local time from POSIX timestamp. + """ + ) + combine = _make_error_func('combine', + """ + Timsetamp.combine(date, time) + + date, time -> datetime with same date and time fields + """ + ) + utcnow = _make_error_func('utcnow', + """ + Timestamp.utcnow() + + Return a new Timestamp representing UTC day and time. + """ + ) + timestamp = _make_error_func('timestamp', # noqa:E128 """Return POSIX timestamp as float.""") @@ -372,6 +395,8 @@ class NaTType(_NaT): """) fromordinal = _make_error_func('fromordinal', # noqa:E128 """ + Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None) + passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself @@ -397,8 +422,10 @@ class NaTType(_NaT): now = _make_nat_func('now', # noqa:E128 """ - Return the current time in the local timezone. Equivalent - to datetime.now([tz]) + Timestamp.now(tz=None) + + Returns new Timestamp object representing current time local to + tz. Parameters ---------- @@ -407,6 +434,8 @@ class NaTType(_NaT): """) today = _make_nat_func('today', # noqa:E128 """ + Timestamp.today(cls, tz=None) + Return the current time in the local timezone. This differs from datetime.today() in that it can be localized to a passed timezone. From aa925924e13a8d5f22f3a724fa9fee9095e40a8b Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 13 Nov 2017 08:24:12 -0600 Subject: [PATCH 16/30] Fix typo --- pandas/_libs/tslib.pyx | 2 +- pandas/_libs/tslibs/nattype.pyx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index 43eafda4f7b55..d5297ab72bbac 100644 --- a/pandas/_libs/tslib.pyx +++ b/pandas/_libs/tslib.pyx @@ -288,7 +288,7 @@ class Timestamp(_Timestamp): @classmethod def fromordinal(cls, ordinal, freq=None, tz=None, offset=None): """ - Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None) + Timestamp.fromordinal(ordinal, freq=None, tz=None, offset=None) passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 3910ffd60e15a..5a28c1072f30e 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -395,7 +395,7 @@ class NaTType(_NaT): """) fromordinal = _make_error_func('fromordinal', # noqa:E128 """ - Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None) + Timestamp.fromordinal(ordinal, freq=None, tz=None, offset=None) passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself From 1527cdb3ee24a4753e15c18b2c1c26949f81cbe2 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 13 Nov 2017 14:24:33 -0600 Subject: [PATCH 17/30] PEP8 --- pandas/_libs/tslibs/nattype.pyx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 5a28c1072f30e..d9234bc3779a8 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -340,28 +340,28 @@ class NaTType(_NaT): # The remaining methods have docstrings copy/pasted from the analogous # Timestamp methods. - utcfromtimestamp = _make_error_func('utcfromtimestamp', + utcfromtimestamp = _make_error_func('utcfromtimestamp', # noqa:E128 """ Timestamp.utcfromtimestamp(ts) Construct a naive UTC datetime from a POSIX timestamp. """ ) - fromtimestamp = _make_error_func('fromtimestamp', + fromtimestamp = _make_error_func('fromtimestamp', # noqa:E128 """ Timestamp.fromtimestamp(ts) timestamp[, tz] -> tz's local time from POSIX timestamp. """ ) - combine = _make_error_func('combine', + combine = _make_error_func('combine', # noqa:E128 """ Timsetamp.combine(date, time) date, time -> datetime with same date and time fields """ ) - utcnow = _make_error_func('utcnow', + utcnow = _make_error_func('utcnow', # noqa:E128 """ Timestamp.utcnow() From 7ca34349da6dc701df582f0d48589942cafd7174 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 08:32:26 -0600 Subject: [PATCH 18/30] Fix ordering, escaping --- pandas/core/indexes/category.py | 13 ++++---- pandas/core/indexes/datetimes.py | 56 ++++++++++++++++---------------- pandas/core/indexes/interval.py | 19 +++++------ pandas/plotting/_core.py | 32 +++++++++--------- 4 files changed, 59 insertions(+), 61 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index e1c8b9523839a..c9cae877e38fe 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -46,6 +46,12 @@ class CategoricalIndex(Index, accessor.PandasDelegate): name : object Name to be stored in the index + Attributes + ---------- + codes + categories + ordered + See Also -------- Categorical, Index @@ -60,14 +66,7 @@ class CategoricalIndex(Index, accessor.PandasDelegate): set_categories as_ordered as_unordered - get_loc map - - Attributes - ---------- - codes - categories - ordered """ _typ = 'categoricalindex' diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 1fa25fc2c00ce..b0e22460fdcb0 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -203,34 +203,6 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin, name : object Name to be stored in the index - Notes - ----- - To learn more about the frequency strings, please see `this link - `__. - - See Also - --------- - Index : The base pandas Index type - TimedeltaIndex : Index of timedelta64 data - PeriodIndex : Index of Period data - - Methods - ------- - normalize - strftime - snap - tz_convert - tz_localize - round - floor - ceil - to_datetime - to_period - to_perioddelta - to_pydatetime - to_series - to_frame - Attributes ---------- year @@ -261,6 +233,34 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin, is_year_end is_leap_year inferred_freq + + Methods + ------- + normalize + strftime + snap + tz_convert + tz_localize + round + floor + ceil + to_datetime + to_period + to_perioddelta + to_pydatetime + to_series + to_frame + + Notes + ----- + To learn more about the frequency strings, please see `this link + `__. + + See Also + --------- + Index : The base pandas Index type + TimedeltaIndex : Index of timedelta64 data + PeriodIndex : Index of Period data """ _typ = 'datetimeindex' diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index a22b8aa8ca405..b52daf60f0b29 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -125,6 +125,15 @@ class IntervalIndex(IntervalMixin, Index): values is_non_overlapping_monotonic + Methods + ------- + from_arrays + from_tuples + from_breaks + from_intervals + contains + get_loc + Examples --------- A new ``IntervalIndex`` is typically constructed using @@ -157,16 +166,6 @@ class IntervalIndex(IntervalMixin, Index): IntervalIndex.from_intervals, IntervalIndex.from_tuples cut, qcut : convert arrays of continuous data into categoricals/series of ``Interval``. - - Methods - ------- - from_arrays - from_tuples - from_breaks - from_intervals - contains - get_loc - """ _typ = 'intervalindex' _comparables = ['name'] diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 538dc2c14b80a..ad87f1bd0d8ea 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2507,7 +2507,7 @@ def line(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2522,7 +2522,7 @@ def bar(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2537,7 +2537,7 @@ def barh(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2552,7 +2552,7 @@ def box(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2569,7 +2569,7 @@ def hist(self, bins=10, **kwds): ---------- bins: integer, default 10 Number of histogram bins to be used - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2584,7 +2584,7 @@ def kde(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2601,7 +2601,7 @@ def area(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2616,7 +2616,7 @@ def pie(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2667,7 +2667,7 @@ def line(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2684,7 +2684,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2701,7 +2701,7 @@ def barh(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2718,7 +2718,7 @@ def box(self, by=None, **kwds): ---------- by : string or sequence Column in the DataFrame to group by. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2737,7 +2737,7 @@ def hist(self, by=None, bins=10, **kwds): Column in the DataFrame to group by. bins: integer, default 10 Number of histogram bins to be used - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2752,7 +2752,7 @@ def kde(self, **kwds): Parameters ---------- - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2771,7 +2771,7 @@ def area(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2788,7 +2788,7 @@ def pie(self, y=None, **kwds): ---------- y : label or position, optional Column to plot. - \*\`**kwds` optional + `**kwds` optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns From 5a0e10e5dc7787df94cd55cf25622f07703513f9 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 09:36:02 -0600 Subject: [PATCH 19/30] Add notes on contributing --- doc/source/api.rst | 20 ++++++-------------- doc/source/contributing.rst | 21 +++++++++++++++++++++ pandas/core/categorical.py | 5 +++++ pandas/core/indexes/category.py | 8 ++++---- 4 files changed, 36 insertions(+), 18 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 263df61f7d21f..a60d45c96bb81 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -344,7 +344,6 @@ Binary operator functions Series.add Series.sub - Series.subtract Series.mul Series.div Series.truediv @@ -715,20 +714,21 @@ a :class:`pandas.api.types.CategoricalDtype`. api.types.CategoricalDtype.categories api.types.CategoricalDtype.ordered -Categorical data can be stored in a :class:``pandas.Categorical`` +Categorical data can be stored in a :class:`pandas.Categorical` .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst Categorical -The following two ``Categorical`` constructors are considered API but should only be used when -adding ordering information or special categories is need at creation time of the categorical data: + +The alternative :ref:`Categorical.from_codes` constructor can be used when you +have the categories and integer codes already: .. autosummary:: :toctree: generated/ - Categorical.categories Categorical.from_codes The dtype information is available on the ``Categorical`` @@ -2617,6 +2617,7 @@ Scalar introspection generated/pandas.Series.ix generated/pandas.Series.notnull.rst generated/pandas.Series.set_value + generated/pandas.Series.subtract generated/pandas.Series.cat generated/pandas.Series.dt @@ -2625,15 +2626,6 @@ Scalar introspection generated/pandas.Timestamp.offset generated/pandas.Timestamp.to_datetime - generated/pandas.Categorical.base.rst - generated/pandas.Categorical.itemsize.rst - generated/pandas.Categorical.labels.rst - generated/pandas.Categorical.nbytes.rst - generated/pandas.Categorical.ndim.rst - generated/pandas.Categorical.shape.rst - generated/pandas.Categorical.size.rst - generated/pandas.Categorical.T.rst - generated/pandas.DataFrame.subtract generated/pandas.DataFrame.multiply generated/pandas.DataFrame.divide diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 40189f0e45518..3c09899059794 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -317,6 +317,27 @@ Some other important things to know about the docs: doc build. This approach means that code examples will always be up to date, but it does make the doc building a bit more complex. +- Our API documentation in ``doc/source/api.rst`` houses the auto-generated + documentation from the docstrings. For classes, there are a few subtleties + around controlling which methods and attributes have pages auto-generated. + + We have two autosummary templates for classes. + + 1. ``_templates/autosummary/class.rst``. Use this when you want to + automatically autogenerate a page for public method and attribute on the + class. The class should include the regular ``Parameters`` section, but + need not include ``Attributes`` or ``Methods``. Those sections will be + automatically added to the rendered documentation by numpydoc. + + 2. ``_templates/autosummary/class_without_autosummary``. Use this when you + want to pick a subset of methods / attributes to auto-generate pages for. + When using this template, you should include an ``Attributes`` and + ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an + example. + + Every method should be included in a ``toctree`` in ``api.rst``, else Sphinx + will emit a warning. + .. note:: The ``.rst`` files are used to automatically generate Markdown and HTML versions diff --git a/pandas/core/categorical.py b/pandas/core/categorical.py index 33f07c59a825f..d0851e3ab4f96 100644 --- a/pandas/core/categorical.py +++ b/pandas/core/categorical.py @@ -194,6 +194,11 @@ class Categorical(PandasObject): .. versionadded:: 0.21.0 + Methods + ------- + from_codes + __array__ + Raises ------ ValueError diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index c9cae877e38fe..3812ed96b6c36 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -52,10 +52,6 @@ class CategoricalIndex(Index, accessor.PandasDelegate): categories ordered - See Also - -------- - Categorical, Index - Methods ------- rename_categories @@ -67,6 +63,10 @@ class CategoricalIndex(Index, accessor.PandasDelegate): as_ordered as_unordered map + + See Also + -------- + Categorical, Index """ _typ = 'categoricalindex' From c8504d1c83063587b003544b4b4a122754c820c2 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 09:39:06 -0600 Subject: [PATCH 20/30] Fix kwds again --- pandas/plotting/_core.py | 46 ++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index ad87f1bd0d8ea..e2ce85d8303ec 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1859,7 +1859,7 @@ def _plot(data, x=None, y=None, subplots=False, mark_right : boolean, default True When using a secondary_y axis, automatically mark the column labels with "(right)" in the legend - `**kwds` keywords + `**kwds` : keywords Options to pass to matplotlib plotting method Returns @@ -1955,7 +1955,7 @@ def plot_series(data, kind='line', ax=None, # Series unique array of axes is returned with the same shape as ``layout``. See the prose documentation for more. - `**kwds` : Keyword Arguments + `**kwds` : : Keyword Arguments All other plotting keyword arguments to be passed to matplotlib's boxplot function @@ -2153,7 +2153,7 @@ def hist_frame(data, column=None, by=None, grid=True, xlabelsize=None, Tuple of (rows, columns) for the layout of the histograms bins : integer, default 10 Number of histogram bins to be used - `**kwds` other plotting keyword arguments + `**kwds` : other plotting keyword arguments To be passed to hist function """ _setup() @@ -2216,7 +2216,7 @@ def hist_series(self, by=None, ax=None, grid=True, xlabelsize=None, figure size in inches by default bins: integer, default 10 Number of histogram bins to be used - `**kwds` keywords + `**kwds` : keywords To be passed to the actual plotting function Notes @@ -2328,7 +2328,7 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None, figsize : A tuple (width, height) in inches layout : tuple (optional) (rows, columns) for the layout of the plot - `**kwds` : Keyword Arguments + `**kwds` : : Keyword Arguments All other plotting keyword arguments to be passed to matplotlib's boxplot function @@ -2507,7 +2507,7 @@ def line(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2522,7 +2522,7 @@ def bar(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2537,7 +2537,7 @@ def barh(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2552,7 +2552,7 @@ def box(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2569,7 +2569,7 @@ def hist(self, bins=10, **kwds): ---------- bins: integer, default 10 Number of histogram bins to be used - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2584,7 +2584,7 @@ def kde(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2601,7 +2601,7 @@ def area(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2616,7 +2616,7 @@ def pie(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2667,7 +2667,7 @@ def line(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2684,7 +2684,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2701,7 +2701,7 @@ def barh(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2718,7 +2718,7 @@ def box(self, by=None, **kwds): ---------- by : string or sequence Column in the DataFrame to group by. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2737,7 +2737,7 @@ def hist(self, by=None, bins=10, **kwds): Column in the DataFrame to group by. bins: integer, default 10 Number of histogram bins to be used - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2752,7 +2752,7 @@ def kde(self, **kwds): Parameters ---------- - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2771,7 +2771,7 @@ def area(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2788,7 +2788,7 @@ def pie(self, y=None, **kwds): ---------- y : label or position, optional Column to plot. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2809,7 +2809,7 @@ def scatter(self, x, y, s=None, c=None, **kwds): Size of each point. c : label or position, optional Color of each point. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2834,7 +2834,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, a single number (e.g. `mean`, `max`, `sum`, `std`). gridsize : int, optional Number of bins. - `**kwds` optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns From f7ed01572fe0dbb3dda8bbd9945124680d5bdbcb Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 09:53:39 -0600 Subject: [PATCH 21/30] Wording --- doc/source/contributing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 3c09899059794..0e5d701353d78 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -324,10 +324,10 @@ Some other important things to know about the docs: We have two autosummary templates for classes. 1. ``_templates/autosummary/class.rst``. Use this when you want to - automatically autogenerate a page for public method and attribute on the - class. The class should include the regular ``Parameters`` section, but - need not include ``Attributes`` or ``Methods``. Those sections will be - automatically added to the rendered documentation by numpydoc. + automatically generate a page for every public method and attribute on the + class. The ``Attributes`` and ``Methods`` sections will be automatically + added to the class' rendered documentation by numpydoc. See ``DataFrame`` + for an example. 2. ``_templates/autosummary/class_without_autosummary``. Use this when you want to pick a subset of methods / attributes to auto-generate pages for. From 094f6f6d8990c665cb19e6168b0f87819af680d0 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 09:54:01 -0600 Subject: [PATCH 22/30] Fix ref --- doc/source/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index a60d45c96bb81..5fc46a4ad14df 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -723,7 +723,7 @@ Categorical data can be stored in a :class:`pandas.Categorical` Categorical -The alternative :ref:`Categorical.from_codes` constructor can be used when you +The alternative :meth:`Categorical.from_codes` constructor can be used when you have the categories and integer codes already: .. autosummary:: From 1c2160f7c6e295b95f2bf03e914ca815e282ff40 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 10:11:53 -0600 Subject: [PATCH 23/30] Another fixup --- pandas/plotting/_core.py | 46 ++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index e2ce85d8303ec..c934648a1d111 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1859,7 +1859,7 @@ def _plot(data, x=None, y=None, subplots=False, mark_right : boolean, default True When using a secondary_y axis, automatically mark the column labels with "(right)" in the legend - `**kwds` : keywords + `**kwds` : keywords Options to pass to matplotlib plotting method Returns @@ -1955,7 +1955,7 @@ def plot_series(data, kind='line', ax=None, # Series unique array of axes is returned with the same shape as ``layout``. See the prose documentation for more. - `**kwds` : : Keyword Arguments + `**kwds` : Keyword Arguments All other plotting keyword arguments to be passed to matplotlib's boxplot function @@ -2153,7 +2153,7 @@ def hist_frame(data, column=None, by=None, grid=True, xlabelsize=None, Tuple of (rows, columns) for the layout of the histograms bins : integer, default 10 Number of histogram bins to be used - `**kwds` : other plotting keyword arguments + `**kwds` : other plotting keyword arguments To be passed to hist function """ _setup() @@ -2216,7 +2216,7 @@ def hist_series(self, by=None, ax=None, grid=True, xlabelsize=None, figure size in inches by default bins: integer, default 10 Number of histogram bins to be used - `**kwds` : keywords + `**kwds` : keywords To be passed to the actual plotting function Notes @@ -2328,7 +2328,7 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None, figsize : A tuple (width, height) in inches layout : tuple (optional) (rows, columns) for the layout of the plot - `**kwds` : : Keyword Arguments + `**kwds` : Keyword Arguments All other plotting keyword arguments to be passed to matplotlib's boxplot function @@ -2507,7 +2507,7 @@ def line(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2522,7 +2522,7 @@ def bar(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2537,7 +2537,7 @@ def barh(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2552,7 +2552,7 @@ def box(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2569,7 +2569,7 @@ def hist(self, bins=10, **kwds): ---------- bins: integer, default 10 Number of histogram bins to be used - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2584,7 +2584,7 @@ def kde(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2601,7 +2601,7 @@ def area(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2616,7 +2616,7 @@ def pie(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2667,7 +2667,7 @@ def line(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2684,7 +2684,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2701,7 +2701,7 @@ def barh(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2718,7 +2718,7 @@ def box(self, by=None, **kwds): ---------- by : string or sequence Column in the DataFrame to group by. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2737,7 +2737,7 @@ def hist(self, by=None, bins=10, **kwds): Column in the DataFrame to group by. bins: integer, default 10 Number of histogram bins to be used - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2752,7 +2752,7 @@ def kde(self, **kwds): Parameters ---------- - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2771,7 +2771,7 @@ def area(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2788,7 +2788,7 @@ def pie(self, y=None, **kwds): ---------- y : label or position, optional Column to plot. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2809,7 +2809,7 @@ def scatter(self, x, y, s=None, c=None, **kwds): Size of each point. c : label or position, optional Color of each point. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2834,7 +2834,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, a single number (e.g. `mean`, `max`, `sum`, `std`). gridsize : int, optional Number of bins. - `**kwds` : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns From 6e99be2f5e3324d7d281bea97517b5e9ec8bf60a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 10:17:24 -0600 Subject: [PATCH 24/30] Series of dtype category --- doc/source/api.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 5fc46a4ad14df..fd1b2eba392c8 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -750,6 +750,12 @@ the Categorical back to a numpy array, so categories and order information is no Categorical.__array__ A ``Categorical`` can be stored in a ``Series`` or ``DataFrame``. +To create a Series of dtype ``category``, use ``cat = s.astype(dtype)`` or +``Series(..., dtype=dtype)`` where ``dtype`` is either + +* the string ``'category'`` +* an instance of :class:`~pandas.api.types.CategoricalDtype`. + If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the following usable methods and properties: @@ -775,10 +781,6 @@ following usable methods and properties: Series.cat.as_ordered Series.cat.as_unordered -To create a Series of dtype ``category``, use ``cat = s.astype("category")`` or -``s.astype(categorical_dtype)`` where ``categorical_dtype`` is an instance of -:class:`~pandas.api.types.CategoricalDtype`. - Plotting ~~~~~~~~ From 3bd03db5620f5c9343ded1bc75e6250816e728b2 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 10:28:02 -0600 Subject: [PATCH 25/30] Move more methods to hidden --- doc/source/api.rst | 156 ++++++++++++++++++++++----------------------- 1 file changed, 77 insertions(+), 79 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index fd1b2eba392c8..0685dc70fa997 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -817,8 +817,6 @@ Serialization / IO / Conversion .. autosummary:: :toctree: generated/ - Series.from_csv - Series.from_array Series.to_pickle Series.to_csv Series.to_dict @@ -1064,8 +1062,6 @@ Missing data handling DataFrame.fillna DataFrame.replace DataFrame.interpolate - DataFrame.isnull - DataFrame.notnull Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1204,7 +1200,6 @@ Constructor :toctree: generated/ Panel - Panel.from_dict Attributes and underlying data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1226,8 +1221,6 @@ Attributes and underlying data Panel.ftypes Panel.get_dtype_counts Panel.get_ftype_counts - Panel.empty - Panel.is_copy Conversion ~~~~~~~~~~ @@ -1238,9 +1231,6 @@ Conversion Panel.copy Panel.isna Panel.notna - Panel.as_matrix - Panel.convert_objects - Panel.infer_objects Getting and setting ~~~~~~~~~~~~~~~~~~~ @@ -1249,8 +1239,6 @@ Getting and setting Panel.get_value Panel.set_value - Panel.get - Panel.get_values Indexing, iteration, slicing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1267,11 +1255,6 @@ Indexing, iteration, slicing Panel.xs Panel.major_xs Panel.minor_xs - Panel.keys - Panel.major_axis - Panel.items - Panel.minor_axis - Panel.slice_shift For more information on ``.at``, ``.iat``, ``.loc``, and ``.iloc``, see the :ref:`indexing documentation `. @@ -1311,7 +1294,6 @@ Function application, GroupBy Panel.apply Panel.groupby - Panel.pipe .. _api.panel.stats: @@ -1340,26 +1322,6 @@ Computations / Descriptive Stats Panel.sum Panel.std Panel.var - Panel.agg - Panel.aggregate - Panel.all - Panel.any - Panel.bool - Panel.divide - Panel.kurt - Panel.kurtosis - Panel.mad - Panel.product - Panel.rank - Panel.head - Panel.tail - Panel.where - Panel.mask - Panel.compound - Panel.describe - Panel.multiply - Panel.subtract - Panel.round Reindexing / Selection / Label manipulation @@ -1382,12 +1344,6 @@ Reindexing / Selection / Label manipulation Panel.select Panel.take Panel.truncate - Panel.align - Panel.at_time - Panel.asof - Panel.between_time - Panel.rename_axis - Panel.set_axis Missing data handling @@ -1396,11 +1352,6 @@ Missing data handling :toctree: generated/ Panel.dropna - Panel.fillna - Panel.ffill - Panel.bfill - Panel.interpolate - Panel.replace Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1412,8 +1363,6 @@ Reshaping, sorting, transposing Panel.transpose Panel.swapaxes Panel.conform - Panel.sort_values - Panel.squeeze Combining / joining / merging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1431,7 +1380,6 @@ Time series-related Panel.asfreq Panel.shift Panel.resample - Panel.tshift Panel.tz_convert Panel.tz_localize @@ -1441,21 +1389,12 @@ Serialization / IO / Conversion :toctree: generated/ Panel.from_dict - Panel.toLong - Panel.to_clipboard - Panel.to_dense + Panel.to_pickle Panel.to_excel - Panel.to_frame Panel.to_hdf - Panel.to_json - Panel.to_latex - Panel.to_long - Panel.to_msgpack - Panel.to_pickle Panel.to_sparse - Panel.to_sql - Panel.to_xarray - + Panel.to_frame + Panel.to_clipboard .. _api.index: @@ -1676,7 +1615,6 @@ Categorical Components CategoricalIndex.set_categories CategoricalIndex.as_ordered CategoricalIndex.as_unordered - CategoricalIndex.get_loc CategoricalIndex.map .. _api.intervalindex: @@ -1701,7 +1639,6 @@ IntervalIndex Components IntervalIndex.from_breaks IntervalIndex.from_intervals IntervalIndex.contains - IntervalIndex.get_loc IntervalIndex.left IntervalIndex.right IntervalIndex.mid @@ -2586,9 +2523,11 @@ Scalar introspection generated/pandas.DataFrame.ix generated/pandas.DataFrame.set_value generated/pandas.DataFrame.sortlevel + generated/pandas.DataFrame.isnull + generated/pandas.DataFrame.notnull - generated/pandas.Index.data.rst - generated/pandas.Index.asi8.rst + generated/pandas.Index.data + generated/pandas.Index.asi8 generated/pandas.Index.flags generated/pandas.Index.isnull generated/pandas.Index.names @@ -2600,24 +2539,83 @@ Scalar introspection generated/pandas.Index.str - generated/pandas.Panel.as_blocks.rst - generated/pandas.Panel.blocks.rst - generated/pandas.Panel.consolidate.rst - generated/pandas.Panel.fromDict.rst - generated/pandas.Panel.isnull.rst - generated/pandas.Panel.ix.rst - generated/pandas.Panel.notnull.rst + generated/pandas.Panel.as_blocks + generated/pandas.Panel.blocks + generated/pandas.Panel.consolidate + generated/pandas.Panel.fromDict + generated/pandas.Panel.isnull + generated/pandas.Panel.ix + generated/pandas.Panel.notnull + generated/pandas.Panel.from_dict + generated/pandas.Panel.empty + generated/pandas.Panel.is_copy + generated/pandas.Panel.as_matrix + generated/pandas.Panel.convert_objects + generated/pandas.Panel.infer_objects + generated/pandas.Panel.get + generated/pandas.Panel.get_values + generated/pandas.Panel.keys + generated/pandas.Panel.major_axis + generated/pandas.Panel.items + generated/pandas.Panel.minor_axis + generated/pandas.Panel.slice_shift + generated/pandas.Panel.pipe + generated/pandas.Panel.agg + generated/pandas.Panel.aggregate + generated/pandas.Panel.all + generated/pandas.Panel.any + generated/pandas.Panel.bool + generated/pandas.Panel.divide + generated/pandas.Panel.kurt + generated/pandas.Panel.kurtosis + generated/pandas.Panel.mad + generated/pandas.Panel.product + generated/pandas.Panel.rank + generated/pandas.Panel.head + generated/pandas.Panel.tail + generated/pandas.Panel.where + generated/pandas.Panel.mask + generated/pandas.Panel.compound + generated/pandas.Panel.describe + generated/pandas.Panel.multiply + generated/pandas.Panel.subtract + generated/pandas.Panel.round + generated/pandas.Panel.align + generated/pandas.Panel.at_time + generated/pandas.Panel.asof + generated/pandas.Panel.between_time + generated/pandas.Panel.rename_axis + generated/pandas.Panel.set_axis + generated/pandas.Panel.fillna + generated/pandas.Panel.ffill + generated/pandas.Panel.bfill + generated/pandas.Panel.interpolate + generated/pandas.Panel.replace + generated/pandas.Panel.sort_values + generated/pandas.Panel.squeeze + generated/pandas.Panel.tshift + generated/pandas.Panel.toLong + generated/pandas.Panel.to_dense + generated/pandas.Panel.to_json + generated/pandas.Panel.to_latex + generated/pandas.Panel.to_long + generated/pandas.Panel.to_msgpack + generated/pandas.Panel.to_sql + generated/pandas.Panel.to_xarray + + generated/pandas.Series.from_csv generated/pandas.Series.as_blocks - generated/pandas.Series.asobject.rst + generated/pandas.Series.asobject generated/pandas.Series.bfill generated/pandas.Series.blocks - generated/pandas.Series.consolidate.rst + generated/pandas.Series.consolidate generated/pandas.Series.ffill + generated/pandas.Series.from_array generated/pandas.Series.get_value generated/pandas.Series.index - generated/pandas.Series.isnull.rst + generated/pandas.Series.isnull generated/pandas.Series.ix - generated/pandas.Series.notnull.rst + generated/pandas.Series.notnull generated/pandas.Series.set_value generated/pandas.Series.subtract From ba257ccd5cae4137bdc169be8fe311fab95255c3 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 10:28:23 -0600 Subject: [PATCH 26/30] Hide get_loc --- pandas/core/indexes/interval.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index b52daf60f0b29..6ae55b063b676 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -132,7 +132,6 @@ class IntervalIndex(IntervalMixin, Index): from_breaks from_intervals contains - get_loc Examples --------- From f846713bb65ecd62ea2d378f231e9a1498abef62 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 15:49:32 -0600 Subject: [PATCH 27/30] Just hide attributes --- doc/source/api.rst | 106 +++------------------------------------------ 1 file changed, 5 insertions(+), 101 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 0685dc70fa997..2618b26e272f0 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2512,122 +2512,26 @@ Scalar introspection .. toctree:: :hidden: - generated/pandas.DataFrame.as_blocks - generated/pandas.DataFrame.bfill - generated/pandas.DataFrame.blocks generated/pandas.DataFrame.columns - generated/pandas.DataFrame.consolidate - generated/pandas.DataFrame.ffill - generated/pandas.DataFrame.get_value generated/pandas.DataFrame.index generated/pandas.DataFrame.ix - generated/pandas.DataFrame.set_value - generated/pandas.DataFrame.sortlevel - generated/pandas.DataFrame.isnull - generated/pandas.DataFrame.notnull - - generated/pandas.Index.data generated/pandas.Index.asi8 + generated/pandas.Index.data generated/pandas.Index.flags - generated/pandas.Index.isnull - generated/pandas.Index.names generated/pandas.Index.nlevels - generated/pandas.Index.notnull - generated/pandas.Index.reshape generated/pandas.Index.sort - generated/pandas.Index.sortlevel - - generated/pandas.Index.str - - generated/pandas.Panel.as_blocks + generated/pandas.Panel.agg + generated/pandas.Panel.aggregate generated/pandas.Panel.blocks - generated/pandas.Panel.consolidate - generated/pandas.Panel.fromDict - generated/pandas.Panel.isnull - generated/pandas.Panel.ix - generated/pandas.Panel.notnull - generated/pandas.Panel.from_dict generated/pandas.Panel.empty generated/pandas.Panel.is_copy - generated/pandas.Panel.as_matrix - generated/pandas.Panel.convert_objects - generated/pandas.Panel.infer_objects - generated/pandas.Panel.get - generated/pandas.Panel.get_values - generated/pandas.Panel.keys - generated/pandas.Panel.major_axis generated/pandas.Panel.items + generated/pandas.Panel.ix + generated/pandas.Panel.major_axis generated/pandas.Panel.minor_axis - generated/pandas.Panel.slice_shift - generated/pandas.Panel.pipe - generated/pandas.Panel.agg - generated/pandas.Panel.aggregate - generated/pandas.Panel.all - generated/pandas.Panel.any - generated/pandas.Panel.bool - generated/pandas.Panel.divide - generated/pandas.Panel.kurt - generated/pandas.Panel.kurtosis - generated/pandas.Panel.mad - generated/pandas.Panel.product - generated/pandas.Panel.rank - generated/pandas.Panel.head - generated/pandas.Panel.tail - generated/pandas.Panel.where - generated/pandas.Panel.mask - generated/pandas.Panel.compound - generated/pandas.Panel.describe - generated/pandas.Panel.multiply - generated/pandas.Panel.subtract - generated/pandas.Panel.round - generated/pandas.Panel.align - generated/pandas.Panel.at_time - generated/pandas.Panel.asof - generated/pandas.Panel.between_time - generated/pandas.Panel.rename_axis - generated/pandas.Panel.set_axis - generated/pandas.Panel.fillna - generated/pandas.Panel.ffill - generated/pandas.Panel.bfill - generated/pandas.Panel.interpolate - generated/pandas.Panel.replace - generated/pandas.Panel.sort_values - generated/pandas.Panel.squeeze - generated/pandas.Panel.tshift - generated/pandas.Panel.toLong - generated/pandas.Panel.to_dense - generated/pandas.Panel.to_json - generated/pandas.Panel.to_latex - generated/pandas.Panel.to_long - generated/pandas.Panel.to_msgpack - generated/pandas.Panel.to_sql - generated/pandas.Panel.to_xarray - - generated/pandas.Series.from_csv - generated/pandas.Series.as_blocks generated/pandas.Series.asobject - generated/pandas.Series.bfill generated/pandas.Series.blocks - generated/pandas.Series.consolidate - generated/pandas.Series.ffill generated/pandas.Series.from_array - generated/pandas.Series.get_value generated/pandas.Series.index - generated/pandas.Series.isnull generated/pandas.Series.ix - generated/pandas.Series.notnull - generated/pandas.Series.set_value - generated/pandas.Series.subtract - - generated/pandas.Series.cat - generated/pandas.Series.dt - generated/pandas.Series.str - generated/pandas.Timestamp.offset - generated/pandas.Timestamp.to_datetime - - generated/pandas.DataFrame.subtract - generated/pandas.DataFrame.multiply - generated/pandas.DataFrame.divide - generated/pandas.Series.divide - generated/pandas.Series.multiply From 141107a06c50ea51815152a91e2ee9633d0fabfe Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 14 Nov 2017 16:01:42 -0600 Subject: [PATCH 28/30] Cleanup hidden --- doc/source/api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/api.rst b/doc/source/api.rst index 2618b26e272f0..a9519ac42676c 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2512,6 +2512,7 @@ Scalar introspection .. toctree:: :hidden: + generated/pandas.DataFrame.blocks generated/pandas.DataFrame.columns generated/pandas.DataFrame.index generated/pandas.DataFrame.ix From 3a224be0c5b8ca6cc709321d41b19a33d6a59a1f Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 15 Nov 2017 16:18:48 +0100 Subject: [PATCH 29/30] remove some methods from api.rst --- doc/source/api.rst | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index a9519ac42676c..f3405fcdee608 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -278,7 +278,6 @@ Attributes Series.size Series.strides Series.itemsize - Series.axes Series.base Series.T Series.memory_usage @@ -287,14 +286,8 @@ Attributes Series.empty Series.dtypes Series.ftypes - Series.as_matrix Series.data - Series.get_dtype_counts - Series.get_ftype_counts - Series.get_values Series.is_copy - Series.imag - Series.real Series.name Series.put @@ -307,12 +300,11 @@ Conversion Series.infer_objects Series.convert_objects Series.copy - Series.isna - Series.notna Series.bool Series.to_period Series.to_timestamp Series.tolist + Series.get_values Indexing, iteration @@ -330,7 +322,6 @@ Indexing, iteration Series.items Series.keys Series.pop - Series.compress Series.item Series.xs @@ -480,10 +471,11 @@ Missing data handling .. autosummary:: :toctree: generated/ + Series.isna + Series.notna Series.dropna Series.fillna Series.interpolate - Series.valid Reshaping, sorting ~~~~~~~~~~~~~~~~~~ @@ -500,14 +492,10 @@ Reshaping, sorting Series.unstack Series.searchsorted Series.ravel - Series.reindex_axis Series.repeat - Series.reshape Series.squeeze Series.view Series.sortlevel - Series.swapaxes - Series.transpose Combining / joining / merging @@ -1456,9 +1444,6 @@ Modifying and Computations Index.duplicated Index.equals Index.factorize - Index.format - Index.groupby - Index.holds_integer Index.identical Index.insert Index.is_ @@ -1471,7 +1456,6 @@ Modifying and Computations Index.is_mixed Index.is_numeric Index.is_object - Index.is_type_compatible Index.min Index.max Index.reindex @@ -1484,9 +1468,6 @@ Modifying and Computations Index.unique Index.nunique Index.value_counts - Index.summary - Index.T - Index.transpose Missing Values ~~~~~~~~~~~~~~ From 34834fae25bd7ea1eb6a364c9d2c841e0837eb38 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 15 Nov 2017 16:22:12 +0100 Subject: [PATCH 30/30] fix warning for float64index --- pandas/core/indexes/numeric.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/indexes/numeric.py b/pandas/core/indexes/numeric.py index 362e4bf861653..ae6a810ece510 100644 --- a/pandas/core/indexes/numeric.py +++ b/pandas/core/indexes/numeric.py @@ -300,7 +300,7 @@ class Float64Index(NumericIndex): @property def inferred_type(self): - """Always 'floating' for ``Float64Index""" + """Always 'floating' for ``Float64Index``""" return 'floating' @Appender(_index_shared_docs['astype'])