.. _utils-py:

########
utils.py
########

    >>> import datetime
    >>> import numpy
    >>> epsilon = 0.00001


def update_dates(dates, timestep, unitofstep, deduceaday=False):
================================================================

Adds the specified amount of time to the given dates and returns the result ::
    
    >>> from simo.utils.utils import update_dates
    >>> dates = (datetime.date(2000,1,1),
    ...          datetime.date(2001,1,1),
    ...          datetime.date(2002,1,1),)
    >>> update_dates(dates, 5, 'year') # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    array([...2005...1...1..., ...2006...1...1..., ...2007...1...1...], 
          dtype=object)
    >>> update_dates(dates, 5, 'year', True)# doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    array([...2004...12...31..., ...2005...12...31..., ...2006...12...31...], 
           dtype=object)

def update_date(curdate, timestep, unitofstep, deduceaday=False):
=================================================================

Adds the specified amount of time to the current date and returns the result ::
    
    >>> from simo.utils.utils import update_date
    >>> update_date(datetime.date(2000,1,1), 5, 'year')
    datetime.date(2005, 1, 1)
    >>> update_date(datetime.date(2000,1,1), 5, 'year', True)
    datetime.date(2004, 12, 31)

def calculate_date_diff(start, end, unit):
==========================================

Calculate the difference two dates in given units ::
    
    >>> from simo.utils.utils import calculate_date_diff
    >>> calculate_date_diff(datetime.date(2000,1,1),
    ...                     datetime.date(2004,12,31), 'year')
    5
    >>> calculate_date_diff(datetime.date(2000,1,1),
    ...                     datetime.date(2004,4,1), 'year')
    4
    >>> calculate_date_diff(datetime.date(2000,1,1),
    ...                     datetime.date(1993,12,31), 'year')
    -7
    
def str2date(text, sep='-', order='year first'):
================================================

Parse a date string from xml (type 'xs:date') or generic string to a datetime object ::
    
    >>> from simo.utils.utils import str2date
    >>> str2date('2010-01-01')
    datetime.date(2010, 1, 1)
    >>> str2date('2010.01.01', sep='.')
    datetime.date(2010, 1, 1)
    >>> str2date('1/1/2010', sep='/', order='day first')
    datetime.date(2010, 1, 1)

def str2bool(text):
===================

Parse a boolean string from xml (type 'xs:boolean') to boolean value ::

    >>> from simo.utils.utils import str2bool
    >>> str2bool('TRUE')
    True
    >>> str2bool('True')
    True
    >>> str2bool('true')
    True
    >>> str2bool('FALSE')
    False
    >>> str2bool('False')
    False
    >>> str2bool('false')
    False
    >>> str2bool('xyz')
    False

def secs2str(seconds):
======================

Convert seconds into hh:mm:ss.ss string ::

    >>> from simo.utils.utils import secs2str
    >>> secs2str(1.5)
    '00:00:1.500'
    >>> secs2str(121.9)
    '00:02:1.900'
    >>> secs2str(5121.9)
    '01:25:21.900'


def calculate_NPV(value, discountrate, presentdate, eventdate):
===============================================================

Calculate the discounted NPV (Net Present Value) for a single value or vector::

    >>> from simo.utils.utils import calculate_NPV
    >>> npv = calculate_NPV(100.0, 5.0, datetime.date(2000,1,1),
    ...                     datetime.date(2010,1,1))
    >>> abs(npv - 61.366711) < epsilon
    True
    >>> npv = calculate_NPV(100.0, 5.0, datetime.date(2000,1,1),
    ...                     datetime.date(2010,7,31))
    >>> abs(npv - 59.660061) < epsilon
    True
    >>> npv = calculate_NPV(100.0, 5.0, datetime.date(2000,1,1),
    ...                     datetime.date(2010,12,28))
    >>> abs(npv - 58.475745) < epsilon
    True
    >>> npv = calculate_NPV(100.0, 5.0, datetime.date(2000,1,1),
    ...                     datetime.date(2010,12,31))
    >>> abs(npv - 58.452299) < epsilon
    True
    >>> values = numpy.array([100, 100, 100], dtype=float)
    >>> npv = calculate_NPV(values, 5.0, datetime.date(2000,1,1), 
    ...                     datetime.date(2010,1,1))
    >>> abs(npv - 61.366711) < epsilon
    array([ True,  True,  True], dtype=bool)