;+ ;NAME: DSC_MISSION_COMPARE_CRIB ; ;DESCRIPTION: ; Crib sheet to demonstrate the setup, plotting, and time shifting ; routines added to support straightforward comparisons of linear ; data between multiple missions. ; ;CALLING SEQUENCE: ; .run dsc_mission_compare_crib OR cut-and-paste relevant portions ; ;NOTES: ; DSC_MISSION_COMPARE currently supports the default data loads for ; the DSCOVR, ACE, and WIND missions. ; ; The DSC_SHIFTLINE routine can be used generically, on any previously generated ; line plot -- not just those plots generated by a DSC_MISSION_COMPARE::Plot call. ; ;OUTLINE: ; 1) Setup the DSC_MISSION_COMPARE object ; 1.1) Create the Compare Object ; 1.2) Modify Object Values ; 1.2.1) SetAll ; 1.2.2) SetTitle ; 1.2.3) SetMissions ; 1.2.4) SetVars ; 1.2.5) SetVar ; 1.2.6) ClearVar ; 1.2.7) Ordering and Reorder Method ; 1.2.8) Setting Color options ; 2) Plot the Comparison ; ; include behavior on missing variable; describe combo names created ; 3) Time Shift the Plotted Data (DSC_SHIFTLINE) ; 3.1) Shift String Syntax ; ; One panel (forward/back both lines, one line) ;show cumulative ; 3.2) Shifts on Select Panels and Data Sources ; 3.3) Shifts with DSC_DYPLOT Confidence Intervals ; 3.4) Cleanup DSC_SHIFTLINE Created Variables ; ; ;CREATED BY: Ayris Narock (ADNET/GSFC) 2018 ; ; $LastChangedBy: nikos $ ; $LastChangedDate: 2018-03-12 09:55:28 -0700 (Mon, 12 Mar 2018) $ ; $LastChangedRevision: 24869 $ ; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_3/projects/dscovr/examples/dsc_mission_compare_crib.pro $ ;- ;------------------------------------------------------------------------------ ; 1) Setup the DSC_MISSION_COMPARE object ;------------------------------------------------------------------------------ ;------------------------------------------------------------------------------ ; 1.1) Create the Compare Object ;------------------------------------------------------------------------------ ; Create a new mission compare object via ; Obj_New('DSC_MISSION_COMPARE',..) or DSC_MISSION_COMPARE(...) syntax ; With element KEYWORDS (m1/m2/vars/title) ; Mission kewords (m1/m2) should regex match one of the supported missions ; - This describes a comparison of Bx,By,and Np data between ; the WIND and DSCOVR missions. ; - The TITLE keyword defines the plot title compile_opt IDL2 mco = Obj_New("DSC_MISSION_COMPARE",m1='wi',m2='d',vars=['np','bx','by'],title="My New Title") print,mco,/implied stop ; Will create a default title if none is supplied ; and use default colors if none are supplied mco = DSC_MISSION_COMPARE(m1='ace',m2='dsc',vars=['b']) print,mco,/implied stop ; OR Create the object by passing a structure via the SET= keyword ; - useful if you want to set the variables by toggling structure fields mc_str = {DSC_MISSION_COMPARE} print,mc_str,/implied mc_str.mission1 = 'wi' mc_str.mission2 = 'ds' mc_str.bx = 1 mc_str.vphi = 1 print,mc_str,/implied mco = DSC_MISSION_COMPARE(set=mc_str) ; Will standardize mission names. print,mco,/implied ; Will NOT create a default title, it maintains stop ; the title field found in the passed structure ; Prompts user if a mission is missing/invalid ; or if no variables are set stop mco = DSC_MISSION_COMPARE(title='Values were set interactively') print,mco,/implied stop ; Use the static method FindMTag to see currently ; supported missions std_names = DSC_MISSION_COMPARE.FindMTag(/all) foreach name,std_names do print,name stop ;------------------------------------------------------------------------------ ; 1.2) Modify Object Values ;------------------------------------------------------------------------------ ;------------------------------------------------------------------------------ ; 1.2.1) SetAll ;------------------------------------------------------------------------------ ; Modify all fields of the object by passing a structure mco = DSC_MISSION_COMPARE(set=mc_str) st = mco.getall() ;Retrieve structure from existing object print,st,/implied ;OR Create structure from scratch stop ; st = {DSC_MISSION_COMPARE} st.title = 'Comparing DSCOVR and WIND' st.bx = 0 st.vphi = 0 st.b = 1 st.np = 1 print,st,/implied stop mco.setAll,st ; Modified values passed to the object print,mco,/implied stop stop ; Similar to initializing with a structure, will prompt st.mission1 = '' ; for missing mission/variable settings. mco.setAll,st stop ;------------------------------------------------------------------------------ ; 1.2.2) SetTitle ;------------------------------------------------------------------------------ mco.SetTitle,'A New Title' ; Modify title with a scalar string print,mco,/implied stop mco.SetTitle,5430 ; Bad arguments leave existing title unchanged print,mco.getTitle() stop mco.SetTitle ; Without argument creates the default title print,mco,/implied stop ;------------------------------------------------------------------------------ ; 1.2.3) SetMissions ;------------------------------------------------------------------------------ print,'--Creating Object--' mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars='b') print,mco,/implied print,'--Modifying Missions--' mco.SetMissions,'ace','dsc' ; If missions are changed will prompt user stop ; on whether to update the title mco.SetMissions,'wind' ; One argument updates mission1 stop stop ; No arguments prompts user to select from list mco.SetMissions stop ;------------------------------------------------------------------------------ ; 1.2.4) SetVars ;------------------------------------------------------------------------------ ; Set all comparison variables. ; - If passed a string (scalar or array) will set these variables ; as those to be compared and will de-select all others. mco.setVars,'bx' ; Now only BX is set print,mco,/implied stop mco.setVars,['v','np','bz'] ; Now only V,NP,BZ are set. BX is cleared print,mco,/implied stop stop ; If no strings, or bad strings, are passed mco.setVars ; an interactive prompt is generated. print,mco,/implied stop ; - Can pass a {DSC_MISSION_COMPARE} structure as well. ; Will ignore any title or mission fields set and only ; modify the variable settings. st = mco.getall() ;Retrieve structure from existing object st.title = 'No change to title if structure passed in SetVars call' st.bz = 0 st.vphi = 1 st.b = 1 st.np = 0 mco.setVars,st print,mco,/implied stop ;------------------------------------------------------------------------------ ; 1.2.5) SetVar ;------------------------------------------------------------------------------ ; Set one variable to be compared, leaving other variable ; settings intact. ; mco.setVars,['v','np','bz'] ; Now V,NP,BZ are set. print,mco,/implied stop mco.setVar,'b' ; Now NP,BX,BY and B are all set print,mco,/implied stop mco.setVar,'btheta' ; Now NP,BX,BY,B and BTHETA are all set print,mco,/implied stop mco.setVar,/all ; Use the /all keyword to set all variables for comparison print,mco,/implied stop ;------------------------------------------------------------------------------ ; 1.2.6) ClearVar ;------------------------------------------------------------------------------ ; De-selects one variable from the comparison, leaving other ; variable settings intact. ; mco.setVars,['v','np','bz'] ; Now V,NP,BZ are set. print,mco,/implied stop mco.clearVar,'bz' ; Now only V and NP are set print,mco,/implied stop mco.clearVar,/all ; Use the /all keyword to unset all variables print,mco,/implied stop ;------------------------------------------------------------------------------ ; 1.2.7) Ordering and Reorder Method ;------------------------------------------------------------------------------ ; Reorders the comparison variables. ; If passed no arguments it will enter an interactive session. ; ; Order positions are described by 1-indexed positions. ; (I.e.- the top panel is in position 1, the next panel down in ; position 2, etc.) ;-- General Ordering Rules mco.setVars,['v','bz','np','bphi'] ; Variables set by array (init or setVars) stop ; will be ordered to match the array order. mco.setVar,'b' ; Variables set one-by-one (setVar or setVars interactively) mco.setVar,'vtheta' ; are ordered in the order they set. Using setVar appends the print,mco.getVars() ; element to the order of previously set variables. stop mco.setVar,'b' ; Duplicated variables are ignored. mco.setVar,'bz' mco.setVar,'vphi' print,mco.getVars() stop g = {DSC_MISSION_COMPARE} ; Setting variables from a structure (init, setAll, or setVars) g.v = 1 ; will use a default order matching the order of the variable g.np = 1 ; fields in the object UNLESS you expressly modify the ._ORDER g.b = 1 ; property to a valid ordering. mco.setvars,g stop g._order = ptr_new(['v','np','b']) ; Example: Manually set the ORDER field in passed structure mco.setvars,g stop ;-- Using the Reorder method mco.setVars,['v','bz','np','bphi'] mco.reorder,4 ; Move 4th item to top spot stop ;expected> ['bphi','v','bz','np'] mco.reorder,2,3 ; Move 2nd item to 3rd position stop ;expected> ['bphi','bz','v','np'] mco.reorder,'bz' ; Alternately, identify the moving item with a string stop ; Move BZ to top ;expected> ['bz','bphi','v','np'] mco.reorder,'np',2 ; Move NP item to 2nd position stop ;expected> ['bz','np','bphi','v'] mco.reorder,['np','bz','v','bphi'] ; Arrange panels to match string array stop ;expected> ['np','bz','v','bphi'] mco.reorder,[4,3,2,1] ; Arrange panels to match index array stop ;expected> ['bphi','v','bz','np'] stop ; Set order interactively by supplying (item,position) pairs. mco.reorder ; No '' needed around string entries (e.g.: >np,3 moves NP to 3rd pos) stop ;------------------------------------------------------------------------------ ; 1.2.8) Setting Color Options ;------------------------------------------------------------------------------ ; By default, all lines for the Mission1 variables will be plotted in blue and ; those for Mission 2 in black. ; Use the C1= and C2= keywords at initialization to deviate from the default ; WIND all variables red, DSCOVR all variables green mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars=['vx','np','bz'],c1='r',c2='g') print,mco.getColor(),/implied stop ; WIND Vx is blue, NP is green, Bz is red; All DSCOVR lines in black mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars=['vx','np','bz'],c1=['b','g','r']) print,mco.getColor(),/implied stop ; After creation, use SetColor to modify the color values. mco.setColor,/help ; Print brief ussage reminder stop mco.setColor ; Set all lines to default colors print,mco.getColor(),/implied stop print,mco.getColor(),/implied ; Retrieve currently set colors as colortable values stop mco.setColor,2,'r' ; Set all mission2 lines red print,mco.getColor(),/implied stop mco.setColor,1 ; Set all mission1 lines to default color print,mco.getColor(),/implied stop mco.setColor,1,112 ; Use colortable index as well as single character color desination print,mco.getColor(),/implied stop mco.setColor,2,[3,2,1] ; Color argument can be an array if size = number of set variables print,mco.getColor(),/implied stop ; Can designate a panel to color by string, or panel index(1-based) ; Array and scalar arguments are accepted mco.setColor,1,250,'np' ; Set mission1 NP variable line to colortable valued 250 print,mco.getColor(),/implied stop mco.setColor,2,['r','y'],[1,2] ; Set the Mission2 lines in the 1st and 2nd panels to red and yellow print,mco.getColor(),/implied stop ;------------------------------------------------------------------------------ ; 2) Plot the Comparison ;------------------------------------------------------------------------------ timespan,0,0 mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars=['vx','np','bz'],c1='r',c2='g') stop ; Plot the described comparison using TPLOT mco.plot ; - Will prompt to have at least one variable to compare ; - Will prompt for date/timerange if one has not been previously set ; in TPLOT ; - Loads data into TPLOT as needed ; - TPLOT functionality remains (e.g.: tlimit, dsc_dyplot, etc.) and ; data preferences respected (i.e.: if !dsc.no_download=1 then ; only locally hosted data will be available for plots) stop timespan,'2017-01-01' mco.SetVars,['b','Np','v'] mco.SetMissions,'wind','dsc' mco.plot stop tlimit,'2017-01-01/2:00','2017-01-01/4:00' ; Zoom in stop dsc_dyplot ; Show confidence intervals on DSCOVR Faraday Cup data stop mconames = tnames('WIND&DSC*') ; Creates combination tplot variables for each panel foreach name,mconames do print,name ; with standard naming convention MISSION1&MISSION2_variable stop mco.SetMissions,'ace','wind' ; A panel may not have a comparison if one mco.SetVars,['b','vx','v'] ; mission does not support the given variable mco.plot ; e.g.: Ace 'vx' not availabe in k0 stop ;------------------------------------------------------------------------------ ; 3) Time Shift the Plotted Data (DSC_SHIFTLINE) ;------------------------------------------------------------------------------ ;------------------------------------------------------------------------------ ; 3.1) Shift String Syntax ;------------------------------------------------------------------------------ tlimit,/full tplot,dsc_ezname('b'),title='' ;Create a simple tplot with loaded data stop ; Shift a line plot forward or backward in time using DSC_SHIFTLINE and SHIFTSTRING= keyword ; * Shift String Format: '#d#h#m#s#ms' ; * You may leave out unit id strings, but not repeat them: ; OK '3h2m' ; NOT OK '3h45m13m' ; * Numbers must all be positive integers, with the execption of the leading negative. ; OK '3d4h23m16s400ms' ; OK '-23h' ; NOT OK '15h-4m' ; NOT OK '15.4m' dsc_shiftline,shiftstring='30m' ; 30 minutes ahead stop ; Right side labels are updated to reflect current offset dsc_shiftline,shift='-3h' ; 3 hours back (from previous. i.e.: total offset now 2.5 hours back) stop ; Offset is **cumulative** dsc_shiftline,shift='500s' ; 500 seconds ahead (from current offset) stop dsc_shiftline,shift='2h30m15s' ; 2 hours, 30 minutes, and 15 seconds ahead (from current offset) stop dsc_shiftline,shift='-1d3h5000ms' ; 1 day, 3 hours, and 50000 milliseconds back (from current offset) stop ; N.B.: No additional data is loaded. If shifted timerange ; falls outside the set timespan, no data appears. dsc_shiftline,/reset ; Return line to initial position (i.e.: no offset) stop ;------------------------------------------------------------------------------ ; 3.2) Shifts on Select Panels and Data Sources ;------------------------------------------------------------------------------ mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars='vx') ; Create a 1-panel comparison plot mco.plot stop ; Shift one or more lines within a TPLOT panel using the VARPATTERN= keyword dsc_shiftline,varpattern='dsc',shift='2h' ; Only DSCOVR data shifted ahead 2 hours stop dsc_shiftline,var='wi',shift='-15m' ; Only WIND data shifted back 15 minutes stop dsc_shiftline,shift='-1h30m' ; Both lines shifted back 1.5 hours stop dsc_shiftline,var='swe',/reset ; N.B.: VARPATTERN keyword uses stop ; REGEX matching on tplot variable names. ; Create a shift on a subset of panels using the PANEL= keyword mco.SetVar,'b' ; Create a multi-panel comparison plot mco.SetVar,'np' mco.plot stop dsc_shiftline,panel=2,shift='15m' ; All data in panel 2, ahead 15 minutes stop dsc_shiftline,panel=1,var='wi',shift='-8m' ; WIND data in panel 1, back 8 minutes stop dsc_shiftline,panel=[2,3],var='dsc',shift='1h15s' ; DSCOVR data in panels 2 and 3, ahead 1h15s stop dsc_shiftline,/reset ; No PANEL keyword => all panels stop ; Pass ARRAY arguments to VAR= and SHIFT= keywords ; to correspond with selected panels dsc_shiftline,panel=[1,3],var='dsc',shift=['8m','-1h'] ; DSCOVR data ahead 8 minutes in panel 1 stop ; DSCOVR data back 1 hour in panel 3 dsc_shiftline,/reset dsc_shiftline,panel=[2,3],var=['wi','dsc'],shift='10m' ; WIND data ahead 10 minutes in panel 2 stop ; DSCOVR data ahead 10 minutes in panel 3 dsc_shiftline,/reset dsc_shiftline,var=['wi','wi','dsc'],shift=['-30m','2h','400m'] stop ; Panel 1 - WIND data back 30 minutes ; Panel 2 - WIND data ahead 2 hours ; Panel 3 - DSCOVR data ahead 400 minutes ;------------------------------------------------------------------------------ ; 3.3) Shifts with DSC_DYPLOT Confidence Intervals ;------------------------------------------------------------------------------ ; Create a plot showing confidence intervals timespan,'2017-01-01' mco = DSC_MISSION_COMPARE(m1='wind',m2='dsc',vars=['vx','np','bz']) mco.plot tlimit,'2017-01-01/10:00','2017-01-01/12:00' dsc_dyplot stop ; Basic call to DSC_SHIFTLINE erases confidence intervals dsc_shiftline,var='wi',shift='-7m' stop ; Call with /DSCDY keyword to mimic a no-argument DSC_DYPLOT call ; i.e.: settings for each variable are read from their tplot data options dsc_shiftline,/reset dsc_shiftline,var='wi',shift='-7m',/dscdy stop ; Use DYINFO= keyword for more complex dsc_dyplot calls mco.plot dsc_dyplot,panel=[1,3],/force,new_dyinfo=dyinfo ; Store the dy settings passed in this call stop ; In this case: force showing any available ; confidence for panels 1 and 2, not 3 dsc_shiftline,var='wi',shift='-7m',dyinfo=dyinfo stop ;------------------------------------------------------------------------------ ; 3.4) Cleanup DSC_SHIFTLINE Created Variables ;------------------------------------------------------------------------------ foreach name,tnames() do print,name ; DSC_SHIFTLINE creates combo and single variable stop ; containing the string 'SHIFT' dsc_deletevars,/shift ;Will remove all single and combo-variables containing stop ;'SHIFT' in the name (Not just DSCOVR data.) foreach name,tnames() do print,name ; DSC_SHIFTLINE creates combo and single variable stop END