[Previous]
[Next]
NAME:
TagArray
PURPOSE:
(First check whether the IDL functions strjoin and/or
STRSPLIT can do what you need)
Combine string arrays into single string separated by
separator character, or v.v.
CATEGORY:
Toolbox: generic
CALLING SEQUENCE:
FUNCTION TagArray, tag_in, sep, nonull=nonull, split=split
INPUTS:
tag scalar, array; type: string
if scalar, or /split keyword set:
the string is decomposed into elements separated by the
'sep' character(s). The result is returned as a string array
with one dimension more than the input array: the leading
dimension is the number of tags found (see RESTRICTIONS).
if array: the elements in the array are
concatenated, separated by the 'sep' character
OPTIONAL INPUT PARAMETERS:
sep scalar, or array; type: 1-char string: default is a scalar and depends on OS
if /split is used then 'sep' can be an array of 1-char separator strings
/nonull if extracting tags, discard null-string tags
/split if 'tag' is an array that needs to be decomposed then
split needs to be set (by default, arrays are
concatenated; a scalar is always decomposed, even
if /split is not set).
OUTPUTS:
R either a string array of tags, or a scalar string
of concatenated tags.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
TimeSplit
RESTRICTIONS:
If keyword /split is set than the first elements in the 'tag' array is analyzed
for the presence of separators. The result is applied to all strings. So all
strings in 'tag' must have the same structure: same length and separators in the
same positions.
SIDE EFFECTS:
Note that an array[1] is treated differently from a scalar.
An array[1] is returned unmodified as a scalar
it is NOT decomposed if it contains 'sep' characters.
EXAMPLE:
t = tagarray('1998:337:23:53.000',[':','.']
results in:
t =['1998','337','23','53','000']
PROCEDURE:
The default separator is a comma on 'Win32', a colon on 'linux'
On other OS it is a colon (as on linux).
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeArray
PURPOSE:
Converts time structure to array and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeArray(t [,/linear])
INPUTS:
t array; type: time structure array, or non-structure
array[2,*], array[*]
time to be converted from array to structure or v.v.
OPTIONAL INPUT PARAMETERS:
/linear returns scalar integer instead of 2-element integer
OUTPUTS:
u array; type: array[2,*] or time structure
converted time
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SubArray, SuperArray, TimePieces, TimeStandardize
CALLED BY:
Carrington, CarringtonT, CarringtonT0, IsBadTime, TimeOrigin
PROCEDURE:
> If the input time is a structure array[*] then it is returned as an
integer array[2,*] (with days and fract-day units) If /linear is set
then an integer array[*] is returned in fract-day units
> If an non-structure array is input then it should be an array[2,*]
(leading dimension of 2) if /linear NOT set, or an array[1,*] if
/linear is set. This is returned as a structure array.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeDay
PURPOSE:
Converts numerical day value to time structure and v.v
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeDay, t
INPUTS:
t array; type: time structure or any numerical type
OUTPUTS:
Result array; type: nummerical or time structure
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsTime, TimePieces, TimeStandardize
CALLED BY:
TimeGet, TimeSet
RESTRICTIONS:
This function is for use in TimeGet and TimeSet only.
Other code should make calls to TimeGet or TimeSet:
u = TimeSet(day=t,/diff)
u = TimeGet(day=t,/diff)
SIDE EFFECTS:
Accesses !TimeUnits.in_day
PROCEDURE:
> If the input is of type structure than an integer array is
returned if all the fractions of a day are zero, or else a
double array is returned
> If the input is a numerical array then it is converted to
a time structure with the integer part as the number of days,
and the fraction as time of day.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeEaster
PURPOSE:
Get date for Easter in given year
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeEaster, T
INPUTS:
T scalar or array; type: numerical or time structure
OPTIONAL INPUT PARAMETERS:
/scalar passed to TimeSet
OUTPUTS:
Result
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsTime, TimeGet, TimeSet, TimeUnit
PROCEDURE:
From http://charon.nmsu.edu/~lhuber/leaphist.html
MODIFICATION HISTORY:
JUL-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeFixYear
PURPOSE:
Complete year specified in 2 digits
CATEGORY:
Tricks
CALLING SEQUENCE:
Y = TimeFixYear(Yr)
INPUTS:
Yr array; type: integer
OUTPUTS:
Y array; type integer
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
InsituTimeSeries [1], InsituTimeSeries [2], TimeSplit, getnagoyasources
getootyasources, nagoya_glevel, sgp4_eph, sgp4_tle, smei_last_tle
PROCEDURE:
Where 0<=Yr<=50, Yr is changed to 2000+Yr
Where 50<Yr<100, Yr is changed to 1900+Yr
Everywhere else Yr is unmodified
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeGet
PURPOSE:
Get information from time structure
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeGet, t, unit , $
difference = difference , $
full = full , $
d2000 = d2000 , $
jd = jd , $
mjd = mjd , $
njd = njd , $
jepoch = jepoch , $
bepoch = bepoch , $
djepoch = djepoch , $
dbepoch = dbepoch , $
smei = smei , $
carrington_ = carrington_ , $
unix = unix , $
botime = botime , $
eotime = eotime , $
bomonth = bomonth , $
eomonth = eomonth , $
fotime = fotime , $
roundt = roundt , $
dow = dow , $
month = month , $
dom = dom , $
doy = doy , $
yrmd = yrmd , $
yrdoy = yrdoy , $
dhms = dhms , $
scalar = scalar , $
year = year , $
;yr = yr , $ ; ambiguous keyword
day = day , $
hour = hour , $
hr = hr , $
minute = minute , $
sec = sec , $
msec = msec , $
ydoy = ydoy , $
ymd = ymd , $
sys = sys , $
vms = vms , $
iso8601 = iso8601 , $
_ymd = _ymd , $
_ydoy = _ydoy , $
format = format , $
_extra = _extra
INPUTS:
t array[*]; type: time structure
input times
unit scalar; type: integer; default: none
integer identifying one of the time units year,
day, hour, minute, sec or msec. Should be a return
value of the fnc TimeUnit.
Alternatively, setting one of the keywords /year, /day, /hour,
/minute, /sec or /msec accomplishes the same.
/hr is the same as /hour.
'unit' must be set for keywords /full, /botime, /roundt.
If 'unit' is set without any of these keywords present then
the associated time unit is extracted from 't'.
OPTIONAL INPUT PARAMETERS:
/difference by default the input time is treated as an absolute
time, i.e. a time relative to the time origin !TimeZero.
If /difference is set then the input time is treated
as a time difference, i.e. the returned values will be
be independent of !TimeZero.
The distinction is significant if !TimeZero is set to an
irregular time, e.g. if the time origin is 2000 Jan 1,
00:00:03, and t = 0, then
TimeGet(/sec ) returns 3 while
TimeGet(/sec, /diff) returns 0.
Internally the difference is that by default the time
!TimeZero+t is processed, while with /diff set only the
input time t is processed Note that !TimeZero+t is the
number of days elapsed since 2000 Jan 1, 0 UT.
For keywords extracting calendar date information
setting /difference is somewhat tricky because the calculation
assumes that time is specified relative to 2000 Jan 1, 0 UT
(i.e. !TimeZero+t). Setting /difference would produce wrong
results unless the input t itself already has !TimeZero added to it.
/full used only if 'unit' is set
converts to units of 'unit'
/botime used only if 'unit' is set
truncates to 'unit'
roundt=roundt If one of the TimeString keywords (see below)
is set:
/roundt is passed to TimeString
If none of the TimeString keywords is set:
used only if 'unit' is set,
and rounds to 'unit'
/d2000 ?? undocumented (extract days since current origin, usually 2000.0??
/jd extract Julian date
/mjd extract modified Julian date
/njd extract days since 2000 Jan 1.5
/jepoch extract Julian epoch
/djepoch extract Julian epoch - 2000
/bepoch extract Besselian epoch
/dbepoch extract Besselian epoch - 1900
/d2000 extract days since 2000/01/01 00 UT (???)
/dow extract day of week
/month extract month (integer between 1 and 12)
to convert to 3-char strings, see TimeMonth
/dom extract day of month (with fraction for time of day)
/doy extract day of year (with fraction for time of day)
/scalar if set and only one time is specified (i.e. T is array[1])
then the result is output as a scalar (by default the
output will also be an array[1] (note: this only applies if
the output is not a time structure, since structures are
always arrays).
Any one of the following keywords trigger a conversion of
the input to string format. See TimeString for more information.
format=format
/ydoy
/ymd
/sys
/vms
/iso8601
/_ymd
/_ydoy
OUTPUTS:
u = TimeGet( t, /dhms [, /difference])
u array[5,*]; type: integer
input time split into days, hours, minutes, sec and msec
u[0,*] days
u[1,*] hours
u[2,*] minutes
u[3,*] seconds
u[4,*] milli-seconds
u = TimeGet( t, /full [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: numerical type, usually double
input time in units of 'unit'
/year time converted to Julian years
/day time converted to days
/hour time converted to hours
/minute time converted to minutes
/sec time converted to seconds
/msec time converted to milli-seconds
Internally a recursive call to TimeGet is made with /difference
and /dhms set.
u = TimeGet( t, /botime [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u = TimeGet( t, /eotime [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: time structure
input time truncate to 'unit'
/year time truncated to start/end of year (doy=1.0)
(though technically legal you probably don't want
to specify /difference with this keyword).
/day time truncated to start/end of day
/hour time truncated to start/end of hour
/minute time truncated to start/end of minute
/sec time truncated to start/end of second
/msec time truncated to start/end of milli-second
If /difference is NOT set then 'u' is returned relative to
the internal time origin !TimeZero (i.e. !TimeZero is subtracted
after the truncation has been done).
u = TimeGet( t, /bomonth [, /difference)
u = TimeGet( t, /eomonth [, /difference)
u array[*]; type: time structure
input time truncate to start/end of month
If /difference is NOT set then 'u' is returned relative to
the internal time origin !TimeZero (i.e. !TimeZero is subtracted
after the truncation has been done).
u = TimeGet( t, /fotime [, /difference, /full, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: time structure (/full NOT set) or numerical
(/full SET).
fraction of time left after subtracting the result
of TimeGet(t,/botime).
/year fraction of year left
/day fraction of day left
/hour fraction of hour left
/minute fraction of minute left
/sec fraction of second left
/msec fraction of milli-second left
If /full is SET then the remaining fraction is converted
into time units 'unit'. This is a shortcut for two TimeGet calls:
u = TimeGet(t, /fotime, /day, /full)
is the same as:
u = TimeGet(t, /fotime, /day)
u = TimeGet(u, /diff, /full, /day)
u = TimeGet( t, unit, roundt=roundt [, /difference])
u = TimeGet( t, /roundt [, /difference, $
[year=year, day=day, hour=hour, minute=minute, sec=sec, msec=msec]])
u array[*]; type: time structure
rounded input time
year = year time rounded to 'year' Julian years
(same as setting day=365.25d0)
day = day time rounded to 'day' days
hour = hour time rounded to 'hour' hours
minute = minute time rounded to 'minute' minutes
sec = sec time rounded to 'sec' seconds
msec = msec time rounded to 'msec' milli-second
Setting e.g. /day is the same as day=1, i.e. rounding occurs
to the nearest unit of time specified.
If /difference is NOT set then 'u' is returned relative to
the internal time origin !TimeZero (i.e. !TimeZero is subtracted
after the rounding has been done).
u = TimeGet( t [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: integer
specified time-component extracted from 'u'
year = year year (integer array)
day = day day of year (integer array)
The calendar keywords /julian and jul2greg affect
the result (see TimeYDoy).
(though technically legal you probably don't want
to specify /difference with these two keywords).
hour = hour hours
minute = minute minutes
sec = sec seconds
msec = msec milli-seconds
These four are implemented as recursive calls to
TimeGet with /difference and /dhms set.
u = TimeGet( t, /d2000 [ , /difference] ) # days since 2000 Jan 1, 0 UT
u = TimeGet( t, /jd [ , /difference] ) Julian days
u = TimeGet( t, /mjd [ , /difference] ) Modified Julian days, JD-2400000
u = TimeGet( t, /njd [ , /difference] ) New Julian days = days since 2000 Jan 1, 12 UT
u = TimeGet( t, /jepoch [ , /difference] ) Julian epoch
u = TimeGet( t, /bepoch [ , /difference] ) Besselian epoch
u array[*]; type; numerical
calendar date 't' converted to indicated format
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
u = TimeGet( t, /dow [ , /difference] )
u array[*]; type: string
day of week as 2-char string, 'SUN','MON', etc.
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
u = TimeGet( t, /month [ , /difference] )
u array[*]; type: integer
month as integer 1-12. To convert to 3-char strings,
'JAN','FEB', etc.; see TimeMonth).
If /difference is used, make sure that t reflects elapsed
times since 2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result
(see TimeYDoy).
u = TimeGet( t, /dom [ , /difference] )
u = TimeGet( t, /doy [ , /difference] )
array[*]; type: numerical
day of the month or year with fraction for time of day.
If /difference is used, make sure that t reflects elapsed
times since 2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result
(see TimeYDoy).
u = TimeGet( t, /yrmd [ , /difference] )
array[3,*]; type: numerical
year, month and day of the month (with fraction for time of day).
If /difference is used, make sure that t reflects elapsed
times since 2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result
(see TimeYDoy).
u = TimeGet( t, /yrdoy [ , /difference] )
array[*]; type: numerical
year and day of the year (with fraction for time of day).
If /difference is used, make sure that t reflects elapsed
times since 2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result
(see TimeYDoy).
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
CarringtonT0, CvSky_Equatorial, CvSky_GSM, CvSky_Geographic, CvSky_Heliographic
CvSky_IHG, CvSky_Precess, GeographicInfo, HOSOrbit, InSitu, InsituTimeSeries [1]
InsituTimeSeries [2], KeplerOrbit, MessengerOrbit, NewcombSun, PA_Pole
PlotCoronagraph, PlotEarthSkymap, PlotEloTimeMap, PlotPlanarCut, PlotPolarSkymap
PlotSolarDisk, PlotSphereCut, RemoteView_BodyLoc, RemoteView_CMEDensity
RemoteView_Display2D, RemoteView_Display3D, RemoteView_FOV, StereoAOrbit
StereoBOrbit, TimeEaster, TimeGST, TimeOp, TimeSet, TimeSplit, TimeString, TimeSystem
TimeXAxis, TimeYDate, TimeYDoy, UlyssesOrbit, clock, getnagoyasources
getootyasources, getsmeisources, img_read, jpl_eph, lsqLinearFit, mpc_comets
mpc_eph, mpc_minor_planets, mpc_orbit_eph, nagoya_glevel, qEphem
qImage_cw_Property, qImage_cw_Where, qLine_Curve, qLine_FitPlot, qnagoya
qnagoya_pointsources, qsmei_sky_pick, ra_fictitious_sun, skyd_cat, skyd_version
smei_base_testcase, smei_buf, smei_buf_get, smei_buf_getframe, smei_buf_prep
smei_buf_read, smei_coriolis, smei_filename, smei_filepath, smei_frm_base
smei_frm_cp, smei_frm_cvhdr, smei_frm_eclipse, smei_frm_findpoint, smei_frm_info
smei_frm_read, smei_frm_smoothdark, smei_frm_summary, smei_frm_track
smei_frm_where, smei_getfile, smei_hdr_c3maskupload, smei_hdr_get, smei_hdr_make
smei_hdr_plot, smei_hdr_update, smei_mkbase, smei_mkcal, smei_mkcal_auto
smei_mkdrives, smei_mkmask, smei_mkorb, smei_mkorb_auto, smei_mksidereal
smei_mksky, smei_orbit_stats, smei_plot_timeseries, smei_rewind
smei_sgp4_orbits, smei_sky_atlocation, smei_sky_getmask, smei_sky_track
smei_star_fit, smei_star_remove, smei_star_show, smei_star_showsmooth
smei_star_writepnt, smei_www_skymaps, smei_zld_remove [1], smei_zld_remove [2]
smei_zld_weekly, smeidb_mounted, stopwatch, usno_eph, vu_coronagraph
vu_earthskymap, vu_elotime, vu_extract, vu_get_page, vu_getdata, vu_image, vu_insitu
vu_insitu_persist, vu_insitu_raw, vu_insitucurve, vu_linecut, vu_lineofsight
vu_localskymap, vu_mean, vu_movie, vu_nagoyasourcemap, vu_new_time, vu_planarcut
vu_radialcut, vu_read, vu_remoteview, vu_select, vu_solardisk, vu_spherecut
vu_stereoview, vu_synopticmap, vu_update_hours, vu_update_marker, vu_vox_write
vu_whatis, vu_write, wso_read, www_help_tree
RESTRICTIONS:
If the return value is a one-element non-structure it is returned as a 1-element array,
unless /scalar is set.
CALLS: ***
Carrington, InitVar, IsType, SubArray, SuperArray, TimeDay, TimeOp, TimePieces, TimeSet
TimeShift, TimeStandardize, TimeString, TimeUnit, TimeYDate, TimeYDoy, smei_coriolis
PROCEDURE:
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
NOV-2003, Paul Hick (UCSD/CASS)
Fixed bug in use of /botime keyword
JAN-2004, Paul Hick (UCSD/CASS)
Fairly substantial rewrite, converting from the old time structure
with year,doy,h,m,s,msec fields to the new structure with two integer fields.
APR-2004, Paul Hick (UCSD/CASS)
Fixed bug with /roundt for rounding to hours, minutes, seconds or milliseconds
JUL-2004, Paul Hick (UCSD/CASS)
Added /eotime keyword
JUL-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
If input arg t is a string it is now converted to a time
structure using TimeSet.
Renamed keyword /ydoy to /yrdoy (to avoid conflict with
keyword /ydoy of function TimeString).
Added a list of keywords passed to TimeString:
/ydoy, /ymd, /sys, /vms, /_ymd, /_ydoy, format=format
If any one of these keywords is set then TimeString is called
with the same keyword.
With this change it should no longer be necessary to call
TimeString directly. Instead call TimeGet with the same keywords.
Removed keyword /stringt (not needed anymore)
JUL-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /bomonth and /eomonth keywords.
JUL-2009, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword /unix.
[Previous]
[Next]
NAME:
TimeGST
PURPOSE:
Calculate Greenwich Sidereal Time from UT
Good for years 1901 through 2099. Accuracy is 0.006 degree.
CATEGORY:
Celestial mechanics
CALLING SEQUENCE:
gst = TimeGST(T, /degrees)
INPUTS:
T array; type: time structure
universal time (UT)
OPTIONAL INPUT PARAMETERS:
/degrees if set output is in degrees (default: radians)
OUTPUTS:
gst array; type: double
Greenwich sidereal time
INCLUDE:
@compile_opt.pro ; Return to caller
CALLS: ***
TimeGet, TimeOp, TimeSet, TimeUnit, ToDegrees
CALLED BY:
EarthTransit3DLoc, GeographicInfo
RESTRICTIONS:
Only valid for years 1901 through 2099
PROCEDURE:
Local Sidereal Time (LST) is defined as the Hour Angle of the
vernal equinox. GST is RA of local meridian at Greenwich
MODIFICATION HISTORY:
See: C.T. Russell, Geophysical Coordinate Transformations,
in: Cosmic Electrodynamics 2 (1971) 184-196
[Previous]
[Next]
NAME:
TimeInterpol
PURPOSE:
Interpolation of a function of time.
CATEGORY:
Tell time
CALLING SEQUENCE:
F = TimeInterpol(FF, TT, T, Unit, _extra=_extra)
INPUTS:
FF array[n]; type: any numerical array
list of function values
TT array[n]; type: time structure
list of times where function values FF are supplied
T array[m]; type: time structure
list of times where interpolates are needed
OPTIONAL INPUT PARAMETERS:
Unit scalar; type: integer; default: TimeUnit(/days)
time units used for the interpolation (see PROCEDURE)
_extra=_extra
extra keyword passed to IDL function 'interpol'
OUTPUTS:
F array[n]; type: same as FF
list of interpolated values at times T
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
INTERPOL, InitVar, IsType, SyncDims, TimeOp, TimeUnit
CALLED BY:
mpc_eph, vu_atlocation, vu_gettime, vu_insitu_persist, vu_insitu_raw, vu_mean
vu_remoteview, vu_timeseries
PROCEDURE:
Input arrays TT and T are converted to time differences relative to
TT[0] in units specified by the Unit argument. Interpolation is done
with the IDL interpol function using these time difference arrays.
MODIFICATION HISTORY:
MAR-2001, Paul Hick (UCSD/CASS)
SEP-2001, Paul Hick (UCSD/CASS)
Added interpolation on multidimensional arrays
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added check for new time of time structure
[Previous]
[Next]
NAME:
TimeLimits
PURPOSE:
Extract information about a array of times
CATEGORY:
Tell time
CALLING SEQUENCE:
FUNCTION TimeLimits, T, unit, $
mint = mint , $
maxt = maxt , $
bounds = bounds, $
range = range , $
mid = mid , $
t0 = t0
INPUTS:
T array; type: time structure
times to be processed
OPTIONAL INPUT PARAMETERS:
unit scalar; type: integer
If'unit' is not specified all times are returned
as a time structure
If 'unit' ist specified then times are returned
as a difference from T[0] in units of 'unit'.
/mint return earliest time
/maxt return latest time
/mid return center time
/bounds return earliest and latest time
(earliest time = R[0], latest time = R[1])
This is the default if no keyword is specified.
/range (use only with chronological or reverse
chronological arrays, SEE RESTRICTIONS)
return earliest and latest time,
The pair of times is returned in the
same order as they occur in the input array T,
e.g. if the array is in reverse chronological order
than R[0] is the latest, and R[1] the earliest time.
(this keyword is primarily use in plotting routines
to reverse the time axis).
OUTPUTS:
R array[1], array[2]; type: time structure of float
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, MEAN, TimeOp, TimeUnit
CALLED BY:
InsituTimeSeries [1], InsituTimeSeries [2], TimeLInterpol, TimeXAxis
lsqLinearFit, mpc_eph, qLine_Curve, qView_GetData, sgp4_eph, sgp4_tle
smei_buf_getframe, smei_buf_prep, smei_buf_read, smei_frm_eclipse
smei_frm_findpoint, smei_frm_smoothdark, smei_frm_summary, smei_getfile
smei_hdr_get, smei_hdr_plot, smei_hdr_update, smei_mkcal, smei_mkorb, smei_sky
smei_star_fit, smei_star_show, vu_insitucurve
RESTRICTIONS:
If the min and max time is required for an input array T that is
not (reverse) chronological the /range keyword can produce unexpected
results (the minimum time may end up in R[1], not R[0]).
Use trange = TimeLimits(T,/bounds) if you need to be sure
that the minimum time is R[0] and the maximum time R[1].
PROCEDURE:
R = TimeLimits(T, /mint [, unit])
R = TimeLimits(T, /maxt [, unit])
R = TimeLimits(T, /mid [, unit])
R = TimeLimits(T, /bounds[, unit])
R = TimeLimits(T, /range [, unit])
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS)
SEP-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /bounds keyword
[Previous]
[Next]
NAME:
TimeLInterpol
PURPOSE:
Linear interpolation on a function of time
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeLInterpol, ff, tt, t, unit, $
scalar = scalar , $
inear = inear , $
dtnear = dtnear , $
ilow = ilow , $
dtlow = dtlow , $
fraction= fraction , $
ihigh = ihigh , $
dthigh = dthigh
INPUTS:
ff array[n]; type: any
function values
if ff does not exist then the array index
lindgen(n) is used
tt array[n]; type: time structure
UT times
t array[m]; type: time structure
times were interpolated values are needed
OPTIONAL INPUTS:
/scalar if n=1 then return values will be scalars instead
of array[1]
OUTPUTS:
inear = inear
dtnear = dtnear
ilow = ilow
dtlow = dtlow
ihigh = ihigh
dthigh = dthigh
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
ArrayLocation, InitVar, IsType, TimeLimits, TimeOp, TimeUnit
CALLED BY:
smei_coriolis, smei_mkorb
PROCEDURE:
MODIFICATION HISTORY:
DEC-2005, Paul Hick (UCSD/CASS)
[Previous]
[Next]
NAME:
TimeMonth
PURPOSE:
Converts integer month to 3-char month and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeMonth, month, check=check, year=year, full=full, mixed=mixed, lowcase=lowcase
INPUTS:
month scalar or array; type: integer or string
if integer then values must be between 1 and 12
if char then values must be one of
JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC
(case insensitive).
OPTIONAL INPUT PARAMETERS:
/check if set then no conversion is done, but the input
array is checked to make sure all entries are valid.
The input array must be numeric (usually integer).
year=year if /check is set, or numeric input is converted to string
then months outside the range 1-12 are mapped back
into the range 1-12. In this case 'year' is updated
accordingly where the month was changed.
(e.g. if month=14 and year=2003 on input, then
month=2 and year=2004 is returned).
OUTPUTS:
mon same array type as input; type; string or integer
converted month array
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncArgs
CALLED BY:
TimeSet, TimeString, TimeYDate, smei_www_skymaps
PROCEDURE:
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS)
MAY-2008, Paul Hick (UCSD/CASS)
Integer month input is now mapped to range 1,12
instead of aborting when outside this range.
JUL-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword 'year'.
[Previous]
[Next]
NAME:
TimeOp
PURPOSE:
Simple operations on times
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeOp, t, u, unit , $
add = add , $
subtract = subtract , $
meant = meant , $
times = times , $
divide = divide , $
wt = wt , $
wu = wu , $
units = units , $
old_units = old_units , $
new_units = new_units , $
signdiff = signdiff
v = TimeOp(t,u, /add)
v = TimeOp(t,u, /subtract)
v = TimeOp(t,u, /meant, wt=wt, wu=wu)
u = TimeOp(t, /units, old_units=old_units, new_units=new_units)
INPUTS:
t array; type: time structure
u array; type: time structure
OPTIONAL INPUT PARAMETERS:
/add if set, add t and u (not that u in this case is interpreted
as a time difference
/subtract if set, get the time difference t-u
/meant return a weighted mean of t and u (with weights wt and wu)
/times
/divide
/units if set convert from 'old_units' to 'new_units'
If none of the above keywords is set then /subtract is assumed.
wt=wt scalar or array; type: double; default: 1.0d0-wu or 0.5d0
weight for first time array (t)
wu=wu scalar or array; type: double; default: 1.0d0-wt or 0.5d0
weight for second time array (u)
Input is converted to double if necessary
old_units=old_units
scalar; type: integer; default: !TimeUnits.in_day
# times per day currently stored in t
new_units=new_units
scalar; type: integer; default: !TimeUnits.tiny
new units
OUTPUTS:
u array; type: time structure
added times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeGet, TimePieces, TimeSet, TimeStandardize, TimeUnit
CALLED BY:
Carrington, CarringtonT, CarringtonT0, CarringtonVar, EarthTransit3DLoc
GeographicInfo, InsituTimeSeries [1], InsituTimeSeries [2], IsBadTime, PlotCurve
PlotPrep, RemoteView_BodyLoc, RemoteView_CMEDensity, RemoteView_Init_FOV
TimeGST, TimeGet, TimeInterpol, TimeLInterpol, TimeLimits, TimeOrigin, TimeScale
TimeSet, TimeShift, TimeSplit, TimeSystem, TimeXAxis, big_orbit, even_light
getnagoyasources, getootyasources, getsmeisources, gridgen, gridgen1d, jpl_eph
jpl_test, mpc_eph, nso_fe_plot, qImage_cw_DrawEphem, qLine_Curve, qView_UpdateTime
sgp4_eph, sgp4_orbit_axis, sgp4_tle, skyd_cat, smei_base_testcase, smei_buf
smei_buf_getframe, smei_buf_prep, smei_buf_read, smei_buf_splitfile
smei_camera_gain, smei_coriolis, smei_filepath, smei_frm_cp, smei_frm_cvhdr
smei_frm_findpoint, smei_frm_info, smei_frm_read, smei_frm_smoothdark
smei_frm_summary, smei_getfile, smei_hdr_get, smei_hdr_make, smei_hdr_plot
smei_hdr_update, smei_mkbase, smei_mkdrives, smei_mkorb, smei_mkorb_auto
smei_mksky, smei_orbit_stats, smei_rewind, smei_sgp4_orbits, smei_sky_atlocation
smei_sky_read, smei_sky_track, smei_star_fit, smei_star_remove
smei_star_showsmooth, smei_star_split, smei_star_test, smei_time
smei_zld_remove [1], smei_zld_remove [2], smei_zld_weekly, stopwatch
vu_atlocation, vu_elotime, vu_getdata, vu_gettime, vu_header, vu_insitu
vu_insitu_persist, vu_insitu_raw, vu_insitucurve, vu_is_sequence, vu_localskymap
vu_mean, vu_movie, vu_nagoyasourcemap, vu_new_time, vu_select, vu_timeseries
vu_update_hours, vu_update_marker, vu_vox_draworbit, vu_vox_write, vu_weight
vu_whatis, www_help_tree
PROCEDURE:
/meant set:
If neither wu nor wt are specified then the unweighted mean time
(t+u)/2 is returned.
If only one weight is defined then the other weight is set to
1-(specified) weight, i.e. a weighted mean is calculated:
wt*t+(1-wt(u)) or (1-wu)*t+wu*t
If both weights are specified the wt*t+wu*u is returned.
Uses !TimeUnits
Note that the units in the returned time are not necessarily consistent
anymore with !TimeUnits.in_day. It is the users responsibility to make
sure that this does not lead to mayhem.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS)
APR-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Fixed bug in calculation of signdiff
Added keyword /scalar to TimeGet call used to get signdiff.
Signdiff is now a returned as a scalar if both t and u are
1-element time structure arrays.
[Previous]
[Next]
NAME:
TimeOrigin
PURPOSE:
Converts time structure to array and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeOrigin(t)
INPUTS:
t0 /get NOT set:
array[1]; type: time structure
time origin additional offset to the origin
defined in keywords /d2000, /jd, /mjd, /njd
OPTIONAL INPUT PARAMETERS:
/get if set then the current settings are returned in t0
/time do not change the origin, only change time units
/d2000 if set then the origin is set to 2000 Jan 1, 0 UT
(plus t0 if specified).
/jd if set then the origin is set to JD=0
(plus t0 if specified)
/mjd if set then the origin is set to JD=2400000
(plus t0 if specified)
/njd if set then the origin is set to 2000 Jan 1, 12 UT
(plus t0 if specified)
units_in_day=units_in_day
scalar; type: integer; default: !TimeUnits.in_day
# times per day
OUTPUTS:
u array; type: array[2,*] or time structure
converted time
OPTIONAL OUTPUT PARAMETERS:
t0 /get SET: current settings of time origin and time units
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeArray, TimeOp
CALLED BY:
Carrington, CarringtonT, TimeShift
PROCEDURE:
Uses structure definition in !TheTime
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimePieces
PURPOSE:
Manipulate time structures
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimePieces, t, p, days=days, tiny=tiny, units=units, add=add
INPUTS:
t array; type: time structure; default: !TheTime
times
p array; type: integer
time component to be entered into 't'
OPTIONAL INPUT PARAMETERS:
/days return # whole days in t
/units return fraction of day in current units
/tiny return fractions of day in smallest permitted
time units (as set in !TimeU.tiny)
OUTPUTS:
v array; type: integer
returns a part of the input time.
If /days and /tiny NOT set:
fraction of day in current units
(as set by !TimeUnits.in_day)
If /day SET:
# whole days in t
If /tiny SET:
fraction of day in smallest permitted units
(as set by !TimeUnits.tiny)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
TimeArray, TimeDay, TimeGet, TimeOp, TimeSet, TimeStandardize
RESTRICTIONS:
The assumption is made that !TimeUnits.tiny is an
integer multiple of TimeUnits.in_day. If this is not the case
integer truncation occurs, with probably pretty nasty side effects.
PROCEDURE:
As much as possible all access to the fields in the time
structure should be channelled through this function.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
timeposn
PURPOSE:
Finds location of time in string
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION timeposn, names_, $
front = front , $
back = back , $
time = time , $
cbreak = cbreak, $
format = format, $
extract = extract,$
part = part , $
length = length
INPUTS:
names array; type: string
strings containing times
OPTIONAL INPUT PARAMETERS:
cbreak=cbreak scalar or 2-element array; type: string; default: '_' (underscore)
separator between time fields. The 2nd, if present is
used as separator between hrs, min and seconds fields.
part=part scalar; type: string
usually part='name'. 'names' is treated as
a file name and only part 'part' of the name
is processed (e.g. GetFileSpec(names,part=part)
only processed the file name part after stripping
directory and extension)
/extract return times (i.e. as also returned in keyword 'time')
OUTPUTS:
p array; type: long
position in 'names' where the time starts
-1 if no time was found
OPTIONAL OUTPUT PARAMETERS:
time=time array; type: time structure
times extracted from 'names'.
Set to !TheTime if no time was found
front=front array; type: string
part of 'names' preceeding the time
back=back array; type: string
part of 'names' trailing the time
format=format array; type: string
format string used to extract the time with TimeSet
length=length array; type: integer
format length, i.e. strlen(format)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
GetFileSpec, InitVar, IsType, SyncArgs, TimePosn_add, TimePosn_backcheck
TimePosn_test, TimeSet, UNIQ, boost, strposn
CALLED BY:
skyd_cat, smei_TimePosn, smei_buf_splitfile, smei_coriolis, smei_filename
smei_frm_read, smei_getfile, smei_hdr_update, smei_mkorb, smei_property
smeidb_mounted
PROCEDURE:
YMD and YDOY type formats are accepted:
YYYY[_DOY_HHMMSS] and YYYY[_MN_DD_HHMMSS]
where the parts between brackets are optional.
The date and time of day can be separated by a space (instead
of a cbreak char. A separate cbreak can be specified for the
hours, minutes and seconds field (usually a colon).
IF a millisecond field is present it can be separated from
the minutes field by a dot.
EXAMPLE:
Format YYYY/MN/DD hh:mm:ss.fff is detected with cbreak=['/',':']
MODIFICATION HISTORY:
JUL-2005, Paul Hick (UCSD/CASS)
DEC-2007, Paul Hick (UCSD/CASS)
Added /reverse_order to TimePosn_test call that searches
for the year field.
MAR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keywords /extract, part=part and length=length.
Added code to process cbreak='' (null_string)
[Previous]
[Next]
NAME:
TimePosn_add
PURPOSE:
Internal use for TimePosn only
INPUTS:
format
times
back
slack
piece scalar; type: string
piece of format string for time (e.g. 'YYYY')
CALLING SEQUENCE:
PRO TimePosn_add, format,times,back,slack,f,b,trail,cc,is_too, piece
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
timeposn
MODIFICATION HISTORY:
[Previous]
[Next]
NAME:
TimePosn_backcheck
PURPOSE:
Internal use for TimePosn only
CALLING SEQUENCE:
FUNCTION TimePosn_backcheck, back, check
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
timeposn
MODIFICATION HISTORY:
[Previous]
[Next]
NAME:
TimePosn_test
PURPOSE:
(Internal use by timeposn only)
Tests for a number of ntest chars in ctest
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimePosn_test, ctest, ntest, cbreak, trail, lead, $
complement = complement , $
reverse_order = reverse_order , $
test_null = test_null
INPUTS:
ctest array; type: string
array of strings to be tested
Typically ctest is the "front" return argument of a call
to strposn called with /frontdefault set, i.e.
ctest will end with the cbreak char, or is the remaining
part of the string tested with strposn if no cbreak
was present.
ntest scalar; type: integer
we are looking for isolated sequence of ntest numbers
at the start (/reverse_order NOT set) or the end of
ctest (/reverse_order SET).
cbreak scalar; type: string
The break char used in the strposn call (usually '_')
(only used if /reverse_order SET)
OPTIONAL INPUT PARAMETERS:
OUTPUTS:
result array; type: integer
indices in ctest where strmid(ctest,0,ntest)
is a self-contained number (i.e. numerical chars
only, NOT followed by another numerical char)
ctest array; type: string
ctest[result] contains the self-contained
numbers (i.e. the length of these substrings
is ntest). The other entries in ctest are
unmodified.
lead array; type: string
if /reverse_order is NOT set: array of null strings.
if /reverse_order SET: part of ctest preceeding
an isolated sequence of numbers.
trail array; type: string
trail[result] is the trailing part (not
returned in ctest[result]. The other entries
in trail are blank strings
OPTIONAL OUTPUT PARAMETERS:
complement=complement
complement of the return index array
i.e. indices in ctest that do not contain an
isolated sequence of numbers
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, strreverse, where_common
CALLED BY:
timeposn
PROCEDURE:
MODIFICATION HISTORY:
JUL-2005, Paul Hick (UCSD/CASS)
DEC-2007, Paul Hick (UCSD/CASS)
Added keyword /reverse_order
MAR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword /test_null
[Previous]
[Next]
NAME:
TimeReadMe
PURPOSE:
Help file for time variables in SMEI IDL software
CATEGORY:
gen/idl/toolbox/time
SEE ALSO:
TimePieces, defsysv_smei
PROCEDURE:
Three system variables are defined at startup (in defsysv_smei.pro)
to control the handling of time variables:
IDL> help, /structure, !timeunits
** Structure TIMEUNITS, 2 tags, length=8, data length=8:
IN_DAY LONG 86400000
TINY LONG 86400000
IDL> help, /structure, !thetime
** Structure THETIME, 2 tags, length=8, data length=8:
DAYS LONG 0
UNITS LONG 0
IDL> help, /structure, !timezero
** Structure THETIME, 2 tags, length=8, data length=8:
DAYS LONG 0
UNITS LONG 0
!TimeUnits has two integer fields:
!TimeUnits.in_days defines the unit used to keep track of the time of day
in !TheTime.units. It is the number of these time units in one whole day.
Currently this unit is milli-second, i.e. !TimeUnits.in_day = 86,400,000
Other allowed values are 24 (time-of-day units are hours), 1440 (units are
minutes) or 86400 (units are seconds).
!TimeUnits.tiny defines the smallest allowed time units allowed for the
time of day. Currently this also is milli-second, i.e.
!TimeUnits.tiny=!TimeUnits.in_day.
!TimeUnits.tiny is used primarily in rounding operations
(see the /roundt keyword on TimeGet).
All time variables are defined as arrays of !TheTime structures.
!TheTime has two long integer fields that together define the time elapsed since
some reference time (time origin).
!TheTime.days keeps track of integer days.
!TheTime.units keeps track of the time of day in units defined by !TimeUnits.in_day.
i.e. the time (in days) elapsed since the reference time is
!TheTime.days+!TheTime.units/!TimeUnits.in_day.
By default the reference time is set in !TimeZero.
!TimeZero itself is a !TheTime structure, and defines the time elapsed since
the 'absolute time origin' 2000, Jan 1, 0 UT. The default for !TimeZero is {0,0}
i.e. the current origin is set by default to the absolute origin.
TimeOrigin:
The function TimeOrigin is used to manipulate !TimeZero, and the setting
of !TimeUnits.in_day (!TimeUnits.tiny is never changed).
TimeShift:
A change of origin usually means that time variables need to be modified to
reflect the new origin. This is done with TimeShift.
TimeSet:
Most common real-life times can be converted to a !TheTime structure using
TimeSet. Examples are yr,mon,day triplets, yr,doy pair, (Modified) Julian Days,
Julian epochs, various string formats, etc.
TimeGet:
This function is used to extract real-life data from a !TheTime structure.
Examples are year, day of year, day of week, day of month, Julian day, etc.
It also provides additional services, such as rounding of times.
Usage:
In principle, every routine that takes a time structure as input,
should assume that the time specifies time elapsed since the origin
!TimeZero.
MODIFICATION HISTORY:
FEB-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeRound
PURPOSE:
Find rounded values bracketing the specified time range
CATEGORY:
Tell time
CALLING SEQUENCE:
R = TimeRound(dT,Unit)
INPUTS:
dT array; type: integer or float
times (in unit of 'Unit')
Unit array; type: integer
determines the time units of dT
(set by TimeUnit)
OUTPUTS:
R array[2]; type: float
two times bracketing dT (in units of 'Unit')
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
TimeXAxis
PROCEDURE:
Tricky and imperfect
MODIFICATION HISTORY:
???-????, Paul Hick (pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeScale
PURPOSE:
Returns range of time axis to data units established by
a previous call to TimeXAxis
CATEGORY:
Telling time
CALLING SEQUENCE:
R = TimeScale(t)
INPUTS:
t array; type: time structure
time array to be converted to data units
OPTIONAL INPUT PARAMETERS:
OUTPUTS:
R array; type: float
times converted to data units
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
TimeOp
CALLED BY:
TimeXAxis, qLine_FitPlot, smei_frm_summary, smei_hdr_plot
COMMON BLOCKS:
common TimeScale, torigin, trange, tunit, texact
PROCEDURE:
> The common block is set by a call to TimeXAxis.
MODIFICATION HISTORY:
JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeSet
PURPOSE:
Convert real-world time units to time structure.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
T = TimeSet(Tunit,unit)
T = TimeSet(/diff, year=year, day=day
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(year=year, doy=doy
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(year=year, month=month, day=day
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(Tunit, T0, format=format
See TimeSplit
INPUTS:
For time differences:
--------------------
The calculation does not involve the internal time origin !TimeZero,
although the time can still be interpreted as the time elapsed
since !TimeZero)
T = TimeSet(Tunit, unit)
Tunit array; type: any numerical type
times specified in units of 'unit'
unit scalar; type: integer; default: none
integer indicating the time units of 'Tunit'
Should be a return value of fnc TimeUnit.
The input 'Tunit' in units of 'unit' are converted
to a standard time structure.
T = TimeSet(/diff, year=year, day=day, hour=hour, $
minute=minute, sec=sec, msec=msec)
The arguments can be a combination of scalars and arrays
of any numerical type (incl. float or double).
Input units are combined into standard time structure.
Years are interpreted as Julian years of 365.25 days.
The /diff keyword is optional, but more robust. If omitted a list
of checks for 'calendar keywords' (see below) is done; if none is
found then a recursive call with /difference SET follows.
For specific dates ('calendar times'):
--------------------------------------
Calendar times can be set in a number of different 'calendar keywords'.
In addition to the keywords specified below, the time-of-day keywords hour,
minute, sec and msec are permitted. The associated elapsed time (i.e. a time
difference calculated internally by a recursive call to TimeSet with /diff set)
is added to the time calculated from the main keywords.
The resulting time is returned relative to the current origin !TimeZero,
i.e. the returned value T depends on the setting of !TimeZero with
!TimeZero+T the time elapsed since 2000 Jan 1, 0 UT.
T = TimeSet(year=year, doy=doy)
Specify Year and Day Of Year.
The year is an integer; if omitted it is set using the system time;
doy (day of year) MUST be specified and can include a fraction for
the time of day. Calendar related keywords /julian and /jul2greg are
permitted (see TimeYDoy)
T = TimeSet(year=year, month=month, day=day)
Specify Year, Month, Day Of Month.
The year is an integer; if omitted it is set using the system time;
the month MUST be present either as an integer (1-12) or as a 3-char string
('jan', 'feb', etc.; case insensitive); the day of the month, if not defined,
is set to 1, and it can include a fraction for the time of day.
Calendar related keywords /julian and /jul2greg are permitted
(see TimeYDoy, TimeYDate).
T = TimeSet(jd =jd )
T = TimeSet(mjd=mjd)
T = TimeSet(njd=njd)
Specify a Julian day (number of days elapsed since noon of a specific date)
'jd' is the conventional Julian day (e.g. jd=2451545 is 2000 Jan 1, 12 UT)
'mjd' is the modified Julian day, JD-2400000, i.e.the first two digits of
the Julian day are dropped; e.g. mjd=51545 is 2000 Jan 1, 12 UT)
'njd' is the new Julian day, JD-2451545, (e.g. njd=0 is 2000 Jan 1, 12 UT)
Specify an epoch:
T = TimeSet(jepoch=jepoch [, /diff])
T = TimeSet(bepoch=bepoch [, /diff])
Specify time as Julian epoch and Besselian epoch. These are typically
specified as double arrays.
String times for specific dates:
T = TimeSet(TT, [T0 , format=format, $
year=year, day=day, hour=hour,minute=minute, sec=sec, msec=msec])
With TT a time in string time representation and T0 a time origin
(see TimeSplit). The string time is converted to a time structure
by a call to TimeSplit (using T0 and 'format'). The additional
keywords are added to the resulting time.
OPTIONAL INPUT PARAMETERS:
/difference if set, initialize a time difference
/stringt if set, a call to TimeString is made, resulting in
the return of a time in string representation.
OUTPUTS:
T array; type: standard time structure or string
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
Carrington, InitVar, IsType, SyncArgs, TimeDay, TimeGet, TimeMonth, TimeOp, TimePieces
TimeShift, TimeSplit, TimeStandardize, TimeString, TimeSystem, TimeUnit, TimeYDate
TimeYDoy, smei_coriolis
CALLED BY:
Carrington, CarringtonT, CarringtonT0, CarringtonVar, CvSky_Galactic
EarthTransit3DLoc, FUNCTION smeilatest lastorbit, GeographicInfo, InSitu
InsituTimeSeries [1], InsituTimeSeries [2], MessengerOrbit, PlotCurve
PlotEloTimeMap, PlotPrep, RemoteView_BodyLoc, StereoAOrbit, StereoBOrbit
TimeEaster, TimeGST, TimeGet, TimeOp, TimeSplit, TimeString, TimeSystem, TimeXAxis
TimeYDate, TimeYDoy, UlyssesOrbit, big_eph, big_orbit, clock, cv, getnagoyasources
getootyasources, getsmeisources, gridgen, gridgen1d, jpl_eph, jpl_test, makemovie
mpc_comets, mpc_eph, mpc_orbit_eph, mpc_packed_date, nagoya_glevel, nso_fe_plot
nso_fe_start, qEphem_State, qImage_cw_DrawEphem, qImage_cw_Ephem
qImage_cw_Where, qLine_Curve, qView_ApplyGain, qView_GetData, qView_PlotSeries
qView_PlotTrack, qView_Save2File, qView_UpdateTime, qnagoya_pointsources
qnagoya_skymap, sgp4_eph, sgp4_orbit_axis, sgp4_tle, skyd_cat, skyd_version
smei_base_testcase, smei_buf_get, smei_buf_getframe, smei_buf_prep
smei_buf_splitfile, smei_camera_gain, smei_coriolis, smei_filename
smei_filepath, smei_findpnt, smei_frm_cp, smei_frm_cvhdr, smei_frm_drive
smei_frm_eclipse, smei_frm_findpoint, smei_frm_mask, smei_frm_smoothdark
smei_frm_summary, smei_getfile, smei_hdr_c3maskupload, smei_hdr_get
smei_hdr_make, smei_hdr_plot, smei_hdr_update, smei_last_tle, smei_mkbase
smei_mkcal, smei_mkdrives, smei_mkmask, smei_mkorb, smei_mkorb_auto
smei_mksidereal, smei_mksky, smei_orbit_stats, smei_plot_timeseries
smei_property, smei_rewind, smei_sgp4_orbits, smei_sky, smei_sky_atlocation
smei_sky_read, smei_sky_track, smei_star_fit, smei_star_show
smei_star_showsmooth, smei_star_split, smei_star_test, smei_time
smei_www_skymaps, smei_zld_remove [1], smei_zld_remove [2], smei_zld_weekly
smeidb_mounted, timeposn, usno_eph, vu_elotime, vu_header, vu_insitu
vu_insitu_persist, vu_insitu_raw, vu_insitucurve, vu_localskymap, vu_movie
vu_nagoyasourcemap, vu_new_time, vu_set_time_entry, vu_update_hours
vu_vox_draworbit, vu_vox_read, vu_vox_write, vu_weight, wso_read
PROCEDURE:
Messy, but it works
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
AUG-2000, Paul Hick (UCSD/CASS)
Introduced keyword Month, which accepts both integer and character
specifications. This makes keywords iMon (for integer input) and
cMon (for character input) obsolete.
JUL-2003, Paul Hick (UCSD/CASS)
If Doy of Day is specified without a year then the current year is used.
DEC-2003, Paul Hick (UCSD/CASS)
Fixed problem with keyword month. Only types string and integer were
acceptable. Anything else would cause an error. Now if is neither string
nor integer, it is converted to integer by rounding.
JAN-2004, Paul Hick (UCSD/CASS)
Fairly substantial rewrite, converting from the old time structure
with year,doy,h,m,s,msec fields to the new structure with two integer fields.
JUN-2004, Paul Hick (UCSD/CASS)
Added processing of string times. Hopefully this elimates the necessity to
call TimeSplit and TimeString directly.
OCT-2007, Paul Hick (UCSD/CASS)
Added keyword fmtspec (see TimeSplit)
JUL-2009, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword /unix
[Previous]
[Next]
NAME:
TimeShift
PURPOSE:
Converts between various possible origins
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeShift(from_time=from_time, from_d2000=from_d2000, from_jd=from_jd, $
from_mjd=from_mjd, from_njd=from_njd, /to_time, /to_d2000, /to_jd, /to_mjd, /to_njd
INPUTS:
from_time=from_time current origin
from_y200=from_d2000 2000 Jan 1, 0 UT
from_jd=from_jd JD = 0
from_mjd=from_mjd JD = 2400000
from_njd=from_njd 2000 Jan 1, 12 UT
array; type: time structure
times relative to implied origin
/to_time if set return time relative to 2000 Jan 1, 0 UT
/to_d2000
/to_jd
/to_mjd
/to_njd
OUTPUTS:
u array; type: time structure
converted times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeOp, TimeOrigin
CALLED BY:
TimeGet, TimeSet
PROCEDURE:
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeSplit
PURPOSE:
Convert times from string to numerical
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeSplit, TSS, T0, $
template = template , $
format = format , $
rational = rational , $
fmtspec = fmtspec
INPUTS:
TS array; type: string
times in string form
T0 array[1]; type: time structure
time origin
OPTIONAL INPUTS:
format=format
scalar; type: sting; default: none
string template specifying the time format, e.g. 'YEAR/MN/DD hh:mm:ss.mss'
Valid components are:
YEAR for 4-digit year
YY for 2-digit year (converted using TimeFixYear)
DOY for the day of year
MON for 3-char month ('jan')
MN for 2-digit month (01-12)
DD for the day of the month
hh for the hour of the day
mm for the minutes
ss for the seconds
mss for the milliseconds
OUTPUTS:
T array; type: time structure
output times with numerical values for the
seperate components of the time array
If an error occurs then T = -1 is returned.
The function IsTime(T) can be used to check for an
error condition.
OPTIONAL OUTPUTS:
fmtspec=fmtspec
scalar; type: string
if format NOT set: format string used to interpret
the input strings.
if format SET: specfmt is same as input format
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncDims, TagArray, TimeFixYear, TimeGet, TimeOp, TimeSet, TimeUnit
destroyvar, flt_string
CALLED BY:
TimeSet
RESTRICTIONS:
The first element of the TS array is used to analyze the exact string format.
This format is used to decompose all string elements in their constituent parts.
Hence, if TS is a string array, all entries must have exactly the same format!!!
PROCEDURE:
The string times in TS do not have to be complete.
Missing parts are taken from the time origin T0
Four types of strings can be entered:
1999:300:00:00:00.000
1999/11/20 00:00:00.000 (YMD format)
SAT JAN 10 00:00:00 1991 (SYS format)
19-NOV-1999 23:48:11.00 (VMS format)
03-23-2000 23:48:11 (SMEI format)
2003_023_234811000 (L1A format)
2003-10-11T23:48:11.000 (ISO-8601 format)
MODIFICATION HISTORY:
AUG-1998, Paul Hick (UCSD/CASS)
NOV-1999, Paul Hick (UCSD/CASS)
Added VMS format, fairly substantial rewrite
APR-2000, Paul Hick (UCSD/CASS)
Added SMEI format '03-23-2000 23:48:11'
MAR-2003, Paul Hick (UCSD/CASS)
Added processing of strings like 2003_175_123456789
OCT-2003, Paul Hick (UCSD/CASS)
Added processing of strings like 2003_10_02_123456789
NOV-2003, Paul Hick (UCSD/CASS)
Added keyword 'template'
JUN-2005, Paul Hick (UCSD/CASS)
Rename keyword 'template' to 'format'.
SEP-2007, Paul Hick (UCSD/CASS)
Added some code to handle ISO-8601 compliant times
OCT-2007, Paul Hick (UCSD/CASS)
Added output format spec keyword 'fmtspec'
DEC-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added code to allow input of fractional units in
day of month, hour, minutes, seconds, e.g.
'2003/10/10.5' or '2003/10/10 12.5'
[Previous]
[Next]
NAME:
TimeStandardize
PURPOSE:
Standardize times
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
FUNCTION TimeStandardize, t
INPUTS:
t array; type: time structure
times
OUTPUTS:
t array; type: time structure
standardized times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
TimePieces
CALLED BY:
TimeArray, TimeDay, TimeGet, TimeOp, TimeSet
SIDE EFFECTS:
Uses !TimeUnits.in_day
PROCEDURE:
Makes sure that the fraction of days stored in t.units
is a positive fraction and less than one day.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeString
PURPOSE:
Converts times intro string form
CATEGORY:
Tell time
CALLING SEQUENCE:
FUNCTION TimeString, TT , $
ydoy = ydoy , $
ymd = ymd , $
sys = sys , $
vms = vms , $
iso8601 = iso8601 , $
_ymd = _ymd , $
_ydoy = _ydoy , $
from = from , $
upto = upto , $
part = part , $
roundt = roundt , $
format = format
INPUTS:
T array; type: time structure
times to be converted to string form
OPTIONAL INPUTS:
/ydoy returns string in form '1999:201:00:00:00.000'
/ymd returns string in form '1999/11/22 00:00:00.000'
/sys if set, a PC-style system string is returned (in uppercase)
/vms if set, a VMS-style system string is returned (in uppercase)
/iso8601 if set, a ISO-8601 compliant format is used:
i.e. 2007-01-01T01:01:01.000
/_ydoy returns string in form 1999_201_000000000'
/_ymd returns string in form 1999_11_22_000000'
part scalar; type: integer
same as specifying 'from' and 'upto' with the same argument
from scalar; type: integer
should be set using the return value of TimeUnit.
If 'format' is NOT set then the time string will start
at the indicated time unit.
If 'format' is SET then 'from' is ignored.
upto scalar; type: integer
should be set using the return value of TimeUnit.
If 'format' is NOT set then the time string will end
indicated time unit. If in addition /roundt is set then
TT is rounded to unit 'upto' before being turned into a string.
If 'format' is SET, and in addition /roundt is set, then
'upto' is used for roundoff only.
format=format
scalar; type: string; default: none
string format specifying the time format, e.g. 'YEAR/MN/DD hh:mm:ss.mss'
The format can combine any of the following sections in any order:
YEAR insert 4-digit year
YY insert 2-digit year
DOY insert day of year
MON insert month as 3-char string ('jan')
MONTH insert full name of month
MN insert month as 2-digit integer (1-12)
DD insert day of month as 2-digit integer
DOW insert day of week as 3-char string ('sat')
hh insert hour of day
mm insert minutes
ss insert seconds
mss,fff insert milliseconds
OUTPUTS:
R array; type: string
times in string form
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncDims, TimeGet, TimeMonth, TimeSet, TimeUnit
CALLED BY:
TimeGet, TimeSet
SEE ALSO:
TimeSplit
SIDE EFFECTS:
An earlier version of TimeString did not have the 'roundt' keyword.
It would always round when upto was set to units of hours or smaller,
and not round for units of years or days.
PROCEDURE:
If 'format' is NOT set the following formats are supported:
YDOY format: '0000:000:00:00:00.000' (default)
YMD format: '0000/00/00 00:00:00.000'
SYS format: 'SAT JAN 10 00:00:00 1991'
VMS format: '19-NOV-1999 23:48:11.00'
_YDOY format: '0000_000_000000000'
_YMD format: '0000_00_00_000000000'
The 'format' keyword obviously is a more transparent way of setting
a specific time format. The only reason to use one of the specific
formats above is the 'from' keyword, which is not implemented (yet??)
for the 'format' keyword (other than explicitly mutilating the
'format' itself).
MODIFICATION HISTORY:
AUG-1998, Paul Hick (UCSD/CASS)
NOV-1999, Paul Hick (UCSD/CASS)
Added VMS keyword
MAR-2003, Paul Hick (UCSD/CASS)
Added /fsys keyword
OCT-2003, Paul Hick (UCSD/CASS)
Renamed /fsys to /_ydoy. Added /_ymd.
NOV-2003, Paul Hick (UCSD/CASS)
Added keyword 'template'.
JAN-2003, Paul Hick (UCSD/CASS)
Removed /fsys keyword.
Added keyword /roundt. Rounding was automatic for 'upto' units
of hours or smaller. Rounding needs to be specified explicitly
for all units now.
OCT-2004, Paul Hick (UCSD/CASS)
Fixed bug in processing of seconds and msec. If the template
contained 'hhmmss' to represent hour, minute, seconds then the
trailing 'mss' would be interpreted as millisecond. This is fixed
by clearing portion of the template after they have been used.
JUN-2005, Paul Hick (UCSD/CASS)
Changed 'template' keyword to 'format'. 'template' is still supported
(for now).
JUL-2007, Paul Hick (UCSD/CASS)
Removed keyword 'template'
SEP-2007, Paul Hick (UCSD/CASS)
Added keyword /iso8601 to make string in ISO8601-compliant form
APR-2011, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added option to use 'month' in format to be substituted by
full name of month (e.g. 'January' instead of 'JAN')
[Previous]
[Next]
NAME:
TimeSystem
PURPOSE:
Convert system time to UT
CATEGORY:
Time
CALLING SEQUENCE:
ut = TimeSystem(local2ut)
INPUTS:
local2ut scalar; type:integer; default: 0
offset between local time and UT
OPTIONAL INPUT PARAMETERS:
/utc (this keyword was introduced in IDL 5.4)
passed to the IDL function systime
If this keyword is set then systime already
returns UT. If /utc is used then local2ut should
be set to zero.
OUTPUTS:
ut scalar; type: time structure
current universal time
INCLUDE:
@compile_opt.pro ; Return to caller
CALLS: ***
InitVar, IsType, TimeGet, TimeOp, TimeSet
CALLED BY:
RemoteView_FOV, RemoteView_Init_Matrix, RemoteView_Init_View, TimeSet, arg_time
big_eph, even_light, qEphem, qnagoya, sgp4_orbit_axis, smei_buf, smei_findpnt
smei_frm_summary, smei_getfile, smei_hdr_plot, smei_hdr_update, smei_mkcal
smei_mksky, smei_orbit_stats, smei_star_remove, smei_star_writepnt
smei_www_skymaps, smei_zld_remove [1], smei_zld_remove [2], smei_zldsky
stopwatch, vu_write, www_help_tree
PROCEDURE:
The system time is retrieved using the IDL systime function,
and is assumed to set to the local time.
UT is calculated by adding 'local2ut' hours to the system time.
Note that this means that local2ut=0 simply returns the system time.
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS)
JUL-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Fixed version problem reported by Dick Altrock.
Embedded the 'systime' call containing the /utc keyword inside
a 'call_function' call to avoid compilation problems on
pre-5.4 versions of IDL.
[Previous]
[Next]
NAME:
TimeUnit
PURPOSE:
Provides information about time units used in time structures
CATEGORY:
Tell time
CALLING SEQUENCE:
FUNCTION TimeUnit, tunit, $
nextup = nextup , $
mmsec = mmsec , $
all = all , $
years = years , $
yrs = yrs , $
days = days , $
hours = hours , $
hrs = hrs , $
minutes = minutes , $
seconds = seconds , $
mseconds= mseconds
T = TimeUnit( [/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
T = TimeUnit(/NextUp,[/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
T = TimeUnit(/msec ,[/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
INPUTS:
tunit scalar; type: integer
if tunit exist the corresponding name for the unit of time
is returned (tag name of time structure, i.e. Y,M,D,H,M,S,MS)
OPTIONAL INPUT PARAMETERS:
/years,/days,/hours,/minutes,/seconds,/mseconds
sets time unit for which information is needed (set only one at a time)
/all returns information for all time units
If /all is not set and no time unit keyword is set, then /day is assumed
/nextup return the number of units in the next larger time unit
e.g. if /hours is set the value is 24 (24 hours in a day)
/mmsec returns number of mseconds (smallest time unit) in time unit
e.g. if /hours is set the value is 60*60*100=3600000
If neither /nextup nor /mmsec is set the position of the time unit tag in the
structure is returned.
OUTPUTS:
T scalar, if one of the time unit keywords is set.
array[7] if /all is set
The array is a long integer array if tag numbers are returned;
or double precision if /nextup or /mmsec are used
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
AngleUnits, Carrington, CarringtonT0, CarringtonVar, CvSky_Heliographic, CvSky_IHG
EarthTransit3DLoc, GeographicInfo, InSitu, InsituTimeSeries [1]
InsituTimeSeries [2], IsBadTime, PA_Pole, PlotCoronagraph, PlotEarthSkymap
PlotPolarSkymap, PlotSynopticMap, RemoteView_CMEDensity, RemoteView_Display2D
RemoteView_Display3D, RemoteView_FOV, RemoteView_Init_FOV, TimeEaster, TimeGST
TimeGet, TimeInterpol, TimeLInterpol, TimeLimits, TimeOp, TimeSet, TimeSplit
TimeString, TimeXAxis, even_light, getnagoyasources, getootyasources
getsmeisources, gridgen, gridgen1d, img_read, jpl_eph, jpl_test, lsqLinearFit
makemovie, mpc_eph, nagoya_glevel, qEphem, qImage_cw_DrawEphem, qLine_Curve
qLine_FitPlot, qView_Save2File, qView_UpdateTime, qnagoya, qnagoya_pointsources
sgp4_eph, sgp4_orbit_axis, sgp4_tle, skyd_cat, skyd_version, smei_base_testcase
smei_buf, smei_buf_get, smei_buf_getframe, smei_buf_prep, smei_buf_read
smei_camera_gain, smei_filename, smei_filepath, smei_frm_base, smei_frm_cp
smei_frm_cvhdr, smei_frm_eclipse, smei_frm_findpoint, smei_frm_hbar
smei_frm_info, smei_frm_read, smei_frm_smoothdark, smei_frm_summary
smei_frm_track, smei_getfile, smei_hdr_c3maskupload, smei_hdr_get, smei_hdr_make
smei_hdr_plot, smei_hdr_update, smei_mkbase, smei_mkcal, smei_mkcal_auto
smei_mkdrives, smei_mkmask, smei_mkorb, smei_mkorb_auto, smei_mksidereal
smei_mksky, smei_orbit_stats, smei_plot_timeseries, smei_rewind
smei_sgp4_orbits, smei_sky_atlocation, smei_sky_getmask, smei_sky_track
smei_star_fit, smei_star_remove, smei_star_show, smei_star_showsmooth
smei_star_split, smei_star_test, smei_www_skymaps, smei_zld_remove [1]
smei_zld_remove [2], smei_zld_weekly, stopwatch, vu_atlocation, vu_coronagraph
vu_earthskymap, vu_elotime, vu_get_page, vu_getdata, vu_gettime, vu_header, vu_image
vu_insitu, vu_insitu_persist, vu_insitu_raw, vu_insitucurve, vu_is_sequence
vu_linecut, vu_lineofsight, vu_localskymap, vu_mean, vu_movie, vu_new_time
vu_planarcut, vu_radialcut, vu_remoteview, vu_select, vu_solardisk, vu_spherecut
vu_stereoview, vu_synopticmap, vu_timeseries, vu_update_hours, vu_update_marker
vu_vox_write, vu_weight, vu_whatis, vu_write, wso_read, www_help_tree
PROCEDURE:
MODIFICATION HISTORY:
SEP-1998, Paul Hick (UCSD/CASS)
OCT-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added tunit argument
[Previous]
[Next]
NAME:
TimeXAxis
PURPOSE:
Plot horizontal time axis
CATEGORY:
Plotting
CALLING SEQUENCE:
PRO TimeXAxis, TR, unit, $
t0 = T0 , $
same_T0 = same_T0 , $
exact = exact , $
noxtitle= noxtitle , $
yrxtitle= yrxtitle , $
tick_get= tick_get , $
axis_only=axis_only , $
xaxis = xaxis , $
starttime=starttime , $
nmajor = nmajor , $
from = from , $
upto = upto , $
trim = trim , $
xminor = xminor , $
xtickn = xtickn , $
xtickv = xtickv , $
xstyle = xstyle , $
ydoy = ydoy , $
_ydoy = _ydoy , $
_extra = _extra ;, title=title
INPUT PARAMETERS:
TR array; type: float or time structure
(must have at least two elements)
Defines range of times to be plotted
If TR is a float array then TR is a time relative to the
time origin T0 in units of 'unit'.
If T0 is not specified then TR MUST be an array
of time structures (T0 will be set internally using TR)
Only min(TR) and max(TR) are used.
Unit scalar; type: integer; default: TimeUnit(/days)
Determines the units of TR (if TR is a float array)
Use function TimeUnit to specify unit
Graphics keywords to the PLOT command are used using the _extra mechanism.
OPTIONAL INPUT PARAMETERS:
t0=T0 scalar; type: time structure
Time origin. MUST be set if TR is specified as a float array
/same_T0
if set then the time origin from a previous call to TimeXAxis
is used. If there is no origin available then the keyword is
ignored. If there is an origin available then this keyword
overrides the t0 keyword.
/exact forces time axis to cover exactly min(TR) to max(TR)
/noxtitle
suppress title for time axis
title=title NOT TRUE
title for time axis. If omitted and /noxtitle is not set then
the title is time at the start of the time axis is used as title.
from, upto
if set these keywords determine which time units are used in
the axis labels.
/axis_only
by default, the IDL plot procedure with the /nodata keyword
is used to plot the axis. If /axis_only is used then the
IDL axis procedure is used.
nmajor=nmajor
# of major tickmarks on time axis.
xstyle=xstyle
IDL xstyle keyword, but MUST be an even number
(internally 1 is added; keyword /exact controls whether
the time axis is exact or not)
/ydoy plot DOY along x-axis instead of Month/Day of Month
Usually the labels are calculated internally from the specified time array.
Override this by explicitly setting the xtickv keyword (and, optional,
the xtickn keyword:
xtickv=xtickv
xtickn=xtickv
OPTIONAL OUTPUT PARAMETERS:
starttime=starttime
scalar; type: string
time at beginning of time axis.
tick_get=tick_get
array; type: float
tickmark labels used (i.e. value of keyword xtickv
on IDL plot or axis procedures)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
InSitu, PlotCurve, PlotEloTimeMap, PlotPrep, PlotSynopticMap, jpl_test, qLine_Curve
smei_frm_summary, smei_hdr_plot, vu_insitucurve
COMMON BLOCKS:
common TimeScale, torigin, trange, tunit, texact
CALLS: ***
InitVar, IsTime, IsType, REVERSE, TimeGet, TimeLimits, TimeOp, TimeRound, TimeScale
TimeSet, TimeUnit, UNIQ, destroyvar, gridgen
PROCEDURE:
The common block stores the time origin (as a time structure) and the
time units used to generate the time axis. These are used by PlotCurve
to plot data points if the first argument to PlotCurve is a time
structure.
MODIFICATION HISTORY:
MAY-1991, Paul Hick (ARC)
Cribbed from the UTPLOT package
SEP-1998, Paul Hick (UCSD/CASS)
Introduced time structures
JAN-2001, Paul Hick (UCSD/CASS)
Renamed from TimeAxis to TimeXAxis to avoid conflict in SSW
MAY-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /ydoy keyword
[Previous]
[Next]
NAME:
TimeYDate
PURPOSE:
Gets day of year from year, month day, or gets month and
day from year and day of year
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
PRO TimeYDate, yr, month, day, doy, get_date=get_date, julian=julian, jul2greg=jul2greg
INPUTS:
yr scalar or array; type: integer
year
/get_date NOT set:
month scalar or array; type: integer or string
month as integer in 1-12 or strings of type
'JAN','FEB', etc. (case-insensitive)
day scalar or array; type: any
day of month, possibly including a fraction for
the time of day.
/get_date SET:
doy scalar or array; type: any
day of year, possibly including a fraction for
the time of day.
OPTIONAL INPUT PARAMETERS:
/get_date by default, yr, month and day are assumed to be input
and the doy is returned. If /get_date is set then
yr and doy are input and month and day are output.
/julian interpret yr,doy and yr,mon,day as dates in Julian calendar
/jul2greg
jul2greg=jul2greg
array[1]; type: time structure
time at which the transition from Julian to Gregorian
calendar is made.
/jul2greg is the same as jul2greg=TimeSet(yr=1582, mon='oct', day=15)
OUTPUTS:
/get_date set:
month scalar or array; type: integer or string
month as integer in 1-12
(use TimeMonth to get 3-char strings)
day scalar or array; type: same as input doy
day of month, with the fraction from the input
doy added (if present)
/get_date NOT set:
doy scalar or array; type: same as input day
day of year, with the fraction from the input
day added (if present).
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
TimeGet, TimeSet
SIDE EFFECTS:
yr is converted to integer if it isn't already. None of the
other input variables are modified.
CALLS: ***
InitVar, IsTime, IsType, SyncArgs, TimeGet, TimeMonth, TimeSet, TimeYDoy
PROCEDURE:
For the input arguments combinations of scalars and arrays are permitted.
If integer day and doy are used the conversion is exact. For floating input
the fraction is moved from day to doy or v.v., i.e. it is not exact.
The relation between yr,month,day and yr,doy depends only on
whether yr is a leap year or not.
Two calendar schemes are implemented. In the Julian calendar
(/julian SET) every multiple of 4 is a leap year. In the Gregrorian
calendar (/julian NOT set) every multiple of 4 is a leap year, except
when the year is a centennial year that is not a multiple of 400
(i.e. 1700, 1800, 1900 are not leap years, but 1600 and 2000 are),.
See also documentation of TimeYDoy
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS)
JUL-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
If /get_date NOT set (and yr, month, day are input), and
month is integer, outside the range 1-12, then month is now
mapped back into the range 1-12 and yr is increased/decreased
accordingly. This is used in TimeGet when the /eomonth
(end of month) keyword is set to bridge into the next year.
[Previous]
[Next]
NAME:
TimeYDoy
PURPOSE:
Converts date in yr, doy to number of days elapsed
since 2000 Jan 1, 0 UT and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
PRO TimeYDoy, yr, doy, day, get_date=get_date, julian=julian, jul2greg=jul2greg
INPUTS:
/get_date NOT set:
yr scalar or array; type: integer
year
doy scalar or array; type: any
day of year, possibly including a fraction for
the time of day.
/get_date SET:
day scalar or array: type: any
number of days elapsed since 2000 Jan 1, UT (Gregorian)
possibly including a fraction for the time of day.
Use TimeShift(d2000=TimeSet(day=day), /to_time) to convert
to a time structure (relative to current origin).
OPTIONAL INPUT PARAMETERS:
/get_date by default the number of days elapsed is calculated from
the date. If /get_date is set than the date is obtained
from the number of days elapsed since 2000 Jan 1, 0 UT.
(Gregorian).
/julian interpret yr, doy as date in Julian calendar
/jul2greg
jul2greg=jul2greg
array[1]; type: time structure
time at which the transition from Julian to Gregorian
calendar is made.
/jul2greg is the same as jul2greg=TimeSet(yr=1582, mon='oct', day=15)
OUTPUTS:
/get_date NOT set:
day scalar or array: type: double
number of days elapsed since 200 Jan 1, UT (Gregorian).
the fraction of day is copied from the input day of year
(if present)
/get_date SET:
yr scalar or array; type: integer
year
doy scalar or array; type: same as input 'day'
day of year, the fraction of day is copied from the
input day (if present)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsTime, IsType, TimeGet, TimeSet
CALLED BY:
TimeGet, TimeSet, TimeYDate
SIDE EFFECTS:
If /get_date NOT set then yr is converted to integer if it isn't already.
PROCEDURE:
The date yr,doy is a Julian date (if /julian SET) or a Gregorian date
(/julian NOT set). 'day' always is # days since 2000 Jan 1.0 (Gregorian)
i.e. Julian days minus 2451544.5
JD = 2451557.5 = 2000 Jan 14.0 (Gregorian) = 2000 Jan 1.0 (Julian)
JD = 2451544.5 = 2000 Jan 1.0 (Gregorian)
JD = 2299160.5 = 1582 Oct 15.0 (Gregorian) = 1582 Oct 5.0 (Julian)
(= -152384.0 days from 2000 Jan 1.0, Gregorian)
JD = 2361221.5 = 1752 Sep 14.0 (Gregorian) = 1752 Sep 3.0 (Julian)
The keyword jul2greg can be used to automatically switch from
Julian to Gregorian calendar. In general jul2greg is defined as
a UT standard time structure. If specified as keyword /jul2greg
then the time 1582 Oct 15.0 (Gregorian is used). The gap between
calendars at that time was 10 days.
Another useful transition would be 1752 Sep 14.0 (Gregorian).
The Britisch empire switched from 1752, Sep 2 to 1752 Sep 14
(11 day gap; the extra day comes from the year 1700 which is a leap
year in the Julian calendar but not in the Gregorian calendar).
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
twin
PURPOSE:
'TEK': Switch between alphanumeric and graphics screen
'X': Hide or show graphics window
'REGIS': Nothing
CALLING SEQUENCE:
PRO twin, mode, $
hide = hidewin, $
show = showwin, $
reset = reset, $
tl = topleft, $
tr = topright, $
br = bottomright, $
bl = bottomleft, $
center = center, $
cl = centerleft, $
tc = topcenter, $
cr = centerright, $
bc = bottomcenter, $
winnr = winnr, $
newwin = newwin, $
delete = delete, $
allwin = allwin, $
copywin = copywin, $
stackwin = stackwin, $
title = win_title, $
quarterscreen = QuarterScreen, $
onethirdscreen = OneThirdScreen,$
xsize = win_xsize, $
ysize = win_ysize, $
xysize = win_xysize, $
aspectratio = aspectratio, $
infowin = infowin, $
winmodes = winmodes, $
windex = windex, $
winwall = winwall, $
nocoordinates = nocoordinates,$
wallpaper = WallPaper, $
scream = scream
OPTIONAL INPUT:
mode 1 = restore graphics screen
2 = restore alphanumeric screen
if omitted the procedure works as a switch between both screens
In X-windows only:
The following keywords are used only when a window is created (in the
first call to Twin for the window):
/hide show window (equivalent of mode=2)
/show hide window (equivalent of mode=1)
title=title
if set and non-zero, used as title for window
xsize=xsize
horizontal window size
ysize=ysize
vertical window size
/quarter_screen
defines a window size of one quarterscreen (half screen
high/wide) (i.e. /tl,/tr,/bl,/br windows would fill up screen)
/onethird_screen
defines a window size of one-third screen high/wide
(i.e. all nine windows together would fill up screen)
/nocoordinates
by default, every time a 'show' is executed, the data
coordinates are set equal to device coordinates for the new
active window (!x.s and !y.s are modified directly).
If the /nocoordinates keyword !x and !y remain unchanged.
Keywords for selection of windows (if keyword WallPaper is NOT set):
/tl manipulates window in top-left corner
/tr manipulates window in top-right corner
/br manipulates window in bottom-right corner
/bl manipulates window in botton-left corner
/c manipulates window in center of screen
/cl manipulates window at center-left of screen
/tc manipulates window at top-center of screen
/cr manipulates window at center-right of screen
/bc manipulates window at bottom-center of screen
/newwin the next unused window is opened (ignored if /stackwin is used)
the position of the new window is topleft for /tl, etc.
/stackwin
same as newwin, but tries to stack the windows side by side
(left to right and top to bottom)
winnr=winnr
array of integers in the range [0,8], corresponding to the
windows /tl,/tr,..,etc.
The above window selection keywords work accumulative. E.g. the command
twin,/new,/tl,winnr=winnr
will manipulate the topleft window, plus the `winnr' windows, and it
will create the next available unused window.
/allwin selects all existing windows; or, if no windows exist yet,
selects all nine windows. /allwin is ignored if one of the
above keywords for window selection is used.
If none of the above keywords is used for selection, then the active
window is used (if it is one of the nine TWIN windows).
If there is no active window, then the first window is used.
/delete the specified window(s) is deleted
if both xsize and ysize are specified the window is deleted
only if the specified values differ from the window dimensions;
To find out whether or not the window has been deleted,
check the return value of DELETE (=0 if the window was not
deleted; =1 if the window was deleted)
Keywords for WallPaper option:
/wallpaper
fill up screen with small windows side by side until screen
is full
/wallpaper,/delete
delete all windows created with previous /wallpaper call
/wallpaper,show=number
makes panel `number' the active window and establishes
data coordinates which are identical to device coordinates.
OPTIONAL OUTPUT: (only if keyword DELETE is used)
delete = 0: No window deleted, =1: window deleted
windex
winmodes
CALLS: ***
InitVar, IsDisplay, IsType, IsWindowSystem, wvalid
CALLED BY:
RemoteView_Display2D, RemoteView_Display3D, RemoteView_PlotVertices
even_light, even_light_corrections, even_light_figures, even_light_info
even_light_photometry, even_light_plot, even_light_registration, get_page
jpl_test, nagoya_glevel, qView_Wall, set_page, smei_star_fit, view
PROCEDURE:
> 'TEK': Print escape sequences ("<ESC>[0/w" and "<ESC)[2/w") as given
on page 20.2 of the HDS programmers manual
> 'X': Calls to wset and wshow
> Windows are created with backing store enabled.
> The number in the window title is the TWIN number (0,..,8; which can
be used in the 'winnr' keyword), or, if the wallpaper option is used,
it's the panel number (0,..; which can be used in the /show keyword
to set the active panel window).
INCLUDE:
@compile_opt.pro ; On error, return to caller
COMMON BLOCKS:
common save_twin, old_mode,nr_window,xs_window,ys_window,nwall,xwall,ywall,nr_wall,ti_window
WARNING:
> The title of the window contains a number which is NOT THE IDL WINDOW ID
(!D.WINDOW). Every time a `wset' is executed the new !D.WINDOW value
is printed in the text window.
> In the first call to TWIN or during a /reset all existing windows are
nuked (including windows not created by TWIN).
> If TWIN encounters an active window not created by TWIN, the active
window is assimilated (and is treated as a TWIN window in following
calls to TWIN).
RESTRICTIONS:
> If called without the 'mode' argument, it may be necessary to call the
procedure twice to effect the desired change
> If TWIN is called without the /wallpaper keyword, then existing
wallpaper is removed before continuing (the reverse is not true:
wallpaper can be created, while TWIN windows are present.
MODIFICATION HISTORY:
DEC-1993, Paul Hick (UCSD)
JUL-2000, Paul Hick (UCSD); added call to 'wvalid' to make sure that the
requested window still exists before calling wshow or wset
[Previous]
[Next]
NAME:
txt_block_read
PURPOSE:
Read blocks of numerical data into multi-dimensional
data array
CALLING SEQUENCE:
FUNCTION txt_block_read, InFile , $
yy = yy , $
dd = dd , $
primary_column = primary_column, $
missing_value = missing_value , $
group = group , $
get_main_label = get_main_label, $
get_sub_label = get_sub_label , $
drop_main_label = drop_main_label,$
drop_sub_label = drop_sub_label, $
label = label , $
trail = trail , $
main_label = main_label , $
sub_label = sub_label , $
header = header , $
commentchar = commentchar , $
silent = silent , $
integer = integer , $
double_precision= double_precision
INPUTS:
InFile scalar; type: string
name of file
OPTIONAL INPUTS:
primary_column = primary_column
scalar; type: integer (see PROCEDURE)
silent = silent
/integer
/double_precision
passed to flt_string. This determines the type of
the outupt arrays yy and dd. If neither is
specified the type is float.
group = group
scalar; type: integer; default: 0
if set to a positive integer; the blocks are
subcategorized in 'main' labels, with a set
of subcategory (see PROCEDURE)
OUTPUTS:
status scalar; type: integer
0 : error
1 : success
OPTIONAL OUTPUTS:
header = header
array, type: string
header array (i.e. lines preceeding the blocks
of numbers).
yy = yy
array[ny]; type: numeric (see keywords /integer
and /double_precision)
If group=0:
dd = dd
array[N,Mk,K]
array; type: numeric (see keywords /integer
and /double_precision)
label = label[K]
The strings in the line preceeding each of the blocks
trail = trail[K]
The strings in the line following each of the
blocks (for 'closed' blocks only)
If group > 0:
dd = dd
array[N,Mk,Ksub,Kmain]
main_label = main_label
array[Ksub,Kmain]
The strings in the line preceeding each of the blocks
sub_label = sub_label
array[Ksub,Kmain]
The strings in the line following each of the
blocks (for 'closed' blocks only)
INCLUDE:
@compile_opt.pro
CALLS: ***
BadValue, InitVar, IsType, UNIQ, boost, destroyvar, flt_string, txt_read, where_common
PROCEDURE:
The file needs to be structured in the following way:
1. header; all lines start with the specified
comment char (default is a semicolon, ';')
2. single line starting with the comment char
This line is returned in the array 'label'
3. block of M1 lines containg N numbers, NOT starting
with the comment char.
This group of lines is run through flt_string
to return an array B1[N,M1].
4. optional, a single line starting with comment char,
terminating the block of numbers
This line, if present, is returned in the array 'trail'
Repeat 2,3,4 any number of times for a total
of K blocks. Note that the number of lines in the
blocks, Mk (k=0,K-1) can vary from block to block,
but the number of values in each line, N, is the same.
One column 0<= n <= N is assigned the role of primary
column (the first colum, n=0, is the default).
All values in the primary column in each individual
block must be unique, but will overlap between blocks
(in the simplest case the primary column will contain
the same numbers in each block).
A list of unique values is constructed from the numbers
Bk[n,0..Mk-1],k=0,K-1.
in the primary columns across all blocks. The number
of values, MK, will be at least the largest of the Mk
(k=0,K-1). This list of unique values is returned in
the array yy[MK].
The remaining columns for all blocks are returned
in the array dd[N,MK,K].
For block k the primary column values Bk[n,0..Mk-1]
and the remaining columns B[*,0..Mk-1,k]
are mapped into the same position in yy and the
2nd dimension of dd, respectively.
If group is set to a definite positive integer, an
attempt is made to divide the K blocks further into
Kmain main categories with Ksub subcategories
with Kmain x Ksub = K.
The names of the main categories are the first
'group' words in the array 'label'. The names of
the subcategories are the remaining unused words
in label.
MODIFICATION HISTORY:
DEC-2012, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
txt_read
PURPOSE:
Read entire ascii file into character array
CATEGORY:
I/O
CALLING SEQUENCE:
FUNCTION txt_read, InFile, data, $
approx_recl = approx_recl , $
range_recl = range_recl , $
recl = recl , $
nrec = nrec , $
silent = silent , $
delete = delete , $
test = test
INPUTS:
file scalar; type: string
fully qualified file name
OPTIONAL INPUT PARAMETERS:
approx_recl=approx_recl
scalar; type: integer
approximate record length in bytes
(passed to GuessRecs)
range_recl=range_recl
scalar: type: integer: default: 1
range of recordlength tested is approx_recl +/- range
(passed to GuessRecs)
OUTPUTS:
status scalar: type: byte
0: file not read
1: file read, data returned in 'data' array
data array[n]; type: string
array containing all records in file
(only if status=1)
OPTIONAL OUTPUT PARAMETERS:
recl=recl scalar: type: integer
guess at record length in bytes (= file size/# records)
(-1 if not succesful; output from GuessRecs)
nrec=nrec scalar: type: integer
# records on file
(nrec=-1 if opening of the file fails)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
GuessRecs, InitVar, IsType, destroyvar, do_file, gunzip_file, hide_env
CALLED BY:
FUNCTION smeilatest lastorbit, cv, env_slashes, getnagoyasources
getootyasources, mpc_comets, mpc_minor_planets, nagoya_glevel, physics_constant
sgp4_eph, sgp4_tle, skyd_cat, smei_base_testcase, smei_blocked, smei_buf
smei_buf_get, smei_buf_prep, smei_coriolis, smei_cv_catalogue, smei_frm_mask
smei_last_tle, smei_mkbase, smei_mkcal, smei_mkcal_auto, smei_mkorb
smei_mkorb_auto, smei_mksky, smei_orbit_stats, smei_rewind, smei_setup_roi
smei_sgp4_orbits, smei_star_cleanlist, smei_star_cleanup, smei_star_list
smei_www_skymaps, txt_block_read
PROCEDURE:
If the approximate record length is specified then GuessRecs is called
to determine the record length. This will give only correct results for
fixed record length files.
If the approximate record length is not specified then the file is
pre-read to determine the record length. This will also work for
files with a variable record length.
MODIFICATION HISTORY:
JUL-2000, Paul Hick (UCSD/CASS)
JUL-2000, Paul Hick (UCSD/CASS)
Added capability to read gzipped files
DEC-2006, Paul Hick (UCSD/CASS)
Bug fix. If /test is set and guessrecs failed, then
errormessage was not defined.
SEP-2007, Paul Hick (UCSD/CASS)
Bugfix. Test after GuessRecs changed from nrec EQ 0
nrec LE 0.
APR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Bugfix. If approx_recl was used on an empty file
errormessage was not defined.