From 2d64a65dc83c1c03b5205bc050312b10bb077b45 Mon Sep 17 00:00:00 2001 From: Irv Lustig Date: Thu, 2 Jan 2020 16:28:55 -0500 Subject: [PATCH 1/4] DOC: Add strings for dypes in basic.rst --- doc/source/getting_started/basics.rst | 44 +++++++++++++++++++-------- doc/source/reference/arrays.rst | 3 +- 2 files changed, 33 insertions(+), 14 deletions(-) diff --git a/doc/source/getting_started/basics.rst b/doc/source/getting_started/basics.rst index d489d35dc1226..7c7559dc79a56 100644 --- a/doc/source/getting_started/basics.rst +++ b/doc/source/getting_started/basics.rst @@ -1937,21 +1937,39 @@ See :ref:`extending.extension-types` for how to write your own extension that works with pandas. See :ref:`ecosystem.extensions` for a list of third-party libraries that have implemented an extension. -The following table lists all of pandas extension types. See the respective +The following table lists all of pandas extension types. For methods requiring ``dtype`` +arguments, strings can be specified as indicated. See the respective documentation sections for more on each type. -=================== ========================= ================== ============================= ============================= -Kind of Data Data Type Scalar Array Documentation -=================== ========================= ================== ============================= ============================= -tz-aware datetime :class:`DatetimeTZDtype` :class:`Timestamp` :class:`arrays.DatetimeArray` :ref:`timeseries.timezone` -Categorical :class:`CategoricalDtype` (none) :class:`Categorical` :ref:`categorical` -period (time spans) :class:`PeriodDtype` :class:`Period` :class:`arrays.PeriodArray` :ref:`timeseries.periods` -sparse :class:`SparseDtype` (none) :class:`arrays.SparseArray` :ref:`sparse` -intervals :class:`IntervalDtype` :class:`Interval` :class:`arrays.IntervalArray` :ref:`advanced.intervalindex` -nullable integer :class:`Int64Dtype`, ... (none) :class:`arrays.IntegerArray` :ref:`integer_na` -Strings :class:`StringDtype` :class:`str` :class:`arrays.StringArray` :ref:`text` -Boolean (with NA) :class:`BooleanDtype` :class:`bool` :class:`arrays.BooleanArray` :ref:`api.arrays.bool` -=================== ========================= ================== ============================= ============================= ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +|Kind of Data | Data Type | Scalar | Array | String Shortcuts | Documentation | ++==================+===========================+====================+===============================+=========================================+===============================+ +|tz-aware datetime | :class:`DatetimeTZDtype` | :class:`Timestamp` | :class:`arrays.DatetimeArray` | ``'datetime64[ns, ]'`` | :ref:`timeseries.timezone` | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +|Categorical | :class:`CategoricalDtype` | (none) | :class:`Categorical` | ``'category'`` | :ref:`categorical` | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +|period | :class:`PeriodDtype` | :class:`Period` | :class:`arrays.PeriodArray` | ``'period[]'``, | :ref:`timeseries.periods` | +|(time spans) | | | | ``'Period[]'`` | | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +|sparse | :class:`SparseDtype` | (none) | :class:`arrays.SparseArray` | ``'Sparse'``, ``'Sparse[int]'``, | :ref:`sparse` | +| | | | | ``'Sparse[int32, 0]'``, | | +| | | | | ``'Sparse[int64, 0]'``, | | +| | | | | ``'Sparse[float32, nan]'``, | | +| | | | | ``'Sparse[float64, nan]'`` | | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| intervals | :class:`IntervalDtype` | :class:`Interval` | :class:`arrays.IntervalArray` | ``'interval'``, ``'Interval'``, | :ref:`advanced.intervalindex` | +| | | | | ``'Interval[]'``, | | +| | | | | ``'Interval[datetime64[ns, ]]'``, | | +| | | | | ``'Interval[timedelta64[]]'`` | | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| nullable integer + :class:`Int64Dtype`, ... | (none) | :class:`arrays.IntegerArray` | ``'Int8'``, ``'Int16'``, ``'Int32'``, | :ref:`integer_na` | +| | | | | ``'Int64'``, ``'UInt8'``, ``'UInt16'``, | | +| | | | | ``'UInt32'``, ``'UInt64'`` | | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Strings | :class:`StringDtype` | :class:`str` | :class:`arrays.StringArray` | ``'string'`` | :ref:`text` | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Boolean (with NA)| :class:`BooleanDtype` | :class:`bool` | :class:`arrays.BooleanArray` | ``'boolean'`` | :ref:`api.arrays.bool` | ++------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ Pandas has two ways to store strings. diff --git a/doc/source/reference/arrays.rst b/doc/source/reference/arrays.rst index cf14d28772f4c..958e7bc1be671 100644 --- a/doc/source/reference/arrays.rst +++ b/doc/source/reference/arrays.rst @@ -12,7 +12,8 @@ For most data types, pandas uses NumPy arrays as the concrete objects contained with a :class:`Index`, :class:`Series`, or :class:`DataFrame`. -For some data types, pandas extends NumPy's type system. +For some data types, pandas extends NumPy's type system. String shortcuts for these types +can be found at :ref:`basics.dtypes`. =================== ========================= ================== ============================= Kind of Data Pandas Data Type Scalar Array From a2cf970b76de1e12a1c05af600b05d410f057886 Mon Sep 17 00:00:00 2001 From: Irv Lustig Date: Thu, 2 Jan 2020 17:51:24 -0500 Subject: [PATCH 2/4] remove extraneous Sparse types. use 'alias' rather than 'shortcut' --- doc/source/getting_started/basics.rst | 9 +++------ doc/source/reference/arrays.rst | 2 +- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/doc/source/getting_started/basics.rst b/doc/source/getting_started/basics.rst index 7c7559dc79a56..c910807135496 100644 --- a/doc/source/getting_started/basics.rst +++ b/doc/source/getting_started/basics.rst @@ -1942,7 +1942,7 @@ arguments, strings can be specified as indicated. See the respective documentation sections for more on each type. +------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -|Kind of Data | Data Type | Scalar | Array | String Shortcuts | Documentation | +|Kind of Data | Data Type | Scalar | Array | String Aliases | Documentation | +==================+===========================+====================+===============================+=========================================+===============================+ |tz-aware datetime | :class:`DatetimeTZDtype` | :class:`Timestamp` | :class:`arrays.DatetimeArray` | ``'datetime64[ns, ]'`` | :ref:`timeseries.timezone` | +------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ @@ -1952,13 +1952,10 @@ documentation sections for more on each type. |(time spans) | | | | ``'Period[]'`` | | +------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ |sparse | :class:`SparseDtype` | (none) | :class:`arrays.SparseArray` | ``'Sparse'``, ``'Sparse[int]'``, | :ref:`sparse` | -| | | | | ``'Sparse[int32, 0]'``, | | -| | | | | ``'Sparse[int64, 0]'``, | | -| | | | | ``'Sparse[float32, nan]'``, | | -| | | | | ``'Sparse[float64, nan]'`` | | +| | | | | ``'Sparse[float]'`` | | +------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ | intervals | :class:`IntervalDtype` | :class:`Interval` | :class:`arrays.IntervalArray` | ``'interval'``, ``'Interval'``, | :ref:`advanced.intervalindex` | -| | | | | ``'Interval[]'``, | | +| | | | | ``'Interval[]'``, | | | | | | | ``'Interval[datetime64[ns, ]]'``, | | | | | | | ``'Interval[timedelta64[]]'`` | | +------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ diff --git a/doc/source/reference/arrays.rst b/doc/source/reference/arrays.rst index 958e7bc1be671..2c8382e916ed8 100644 --- a/doc/source/reference/arrays.rst +++ b/doc/source/reference/arrays.rst @@ -12,7 +12,7 @@ For most data types, pandas uses NumPy arrays as the concrete objects contained with a :class:`Index`, :class:`Series`, or :class:`DataFrame`. -For some data types, pandas extends NumPy's type system. String shortcuts for these types +For some data types, pandas extends NumPy's type system. String aliases for these types can be found at :ref:`basics.dtypes`. =================== ========================= ================== ============================= From 1feefc69241a8944bbdf3e7cd042336ef9554be7 Mon Sep 17 00:00:00 2001 From: Irv Lustig Date: Fri, 3 Jan 2020 06:51:39 -0500 Subject: [PATCH 3/4] add spaces. Fix ref to SparseArray --- doc/source/getting_started/basics.rst | 52 +++++++++++++-------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/doc/source/getting_started/basics.rst b/doc/source/getting_started/basics.rst index c910807135496..3e1e1d495be28 100644 --- a/doc/source/getting_started/basics.rst +++ b/doc/source/getting_started/basics.rst @@ -1941,32 +1941,32 @@ The following table lists all of pandas extension types. For methods requiring ` arguments, strings can be specified as indicated. See the respective documentation sections for more on each type. -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -|Kind of Data | Data Type | Scalar | Array | String Aliases | Documentation | -+==================+===========================+====================+===============================+=========================================+===============================+ -|tz-aware datetime | :class:`DatetimeTZDtype` | :class:`Timestamp` | :class:`arrays.DatetimeArray` | ``'datetime64[ns, ]'`` | :ref:`timeseries.timezone` | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -|Categorical | :class:`CategoricalDtype` | (none) | :class:`Categorical` | ``'category'`` | :ref:`categorical` | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -|period | :class:`PeriodDtype` | :class:`Period` | :class:`arrays.PeriodArray` | ``'period[]'``, | :ref:`timeseries.periods` | -|(time spans) | | | | ``'Period[]'`` | | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -|sparse | :class:`SparseDtype` | (none) | :class:`arrays.SparseArray` | ``'Sparse'``, ``'Sparse[int]'``, | :ref:`sparse` | -| | | | | ``'Sparse[float]'`` | | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -| intervals | :class:`IntervalDtype` | :class:`Interval` | :class:`arrays.IntervalArray` | ``'interval'``, ``'Interval'``, | :ref:`advanced.intervalindex` | -| | | | | ``'Interval[]'``, | | -| | | | | ``'Interval[datetime64[ns, ]]'``, | | -| | | | | ``'Interval[timedelta64[]]'`` | | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -| nullable integer + :class:`Int64Dtype`, ... | (none) | :class:`arrays.IntegerArray` | ``'Int8'``, ``'Int16'``, ``'Int32'``, | :ref:`integer_na` | -| | | | | ``'Int64'``, ``'UInt8'``, ``'UInt16'``, | | -| | | | | ``'UInt32'``, ``'UInt64'`` | | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -| Strings | :class:`StringDtype` | :class:`str` | :class:`arrays.StringArray` | ``'string'`` | :ref:`text` | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ -| Boolean (with NA)| :class:`BooleanDtype` | :class:`bool` | :class:`arrays.BooleanArray` | ``'boolean'`` | :ref:`api.arrays.bool` | -+------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Kind of Data | Data Type | Scalar | Array | String Aliases | Documentation | ++===================+===========================+====================+===============================+=========================================+===============================+ +| tz-aware datetime | :class:`DatetimeTZDtype` | :class:`Timestamp` | :class:`arrays.DatetimeArray` | ``'datetime64[ns, ]'`` | :ref:`timeseries.timezone` | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Categorical | :class:`CategoricalDtype` | (none) | :class:`Categorical` | ``'category'`` | :ref:`categorical` | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| period | :class:`PeriodDtype` | :class:`Period` | :class:`arrays.PeriodArray` | ``'period[]'``, | :ref:`timeseries.periods` | +| (time spans) | | | | ``'Period[]'`` | | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| sparse | :class:`SparseDtype` | (none) | :class:`SparseArray` | ``'Sparse'``, ``'Sparse[int]'``, | :ref:`sparse` | +| | | | | ``'Sparse[float]'`` | | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| intervals | :class:`IntervalDtype` | :class:`Interval` | :class:`arrays.IntervalArray` | ``'interval'``, ``'Interval'``, | :ref:`advanced.intervalindex` | +| | | | | ``'Interval[]'``, | | +| | | | | ``'Interval[datetime64[ns, ]]'``, | | +| | | | | ``'Interval[timedelta64[]]'`` | | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| nullable integer + :class:`Int64Dtype`, ... | (none) | :class:`arrays.IntegerArray` | ``'Int8'``, ``'Int16'``, ``'Int32'``, | :ref:`integer_na` | +| | | | | ``'Int64'``, ``'UInt8'``, ``'UInt16'``, | | +| | | | | ``'UInt32'``, ``'UInt64'`` | | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Strings | :class:`StringDtype` | :class:`str` | :class:`arrays.StringArray` | ``'string'`` | :ref:`text` | ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ +| Boolean (with NA) | :class:`BooleanDtype` | :class:`bool` | :class:`arrays.BooleanArray` | ``'boolean'`` | :ref:`api.arrays.bool` | ++-----------------0-+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ Pandas has two ways to store strings. From 7011988145b841bf8948a691177dccab5da0d38a Mon Sep 17 00:00:00 2001 From: Irv Lustig Date: Fri, 3 Jan 2020 07:45:24 -0500 Subject: [PATCH 4/4] fix typo in last line of dtype table --- doc/source/getting_started/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/basics.rst b/doc/source/getting_started/basics.rst index 3e1e1d495be28..f47fa48eb6202 100644 --- a/doc/source/getting_started/basics.rst +++ b/doc/source/getting_started/basics.rst @@ -1966,7 +1966,7 @@ documentation sections for more on each type. | Strings | :class:`StringDtype` | :class:`str` | :class:`arrays.StringArray` | ``'string'`` | :ref:`text` | +-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ | Boolean (with NA) | :class:`BooleanDtype` | :class:`bool` | :class:`arrays.BooleanArray` | ``'boolean'`` | :ref:`api.arrays.bool` | -+-----------------0-+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ ++-------------------+---------------------------+--------------------+-------------------------------+-----------------------------------------+-------------------------------+ Pandas has two ways to store strings.