DOC: 'MS' offset alias does not work as described with pd.date_range()

[JamesSciberras]

• I have checked that the issue still exists on the latest versions of the docs on master here

Location of the documentation

https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases

Documentation problem

The current documentation for the MS offset alias reads as follows: "month start frequency", indicating that it is the complement of M (which is "month end frequency").

However, for any date supplied to pd.date_range(start=[date], ... freq='MS') other than the first of the month, this offset alias starts from the beginning of the next month. See this StackOverflow post (second answer) for a more detailed explanation.

However, in brief:

start = "2020-03-08"
end = "2021-03-08"
pd.date_range(start, end, freq='MS')

gives

DatetimeIndex(['2020-04-01', '2020-05-01', '2020-06-01', '2020-07-01',
           '2020-08-01', '2020-09-01', '2020-10-01', '2020-11-01',
           '2020-12-01', '2021-01-01', '2021-02-01', '2021-03-01'],
          dtype='datetime64[ns]', freq='MS')

It should be noted that supplying the first day of the month as the start date keeps the expected behaviour (i.e. the start point of the range is the first of the month supplied).

Suggested fix for documentation

If the behaviour of the MS offset alias is indeed correct (i.e. to start at the beginning of the next month), then this should be indicated in the documentation with a note.

For example:
"""
MS = month start frequency. Note, for any day other than the first day of the month this will cause the offset to start at the beginning of the next month.
"""

The above explanation correctly encapsulates the current functionality of the MS offset, especially within pd.date_range(). The current documentation would incorrectly lead a person to believe that the MS offset would cause the start date to be the start of the month of the date supplied.

If this behaviour is not correct, and MS should be causing the start date to be the start of the month of the date supplied, then a subsequent bug would need to be raised.

[loicdiridollou]

Looking at the documentation, correct me if I am wrong, but it still looks quite intuitive.
The date_range function will just extract the timestamps corresponding to a certain frequency like MS in the interval [start_date, end_date]. I don't see a rationale that the function will return a timestamp that is outside of the interval, but happy to discuss that point and better understand your point @JamesSciberras.
I have made a PR to add a little note after the paragraph tackling more globally this question, please ditch it if it is just crowding the documentation and not adding real value.

[JamesSciberras]

Thanks for your response @loicdiridollou. My main issue with this, is that if I was to supply a date in the middle of the month, for example today 2021-11-22, and use the MS interval, I would assume that the first entry of this interval period would be the start of the month that I am in, i.e. 2021-11-01. However, instead the interval would begin on the first day of the next month, i.e. 2021-12-01.

This might be correct behaviour, but it is not an intuitive assumption to make. Thank you for making the PR - I think that does help clarify things a bit further!

Thank you for taking the time today, and please let me know if you wish to discuss further!

[loicdiridollou]

I think the way it was built was to say "we are taking the intersection between the interval [start_date, end_date] and the set of timestamps corresponding to the frequency given.
In your reasoning, why would you take the timestamp of the first of the month before the start_date, that is where I am having a little trouble following your idea. We pass a start_date argument to tell the function not to return dates before that, or at least this is how I think of it. Because once you allow to return values outside of the interval, it opens the door to a many more questions like yours, why when choosing the M frequency it does not return the timestamp of the end of the month even if you passed 2021-11-22 as end_date. It would make the function much less predictable I guess, I hope I am clear enough!

[JamesSciberras]

My reasoning is that MS (i.e. "month start") would provide the first of the month of whatever date is passed in. There are situations where you would be passing in dates and want to effectively floor it to the beginning of the month. I was basing this on the name of the frequency parameter, and the fact that it was presented as the converse to M which mkaes the date the last date of the month.

I understand that this was my misinterpretation of the function, but since there were other similar comments on StackOverflow I thought might be useful to clarify it.

Thank you for your time and help, and I hope the PR goes through!