DOC: Update DateOffset intro in timeseries.rst #23385

mroeschke · 2018-10-27T22:52:27Z

Updated timeseries.rst introduction to DateOffsets

Explain relationship with Timedelta
Clarify explanation of rollforward/back
Bring all the offsets and their aliases to the front

Misc fixes:

Period dtypes are preserved in Series & DataFrames
Rendering for timezone nonexistent examples

mroeschke · 2018-10-27T22:54:10Z

mroeschke · 2018-10-27T22:55:03Z

@datapythonista if you could have a look

codecov · 2018-10-27T23:33:53Z

Codecov Report

Merging #23385 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #23385   +/-   ##
=======================================
  Coverage   92.24%   92.24%           
=======================================
  Files         161      161           
  Lines       51318    51318           
=======================================
  Hits        47339    47339           
  Misses       3979     3979

Flag	Coverage Δ
#multiple	`90.63% <ø> (ø)`	⬆️
#single	`42.31% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/dtypes/common.py	`94.37% <0%> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fe52d9f...1f159b1. Read the comment docs.

datapythonista

Looks good, added some comments.

It's probably worth that @jbrockmendel takes a look too.

datapythonista · 2018-10-28T01:17:00Z

doc/source/timeseries.rst

@@ -8,6 +8,7 @@
   import numpy as np
   import pandas as pd
   from pandas import offsets
+   from pandas.tseries.offsets import *


I'd avoid importing star even in the documentation.

datapythonista · 2018-10-28T01:18:32Z

doc/source/timeseries.rst

-:class:`Series` and :class:`DataFrame` have extended data type support and functionality for ``datetime`` and ``timedelta``
-data when the time data is used as data itself. The ``Period`` and ``DateOffset`` data will be stored as ``object`` data.
+:class:`Series` and :class:`DataFrame` have extended data type support and functionality for ``datetime``, ``timedelta``
+and ``Period`` data when the time data is used as data itself. The ``DateOffset`` data will be stored as ``object`` data.


I find the "when the time data is used as data itself" not very clear

datapythonista · 2018-10-28T01:25:00Z

doc/source/timeseries.rst

-Subclasses of ``DateOffset`` define the ``apply`` function which dictates
-custom date increment logic, such as adding business days:
+These frequency strings map to a :class:`DateOffset` object and its subclasses. A :class:`DateOffset`
+is similar to a :class:`Timedelta` that represents a duration of time but follows specific calendar duration rules.


I think an example (explaining, not code) would be helpful here. What calendar duration rules means can not be so obvious. Just saying that in one case we are adding 24 hours, and in the other we are going to the same time of the next day, even if that can be 23 or 25 hours, would make this much clearer I think.

datapythonista · 2018-10-28T01:29:59Z

doc/source/timeseries.rst

@@ -968,6 +964,7 @@ particular day of the week:

 .. ipython:: python

+   d = datetime(2008, 8, 18, 9, 0)


I personally prefer to import datetime, and then use datetime.datetime(...). I think it's more explicit, and better to import modules directly.

jreback · 2018-10-28T02:38:17Z

doc/source/timeseries.rst

-	"""DateOffset increments between business days"""
-        def apply(self, other):
-            ...
+The basic :class:`DateOffset` acts similar to ``dateutil.relativedelta`` that shifts a date time


can you add a link to dateutil docs for this

jreback · 2018-10-28T02:38:46Z

doc/source/timeseries.rst

-It's definitely worth exploring the ``pandas.tseries.offsets`` module and the
-various docstrings for the classes.
+   # This particular day contains a day light savings time transition
+   ts = pd.Timestamp('2016-10-30 00:00:00', tz='Europe/Helsinki')


I would put this section on DST a bit lower, as you really should explain DateOffsets first

mroeschke · 2018-10-28T19:52:49Z

Updated based on the review.

Also change the page's from datetime import datetime, timedelta, time to import datetime and offsets are called like pd.offsets.* instead of them getting start imported from the top.

jbrockmendel · 2018-10-28T20:43:55Z

doc/source/timeseries.rst

-:class:`Series` and :class:`DataFrame` have extended data type support and functionality for ``datetime`` and ``timedelta``
-data when the time data is used as data itself. The ``Period`` and ``DateOffset`` data will be stored as ``object`` data.
+:class:`Series` and :class:`DataFrame` have extended data type support and functionality for ``datetime``, ``timedelta``
+and ``Period`` data when passed into those constructors. ``DateOffset``


May need to be careful about this, as Period only supports a subset of DateOffsets, which has caused confusion in the past.

Good to know. This section is more describing what dtypes are supported by Series and DataFrames (i.e. Period dtype is supported but not DateOffset (since it doesnt really have its own data type))

jreback · 2018-10-30T12:21:49Z

can you post a rendering of this?

mroeschke · 2018-10-30T16:59:32Z

jorisvandenbossche

Thanks for working on this!

doc/source/timeseries.rst

jorisvandenbossche · 2018-10-30T16:47:02Z

doc/source/timeseries.rst

+is similar to a :class:`Timedelta` that represents a duration of time but follows specific calendar duration rules.
+For example, a :class:`Timedelta` day will always increment ``datetimes`` by 24 hours, while a :class:`DateOffset` day
+will increment ``datetimes`` to the same time the next day whether a day represents 23, 24 or 25 hours due to daylight
+savings time. However, the following date offsets behave like :class:`Timedelta` and respect absolute time:


I would explain the logic of this list: all offsets of an hour or smaller

(and maybe just put them in running text instead of a list)

jreback · 2018-10-31T12:27:21Z

lgtm.

jreback · 2018-11-03T14:25:59Z

over to you @jorisvandenbossche

datapythonista

lgtm

jorisvandenbossche

some small comments

jorisvandenbossche · 2018-11-05T09:56:58Z

doc/source/timeseries.rst

+   # Bring the date to the closest offset date (Monday)
+   offset.rollforward(ts)
+   # Date is brought to the closest offset date first and then the hour is added
+   ts + offset


I didn't directly understand this difference between rollforward and addition based on this example. Would it be worth expanding more on it?

I think this example is fairly clear when rendered. Feel free to let me know what part isn't totally clear

jorisvandenbossche · 2018-11-05T09:58:24Z

doc/source/timeseries.rst


 .. ipython:: python

   ts = pd.Timestamp('2014-01-01 09:00')
-   day = Day()
+   day = pd.offsets.Day()
   day.apply(ts)


apply has not yet been explained (it was there before above, but in a part you deleted)

Good point. Added this in an earlier section.

jorisvandenbossche · 2018-11-05T10:02:56Z

doc/source/timeseries.rst

-  increment will be applied multiple times.
-* It has :meth:`~pandas.DateOffset.rollforward` and
-  :meth:`~pandas.DateOffset.rollback` methods for moving a date forward or 
-  backward to the next or previous "offset date".


I have the feeling this summary list had some value as well. Should we keep it?

I demonstrated the first two points in examples above and I think I clarified rollback and rollforward a lot better in its own section.

mroeschke · 2018-11-14T19:39:04Z

@jorisvandenbossche any additional comments?

jreback · 2018-11-23T03:19:04Z

@jorisvandenbossche

datapythonista · 2018-11-26T14:46:09Z

@jorisvandenbossche do you mind checking if your comments have been addressed and this can be merged? We're making other changes to timeseries.rst and would be nice to avoid conflicts as much as possible.

mroeschke · 2018-11-30T23:31:28Z

I'll push this in tomorrow if there are no other comments. I can always follow up after merging this PR.

datapythonista · 2018-12-01T23:37:42Z

thanks @mroeschke

Matt Roeschke added 2 commits October 27, 2018 15:45

Update DateOffset intro section

d3a2438

add explaination to frequency strings

d2b252f

gfyoung added Timedelta Timedelta data type 2/3 Compat Docs and removed 2/3 Compat labels Oct 27, 2018

mroeschke added the Frequency DateOffsets label Oct 28, 2018

datapythonista reviewed Oct 28, 2018

View reviewed changes

jreback reviewed Oct 28, 2018

View reviewed changes

Matt Roeschke added 2 commits October 28, 2018 09:34

Merge remote-tracking branch 'upstream/master' into offset_intro

d97917c

address review

5e3f45e

jbrockmendel reviewed Oct 28, 2018

View reviewed changes

Merge remote-tracking branch 'upstream/master' into offset_intro

71dc876

jorisvandenbossche reviewed Oct 30, 2018

View reviewed changes

Address_comments

a4535c0

jreback added this to the 0.24.0 milestone Oct 31, 2018

datapythonista approved these changes Nov 4, 2018

View reviewed changes

jorisvandenbossche reviewed Nov 5, 2018

View reviewed changes

Matt Roeschke added 3 commits November 5, 2018 22:04

address comments

fffadd9

Merge remote-tracking branch 'upstream/master' into offset_intro

491cc08

Merge remote-tracking branch 'upstream/master' into offset_intro

d2cc84f

Matt Roeschke added 5 commits November 10, 2018 17:53

Merge remote-tracking branch 'upstream/master' into offset_intro

a9bbbb5

Merge remote-tracking branch 'upstream/master' into offset_intro

4481a1e

Merge remote-tracking branch 'upstream/master' into offset_intro

f33bbd0

Merge remote-tracking branch 'upstream/master' into offset_intro

331eb51

Merge remote-tracking branch 'upstream/master' into offset_intro

1f159b1

mroeschke mentioned this pull request Nov 25, 2018

DOC: Fix PEP-8 issues in timeseries.rst #23898

Merged

datapythonista merged commit b45eb26 into pandas-dev:master Dec 1, 2018

mroeschke deleted the offset_intro branch December 2, 2018 02:09

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Update DateOffset intro in timeseries.rst (pandas-dev#23385)

c28a7d5

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Update DateOffset intro in timeseries.rst (pandas-dev#23385)

d068393

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Update DateOffset intro in timeseries.rst #23385

DOC: Update DateOffset intro in timeseries.rst #23385

mroeschke commented Oct 27, 2018

mroeschke commented Oct 27, 2018

mroeschke commented Oct 27, 2018

codecov bot commented Oct 27, 2018 •

edited

Loading

datapythonista left a comment

datapythonista Oct 28, 2018

datapythonista Oct 28, 2018

datapythonista Oct 28, 2018

datapythonista Oct 28, 2018

jreback Oct 28, 2018

jreback Oct 28, 2018

mroeschke commented Oct 28, 2018

jbrockmendel Oct 28, 2018

mroeschke Oct 29, 2018

jreback commented Oct 30, 2018

mroeschke commented Oct 30, 2018

jorisvandenbossche left a comment

jorisvandenbossche Oct 30, 2018

jreback commented Oct 31, 2018

jreback commented Nov 3, 2018

datapythonista left a comment

jorisvandenbossche left a comment

jorisvandenbossche Nov 5, 2018

mroeschke Nov 6, 2018

jorisvandenbossche Nov 5, 2018

mroeschke Nov 6, 2018

jorisvandenbossche Nov 5, 2018

mroeschke Nov 6, 2018

mroeschke commented Nov 14, 2018

jreback commented Nov 23, 2018

datapythonista commented Nov 26, 2018

mroeschke commented Nov 30, 2018

datapythonista commented Dec 1, 2018

		@@ -968,6 +964,7 @@ particular day of the week:

		.. ipython:: python

		d = datetime(2008, 8, 18, 9, 0)

DOC: Update DateOffset intro in timeseries.rst #23385

DOC: Update DateOffset intro in timeseries.rst #23385

Conversation

mroeschke commented Oct 27, 2018

mroeschke commented Oct 27, 2018

mroeschke commented Oct 27, 2018

codecov bot commented Oct 27, 2018 • edited Loading

Codecov Report

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mroeschke commented Oct 28, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Oct 30, 2018

mroeschke commented Oct 30, 2018

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Oct 31, 2018

jreback commented Nov 3, 2018

datapythonista left a comment

Choose a reason for hiding this comment

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mroeschke commented Nov 14, 2018

jreback commented Nov 23, 2018

datapythonista commented Nov 26, 2018

mroeschke commented Nov 30, 2018

datapythonista commented Dec 1, 2018

codecov bot commented Oct 27, 2018 •

edited

Loading