From 734d01843c24133c19d424ce0506f0b1518331b3 Mon Sep 17 00:00:00 2001 From: Andy Hayden Date: Wed, 12 Jun 2013 03:51:40 +0100 Subject: [PATCH 1/4] DOC add to_datetime to api.rst --- doc/source/api.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index a4be0df5f489e..7e863a4429487 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -126,7 +126,7 @@ Data manipulations merge concat -Top-level Missing Data +Top-level missing data ~~~~~~~~~~~~~~~~~~~~~~ .. currentmodule:: pandas.core.common @@ -137,6 +137,17 @@ Top-level Missing Data isnull notnull +Top-level dealing with datetimes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: pandas.tseries.tools + +.. autosummary:: + :toctree: generated/ + + to_datetime + + Standard moving window functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 0870ad3d15e9713097c4b648ce54c410c2faea44 Mon Sep 17 00:00:00 2001 From: Andy Hayden Date: Fri, 14 Jun 2013 03:01:11 +0100 Subject: [PATCH 2/4] WIP some to_datetime docs additions --- doc/source/timeseries.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index f8d1e8323b9f5..53a5441e0cb23 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -110,6 +110,37 @@ scalar values and ``PeriodIndex`` for sequences of spans. Better support for irregular intervals with arbitrary start and end points are forth-coming in future releases. + +.. _timeseries.converting: + +Converting to Timestamps +------------------------ + +To convert a list or Series of datetimes or strings (or a mixture, or NAs), +you can use the ``to_datetime`` function: + +.. ipython:: python + + pd.to_datetime(['Jul 31, 2009', '2010-01-10']) + + pd.to_datetime(['2005/11/23', '2010.12.31'']) + +If you use dates start with the dayfirst (European style), you can pass +the dayfirst flag: + +.. ipython:: python + + to_datetime(['12-13-2012'], dayfirst=True) + +*There is a known bug that this falls back to not dayfirst if there are +inconsistent date formats.* + +Pass ``coerce=True`` to convert data to ``NaT`` (not a time): + +.. ipython:: python + + pd.to_datetime(['2009-07-31', 'asd'], coerce=True) + .. _timeseries.daterange: Generating Ranges of Timestamps From fcfe3f3f9dc2a61781200c9bf4b3f2d6f2f7b642 Mon Sep 17 00:00:00 2001 From: Andy Hayden Date: Tue, 18 Jun 2013 02:51:16 +0100 Subject: [PATCH 3/4] WIP to_datetime docs more rewriting --- doc/source/timeseries.rst | 47 ++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 11 deletions(-) diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index 53a5441e0cb23..1d22944d72cc3 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -116,30 +116,55 @@ future releases. Converting to Timestamps ------------------------ -To convert a list or Series of datetimes or strings (or a mixture, or NAs), -you can use the ``to_datetime`` function: +To convert a Series or list-like object of date-like objects e.g. strings, +epochs, or a mixture, you can use the ``to_datetime`` function. When passed +a Series, this returns a Series (with the same index), whilst a list-like +is converted to a DatetimeIndex: .. ipython:: python - pd.to_datetime(['Jul 31, 2009', '2010-01-10']) + to_datetime(Series(['Jul 31, 2009', '2010-01-10', None])) - pd.to_datetime(['2005/11/23', '2010.12.31'']) + to_datetime(['2005/11/23', '2010.12.31']) -If you use dates start with the dayfirst (European style), you can pass -the dayfirst flag: +If you use dates which start with the day first (i.e. European style), +you can pass the ``dayfirst`` flag: .. ipython:: python - to_datetime(['12-13-2012'], dayfirst=True) + to_datetime(['04-01-2012 10:00'], dayfirst=True) -*There is a known bug that this falls back to not dayfirst if there are -inconsistent date formats.* + to_datetime(['14-01-2012', '01-14-2012'], dayfirst=True) + +.. warning:: + + You see in the above example that ``dayfirst`` isn't strict, so if a date + can't be parsed with the day being first it will be parsed as if + ``dayfirst`` were False. + + +Pass ``coerce=True`` to convert bad data to ``NaT`` (not a time): + +.. ipython:: python + + to_datetime(['2009-07-31', 'asd']) + + to_datetime(['2009-07-31', 'asd'], coerce=True) + +It's also possible to convert integer or float epoch times. The default unit +for these is nanoseconds (since these are how Timestamps are stored). However, +often epochs are stored in another ``unit`` which can be specified: -Pass ``coerce=True`` to convert data to ``NaT`` (not a time): .. ipython:: python - pd.to_datetime(['2009-07-31', 'asd'], coerce=True) + to_datetime([1]) + + to_datetime([1, 3.14], unit='s') + +.. note:: + + Epoch times will be rounded to the nearest nanosecond. .. _timeseries.daterange: From e5078a6de6d00e6f1ef6df70f8bba764a09b25b0 Mon Sep 17 00:00:00 2001 From: Andy Hayden Date: Wed, 19 Jun 2013 03:09:43 +0100 Subject: [PATCH 4/4] FIX final tweaks --- doc/source/timeseries.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index 1d22944d72cc3..f11bf60549d93 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -118,7 +118,7 @@ Converting to Timestamps To convert a Series or list-like object of date-like objects e.g. strings, epochs, or a mixture, you can use the ``to_datetime`` function. When passed -a Series, this returns a Series (with the same index), whilst a list-like +a Series, this returns a Series (with the same index), while a list-like is converted to a DatetimeIndex: .. ipython:: python @@ -166,6 +166,12 @@ often epochs are stored in another ``unit`` which can be specified: Epoch times will be rounded to the nearest nanosecond. +Take care, ``to_datetime`` may not act as you expect on mixed data: + +.. ipython:: python + + pd.to_datetime([1, '1']) + .. _timeseries.daterange: Generating Ranges of Timestamps