diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst index dd13e8fabf0e9..7e96fdad29193 100644 --- a/doc/source/timeseries.rst +++ b/doc/source/timeseries.rst @@ -1753,22 +1753,56 @@ TZ aware Dtypes .. versionadded:: 0.17.0 -``Series/DatetimeIndex`` with a timezone naive value are represented with a dtype of ``datetime64[ns]``. +``Series/DatetimeIndex`` with a timezone **naive** value are represented with a dtype of ``datetime64[ns]``. .. ipython:: python - dr = pd.date_range('20130101',periods=3) - dr - s = Series(dr) - s + dr_naive = pd.date_range('20130101',periods=3) + dr_naive + s_naive = Series(dr_naive) + s_naive -``Series/DatetimeIndex`` with a timezone aware value are represented with a dtype of ``datetime64[ns, tz]``. +``Series/DatetimeIndex`` with a timezone **aware** value are represented with a dtype of ``datetime64[ns, tz]``. .. ipython:: python - dr = pd.date_range('20130101',periods=3,tz='US/Eastern') - dr - s = Series(dr) - s + dr_aware = pd.date_range('20130101',periods=3,tz='US/Eastern') + dr_aware + s_aware = Series(dr_aware) + s_aware + +Both of these ``Series`` can be manipulated via the ``.dt`` accessor, see :ref:`here `. +See the :ref:`docs ` for more details. + +Further more you can ``.astype(...)`` timezone aware (and naive). + +.. ipython:: python + + # make this naive + s_aware.astype('datetime64[ns]') + + # convert + s_aware.astype('datetime64[ns, CET]') + s_naive.astype('datetime64[ns, CET]') + +.. note:: + + Using the ``.values`` accessor on a ``Series``, returns an numpy array of the data. + These values are converted to UTC, as numpy does not currently support timezones (even though it is *printing* in the local timezone!). + + .. ipython:: python + + s_naive.values + s_aware.values + + Further note that once converted to a numpy array these would lose the tz tenor. + + .. ipython:: python + + Series(s_aware.values) + + However, these can be easily converted + + .. ipython:: python -Both of these ``Series`` can be manipulated via the ``.dt`` accessor, see the :ref:`docs ` as well. + Series(s_aware).dt.tz_localize('UTC').dt.tz_convert('US/Eastern') diff --git a/doc/source/whatsnew/v0.17.0.txt b/doc/source/whatsnew/v0.17.0.txt index f88e5c0a11f9f..9eb005a604b0c 100644 --- a/doc/source/whatsnew/v0.17.0.txt +++ b/doc/source/whatsnew/v0.17.0.txt @@ -447,9 +447,9 @@ Datetime with TZ We are adding an implementation that natively supports datetime with timezones. A ``Series`` or a ``DataFrame`` column previously *could* be assigned a datetime with timezones, and would work as an ``object`` dtype. This had performance issues with a large -number rows. (:issue:`8260`, :issue:`10763`) +number rows. See the :ref:`docs ` for more details. (:issue:`8260`, :issue:`10763`). -The new implementation allows for having a single-timezone across all rows, and operating on it in a performant manner. +The new implementation allows for having a single-timezone across all rows, with operations in a performant manner. .. ipython:: python @@ -469,13 +469,15 @@ This uses a new-dtype representation as well, that is very similar in look-and-f .. ipython:: python df['B'].dtype - type(df['B']).dtype + type(df['B'].dtype) .. note:: There is a slightly different string repr for the underlying ``DatetimeIndex`` as a result of the dtype changes, but functionally these are the same. + Previous Behavior: + .. code-block:: python In [1]: pd.date_range('20130101',periods=3,tz='US/Eastern') @@ -486,12 +488,13 @@ This uses a new-dtype representation as well, that is very similar in look-and-f In [2]: pd.date_range('20130101',periods=3,tz='US/Eastern').dtype Out[2]: dtype('