;+
;PROCEDURE: tplot [,datanames]
;PURPOSE:
; Creates a time series plot of user defined quantities.
;INPUT:
; datanames: A string of space separated datanames.
; wildcard expansion is supported.
; if datanames is not supplied then the last values are used.
; Each name should be associated with a data quantity.
; (see the "STORE_DATA" and "GET_DATA" routines.)
; Alternatively datanames can be an array of integers or strings.
; run "TPLOT_NAMES" to show the current numbering.
;
;KEYWORDS:
; TITLE: A string to be used for the title. Remembered for future plots.
; ADD_VAR: Set this variable to add datanames to the previous plot. If set
; to 1, the new panels will appear at the top (position 1) of the
; plot. If set to 2, they will be inserted directly after the
; first panel and so on. Set this to a value greater than the
; existing number of panels in your tplot window to add panels to
; the bottom of the plot.
; LASTVAR: Set this variable to plot the previous variables plotted in a
; TPLOT window.
; PICK: Set this keyword to choose new order of plot panels
; using the mouse.
; WINDOW: Window to be used for all time plots. If set to -1, then the
; current window is used.
; VAR_LABEL: String [array]; Variable(s) used for putting labels along
; the bottom. This allows quantities such as altitude to be labeled.
; VERSION: Must be 1,2,3, or 4 (3 is default) Uses a different labeling
; scheme. Version 4 is for rocket-type time scales.
; OVERPLOT: Will not erase the previous screen if set.
; NAMES: The names of the tplot variables that are plotted.
; NOCOLOR: Set this to produce plot without color.
; TRANGE: Time range for tplot.
; NEW_TVARS: Returns the tplot_vars structure for the plot created. Set
; aside the structure so that it may be restored using the
; OLD_TVARS keyword later. This structure includes information
; about various TPLOT options and settings and can be used to
; recreates a plot.
; OLD_TVARS: Use this to pass an existing tplot_vars structure to
; override the one in the tplot_com common block.
; HELP: Set this to print the contents of the tplot_vars.options
; (user-defined options) structure.
;
;RESTRICTIONS:
; Some data must be loaded prior to trying to plot it. Try running
; "_GET_EXAMPLE_DAT" for a test.
;
;EXAMPLES: (assumes "_GET_EXAMPLE_DAT" has been run)
; tplot,'amp slp flx2' ;Plots the named quantities
; tplot,'flx1',/ADD ;Add the quantity 'flx1'.
; tplot ;Re-plot the last variables.
; tplot,var_label=['alt'] ;Put Distance labels at the bottom.
; For a long list of examples see "_TPLOT_EXAMPLE"
;
;OTHER RELATED ROUTINES:
; Examples of most usages of TPLOT and related routines are in
; the crib sheet: "_TPLOT_EXAMPLE"
; Use "TNAMES" function to return an array of current names.
; Use "TPLOT_NAMES" to print a list of acceptable names to plot.
; Use "TPLOT_OPTIONS" for setting various global options.
; Plot limits can be set with the "YLIM" procedure.
; Spectrogram limits can be set with the "ZLIM" procedure.
; Time limits can be set with the "TLIMIT" procedure.
; The "OPTIONS" procedure can be used to set all IDL
; plotting keyword parameters (i.e. psym, color, linestyle, etc) as well
; as some keywords that are specific to tplot (i.e. panel_size, labels,
; etc.) For example, to change the relative panel width for the quantity
; 'slp', run the following:
; OPTIONS,'slp','panel_size',1.5
; TPLOT calls the routine "SPECPLOT" to make spectrograms and
; calls "MPLOT" to make the line plots. See these routines to determine
; what other options are available.
; Use "GET_DATA" to retrieve the data structure (or
; limit structure) associated with a TPLOT quantity.
; Use "STORE_DATA" to create new TPLOT quantities to plot.
; The routine "DATA_CUT" can be used to extract interpolated data.
; The routine "TSAMPLE" can also be used to extract data.
; Time stamping is performed with the routine "TIME_STAMP".
; Use "CTIME" or "GETTIME" to obtain time values.
; tplot variables can be stored in files using "TPLOT_SAVE" and loaded
; again using "TPLOT_RESTORE"
;
;CREATED BY: Davin Larson June 1995
;FILE: tplot.pro
;VERSION: 1.97
;LAST MODIFICATION: 02/11/01
; $LastChangedBy: davin-win $
; $LastChangedDate: 2007-05-04 12:26:58 -0700 (Fri, 04 May 2007) $
; $LastChangedRevision: 644 $
; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_2_02/tplot/tplot.pro $
;-
pro tplot,datanames, $
WINDOW = wind, $
NOCOLOR = nocolor, $
VERSION = ver, $
OPLOT = oplot, $
OVERPLOT = overplot, $
TITLE = title, $
LASTVAR = lastvar, $
ADD_VAR = add_var, $
LOCAL_TIME= local_time,$
REFDATE = refdate, $
VAR_LABEL = var_label, $
OPTIONS = opts, $
T_OFFSET = t_offset, $
TRANGE = trng, $
NAMES = names, $
PICK = pick, $
new_tvars = new_tvars, $
old_tvars = old_tvars, $
datagap = datagap, $
help = help
@tplot_com.pro
if keyword_set(old_tvars) then tplot_vars = old_tvars
if keyword_set(help) then begin
printdat,tplot_vars.options,varname='tplot_vars.options'
new_tvars = tplot_vars
return
endif
; setup tplot_vars....
tplot_options,ver=ver,title=title,var_label=var_label,refdate=refdate, $
wind=wind, options = opts
if keyword_set(overplot) then oplot=overplot
if n_elements(trng) eq 2 then trange = time_double(trng)
chsize = !p.charsize
if chsize eq 0. then chsize=1.
def_opts= {ymargin:[4.,2.],xmargin:[12.,12.],position:fltarr(4), $
title:'',ytitle:'',xtitle:'', $
xrange:dblarr(2),xstyle:1, $
version:3, window:-1, wshow:0, $
charsize:chsize,noerase:0,overplot:0,spec:0}
extract_tags,def_opts,tplot_vars.options
; Define the variables to be plotted:
;str_element,tplot_vars,'options.varnames',tplot_var
; if n_elements(tplot_var) eq 0 then $
; str_element,tplot_vars,'options.varnames',['NULL'],/add_replace
if keyword_set(pick) then $
ctime,prompt='Click on desired panels. (button 3 to quit)',panel=mix
if n_elements(mix) ne 0 then datanames = tplot_vars.settings.varnames(mix)
if keyword_set(add_var) then begin
names = tnames(datanames,/all)
if add_var eq 1 then datanames = [names,tplot_vars.options.varnames] else $
if (add_var gt n_elements(tplot_vars.options.varnames)) then $
datanames = [tplot_vars.options.varnames,names] else $
datanames = [tplot_vars.options.varnames[0:add_var-2],names,$
tplot_vars.options.varnames[add_var-1:*]]
endif
dt = size(/type,datanames)
ndim = size(/n_dimen,datanames)
if dt ne 0 then begin
if dt ne 7 or ndim ge 1 then dnames = strjoin(tnames(datanames,/all),' ') $
else dnames=datanames
endif else dnames=tplot_vars.options.datanames
;if dt ne 0 then names= tnames(datanames,/all)
if keyword_set(lastvar) then str_element,tplot_vars,'settings.last_varnames',names
;if keyword_set(names) then begin
; str_element,tplot_vars,'settings.last_varnames',tplot_vars.options.varnames,$
; /add_replace
; str_element,tplot_vars,'options.varnames',names,/add_replace ; array of names
; str_element,tplot_vars,'settings.varnames',names,/add_replace
;endif else names = tplot_vars.options.varnames
str_element,tplot_vars,'options.lazy_ytitle',lazy_ytitle
varnames = tnames(dnames,nd,ind=ind,/all)
str_element,tplot_vars,'options.datanames',dnames,/add_replace
str_element,tplot_vars,'options.varnames',varnames,/add_replace
if nd eq 0 then begin
print,'No valid variable names found to tplot! (use TPLOT_NAMES to display)'
return
endif
;ind = array_union(tplot_vars.options.varnames,data_quants.name)
sizes = fltarr(nd)
for i=0,nd-1 do begin
dum = 1.
lim = 0
get_data,tplot_vars.options.varnames[i],alim=lim
str_element,lim,'panel_size',value=dum
sizes[i] = dum
endfor
plt = {x:!x,y:!y,z:!z,p:!p}
if (!d.flags and 256) ne 0 then begin ; windowing devices
current_window= !d.window > 0
if def_opts.window ge 0 then w = def_opts.window $
else w = current_window
wset,w
if def_opts.wshow ne 0 then wshow,icon=0
endif
str_element,tplot_vars,'settings.y',replicate(!y,nd),/add_replace
str_element,tplot_vars,'settings.clip',lonarr(6,nd),/add_replace
str_element,def_opts,'ygap',value = ygap
str_element,def_opts,'charsize',value = chsize
if keyword_set(nocolor) then str_element,def_opts,'nocolor',nocolor,/add_replace
nvlabs = [0.,0.,0.,1.,0.]
str_element,tplot_vars,'options.var_label',var_label
if keyword_set(var_label) then if size(/type,var_label) eq 7 then $
if ndimen(var_label) eq 0 then var_label=strsplit(var_label,/extrac)
nvl = n_elements(var_label) + nvlabs(def_opts.version)
def_opts.ymargin = def_opts.ymargin + [nvl,0.]
!p.multi = 0
pos = plot_positions(ysizes=sizes,options=def_opts,ygap=ygap)
if keyword_set(trange) then str_element,tplot_vars,'options.trange',trange,/add_replace $
else str_element,tplot_vars,'options.trange',trange
if trange[0] eq trange[1] then $
trg=minmax(reform(data_quants[ind].trange),min_value=0.1) $
else trg = trange
if def_opts.version eq 3 then begin
str_element,def_opts,'num_lab_min',value=num_lab_min
str_element,def_opts,'tickinterval',value=tickinterval
str_element,def_opts,'xtitle',value=xtitle
if not keyword_set(num_lab_min) then $
num_lab_min= 2. > (.035*(pos(2,0)-pos(0,0))*!d.x_size/chsize/!d.x_ch_size)
time_setup = time_ticks(trg,time_offset,num_lab_min=num_lab_min, $
side=vtitle,xtitle=xtitle,tickinterval=tickinterval,local_time=local_time)
time_scale = 1.
if keyword_set(var_label) then begin
time = time_setup.xtickv+time_offset
for i=0,n_elements(var_label)-1 do begin
vtit = strmid(var_label(i),0,3)
get_data,var_label(i),ptr=pdata,alimits=limits
if size(/type,pdata) ne 8 then print,var_label(i),$
' not valid!' else begin
def = {ytitle:vtit, format:'(F6.1)'}
; extract_tags,def,data,tags = ['ytitle','format']
extract_tags,def,limits,tags = ['ytitle','format']
v = data_cut(var_label(i),time)
vlab = strcompress( string(v,format=def.format) ,/remove_all)
w = where(finite(v) eq 0,nw)
if nw gt 0 then vlab(w) = ''
vtitle = def.ytitle + '!C' +vtitle
time_setup.xtickname = vlab +'!C'+time_setup.xtickname
time_setup.xtitle = '!C'+time_setup.xtitle
endelse
endfor
endif
extract_tags,def_opts,time_setup
endif
if def_opts.version eq 2 then begin
time_setup = timetick(trg(0),trg(1),0,time_offset,xtitle)
time_scale = 1.
if keyword_set(var_label) then begin
time = time_setup.xtickv+time_offset
vtitle = 'UT'
for i=0,n_elements(var_label)-1 do begin
vtit = strmid(var_label(i),0,3)
get_data,var_label(i),ptr=pdata,alimits=limits
if size(/type,pdata) ne 8 then print,var_label(i),$
' not valid!' else begin
def = {ytitle:vtit, format:'(F6.1)'}
; extract_tags,def,data,tags = ['ytitle','format']
extract_tags,def,limits,tags = ['ytitle','format']
v = data_cut(var_label(i),time)
vlab = strcompress( string(v,format=def.format) ,/remove_all)
vtitle = vtitle + '!C' +def.ytitle
time_setup.xtickname = time_setup.xtickname +'!C'+vlab
xtitle = '!C'+xtitle
endelse
endfor
def_opts.xtitle = xtitle
endif else def_opts.xtitle = 'Time (UT) '+xtitle
extract_tags,def_opts,time_setup
endif
if def_opts.version eq 1 then begin
deltat = trg(1) - trg(0)
case 1 of
deltat lt 60. : begin & time_scale=1. & tu='Seconds' & p=16 & end
deltat lt 3600. : begin & time_scale=60. & tu='Minutes' & p=13 & end
deltat le 86400. : begin & time_scale=3600. & tu='Hours' & p=10 & end
deltat le 31557600. : begin & time_scale=86400. & tu='Days' & p=7 & end
else : begin & time_scale=31557600. & tu='Years' & p = 5 & end
endcase
ref = strmid(time_string(trg(0)),0,p)
time_offset = time_double(ref)
; print,ref+' '+tu,p,time_offset-trg(0)
def_opts.xtitle = 'Time (UT) '+tu+' after '+ref
str_element,def_opts,'xtickname',replicate('',22),/add_replace
endif
if def_opts.version eq 4 then begin
deltat = trg(1) - trg(0)
time_scale=1.
tu='Seconds'
p=16
ref = strmid(time_string(trg(0)),0,p)
time_offset = 0
print,ref+' '+tu,p,time_offset-trg(0)
def_opts.xtitle = tu+' after launch'
str_element,def_opts,'xtickname',replicate('',22),/add_replace
endif
t_offset = time_offset
def_opts.xrange = (trg-time_offset)/time_scale
if keyword_set(oplot) then def_opts.noerase = 1
;for i=0,nd-1 do begin
; polyfill,(pos[*,i])([[0,1],[2,1],[2,3],[0,3]]),color=5,/norm
;endfor
;stop
init_opts = def_opts
init_opts.xstyle = 5
;if init_opts.noerase eq 0 then erase_region,_extra=init_opts
if init_opts.noerase eq 0 then erase
init_opts.noerase = 1
str_element,init_opts,'ystyle',5,/add
box,init_opts
def_opts.noerase = 1
str_element,tplot_vars,'options.timebar',tbnames
if keyword_set(tbnames) then begin
tbnames = tnames(tbnames)
ntb = n_elements(tbnames)
for i=0,ntb-1 do begin
t = 0
get_data,tbnames[i],data=d
str_element,d,'x',t
str_element,d,'time',t
for j=0,n_elements(t)-1 do $
oplot,(t[j]-time_offset)/time_scale*[1,1],[0,1],linestyle=1
endfor
endif
str_element,/add,tplot_vars,'settings.y', replicate(!y,nd)
str_element,/add,tplot_vars,'settings.clip',lonarr(6,nd)
for i=0,nd-1 do begin
name = tplot_vars.options.varnames(i)
def_opts.position = pos(*,i) ; get the correct plot position
get_data,name,alimits=limits,ptr=pdata,data=data,index=index,dtype=dtype
if not keyword_set(pdata) and dtype ne 3 then print,'Unknown variable: ',name $
else print,index,name,format='(i3," ",a)'
if keyword_set(pdata) then nd2 = n_elements(pdata) else nd2 = 1
if dtype eq 3 then begin
datastr = data
yrange = [0.,0.]
str_element,limits,'yrange',yrange
if ndimen(datastr) eq 0 then datastr = strsplit(datastr,/extract)
nd2 = n_elements(datastr)
if yrange[0] eq yrange[1] then get_ylimits,datastr,limits,trg
endif else datastr=0
for d=0,nd2-1 do begin
newlim = def_opts
newlim.ytitle = keyword_set(lazy_ytitle) ? strjoin(strsplit(name,'_/',/extract),'!c') : name
if keyword_set(datastr) then begin
name = datastr(d)
get_data,name,index=index,data=data,ptr=pdata,alimits=limits2,dtype=dtype
;help,limits2,/st
;stop
if not keyword_set(pdata) then print,'Unknown variable: ',name $
else print,index,name,format='(i3," ",a)'
endif else limits2 = 0
if dtype eq 1 then begin
tshift = 0.d
str_element,data,'tshift',value = tshift
data.x = (*pdata.x - (time_offset-tshift))/time_scale
endif else data={x:dindgen(2),y:findgen(2)}
extract_tags,newlim,data, except = ['x','y','dy','v']
extract_tags,newlim,limits2
extract_tags,newlim,ylimits
extract_tags,newlim,limits
; extract_tags,newlim,def_opts
newlim.overplot = d ne 0
if keyword_set(overplot) then newlim.overplot = 1 ;<- *** LINE ADDED **
if i ne (nd-1) then newlim.xtitle=''
if i ne (nd-1) then newlim.xtickname = ' '
if newlim.spec ne 0 then routine='specplot' else routine='mplot'
str_element,newlim,'tplot_routine',value=routine
color_table= struct_value(newlim,'color_table',default=-1) & pct=-1
if color_table ge 0 then loadct2,color_table,previous_ct=pct
;if debug() then stop
call_procedure,routine,data=data,limits=newlim
if color_table ne pct then loadct2,pct
endfor
def_opts.noerase = 1
def_opts.title = ''
tplot_vars.settings.y[i]=!y
tplot_vars.settings.clip[*,i] = !p.clip
endfor
str_element,tplot_vars,'settings.varnames',varnames,/add_replace
str_element,tplot_vars,'settings.d',!d,/add_replace
str_element,tplot_vars,'settings.p',!p,/add_replace
str_element,tplot_vars,'settings.x',!x,/add_replace
str_element,tplot_vars,'settings.trange_cur',(!x.range * time_scale) + time_offset
if keyword_set(vtitle) then begin ; finish var_labels
xspace = chsize * !d.x_ch_size / !d.x_size
yspace = chsize * !d.y_ch_size / !d.y_size
xpos = pos(0,nd-1) - (def_opts.xmargin(0)-1) * xspace
ypos = pos(1,nd-1) - 1.5 * yspace
xyouts,xpos,ypos,vtitle,/norm,charsize=chsize
endif
time_stamp,charsize = chsize*.5
if (!d.flags and 256) ne 0 then begin ; windowing devices
str_element,tplot_vars,'settings.window',!d.window,/add_replace
if def_opts.window ge 0 then wset,current_window
endif
!x = plt.x
!y = plt.y
!z = plt.z
!p = plt.p
str_element,tplot_vars,'settings.time_scale',time_scale,/add_replace
str_element,tplot_vars,'settings.time_offset',time_offset,/add_replace
new_tvars = tplot_vars
return
end