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
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 /n/home09/ryantosca/IDL/gamap2/date_time/add_date.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/date2ymd.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/day_of_year.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/isleap.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/localtime.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/nymd2tau.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/rewrite_agprod.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/strdate.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/tau2yymmdd.pro)
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 /n/home09/ryantosca/IDL/gamap2/date_time/ymd2date.pro)