DATE & TIME routines in *

All GAMAP Routines

List routines by category:
Atmospheric Sciences | Benchmarking | Color | Date/Time | Doc | File & I/O | BPCH Format | Scientific Data Formats | GAMAP Examples | GAMAP Internals | GAMAP Utilities | GAMAP Data Manipulation | GAMAP Models & Grids | GAMAP Plotting | General | Graphics | Math & Units | Plotting | Regridding | Strings | Structures | Time Series

List routines by alphabetical order:
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Last modified: Fri Jan 24 12:14:05 2014.


List of Routines


Routine Descriptions

ADD_DATE

[Next Routine] [List of Routines]
 NAME:
        ADD_DATE

 PURPOSE:
        Computes the YYYY/MM/DD date after a number of days in the
        future (or past) have elapsed.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = ADD_DATE( YYYYMMDD, NDAYS )

 INPUTS:
        YYYYMMDD -> Today's date in YYYY/MM/DD format

        NDAYS -> The number of days (either positive or negative)
              to add to YYYYMMDD.  Default is 1.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        DATE2YMD    YMD2DATE (function)
       
 REQUIREMENTS:
        None

 NOTES:
        None
   
 EXAMPLES:
        PRINT, ADD_DATE( 20060101, 100 )
           20060411
             ; Computes the date 100 days after 2006/01/01

        PRINT, ADD_DATE( 20060101, -100 )
           20050923
             ; Computes the date 100 days before 2006/01/01

 MODIFICATION HISTORY:
        bmy, 06 Jun 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /home/bmy/IDL/gamap2/date_time/add_date.pro)


DATE2YMD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DATE2YMD

 PURPOSE:
        Given a date in YYYYMMDD format, returns the year, month,
        and day in separate variables.  Also can be used to separate
        time in a HHMMSS format into hours, minutes, seconds.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        DATE2YMD, YYYYMMDD, YEAR, MONTH, DAY

 INPUTS:
        YYYYMMDD -> Today's date as YYYY/MM/DD (or time as HH/MM/SS)
        YEAR     -> Year  (or hour  ) value
        MONTH    -> Month (or minute) value
        DAY      -> Day   (or second) value

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None
       
 REQUIREMENTS:
        None

 NOTES:
        None
    
 EXAMPLE:
        DATE2YMD, 20060101, Y, M, D
        PRINT, Y, M, D
           2006  1   1
             ; Separates the date into Y, M, D variables

        DATE2YMD, 123000, H, Mi, S
        PRINT, H, Mi, S
           12  30  0
             ; Separates the time into H, Mi, S variables

 MODIFICATION HISTORY:
        bmy, 06 Jun 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /home/bmy/IDL/gamap2/date_time/date2ymd.pro)


DAY_OF_YEAR (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DAY_OF_YEAR (function)

 PURPOSE:
        Computes the day number (0-365 or 0-366 if leap year) 
        of a given date.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = DAY_OF_YEAR( MONTH, DAY, YEAR )  OR
        RESULT = DAY_OF_YEAR( YYYYMMDD  )

 INPUTS:
        With 3 arguments:
        MONTH (int or long) -> the input month (1 - 12)
        DAY   (int or long) -> the input day   (0 - 31)
        YEAR  (int or long) -> the input year  (YEAR<0 is BC; YEAR>0 is AD)
        
        With 1 argument:
        YYYYMMDD (long) -> the input date in YYYYMMDD format.

 KEYWORD PARAMETERS:

 OUTPUTS:
        RESULT -> Day number of the year

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        (1) You cannot abbreviate YEAR.  If you specify 10/14/97
            DAY_OF_YEAR will compute the day number for 14 Oct 97 AD 
            instead of 14 Oct 1997 AD

 EXAMPLES:
        (1)
        PRINT, DAY_OF_YEAR( 10, 14, 1997 )
          287
             ; A typical modern date: 14 Oct 1997 AD

        (2)
        PRINT, DAY_OF_YEAR( 19971014 )
          287
             ; The same as example #1, but this time we call
             ; DAY_OF_YEAR with a date in YYYYMMDD format

        (3)
        PRINT, DAY_OF_YEAR( 1, 1, 1 )
          1
             ; Beginning of the "Anno Domini" era: 1 Jan 1 AD

        (4)
        PRINT, DAY_OF_YEAR( 3, 15, -44 )  
           74
             ; When Julius Caesar was murdered: 15 Mar 44 BC

 MODIFICATION HISTORY:
        bmy, 14 Oct 1997: VERSION 1.00
        bmy, 26 Mar 1998: VERSION 1.01
                           -- now written as a function with 
                              more elegant error checking.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 03 Apr 2008: GAMAP VERSION 2.12
                          - Modified to accept either 3 arguments
                            (month, day, year) or one argument
                            (date in YYYYMMDD format)
                          

(See /home/bmy/IDL/gamap2/date_time/day_of_year.pro)


ISLEAP (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISLEAP (function)

 PURPOSE:
        Returns 1 for each year that is a leap year.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = ISLEAP( YEAR )

 INPUTS:
        YEAR -> A year or an array of years. Must be "4 digit" years.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> An integer value or array with 1 for each 
             year that is a leap year.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        For many purposes one should take a look at built-in
        IDL date functions first (version > 5.0).

 EXAMPLE:
        YEARS = FINDGEN(25) + 1980 
        PRINT, 365 + ISLEAP(YEARS), FORMAT='(10i4)'
          366 365 365 365 366 365 365 365 366 365
          365 365 366 365 365 365 366 365 365 365
          366 365 365 365 366

             ; Compute the number of days in each year
             ; from 1980 to 2005 using ISLEAP to add
             ; either 1 or 0 to 365.

 MODIFICATION HISTORY:
        mgs, 02 Oct 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments, cosmetic changes

(See /home/bmy/IDL/gamap2/date_time/isleap.pro)


LOCALTIME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LOCALTIME

 PURPOSE:
        Returns the local time at a particular location, given the
        Universal Time (aka Greenwich Time) and longitude.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = LOCALTIME( UTC, LON )

 INPUTS:
        UTC -> Universal Time (aka Greenwich Time) in hours.
             UTC may be either a scalar or a vector.

        LON -> Longitude in degrees.  LON may be in the range
             -180..180 or 0..360.  LON may be either a scalar
             or a vector.

 KEYWORD PARAMETERS:
        /DOUBLE -> Set this switch to return local time in
             double precision.  Default is to return local time
             in single precision.
            
 OUTPUTS:
        RESULT -> The local time corresponding to UTC and LON.
             If UTC and LON are vectors, then RESULT will also
             be a vector of local times.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, LOCALTIME( 0, -71.06 )
          19.2627

             ; Returns the local time (approx 19.26 decimal, which
             ; is approx 19:15 PM) at Boston (lon=71.06W) when
             ; it is 00:00 UTC.

        (2)
        PRINT, LOCALTIME( 0, -71.06, /DOUBLE )
          19.262667

             ; Same as Example (1), but returns local time
             ; as double precision.
 
        (3) 
        PRINT, LOCALTIME( [0,1,2], -71.06, /DOUBLE )
             19.262667   20.262667   21.262667

             ; Returns the local times at Boston (as in 
             ; Examples (1) and (2)) when it is 00:00, 01:00,
             ; and 02:00 UTC time.

 MODIFICATION HISTORY:
        dbm, 30 Jul 2007: VERSION 1.00

(See /home/bmy/IDL/gamap2/date_time/localtime.pro)


NYMD2TAU (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NYMD2TAU (function)

 PURPOSE:
        Computes the value of TAU, which is the elapsed hours between
        the current date/time and the beginning of an epoch. This is
        the starting date for 3D model data assimilation.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = NYMD2TAU( NYMD, [NHMS [,NYMD0, NHMS0]] )

 INPUTS:
        NYMD (long)  -> YY/MM/DD for this date (e.g. 940101)
                  You can either specify year as 4 digits or 2 digits.
                  With 2 digits, year < 50 will be assumed to be 2000+YY.A

        NHMS (long)  -> HH/MM/SS for this date (e.g. 060000)
                  will be defaulted to 000000

        NYMD0 (long) -> YY/MM/DD for the start of the epoch
                  default is {19}850101 which is the GEOS-1 start

        NHMS0 (long) -> HH/MM/SS for the start of the epoch
                  will be defaulted to 000000
        
 KEYWORD PARAMETERS:
        /GEOS1 -> use 1985/01/01 as epoch start

        /GISS_II -> use 1980/01/01 as epoch start

 OUTPUTS:
        RESULT -> The function returns the TAU value as a 
             double-precision number

 SUBROUTINES:
        NYMD2STRU : extracts year, month, day, hour, minute and seconds from
            NYMD and NHMS values.

        JULDAY (IDL user library procedure)

 REQUIREMENTS:

 NOTES:
        Function NYMD2STRU is also contained in function TAU2YYMMDD.
        Take care when changes are necessary !

 EXAMPLE:
        ; (1) Compute TAU value for 0h on Jan 1, 1994, with the 
        ;     epoch starting on 0h on Jan 1, 1980 (GISS II value).
        ;
        TAU = nymd2tau( 940101L, 0L, 800101L, 0L )

        ; (2) Compute TAU value for 0h on Jan 1, 1994, for the 
        ;     default GEOS-1 epoch (850101L, 0L).
        ;
        TAU = nymd2tau( 940101L, 0L )

        ; (3) Compute GISS model II tau values for the first of
        ;     each month in 1990
        date = [ 900101L, 900201L, 900301L, 900401L, 900501L, 900601L, $
                 900701L, 900801L, 900901L, 901001L, 901101L, 901201L ]

        tau = nymd2tau(date,/GISS)


 MODIFICATION HISTORY:
        bmy, 26 Mar 1998: VERSION 1.00
        mgs, 26 Mar 1998: - now year 2000 compliable 
        mgs, 23 Mar 1999: - now handles vectors as input
        bmy, 23 Mar 2005: GAMAP VERSION 2.03
                          - Added /NO_Y2K keyword to suppress 
                            special Y2K treatment of dates (i.e.
                            treat dates w/ 2 digits as from 1900's)
                          - renamed internal function NYMD2STRU to
                            N2T_NYMD2STRU to avoid conflict with
                            similar function in "tau2yymmdd.pro"
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /home/bmy/IDL/gamap2/date_time/nymd2tau.pro)


REWRITE_AGPROD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	 REWRITE_AGPROD


 PURPOSE:
        To rewrite a APROD / GPROD restart file with a different
        timestamp TAU0. The correspondence b/w file name and timestamp
        is enforced, as required by GEOS-Chem.

 CATEGORY:
	 Date & Time


 CALLING SEQUENCE:
	 REWRITE_AGPROD, INFILE='old_file_name', TAU0=tau | YMD=yyyymmdd

 INPUTS:
	 None

 KEYWORD PARAMETERS:

        INFILENAME -> initial restart_aprod_gprod file. If not
             passed, a dialog window will pop up.

        TAU0 (double) -> the new time stamp you want, in Tau units

        YMD (long) -> the new time stamp you want, in YYMMDD or YYYYMMDD

        HH -> hour for this date (e.g. 6 for 6 a.m.)  Default is 0.

        Either TAU0 or YMD should be passed. If both are passed,
        TAU0 is used.

 OUTPUTS:
 	 None.

 SIDE EFFECTS:
	 A file named restart_aprod_gprod.YYYYMMDDHH where YYYYMMDDHH
        corresponds with TAU0 in the data blocks is created.

 RESTRICTIONS:
	 The input file must be a restart_aprod_gprod file.

 NOTES:
        This is not a regridding routine. To regrid a
        restart_aprod_gprod file, use :

           REGRIDV_RESTART, ..., DIAGN=0

        or/and

           REGRIDH_RESTART, ..., DIAGN=0

 EXAMPLE:
        REWRITE_AGPROD, YMD=20010701

 MODIFICATION HISTORY:
	 phs,    Jul 2007: version 0.1
        phs, 04 Apr 2007: GAMAP VERSION 2.12
                          - commemts
                          - clean non_global pointers
                          - added YMD and HH keywords
        ccc, 09 Aug 2010: GAMAP VERSION 2.14
                          - add automatic definition of outfilename

(See /home/bmy/IDL/gamap2/date_time/rewrite_agprod.pro)


STRDATE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRDATE (function)

 PURPOSE:
        Format a "standard form" date string 

 CATEGORY:
        Date & Time, Strings

 CALLING SEQUENCE:
        RESULT = STRDATE( [ DATE ] [, Keywords ] )

 INPUTS:
        DATE -> (OPTIONAL) Either a up to 6 element array containing 
            year, month, day, hour, minute, and secs (i.e. the format 
            returned from BIN_DATE) or a structure containing year, 
            month, day, hour, minute, seconds (as returned from 
            TAU2YYMMDD) or a date string in "standard" format as 
            returned by SYSTIME(0).  If DATE is omitted, STRDATE will 
            automatically return the current system time. 

 KEYWORD PARAMETERS:
        /SHORT -> omit the time value, return only date

        /SORTABLE -> will return 'YYYY/MM/DD HH:MM' 

        /EUROPEAN -> will return 'DD.MM.YYYY HH:MM'

        IS_STRING -> Indicates that DATE is a date string 
            rather than an integer array.  This keyword is now 
            obsolete but kept for compatibility.

 OUTPUTS:
        RESULT -> A date string formatted as 'MM/DD/YYYY HH:MM'.
            If SHORT flag is set, the format will be 'MM/DD/YYYY'

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        DATATYPE (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) /EUROPEAN and /SORTABLE will have effect of 
            /SORTABLE but with dots as date Seperators.

 EXAMPLES:
        (1)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ] )
           01/01/2001 12:30
             ; Date string for 2001/01/01 12:30 in USA format

        (2)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /EUROPEAN )
           01.01.2001 12:30
             ; Date string for 2001/01/01 12:30 in European format

        (3)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE )
           2001/01/01 12:30
             ; Date string for 2001/01/01 12:30 in YYYY/MM/DD format

        (4)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE, /SHORT )
           2001/01/01
             ; Date string for 2001/01/01 w/o hours and minutes

        (5)
        RESULT = TAU2YYMMDD( 144600D )
        PRINT, STRDATE( RESULT, /SORTABLE )
           2001/07/01 00:00
             ; Use TAU2YYMMDD to convert a TAU value (in this case
             ; for July 1, 2001) to a structure.  Then pass the
             ; structure to STRDATE to make a string.

 MODIFICATION HISTORY:
        mgs, 11 Nov 1997: VERSION 1.00
        mgs, 26 Mar 1998: VERSION 1.10 
                          - examines type of DATE parameter 
                            and accepts structure input.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Renamed /GERMAN to /EUROPEAN
                          - Updated comments, cosmetic changes
                          - Now uses function DATATYPE

(See /home/bmy/IDL/gamap2/date_time/strdate.pro)


TAU2YYMMDD (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        TAU2YYMMDD (function)

 PURPOSE:
        Converts a tau value (elapsed hours between
        the current date/time and the beginning of an epoch) into a
        calendar date and time value.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = TAU2YYMMDD( TAU, [ NYMD0, NHMS0 ] )

 INPUTS:
        TAU -> the tau value to be converted (type long)

        NYMD0 (long) -> YY/MM/DD for the start of the epoch
                  default is {19}850101 which is the GEOS-1 start

        NHMS0 (long) -> HH/MM/SS for the start of the epoch
                  will be defaulted to 000000
        
 KEYWORD PARAMETERS:
        /NFORMAT --> produce 2-element vector instead of structure
              The result will be NYMD and NHMS with NYMD as YYYYMMDD.

        /SHORT --> produce 2-element vector with 2-digit year format.
              (implies NFORMAT=1)

        /GEOS1 -> use 1985/01/01 as epoch start

        /GISS_II -> use 1980/01/01 as epoch start

 OUTPUTS:
        RESULT -> The function returns the calendar date and time as 
             either a structure with tags YEAR, MONTH, DAY, HOUR, 
             MINUTE, SECOND or a 2 element array with NYMD and NHMS 
             long values.

 SUBROUTINES:
        NYMD2STRU -> extracts year, month, day, hour, minute 
             and seconds from NYMD and NHMS values.

 REQUIREMENTS:
        None

 NOTES:
        Function NYMD2STRU is also embedded in NYMD2TAU function. This should
        be kept in mind when changes are necessary.

        Function STRDATE can be used to produce a formatted string from
        the structure returned by TAU2YYMMDD.

 EXAMPLE:
        ; get calendar structure from tau value for 1994/01/01 (GEOS)

           print,tau2yymmdd(78888,/GEOS1)

        result (structure with Year, Month, Day, Hour, Minute, Second):
        {    1994     1      1      0      0      0}

        ... and in the format of NYMD, NHMS

           print,tau2yymmdd(78888,/GEOS1,/NFORMAT)
           print,tau2yymmdd(78888,/GEOS1,/NFORMAT,/SHORT)

        results (array with 2 elements):
              19940101           0
                940101           0

 MODIFICATION HISTORY:
        mgs, 26 Mar 1998: VERSION 1.00
        mgs, 16 Mar 1999: - now allows floating point tau values
                            CAUTION: Use double for second precision !
        bmy, 27 Jul 1999: VERSION 1.42
                          - updated comments
        bmy, 03 Jan 2000: VERSION 1.44
                          - updated comments
        bmy, 23 Mar 2005: GAMAP VERSION 2.03
                          - renamed internal function NYMD2STRU to
                            T2N_NYMD2STRU to avoid conflict with
                            similar function in "tau2yymmdd.pro";
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /home/bmy/IDL/gamap2/date_time/tau2yymmdd.pro)


YMD2DATE

[Previous Routine] [List of Routines]
 NAME:
        YMD2DATE

 PURPOSE:
        Given year, month, day (or hour, minute, second) values,
        returns a variable in YYYYMMDD (or HHMMSS) format.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = YMD2DATE( YEAR, MONTH, DAY )

 INPUTS:
        YEAR  -> Year  (or hour  ) value
        MONTH -> Month (or minute) value
        DAY   -> Day   (or second) value

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None
       
 REQUIREMENTS:
        None

 NOTES:
        None
    
 EXAMPLE:
        PRINT, YMD2DATE( 2006, 1, 1 )
           20060101
             ; Takes separate Y, M, D values and creates a date variable.

        PRINT, YMD2DATE( 12, 30, 0 )
           123000
             ; Takes separate H, Mi, S values and creates a time variable.

 MODIFICATION HISTORY:
        bmy, 06 Jun 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /home/bmy/IDL/gamap2/date_time/ymd2date.pro)