Skip to content

Commit 1381e51

Browse files
Merge pull request #10589 from bashtage/convert-objects-doc-fix
DOC: Small improvement to convert_objects doc
2 parents b3c338d + 84781f1 commit 1381e51

File tree

2 files changed

+24
-21
lines changed

2 files changed

+24
-21
lines changed

doc/source/basics.rst

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1528,12 +1528,14 @@ object conversion
15281528
:ref:`API changes <whatsnew_0170.api_breaking.convert_objects>`
15291529
for more details.
15301530

1531-
:meth:`~DataFrame.convert_objects` is a method to try to force conversion of
1532-
types from the ``object`` dtype to other types. To try converting specific
1533-
types that are *number like*, e.g. could be a string that represents a number,
1534-
pass ``numeric=True``. To force the conversion, add the keyword argument
1535-
``coerce=True``. This will force strings and number-like objects to be numbers if
1536-
possible, otherwise they will be set to ``np.nan``.
1531+
:meth:`~DataFrame.convert_objects` is a method that converts columns from
1532+
the ``object`` dtype to datetimes, timedeltas or floats. For example, to
1533+
attempt conversion of object data that are *number like*, e.g. could be a
1534+
string that represents a number, pass ``numeric=True``. By default, this will
1535+
attempt a soft conversion and so will only succeed if the entire column is
1536+
convertible. To force the conversion, add the keyword argument ``coerce=True``.
1537+
This will force strings and number-like objects to be numbers if
1538+
possible, and other values will be set to ``np.nan``.
15371539

15381540
.. ipython:: python
15391541
@@ -1549,7 +1551,7 @@ possible, otherwise they will be set to ``np.nan``.
15491551
To force conversion to ``datetime64[ns]``, pass ``datetime=True`` and ``coerce=True``.
15501552
This will convert any datetime-like object to dates, forcing other values to ``NaT``.
15511553
This might be useful if you are reading in data which is mostly dates,
1552-
but occasionally has non-dates intermixed and you want to represent as missing.
1554+
but occasionally contains non-dates that you wish to represent as missing.
15531555

15541556
.. ipython:: python
15551557

doc/source/whatsnew/v0.17.0.txt

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -80,16 +80,16 @@ Other enhancements
8080

8181
.. _whatsnew_0170.api:
8282

83-
Backwards incompatible API changes
84-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85-
8683
.. _whatsnew_0170.api_breaking:
8784

88-
.. _whatsnew_0170.api_breaking.other:
85+
Backwards incompatible API changes
86+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8987

90-
.. _whatsnew_0170.api_breaking.convert_objects:
9188
Changes to convert_objects
9289
^^^^^^^^^^^^^^^^^^^^^^^^^^
90+
91+
.. _whatsnew_0170.api_breaking.convert_objects:
92+
9393
- ``DataFrame.convert_objects`` keyword arguments have been shortened. (:issue:`10265`)
9494

9595
===================== =============
@@ -101,8 +101,8 @@ Old New
101101
===================== =============
102102

103103
- Coercing types with ``DataFrame.convert_objects`` is now implemented using the
104-
keyword argument ``coerce=True``. Previously types were coerced by setting a
105-
keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coerce'``.
104+
keyword argument ``coerce=True``. Previously types were coerced by setting a
105+
keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coerce'``.
106106

107107
.. ipython:: python
108108

@@ -125,7 +125,7 @@ keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coe
125125
df.convert_objects(numeric=True, coerce=True)
126126

127127
- In earlier versions of pandas, ``DataFrame.convert_objects`` would not coerce
128-
numeric types when there were no values convertible to a numeric type. For example,
128+
numeric types when there were no values convertible to a numeric type. For example,
129129

130130
.. code-block:: python
131131

@@ -136,21 +136,22 @@ numeric types when there were no values convertible to a numeric type. For exam
136136
0 a
137137
1 b
138138

139-
returns the original DataFrame with no conversion. This change alters
140-
this behavior so that
139+
returns the original DataFrame with no conversion. This change alters
140+
this behavior so that
141141

142142
.. ipython:: python
143143

144144
pd.DataFrame({'s': ['a','b']})
145145
df.convert_objects(numeric=True, coerce=True)
146146

147-
converts all non-number-like strings to ``NaN``.
147+
converts all non-number-like strings to ``NaN``.
148148

149149
- In earlier versions of pandas, the default behavior was to try and convert
150-
datetimes and timestamps. The new default is for ``DataFrame.convert_objects``
151-
to do nothing, and so it is necessary to pass at least one conversion target
152-
in the method call.
150+
datetimes and timestamps. The new default is for ``DataFrame.convert_objects``
151+
to do nothing, and so it is necessary to pass at least one conversion target
152+
in the method call.
153153

154+
.. _whatsnew_0170.api_breaking.other:
154155

155156
Other API Changes
156157
^^^^^^^^^^^^^^^^^

0 commit comments

Comments
 (0)