;+ ;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. ; GET_PLOT_POSITION: Returns an array containing the corners of each panel in the plot, to make it easier to overplot and annotate plots ; 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 ; ;QUESTIONS? ; See the archives at: http://lists.ssl.berkeley.edu/mailman/listinfo/tplot ;Still have questions: ; Send e-mail to: tplot@ssl.berkeley.edu someone might answer! ; ; $LastChangedBy: davin-mac $ ; $LastChangedDate: 2014-06-27 14:34:15 -0700 (Fri, 27 Jun 2014) $ ; $LastChangedRevision: 15459 $ ; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot.pro $ ;- pro tplot,datanames, $ WINDOW = wind, $ NOCOLOR = nocolor, $ VERBOSE = verbose, $ wshow = wshow, $ OPLOT = oplot, $ OVERPLOT = overplot, $ VERSION = version , $ 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, $ ;It looks like this keyword isn't actually used. pcruce 10/4/2012 get_plot_position=pos,$ help = help compile_opt idl2 @tplot_com.pro if 1 then begin ; check for embedded calls stack = scope_traceback(/structure) stack = stack[0:n_elements(stack)-2] nocallsfrom = ['CTIME','TPLOT'] incommon = array_union(nocallsfrom,stack.routine) w = where(incommon ne -1,nw) if nw gt 0 then begin dprint,dlevel=2,'Calls to TPLOT are not allowed from within '+strupcase(nocallsfrom[w]) return endif endif if size(verbose,/type) eq 0 then str_element,tplot_vars,'options.verbose',verbose ; get default verbose value if it exists if size(wshow,/type) eq 0 then str_element,tplot_vars,'options.wshow',wshow 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,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,/silent 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 begin tpv_opt_tags = tag_names( tplot_vars.options) idx = where( tpv_opt_tags eq 'DATANAMES', icnt) if icnt gt 0 then begin dnames=tplot_vars.options.datanames endif else begin return endelse endelse ;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 dprint,dlevel=0,verbose=verbose,'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 ;test to see if this window exists before wset, jmm, 7-may-2008: ;removed upper limit on window number, jmm, 19-mar-2009 device, window_state = wins if(w Eq 0 Or wins[w]) then wset,w else begin dprint,verbose=verbose, 'Window is closed and Unavailable, Returning' w = current_window def_opts.window = w tplot_options, window = w return endelse if def_opts.wshow ne 0 || keyword_set(wshow) then wshow ;,icon=0 ; The icon=0 option doesn't work with windows str_element,def_opts,'wsize',value = wsize wi,w,wsize=wsize 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.,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=tnames(var_label) ;,/extrac) ;ensure the index does not go out of range, other values will use default if def_opts.version lt 1 or def_opts.version gt 5 then def_opts.version = 3 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 tplot_var_labels,def_opts,trg,var_label,local_time,pos,chsize,vtitle=vtitle,vlab=vlab,time_offset=time_offset,time_scale=time_scale ;return time_offset in the t_offset keyword, if requested if undefined(time_offset) then begin dprint,'Illegal time interval.',dlevel=1 return 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 dprint,verbose=verbose,'Undefined or empty variable data: ',name $ else dprint,verbose=verbose,dlevel=1,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 = tnames(datastr,/all); strsplit(datastr,/extract) nd2 = n_elements(datastr) if yrange[0] eq yrange[1] then get_ylimits,datastr,limits,trg endif else datastr=0 ;allow label placing for pseudo variables all_labels = '' labflag = 0b label_placement = 0 ;array to determine label positions labidx = 0 ;offset for indexing position array str_element, limits,'labflag',labflag if nd2 gt 1 && keyword_set(labflag) && keyword_set(datastr) then begin ;check for labels set on the pseudo variable, use defaults if not set str_element, limits,'labels',all_labels if ~keyword_set(all_labels) then begin for c=0, nd2-1 do begin templab = '' get_data, datastr[c], alimits=templim str_element, templim, 'labels', templab if keyword_set(templab) then begin all_labels = keyword_set(all_labels) ? [all_labels,templab]:templab label_placement = [label_placement,replicate(c,n_elements(templab))] endif endfor endif if n_elements(label_placement) gt 1 then begin label_placement = label_placement[1:n_elements(label_placement)-1] endif endif ;allow colors to be set on pseudo variables colors_set = 0b color_offset = 0 str_element, limits, 'colors', colors_set 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,alimits=limits2,dtype=dtype ;,ptr=pdata ;help,limits2,/st ;stop if not keyword_set(data) then dprint,verbose=verbose,'Unknown variable: ',name $ else dprint,verbose=verbose,dlevel=1,index,name,format='(i3," ",a)' endif else limits2 = 0 if size(/type,data) eq 8 then begin tshift = 0.d str_element,data,'tshift',value = tshift ; printdat,name,tshift,limits2,dtype data.x = (data.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 = ' ' ;add labels if set on pseudo var if keyword_set(all_labels) then begin ;labels not set on pseudo var, placement determined earlier if keyword_set(label_placement) then begin label_index = where(label_placement eq d, nl) if nl lt 1 then label_index = -1 ;labels explicitly set on pseudo var, add labels in order endif else begin label_index = indgen(dimen2(data.y)) + labidx labidx = max(label_index) + 1 endelse ;add aggregated labels/indexes for current variable str_element, newlim, 'label_index', label_index, /add str_element, newlim, 'all_labels', all_labels, /add endif ;set offset into color array, if plotting pseudo vars this should ;allow the next variable's trace to start at the proper color if keyword_set(colors_set) then begin str_element, newlim, 'color_offset', color_offset, /add endif ysubtitle = struct_value(newlim,'ysubtitle',def='') if keyword_set(ysubtitle) then newlim.ytitle += '!c'+ysubtitle if newlim.spec ne 0 then routine='specplot' else routine='mplot' ; if size(/type,data.y 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 ;get offset into color array (for pseudo vars) if keyword_set(colors_set) then begin str_element, newlim, 'color_offset', value=color_offset endif 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 ;option to control left-hand labels for x-axis str_element, def_opts, 'vtitle', vtitle 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