Skip to content

DOC: update the Period.dayofyear docstring #20277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 13, 2018
Merged

DOC: update the Period.dayofyear docstring #20277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d3691ea
Update the Period.dayofyear docstring
techytushar Mar 11, 2018
6ff8d46
see also to .day
jorisvandenbossche Mar 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions pandas/_libs/tslibs/period.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1255,6 +1255,36 @@ cdef class _Period(object):

@property
def dayofyear(self):
"""
Return the day of the year.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Periods represent time spans so it's good to note that this is the start of the period. So maybe

Return the day of the year the of the Period's start.

That's a bit wordy though. Feel free to reword if you have a better phrasing.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, but I didn't understand the meaning of the sentence Return the day of the year the of the Period's start., specifically of the period's start

Copy link
Contributor

@TomAugspurger TomAugspurger Mar 12, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Period is a span, so saying "Day of the year" is a bit ambiguous. Is it the start, end, somewhere in between?

If you have a period like `Period('2017-01-01', freq='A')

In [2]: pd.Period('2017-01-01', freq='A')
Out[2]: Period('2017', 'A-DEC')

In [3]: pd.Period('2017-01-01', freq='A').day
Out[3]: 31

I was apparently wrong about it always being the start. I guess it's related to freq

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment will be relevant to many of the Period attributes like day, dayofyear, .. (also the ones I already merged ..).
So it would be good to be consistent in it.

The annual frequency is by default a "year-end" frequency, so it's indeed freq related.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry, I don't follow... Can you show two cases creating a period starting on the same day but with different frequencies, and how this affect .day, .dayofweek, .dayofyear, etc.?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dukebody small example:

In [30]: p1 = pd.Period('2017-01-01', freq='D')

In [31]: p2 = pd.Period('2017-01-01', freq='M')

In [32]: p1
Out[32]: Period('2017-01-01', 'D')

In [33]: p2
Out[33]: Period('2017-01', 'M')

In [34]: p1.start_time
Out[34]: Timestamp('2017-01-01 00:00:00')

In [35]: p2.start_time
Out[35]: Timestamp('2017-01-01 00:00:00')

In [36]: p1.dayofyear
Out[36]: 1

In [37]: p2.dayofyear
Out[37]: 31

I am not really familiar with this frequency business, but you have certain frequences which are "anchored" at the beginning of the period, and others at the end of the period. But I don't directly see a way how to inspect this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's quite confusing. Should we open a ticket to make .dayofyear etc. always refer to the start time of the period? Not to the "anchored" time. Otherwise these functions are very unpredictable IMO and therefore don't add a lot of value.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I am writing one currently ;)
I suppose those attributes will mainly be useful for frequencies <= 1D

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with merging this PR without referring to the start or end date of the period, and then work on code to make this predictable and change all docstrings to refer to the period start date.


This attribute returns the day of the year on which the particular
date occurs. The return value ranges between 1 to 365 for regular
years and 1 to 366 for leap years.

Returns
-------
int
The day of year.

See Also
--------
Period.day : Return the day of the month.
Period.dayofweek : Return the day of week.
PeriodIndex.dayofyear : Return the day of year of all indexes.

Examples
--------
>>> period = pd.Period("2015-10-23", freq='H')
>>> period.dayofyear
296
>>> period = pd.Period("2012-12-31", freq='D')
>>> period.dayofyear
366
>>> period = pd.Period("2013-01-01", freq='D')
>>> period.dayofyear
1
"""
base, mult = get_freq_code(self.freq)
return pday_of_year(self.ordinal, base)

Expand Down