acgc.time API documentation

# acgc.time

Collection of functions for manipulating times and dates

This module is outdated. These functions can be accomplished with pandas.Timestamp.

@author: cdholmes

View Source

      1#!/usr/bin/env python3
      2# -*- coding: utf-8 -*-
      3"""Collection of functions for manipulating times and dates
      4
      5This module is outdated. These functions can be accomplished with pandas.Timestamp.
      6
      7@author: cdholmes
      8"""
      9
     10import time
     11from datetime import datetime as dt
     12from datetime import timedelta as td
     13
     14import numpy as np
     15import pandas as pd
     16
     17
     18def _seconds_since_epoch(datetime):
     19    ''''Compute seconds since start of Unix epoch
     20
     21    Epoch begins January 1, 1970, 00:00:00 (UTC)
     22
     23    Parameter
     24    ---------
     25    datetime : datetime.datetime
     26        date and time
     27
     28    Returns
     29    -------
     30    sec : float
     31        seconds since
     32    '''
     33    return time.mktime(datetime.timetuple())
     34_sinceEpoch = _seconds_since_epoch
     35
     36def date2yearf(datetime):
     37    '''Convert datetime to year with fraction
     38
     39    Parameters
     40    ----------
     41    datetime : datetime.date or datetime.datetime or list/array of same
     42        date and time
     43
     44    Returns
     45    -------
     46    yearfrac : float or list
     47        year and fraction corresponding to input dates. e.g. 2005.156
     48    '''
     49
     50    yearfrac = []
     51    for d in np.array(datetime):
     52        # Convert numpy datetime64 to datetime
     53        d = pd.to_datetime(d)
     54        # get the year
     55        year = d.year
     56        startOfThisYear = dt(year=year, month=1, day=1)
     57        startOfNextYear = dt(year=year+1, month=1, day=1)
     58        yearElapsed = _sinceEpoch(d) - _sinceEpoch(startOfThisYear)
     59        yearDuration = _sinceEpoch(startOfNextYear) - _sinceEpoch(startOfThisYear)
     60        fraction = yearElapsed/yearDuration
     61
     62        yearfrac.append(d.year + fraction)
     63
     64    # if result has only one value, then convert to scalar
     65    if len(yearfrac)==1:
     66        yearfrac = yearfrac[0]
     67
     68    return yearfrac
     69
     70def yearf2date(yearf,roundSec=True):
     71    '''Convert year with fraction to datetime
     72
     73    Parameters
     74    ----------
     75    yearfrac : float or list of float
     76        year and fraction, e.g. 2005.156
     77    roundSec : bool (default=True)
     78        specify if output should be rounded to the nearest second
     79
     80    Returns
     81    -------
     82    date : datetime.datetime or list of same
     83        date and time corresponding to input
     84    '''
     85
     86    s = _sinceEpoch
     87
     88    date = []
     89    for d in [yearf]:
     90        y = np.int(d)
     91        startOfThisYear = dt(year=y,month=1,day=1)
     92        startOfNextYear = dt(year=y+1, month=1, day=1)
     93        yearDuration = s(startOfNextYear) - s(startOfThisYear)
     94        secElapsed = yearDuration * np.mod(d,1)
     95
     96        if roundSec:
     97            secElapsed = np.round(secElapsed)
     98        date.append(startOfThisYear + td(seconds=secElapsed) )
     99
    100    # if result has only one value, then convert to scalar
    101    if len(date)==1:
    102        date = date[0]
    103
    104    return date
    105
    106def date2doyf(datetime):
    107
    108    '''Convert datetime to day of year with fraction
    109
    110    Parameters
    111    ----------
    112    datetime : datetime.date or datetime.datetime or list of same
    113        date and time
    114
    115    Returns
    116    -------
    117    doyfrac : float or list
    118        day of year and fraction corresponding to input dates. e.g. 100.156
    119    '''
    120
    121    s = _sinceEpoch
    122
    123    doy = []
    124    for d in [datetime]:
    125
    126        year = d.year
    127        month = d.month
    128        day = d.day
    129
    130        startOfThisDay = dt(year=year,month=month,day=day)
    131        dayElapsed = s(d) - s(startOfThisDay)
    132        fraction = dayElapsed/86400.
    133
    134        doy.append(d.timetuple().tm_yday + fraction)
    135
    136     # if result has only one value, then convert to scalar
    137    if len(doy)==1:
    138        doy = doy[0]
    139
    140    return doy
    141
    142def doyf2date(doyf,year,roundSec=True):
    143    '''Convert day of year with fraction to datetime
    144
    145    Parameters
    146    ----------
    147    doyf : float or list of float
    148        day of year and fraction, e.g. 100.156
    149    year : float or list of float
    150        year
    151    roundSec : bool (default=True)
    152        specify if output should be rounded to the nearest second
    153
    154    Returns
    155    -------
    156    date : datetime.datetime or list of same
    157        date and time corresponding to input
    158    '''
    159
    160    if len(year)==1:
    161        year = np.zeros_like(doyf)+year
    162
    163    date = []
    164    for i,d in enumerate(doyf):
    165        startOfThisYear = dt(year=year[i],month=1,day=1)
    166        secElapsed = (d-1)*86400
    167
    168        if roundSec:
    169            secElapsed = np.round(secElapsed)
    170        d = td(seconds=secElapsed)
    171        date.append( startOfThisYear + td(seconds=secElapsed) )
    172
    173    # if result has only one value, then convert to scalar
    174    if len(date)==1:
    175        date = date[0]
    176
    177    return date

def date2yearf(datetime): View Source

    37def date2yearf(datetime):
    38    '''Convert datetime to year with fraction
    39
    40    Parameters
    41    ----------
    42    datetime : datetime.date or datetime.datetime or list/array of same
    43        date and time
    44
    45    Returns
    46    -------
    47    yearfrac : float or list
    48        year and fraction corresponding to input dates. e.g. 2005.156
    49    '''
    50
    51    yearfrac = []
    52    for d in np.array(datetime):
    53        # Convert numpy datetime64 to datetime
    54        d = pd.to_datetime(d)
    55        # get the year
    56        year = d.year
    57        startOfThisYear = dt(year=year, month=1, day=1)
    58        startOfNextYear = dt(year=year+1, month=1, day=1)
    59        yearElapsed = _sinceEpoch(d) - _sinceEpoch(startOfThisYear)
    60        yearDuration = _sinceEpoch(startOfNextYear) - _sinceEpoch(startOfThisYear)
    61        fraction = yearElapsed/yearDuration
    62
    63        yearfrac.append(d.year + fraction)
    64
    65    # if result has only one value, then convert to scalar
    66    if len(yearfrac)==1:
    67        yearfrac = yearfrac[0]
    68
    69    return yearfrac

Convert datetime to year with fraction

###### Parameters

- datetime (datetime.date or datetime.datetime or list/array of same): date and time

###### Returns

- yearfrac (float or list): year and fraction corresponding to input dates. e.g. 2005.156

def yearf2date(yearf, roundSec=True): View Source

     71def yearf2date(yearf,roundSec=True):
     72    '''Convert year with fraction to datetime
     73
     74    Parameters
     75    ----------
     76    yearfrac : float or list of float
     77        year and fraction, e.g. 2005.156
     78    roundSec : bool (default=True)
     79        specify if output should be rounded to the nearest second
     80
     81    Returns
     82    -------
     83    date : datetime.datetime or list of same
     84        date and time corresponding to input
     85    '''
     86
     87    s = _sinceEpoch
     88
     89    date = []
     90    for d in [yearf]:
     91        y = np.int(d)
     92        startOfThisYear = dt(year=y,month=1,day=1)
     93        startOfNextYear = dt(year=y+1, month=1, day=1)
     94        yearDuration = s(startOfNextYear) - s(startOfThisYear)
     95        secElapsed = yearDuration * np.mod(d,1)
     96
     97        if roundSec:
     98            secElapsed = np.round(secElapsed)
     99        date.append(startOfThisYear + td(seconds=secElapsed) )
    100
    101    # if result has only one value, then convert to scalar
    102    if len(date)==1:
    103        date = date[0]
    104
    105    return date

Convert year with fraction to datetime

###### Parameters

- yearfrac (float or list of float): year and fraction, e.g. 2005.156
- roundSec (bool (default=True)): specify if output should be rounded to the nearest second

###### Returns

- date (datetime.datetime or list of same): date and time corresponding to input

def date2doyf(datetime): View Source

    107def date2doyf(datetime):
    108
    109    '''Convert datetime to day of year with fraction
    110
    111    Parameters
    112    ----------
    113    datetime : datetime.date or datetime.datetime or list of same
    114        date and time
    115
    116    Returns
    117    -------
    118    doyfrac : float or list
    119        day of year and fraction corresponding to input dates. e.g. 100.156
    120    '''
    121
    122    s = _sinceEpoch
    123
    124    doy = []
    125    for d in [datetime]:
    126
    127        year = d.year
    128        month = d.month
    129        day = d.day
    130
    131        startOfThisDay = dt(year=year,month=month,day=day)
    132        dayElapsed = s(d) - s(startOfThisDay)
    133        fraction = dayElapsed/86400.
    134
    135        doy.append(d.timetuple().tm_yday + fraction)
    136
    137     # if result has only one value, then convert to scalar
    138    if len(doy)==1:
    139        doy = doy[0]
    140
    141    return doy

Convert datetime to day of year with fraction

###### Parameters

- datetime (datetime.date or datetime.datetime or list of same): date and time

###### Returns

- doyfrac (float or list): day of year and fraction corresponding to input dates. e.g. 100.156

def doyf2date(doyf, year, roundSec=True): View Source

    143def doyf2date(doyf,year,roundSec=True):
    144    '''Convert day of year with fraction to datetime
    145
    146    Parameters
    147    ----------
    148    doyf : float or list of float
    149        day of year and fraction, e.g. 100.156
    150    year : float or list of float
    151        year
    152    roundSec : bool (default=True)
    153        specify if output should be rounded to the nearest second
    154
    155    Returns
    156    -------
    157    date : datetime.datetime or list of same
    158        date and time corresponding to input
    159    '''
    160
    161    if len(year)==1:
    162        year = np.zeros_like(doyf)+year
    163
    164    date = []
    165    for i,d in enumerate(doyf):
    166        startOfThisYear = dt(year=year[i],month=1,day=1)
    167        secElapsed = (d-1)*86400
    168
    169        if roundSec:
    170            secElapsed = np.round(secElapsed)
    171        d = td(seconds=secElapsed)
    172        date.append( startOfThisYear + td(seconds=secElapsed) )
    173
    174    # if result has only one value, then convert to scalar
    175    if len(date)==1:
    176        date = date[0]
    177
    178    return date

Convert day of year with fraction to datetime

###### Parameters

- doyf (float or list of float): day of year and fraction, e.g. 100.156
- year (float or list of float): year
- roundSec (bool (default=True)): specify if output should be rounded to the nearest second

###### Returns

- date (datetime.datetime or list of same): date and time corresponding to input