Monthly
=======

The package ``warsa.timeseries.monthly`` creates monthly or multi-monthly time series.

Imports necessary for the examples below:

.. code-block:: python

	import datetime
	import numpy as np
	import pandas as pd
	from warsa.timeseries import monthly

Generating a one year daily date range starting at 07:30:

.. code-block:: python

    dtid = pd.date_range('2015-11-01 07:30', periods=365, freq='D')

Output::

	DatetimeIndex(['2015-11-01 07:30:00', '2015-11-02 07:30:00',
			   '2015-11-03 07:30:00', '2015-11-04 07:30:00',
			   '2015-11-05 07:30:00', '2015-11-06 07:30:00',
			   '2015-11-07 07:30:00', '2015-11-08 07:30:00',
			   '2015-11-09 07:30:00', '2015-11-10 07:30:00',
			   ...
			   '2016-10-21 07:30:00', '2016-10-22 07:30:00',
			   '2016-10-23 07:30:00', '2016-10-24 07:30:00',
			   '2016-10-25 07:30:00', '2016-10-26 07:30:00',
			   '2016-10-27 07:30:00', '2016-10-28 07:30:00',
			   '2016-10-29 07:30:00', '2016-10-30 07:30:00'],
			  dtype='datetime64[ns]', length=365, freq='D') 

Monthly intervals
_________________

The function ``monthly.intervals`` generates a list of tuples (list of lists), 
each tuple containing monthly or multi-monthly intervals of timestamps 
[ts0, ts1], where ts0 <= ts1. Intervals are closed per default. The corresponding
open intervals of ['2000-01-01 07:30, '2000-01-02 07:30] are 
['2000-01-01 07:30:00.000001, '2000-01-02 07:29:59.999999]. Intervals are used 
to slice time series and to aggregate sub-monthly time series to monthly.
 
``monthly.intervals`` can accumulate months forward and backward using 
correspondly positive or negative values accum. It can start the monthly 
time series at any day and time.

.. code-block:: python

    def print_intervals(values, n=2):
        for i in values[:n] + ['...'] + values[-n:]:
            print i
        print
    print dtid, '\n'

    print 'All months in the year, 1 month interval, closed on both sides'
    print_intervals(monthly.intervals(dtid))
    print 'All months in the year, 1 month interval, left open, and right close'
    print_intervals(monthly.intervals(dtid, closed_right=False))
    print 'All months in the year, 1 month interval, left close, and right open'
    print_intervals(monthly.intervals(dtid, closed_left=False))

    print 'All months in the year, 2 month interval, closed on both sides'
    print_intervals(monthly.intervals(dtid, accum=2))
    print 'All months in the year, 2 month interval, left open, and right close'
    print_intervals(monthly.intervals(dtid, accum=2, closed_right=False))
    print 'All months in the year, 2 month interval, left close, and right open'
    print_intervals(monthly.intervals(dtid, accum=2, closed_left=False))

    print 'All months in the year, -2 month interval, closed on both sides'
    print_intervals(monthly.intervals(dtid, accum=-2))
    print 'All months in the year, -2 month interval, left open, and right close'
    print_intervals(monthly.intervals(dtid, accum=-2, closed_right=False))
    print 'All months in the year, -2 month interval, left close, and right open'
    print_intervals(monthly.intervals(dtid, accum=-2, closed_left=False))

    print 'Selected months in the year, 2 month interval, closed on both sides'
    print_intervals(monthly.intervals(dtid, months=[1, 3, 5, 7, 9, 11], accum=2))

    print 'Selected months in the year, 2 month interval, starting at day 5, 12:30:45.555555'
    print_intervals(monthly.intervals(dtid, months=[1, 3, 5, 7, 9, 11], accum=2,
                                      start_at=datetime.datetime(2000, 1, 5, 12, 30, 45, 555555)))
    print 'Selected months in the year, 2 month interval, starting at the beginning of the month'
    print_intervals(monthly.intervals(dtid, months=[1, 3, 5, 7, 9, 11], accum=2, start_at='beg'))
    print 'Selected months in the year, 2 month interval, starting at the end of the month'
    print_intervals(monthly.intervals(dtid, months=[1, 3, 5, 7, 9, 11], accum=2, start_at='end'))


Outputs::

	DatetimeIndex(['2015-11-01 07:30:00', '2015-11-02 07:30:00',
				   '2015-11-03 07:30:00', '2015-11-04 07:30:00',
				   '2015-11-05 07:30:00', '2015-11-06 07:30:00',
				   '2015-11-07 07:30:00', '2015-11-08 07:30:00',
				   '2015-11-09 07:30:00', '2015-11-10 07:30:00',
				   ...
				   '2016-10-21 07:30:00', '2016-10-22 07:30:00',
				   '2016-10-23 07:30:00', '2016-10-24 07:30:00',
				   '2016-10-25 07:30:00', '2016-10-26 07:30:00',
				   '2016-10-27 07:30:00', '2016-10-28 07:30:00',
				   '2016-10-29 07:30:00', '2016-10-30 07:30:00'],
				  dtype='datetime64[ns]', length=365, freq='D') 

	All months in the year, 1 month interval, closed on both sides
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-02-01 00:00:00')]
	[Timestamp('2015-02-01 00:00:00'), Timestamp('2015-03-01 00:00:00')]
	...
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-10-01 00:00:00')]
	[Timestamp('2016-10-01 00:00:00'), Timestamp('2016-11-01 00:00:00')]

	All months in the year, 1 month interval, left open, and right close
	[Timestamp('2015-01-01 00:00:00.000001'), Timestamp('2015-02-01 00:00:00')]
	[Timestamp('2015-02-01 00:00:00.000001'), Timestamp('2015-03-01 00:00:00')]
	...
	[Timestamp('2016-09-01 00:00:00.000001'), Timestamp('2016-10-01 00:00:00')]
	[Timestamp('2016-10-01 00:00:00.000001'), Timestamp('2016-11-01 00:00:00')]

	All months in the year, 1 month interval, left close, and right open
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-01-31 23:59:59.999999')]
	[Timestamp('2015-02-01 00:00:00'), Timestamp('2015-02-28 23:59:59.999999')]
	...
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-09-30 23:59:59.999999')]
	[Timestamp('2016-10-01 00:00:00'), Timestamp('2016-10-31 23:59:59.999999')]

	All months in the year, 2 month interval, closed on both sides
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-03-01 00:00:00')]
	[Timestamp('2015-02-01 00:00:00'), Timestamp('2015-04-01 00:00:00')]
	...
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-11-01 00:00:00')]
	[Timestamp('2016-10-01 00:00:00'), Timestamp('2016-12-01 00:00:00')]

	All months in the year, 2 month interval, left open, and right close
	[Timestamp('2015-01-01 00:00:00.000001'), Timestamp('2015-03-01 00:00:00')]
	[Timestamp('2015-02-01 00:00:00.000001'), Timestamp('2015-04-01 00:00:00')]
	...
	[Timestamp('2016-09-01 00:00:00.000001'), Timestamp('2016-11-01 00:00:00')]
	[Timestamp('2016-10-01 00:00:00.000001'), Timestamp('2016-12-01 00:00:00')]

	All months in the year, 2 month interval, left close, and right open
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-02-28 23:59:59.999999')]
	[Timestamp('2015-02-01 00:00:00'), Timestamp('2015-03-31 23:59:59.999999')]
	...
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-10-31 23:59:59.999999')]
	[Timestamp('2016-10-01 00:00:00'), Timestamp('2016-11-30 23:59:59.999999')]

	All months in the year, -2 month interval, closed on both sides
	[Timestamp('2014-11-01 00:00:00'), Timestamp('2015-01-01 00:00:00')]
	[Timestamp('2014-12-01 00:00:00'), Timestamp('2015-02-01 00:00:00')]
	...
	[Timestamp('2016-07-01 00:00:00'), Timestamp('2016-09-01 00:00:00')]
	[Timestamp('2016-08-01 00:00:00'), Timestamp('2016-10-01 00:00:00')]

	All months in the year, -2 month interval, left open, and right close
	[Timestamp('2014-11-01 00:00:00.000001'), Timestamp('2015-01-01 00:00:00')]
	[Timestamp('2014-12-01 00:00:00.000001'), Timestamp('2015-02-01 00:00:00')]
	...
	[Timestamp('2016-07-01 00:00:00.000001'), Timestamp('2016-09-01 00:00:00')]
	[Timestamp('2016-08-01 00:00:00.000001'), Timestamp('2016-10-01 00:00:00')]

	All months in the year, -2 month interval, left close, and right open
	[Timestamp('2014-11-01 00:00:00'), Timestamp('2014-12-31 23:59:59.999999')]
	[Timestamp('2014-12-01 00:00:00'), Timestamp('2015-01-31 23:59:59.999999')]
	...
	[Timestamp('2016-07-01 00:00:00'), Timestamp('2016-08-31 23:59:59.999999')]
	[Timestamp('2016-08-01 00:00:00'), Timestamp('2016-09-30 23:59:59.999999')]

	Selected months in the year, 2 month interval, closed on both sides
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-03-01 00:00:00')]
	[Timestamp('2015-03-01 00:00:00'), Timestamp('2015-05-01 00:00:00')]
	...
	[Timestamp('2016-07-01 00:00:00'), Timestamp('2016-09-01 00:00:00')]
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-11-01 00:00:00')]

	Selected months in the year, 2 month interval, closed on both sides, starting at day 5, 12:30:45.555555
	[Timestamp('2015-01-05 12:30:45.555555'), Timestamp('2015-03-05 12:30:45.555555')]
	[Timestamp('2015-03-05 12:30:45.555555'), Timestamp('2015-05-05 12:30:45.555555')]
	...
	[Timestamp('2016-07-05 12:30:45.555555'), Timestamp('2016-09-05 12:30:45.555555')]
	[Timestamp('2016-09-05 12:30:45.555555'), Timestamp('2016-11-05 12:30:45.555555')]

	Selected months in the year, 2 month interval, closed on both sides, starting at the beginning of the month
	[Timestamp('2015-01-01 00:00:00'), Timestamp('2015-03-01 00:00:00')]
	[Timestamp('2015-03-01 00:00:00'), Timestamp('2015-05-01 00:00:00')]
	...
	[Timestamp('2016-07-01 00:00:00'), Timestamp('2016-09-01 00:00:00')]
	[Timestamp('2016-09-01 00:00:00'), Timestamp('2016-11-01 00:00:00')]

	Selected months in the year, 2 month interval, closed on both sides, starting at the end of the month
	[Timestamp('2015-11-30 23:59:59.999999'), Timestamp('2016-01-31 23:59:59.999999')]
	[Timestamp('2016-01-31 23:59:59.999999'), Timestamp('2016-03-31 23:59:59.999999')]
	...
	[Timestamp('2016-07-31 23:59:59.999999'), Timestamp('2016-09-30 23:59:59.999999')]
	[Timestamp('2016-09-30 23:59:59.999999'), Timestamp('2016-11-30 23:59:59.999999')]	
	
	
Setting time
____________

Data used in the examples below:

.. code-block:: python

	dtim = pd.date_range('2000-1-31 07:30', periods=12, freq='M')

Output::

	DatetimeIndex(['2000-01-31 07:30:00', '2000-02-29 07:30:00',
				   '2000-03-31 07:30:00', '2000-04-30 07:30:00',
				   '2000-05-31 07:30:00', '2000-06-30 07:30:00',
				   '2000-07-31 07:30:00', '2000-08-31 07:30:00',
				   '2000-09-30 07:30:00', '2000-10-31 07:30:00',
				   '2000-11-30 07:30:00', '2000-12-31 07:30:00'],
				  dtype='datetime64[ns]', freq='M')	

Set time
++++++++

Changing time of monthly time series is performed with ``monthly.set_time``.
Time is set with ``datetime.time``.

.. code-block:: python

    dti1 = monthly.set_time(dtim, datetime.time(7, 30, 0, 0))  # list
    print pd.DatetimeIndex(dti1)  # DatetimeIndex

	
Output::

	DatetimeIndex(['2000-01-31 09:30:00', '2000-02-29 09:30:00',
				   '2000-03-31 09:30:00', '2000-04-30 09:30:00',
				   '2000-05-31 09:30:00', '2000-06-30 09:30:00',
				   '2000-07-31 09:30:00', '2000-08-31 09:30:00',
				   '2000-09-30 09:30:00', '2000-10-31 09:30:00',
				   '2000-11-30 09:30:00', '2000-12-31 09:30:00'],
				  dtype='datetime64[ns]', freq=None)

				  
Set month begin
+++++++++++++++

This utility function is equivalent to ``set_time`` with ``datetime.time(0, 0, 0, 0)``. 

.. code-block:: python

    dti1 = monthly.set_to_begin(dtim)
    print pd.DatetimeIndex(dti1)

	
Output::

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


Set month end
+++++++++++++

Set the month day and time to the last day of the month and to the time 23:59:59:999999.

.. code-block:: python

    dti1 = monthly.set_to_end(dtim)
    print pd.DatetimeIndex(dti1)

Output::

	DatetimeIndex(['2000-01-31 23:59:59.999999', '2000-02-29 23:59:59.999999',
				   '2000-03-31 23:59:59.999999', '2000-04-30 23:59:59.999999',
				   '2000-05-31 23:59:59.999999', '2000-06-30 23:59:59.999999',
				   '2000-07-31 23:59:59.999999', '2000-08-31 23:59:59.999999',
				   '2000-09-30 23:59:59.999999', '2000-10-31 23:59:59.999999',
				   '2000-11-30 23:59:59.999999', '2000-12-31 23:59:59.999999'],
				  dtype='datetime64[ns]', freq=None)

Check last month's day
++++++++++++++++++++++

.. code-block:: python

    print monthly.is_last_day(datetime.datetime(2016, 2, 29))
    print monthly.is_last_day(pd.Timestamp('2016-2-29'))
    print monthly.is_last_day(np.datetime64('2016-02-29'))

	
Replace year
++++++++++++

.. code-block:: python

    print monthly.replace_year(datetime.datetime(2015, 2, 28), 2016)
    print monthly.replace_year(pd.Timestamp('2015-2-28'), 2016)
    print monthly.replace_year(np.datetime64('2015-02-28'), 2016)
    print monthly.replace_year(datetime.datetime(2016, 2, 29), 2017)

Output::

	2016-02-29 00:00:00
	2016-02-29 00:00:00
	2016-02-29 00:00:00
	2017-02-28 00:00:00