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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index f8d1e8323b9f5..f11bf60549d93 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -110,6 +110,68 @@ 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 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), while a list-like +is converted to a DatetimeIndex: + +.. ipython:: python + + to_datetime(Series(['Jul 31, 2009', '2010-01-10', None])) + + to_datetime(['2005/11/23', '2010.12.31']) + +If you use dates which start with the day first (i.e. European style), +you can pass the ``dayfirst`` flag: + +.. ipython:: python + + to_datetime(['04-01-2012 10:00'], dayfirst=True) + + 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: + + +.. ipython:: python + + to_datetime([1]) + + to_datetime([1, 3.14], unit='s') + +.. note:: + + 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