;+ ; Despin routine for EFI high-res (eff/efp/efw) data. ; ; Syntax: ; thm_efi_despin , probe, datatype, offset, gain [, NOTCH ] [, TWEAK_GAINS ] [, STORED_TNAMES ] ; ; Inputs: ; PROBE: Input, 1-character string identifying which spacecraft. ; DATATYPE: Input, string. 3-character string identifying data type ('eff','efp' or 'efw') ; OFFSET: Input, float, 1 x n (2 dimensions) 3-element array: Ex, Ey, Ez offset. ; GAIN: Input, float. 3-element array: E12, E34, E56 gain. ; TPLOT_NAME: Input. String scalar containing the name of the TPLOT variable to operate on (regardless of PROBE and DATATYPE kwd's). ; ; Options: ; NOTCH: Numeric, 0 or 1. Set equal to the # of harmonics to remove (including fundamental) (i.e. notch=1 removes fundamental only, notch=2 also ; removes 1st harmonic) (default=0 does not notch filter anything). *** DISABLED ***. ; TWEAK_GAINS: Numeric, 0 or 1. Set flag to tweak the E12/E34 gains to minimize the spin tone newname: If specified, the cleaned data is stored as a ; tplot variable with name=newname instead of the default 'th'+sc+'_'+datatype+'_dsl'. ; ; Outputs: ; *** Creates a new tplot variable with the name 'th'+sc+'_'+datatype+'_dsl' or whatever is specified by the newname keyword. *** ; ; STORED_TNAMES: Returns a string array containing each TPLOT variable name invoked in a STORE_DATA operation (chronological order). (Not sorted or uniqued.) ; ; Restrictions: ; Required data must be loaded, including spin phase data. ; Notes: ; This routine ignores E56 when despinning. That is desireable over ; the full transform (a la THM_COTRANS.PRO) because the resolution on E56 ; is much lower than for the spin plane sensors (E12 and E34) so mixing ; in E56 would often increase the noise, and because the geometric ; axis is w/in 1 degree of the spin axis making the result effectively ; in DSL. ; ; Modifications: ; Switched from THM_SPIN_PHASE.PRO to Jim Lewis' SPINMODEL_INTERP_T.PRO, ; (commented out GET_DATA's to _state_spinper/spinphase, modified error ; conditional), edited warning message, up'd doc'n, W.M.Feuerstein, ; 3/19/08. ; Added TPLOT_NAME to specify var. to read. Otherwise, PROBE and DATATYPE ; parameters are used to derive tplot var. name to read. Changed default ; suffix to "_dsz" to match the "THEMIS Science Coordinate Systems ; Definition" (THM-SOC-110). ; Made sure "V" field is carried through data (otherwise it crashes ; THM_CAL_EFI.PRO), redined suffix to "_dsl" (effectively true), fixed ; potential bitwise vs. logical conditional bug, updated doc'n, WMF, ; 3/21/2008 (F). ; Put in return on errors w/ messages for DLIMITS.DATA_ATT.COORD_SYS equal ; to 'dsl' or 'spg', set said field to 'dsl' on conclusion of ; processing, updat'd doc'n, WMF, 3/24/2008. ; Checks validity of pointer from SPINMODEL_GET_PTR.PRO and calls ; THM_LOAD_SPIN,PROBE=PROBE[0] on fail, installed an alternate test for ; spinmodel data (TNAMES('th?_spin*')) to check an error from ; SPINMODEL_INTERP_T.PRO but the error is unrelated, WMF, 3/26/2008. ; Removed check on pointer in favor of incorporating THM_LOAD_SPIN.PRO into ; THM_LOAD_STATE.PRO, WMF, 3/27/2008. ; Updated doc'n, WMF, 3/27/2008. ; Changed "Despinning " PRINT to MESSAGE, if data already despun ; save TPLOT var. instead of just returning (BugzID 111), WMF, 4/4/08 (F). ; Disabled BOOM_OFFSET parameter which is obsolete, WMF, 4/22/2008 (Tu). ; Upd'd doc'n, WMF, 5/21/2008. ; Change (spin-dependent) offset parameter to optional kw OFFSET. Subtract OFFSET only if provided and only if there are 2 spin-dependent ; offsets in boom plane, WMF, 3/2/2009. ; Return OFFSET to a parameter: Subtract X, Y, Z for 2 spin-dependent offsets in boom plane; subtract Z only for 4 spin-dependent offsets, WMF, 3/5/09. ; ; $LastChangedBy: michf $ ; $LastChangedDate: 2008-05-15 11:17:41 -0700 (Thu, 15 May 2008) $ ; $LastChangedRevision: 3095 $ ; $URL: $ ;- pro thm_efi_despin , probe, datatype, offset, gain, $ ; notch=notch, $ newname=newname, $ tweak_gains=tweak_gains, $ tplot_name=tplot_name, $ stored_tnames = stored_tnames, $ use_eclipse_corrections=use_eclipse_corrections,$ _extra=_extra ;========== ; Get data: ;========== if ~size(tplot_name,/type) then $ get_data,'th'+probe[0]+'_'+datatype,data=data,lim=lim,dlim=dlim else $ get_data,tplot_name,data=data,lim=lim,dlim=dlim eff_t=data.x eff=data.y ; ;=========================== ;Check that data is present: ;=========================== if n_elements(eff_t) eq 1 then begin dprint,'ERROR in thm_efi_despin: data not available. Returning...' return endif ;========================================================================= ;Return if data is in a coord. sys. that this routine is not designed for: ;========================================================================= coord=cotrans_get_coord(dlim) if coord ne 'spg' && coord ne 'dsl' then begin message,'*** WARNING!: THM_EFI_DESPIN.PRO only accepts input data in ' + 'SPG or DSL coordinates. Returning...' return endif ;=================================== ;If data is already in the DSL coordinate system, ;assign Ex,Ey,Ez without despinning: ;=================================== if coord eq 'dsl' then begin dprint,'Data is already despun. '+ 'Saving without applying EFI despin...' Ex=eff[*,0] Ey=eff[*,1] Ez=eff[*,2] ;============= ;Else, despin: ;============= endif else begin ;================================================= ;Notify the user that EFI despin is being applied: ;================================================= if ~(~size(tplot_name,/type)) then $ dprint,'Applying EFI despin to: '+tplot_name else $ dprint,'Applying EFI despin to: ','th'+probe[0]+'_'+datatype ;======================= ;Interpolate spin phase: ;======================= model=spinmodel_get_ptr(probe[0],use_eclipse_corrections=use_eclipse_corrections) If(obj_valid(model) Eq 0) Then Begin ;load state data, if not present thm_load_state, probe = probe[0], trange = minmax(eff_t), /get_support_data model = spinmodel_get_ptr(probe[0],use_eclipse_corrections=use_eclipse_corrections) Endif spinmodel_interp_t,model=model,time=eff_t, spinphase=phase,spinper=spinper,use_spinphase_correction=1 ;a la J. L. ;============================ ;Despin and subtract offsets: ;============================ phase*=!dtor phase-=45*!dtor if keyword_set(tweak_gains) then begin Ex1 = eff[*,0]*gain[0]*sin(phase) Ex2 = eff[*,1]*gain[1]*cos(phase) Ey1 = -eff[*,0]*gain[0]*cos(phase) Ey2 = eff[*,1]*gain[1]*sin(phase) tweak1 = smooth(Ex1,60)/smooth(Ex2,60) tweak2 = smooth(Ey1,60)/smooth(Ey2,60) Ex = Ex1+Ex2*median(tweak1) Ey = Ey1+Ey2*median(tweak1) endif else begin Ex = eff[*,0]*gain[0]*sin(phase) + eff[*,1]*gain[1]*cos(phase) ; ;To analyze frequency spectra. Comment for normal use: ; ;****************************************************** ; ; ; Ex0=eff[*,0]*gain[0]*sin(phase) ; Ex1=eff[*,1]*gain[1]*cos(phase) ; ; ; case (size(offset,/dimensions))[1] of ;Needed for Ey section below as well. ; 3: suffix= '_2sdo' ;2 spin-dependent offsets in boom plane. ; 5: suffix= '_4sdo' ;4 spin-dependent offsets in boom plane. ; endcase ; ; ; tempname= newname+'_E12'+suffix ; store_data, tempname, data={x:eff_t,y:eff[*,0]},lim=lim,dlim=dlim ; options, tempname, 'ytitle', 'E12 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_E34'+suffix ; store_data, tempname, data={x:eff_t,y:eff[*,1]}, lim=lim, dlim=dlim ; options, tempname, 'ytitle', 'E34 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; ; ; tempname= newname+'_Ex0'+suffix ; store_data, tempname, data= {x:eff_t,y:Ex0}, lim=lim, dlim=dlim ; options, tempname, 'ytitle', 'Ex0 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_Ex1'+suffix ; store_data, tempname, data= {x:eff_t,y:Ex1}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ex1 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_Ex'+suffix ; store_data, tempname, data= {x:eff_t,y:Ex}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ex ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_cos'+suffix ; store_data, tempname, data= {x:eff_t, y:cos(phase)}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'cos(phase) ; options, tempname, 'labels', '' ; tdpwrspc, tempname Ey = -eff[*,0]*gain[0]*cos(phase) + eff[*,1]*gain[1]*sin(phase) ; ;To analyze frequency spectra. Comment for normal use: ; ;****************************************************** ; ; ; Ey0= -eff[*,0]*gain[0]*cos(phase) ; Ey1= eff[*,1]*gain[1]*sin(phase) ; ; ; tempname= newname+'_Ey0'+suffix ; store_data, tempname, data= {x:eff_t,y:Ey0}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ey0 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_Ey1'+suffix ; store_data, tempname, data= {x:eff_t, y:Ey1}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ey1 ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; ; ; tempname= newname+'_Ey'+suffix ; store_data, tempname, data= {x:eff_t,y:Ey}, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ey ; options, tempname, 'labels', '' ; tdpwrspc, tempname ; tempname= newname+'_Ex_Ey'+suffix ; store_data, tempname, data= {x: eff_t, y: [[Ex],[Ey]] }, lim=lim, dlim=dlim ; options, tempname , 'ytitle', 'Ex, Ey ; options, tempname, 'labels', ['Ex_'+suffix,'Ey_'+suffix] endelse Ez = eff[*,2]*gain[2] ; case (size(offset,/dimensions))[1] of 3: begin ;2 spin-dependent offsets in boom plane. Ex-=offset[0] Ey-=offset[1] Ez-=offset[2] end 5: Ez-=offset[2] ;4 spin-dependent offsets in boom plane. endcase ;=========================== ;Notch filter (if required): ;=========================== ; if n_elements(notch) ne 0 then if notch gt 0 then begin ; rate = eff_t[1]-eff_t[0] ; notch_filter,Ex,notch,rate ; notch_filter,Ey,notch,rate ; notch_filter,Ez,notch,rate ; endif ;====================== ;Change COORD_SYS flag: ;====================== cotrans_set_coord,dlim,'dsl' endelse ;=========== ;Write data: ;=========== if ~(~size(tplot_name,/type)) then begin if n_elements(newname) eq 0 then newname=tplot_name+'_dsl' endif else begin if n_elements(newname) eq 0 then newname='th'+probe[0]+'_'+datatype+'_dsl' endelse store_data,newname,data={x:eff_t,y:[[Ex],[Ey],[Ez]],v:data.v}, lim=lim,dlim=dlim if ~(~size(stored_tnames,/type)) then stored_tnames = [ stored_tnames, newname ] else stored_tnames = [ newname ] dprint,'Stored despun data (SPG -> DSL) in tplot variable '+newname end