This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
Routine inspired by Takuya Hara's mvn_sta_updown_dir.pro, to calculate which STATIC bins look within a specified cone angle, look direction
and coordinate system.
This routine will determine if SPICE kernels are loaded or not. If not, it will load them automatically, based on the timespan set.
INPUTS / KEYWORDS:
dat: STATIC data structure, use eg dat=mvn_sta_get_d1(index=100)
sta_apid: string, the STATIC APID to use. This routine requires one that has anode and defeltor dimensions: 'ce', 'cf', 'd0', 'd1'. The default
is 'd0' if not set.
searchvector: 3D float vector array in the specified coordinate system, [x,y,z]. The routine will find which STATIC bins look in this direction,
within a cone angle of "coneangle". Default if not set is [-1,0,0], which is tailward in the MSO coordinate system. A note on
+- convention: you must define the direction of flow you want to capture. For eg, to find which STATIC bins are facing the
Sun (and will observe the solar wind), searchvector=[-1., 0., 0.], fromframe='MAVEN_MSO'.
coneangle: the cone angle in degrees around searchvector; the routine identifies which STATIC bins fall within this cone angle. Default if not set
is coneangle=30 degrees.
A value of zero degrees means only bins exactly parallel to searchvector are included. A value of 45 means bins within 45 degrees of
searchvector are included. A value of 180 means all bins are included.
fromframe: string: the frame in which searchvector is specified. Available frames are defined in the MAVEN SPICE documentation. The default if
this keyword is not set is 'MAVEN_MSO', which is the MSO coordinate system.
OUTPUT: data structure the same dimensions as dat.data (for a single timestamp). 0 = that bin lies outside the desired look direction, 1 = that
bin lies within the desired look direction.
EXAMPLE:
timespan, '2020-01-01', 1.
mvn_sta_l2_load, sta_apid='d0'
mvn_sta_l2_tplot
kk=mvn_spice_kernels(/load)
i=100 ;define which indice/timestamp to grab
dat=mvn_sta_get_d0(index=i)
result = mvn_sta_find_bin_directions(dat, sta_apid='d0', searchvector=[-1.,0.,0.], coneangle=15.)
This result can then be fed into multiple STATIC analysis routines using the bins keyword. For eg, j_4d(bins=result). j_4d will then calculate
ion flux for only the bins flagged in "result", enabling users to calculate fluxes in the specified searchvector direction.
.r /Users/cmfowler/IDL/STATIC_routines/FOV_routines/mvn_sta_find_bin_directions.pro
(See projects/maven/sta/l2analysis/FOV/mvn_sta_find_bin_directions.pro)
Find the position of the peak eflux in d0 / d1 data products. The simple way to do this is to find the peak eflux,
but sometimes the peak can be broad and can cover several anode-deflector bins instead of just one. This routine
attempts to determine which case exists by first finding the bin with peak eflux, and then checking the bins around this. This routine
thus assumes that the "beam" of ions is to first order represented by the peak in eflux. This an assumption, and may not be
true.
The routine finds neighboring bins around the peak bin, highest eflux first, until the total eflux is >= 75% of the total eflux.
To keep things simple, the routine can only search the 8 bins surrounding the initial bin that contains the overall peak eflux.
data_in: 16x4 d0/d1 data structure for the mass and energy range requied, obtained by eg:
dat0 = mvn_sta_get_d0(index=i)
mvn_sta_convert_units, dat0, 'eflux'
data1 = dat0.data
-> set any data1 elements outside the requested mass or energy range to zero.
data2 = total(data2, 1, /nan) ;sum across energy dimension
data3 = total(data3, 2, /nan) ;sum across mass mass
data4 = transpose(reform(data4, 4, 16)) ;break to 16Ax4D. CMF checked and confirmed that this is the correct order to reform
data_in = data4
peakinfo: output structure containing information about the "peak beam" found by the routine:
xPK, yPK: indices of the peak beam in the FOV, as outputs. If a broad beam is found, these are each 4 element long arrays, corresponding
to the indices for the 2x2 FOV bin.
peakflux: float: % of eflux in the peak bin.
EFratio: % of the total eflux that lies in the "peak" beam.
BeamType: float: 1: at least 75% of the eflux lies in a single A-D bin. Likely a narrow beam.
2: between 50% and 75% of the eflux lies in a 2x2 A-D square. Likely a broader beam.
3: less than 50% of the eflux lies in the 2x2 A-D square. Likely a diffuse plasma / no clear beam.
pts: array [2,n] long, containing the x and y indices of A-D bins that make up the found beam.
beamflux: float: % eflux containe with all pts in the beam.
EFsuccess: 1 = routine successful, 0 = routine unsuccessful.
EFsize: float: the number of A-D bins that comprise the beam (eg number of rows in pts).
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_d0d1_findpeak.pro)
Fitting function used by Amoeba. Fits a gaussian.
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
Routine that determines if the beam is in the FOV, using amoeba to fit a gaussian to the beam in STATIC. This is NOT the top level function - it is recommended that you keep scrolling down to mvn_sta_defl_fov_run! INPUTS: dataY: 1D fltarr array containing energy flux at a single timestamp from the STATIC c8-P2-D data product. dataV: 1D fltarr array containing the deflector angles at a single timestamp, from the STATIC c8-P2-D data product. tpwin: window number that the tplot data are in. This is needed to ensure wset works correctly. wnum: window number to plot the deflector distribution into (not needed if /fplot is NOT set). output: a structure containing all the outputs from the routine, for storing into tplot. Set /fplot to plot the gaussian fit. Slows down the routine on long loops. Default is setting is to NOT plot this. Set /qc to load qualcolors. Set /no_off so that the y axis offset is not a fitting variable. In this case, the lowest real eflux value in the Y data is used as the offset value, and cannot be varied by the fitting routine. Set /zeros to that any zeros in the data have zero weight and do not contribute to the fit. This is useful to "remove" NaNs, and missing data, without changing the size of the arrays. NOTES: To calculate the STATIC FOV flag value for multiple timesteps, use the routine mvn_sta_defl_fov_run. See this routine for caveats as well. The code will search for and remove NaNs, and set them to zero. If /zeros is set, any zero values are given zero weighting and will not influence the fit. EGS: mvn_sta_defl_fov_amoebafit, dataY, dataV, tpwin=0, wnum=1 It is recommended that you use mvn_sta_defl_fov_run instead, which will calculate the FOV flag value over multiple time steps.
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
Input a 4x16 array. Rescale it to a larger set of pixels, for plotting using tv.
arrayin: data array to be up scaled [4x16]
factor: the scaling factor by which to multiply arrayin. Must be an integer. Eg, factor=2 will give an output array of 8x32, where
each 2x2 square is equivalent to a 1x1 square in the original array.
If you set xfact and yfact below, you do not need to set factor.
xfact, yfact: scaling factors for x and y dimensions independently. Same as above, but apply to X and Y dimensions separately.
Setting these will overwrite factor. If you set one, both must be set, as factor will be ignored.
output: the upscaled array.
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
Routine to histogram plot where all bins are evenly sized in x. Using psym=10 in IDL produces the end bins at half the size of the
other bins.
This routine will simply oplot data (using the oplot routine), so make sure it is in the right place in your code.
Xdata, Ydata: fltarrs, etc. Ydata will have one less element than Xdata, because Xdata must bound each side of each bin.
Set /vert to plot as a vertical plot. The defualt is horizontal.
EG: to plot data for 16A, ydata is [16] in size, and contains the eflux for each anode. xdata will be 17 in size, where
xdata = findgen(17).
cmf_sta_hist_plot, Xdata, Ydata
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
Create the STATIC FOV flag, using inputs from mvn_sta_fov_snap. INPUTS: FOVoutput: IDL data structure FOVoutput, from mvn_sta_d0d1c8_fov_crib. OUTPUTS: flagVAL: ;0 means FOV ok, 1+2 mean possible problems, 3 means not ok. Default is 3
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
Crib to get FOV and spacecraft blockage flags using d0/d1 and c8 data. Plan is to use d0 data to get 16A x 4D map. Find peak
eflux or counts. Is there spacecraft bloackage in an adjacent bin? Not sure how to handle deflector fov, as with only 4D, peak
can easily lie in outside bin, but peak can still easily be within FOV. Can use c8 data to help at times. Check if
>X% of eflux or counts lie within a certain anode. If this is the case, assume that the c8 data (which is 16D x 1A) is
representative of that anode. Can check deflector dimension for this peak.
Add in mass and energy dependence via d0 and d1 data. How does this affect c8 data? => if peak lies in same 4 bins in c8,
that it lies in within d0, assume it's the same peak? If not, not sure?
trange: double precision UNIX time:
two element array [a,b]: calculate FOV details between these two times.
single time: a: calculate FOV details for this time.
wnum: window number into which the FOV results are plotted. Dedfault if not set is 2. The plotting occurs when looking at a single
timesptamp. Plotting will not occur by default when a time range is entered, to save time. Use the /forceplot keyword
to overcome this.
erange: [a, b]: floats: energy range in eV between which to look at. STATIC energies typically range between 0.01 and ~5E4 eV,
depending on observation mode.
mrange: [a, b]: floats: mass range in AMU between which to look at. d0 and d1 data products have 8 mass bins.
forceplot: set /forceplot to force the routine to plot the FOV results each timestep, into window wnum. Default is to only do this
plotting when trange is a single timestep.
tpnum: the window number with tplot variables in. This is only required when using this function as part of ctime, to plot the FOV
results as you drag the cursor. The default is tpnum=0 if not set.
ctimeflag: set to 1 if using the routine with ctime, to plot FOV results while moving the cursor over a tplot window. Set to
0 if this is not the case (you are entering a specific time or time range). The user should not have to set this
keyword, it should set automatically based on your input to mvn_sta_fov_snap.
sta_apid: lowercase string: user can set which STATIC data products to use by hand if wanted. Options are 'ce', 'cf', 'd0', 'd1',
as no other STATIC products contain the necessary information.
Set /qc to load qualcolors (Mike Chaffins colorbars). Uses default IDL colors it not set.
top_c, bottom_c: top and bottom color table indices that IDL should used when plotting. Defaults if not set are either 0 and 255,
or those set by qualcolors, if /qc is set.
zrange: [a,b] float array, where a and b are the min and max energy flux values for the colorbar. Useful if you want all plots to
keep the same plot range. If not set, the code uses default variable zranges based on the energy flux present at each timestep.
a and b are real numbers - they will become alog10(a), alog10(b) within the code.
OUTPUTS:
success: 0 means the code did not run (eg no data found). 1 means code ran. See FOVoutput for success codes on each timestamp
analyzed.
NOTES:
The d0 / d1 display may have different colors to the c8 panel. This is because c8 does not have mass descrimination, and thus if
you set mrange, this will filter out some data from the d0/d1 products, which is still included in the c8 product.
EGS:
Run before to load in data:
timespan, '2018-07-08', 1.
mvn_sta_l2_load, sta_apid=['d1', 'c8'], /tplot_vars_create ;note: tplot variables /tplot-vars-create are not needed.
tt0=1530859000.0000000d ;testing - pick up ions
mvn_sta_d0d1c8_fov_crib, trange=[a,b] ;calculate between a time range [a,b].
mvn_sta_d0d1c8_fov_crib, trange=a ;calculate at just one time, a.
.r /Users/cmfowler/IDL/STATIC_routines/FOV_routines/mvn_sta_fov_defl.pro
.r /Users/cmfowler/IDL/STATIC_routines/FOV_routines/mvn_sta_fov_snap.pro
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)
This is the top most routine that users should run. This routine will call upon those above.
INPUTS:
trange: optional: set as:
single UNIX time: calculate FOV results for this time. Results are plotted into the window wnum.
time range [a,b]: calculate FOV results between these two times. Results are not plotted in this mode to save time,
but setting /forceplot will overwrite this.
don't set: use the ctime cursor in your tplot window, and the FOV results will plot as you move the cursor. Set wnum and
tpnum.
wnum: IDL window number into which FOV results are plotted. Default is 2 if not set.
tpnum: IDL window number that your tplot is in. Default is 0 if not set.
success: 1 if routine was able to generate FOV flags, 0 if it wasn't (ie no data available).
I'm not sure this will work when using in the tplot cursor mode.
mrange: AMU mass range to look. Right now doesn't work - looks at all masses.
erange: energy range in eV to look at - right now doesn't work - looks at all energies.
sta_apid: lowercase string: user can set which STATIC data products to use by hand if wanted. Options are 'ce', 'cf', 'd0', 'd1',
as no other STATIC products contain the necessary information.
Set /forceplot to force the routine to plot the FOV results, even when running over multiple timesteps.
Set /qc to use Mike Chaffins qualcolors color tables. If not set, default IDL colors are used.
Set /allvars to create the full set of tplot variables associated with determining the STATIC FOV flag. These are mostly
for testing purposes. If not set, only one variable will be created, mvn_sta_FOV_flag, which contains the final flag information.
top_c, bottom_c: top and bottom color table indices that IDL should used when plotting. Defaults if not set are either 0 and 255,
or those set by qualcolors, if /qc is set.
zrange: [a,b] float array, where a and b are the min and max energy flux values for the colorbar. Useful if you want all plots to
keep the same plot range. If not set, the code uses default variable zranges based on the energy flux present at each timestep.
a and b are real numbers - they will become alog10(a), alog10(b) within the code.
species: there are several ions with pre-set mass parameters; enter the following strings (case independent):
'H', 'He', 'O', 'O2' or 'CO2'. If set, you don't need to set mrange or m_int - these are set for you. The species input overwrites
the mrange and m_int keywords.
mrange: [a,b]: use this keyword to specify the mass range for which flow velocities are calculated for.
Each mass range will have its own tplot variable created. If not set, all masses are used.
Some additional notes:
STATIC d0 and d1 data have 8 mass bins centered on the following AMU values. The following options are allowed for the
mass keyword:
mass = 1.09 AMU
= 2.23 AMU
= 4.67 AMU
= 9.42 AMU
= 17.14 AMU
= 30.57 AMU
= 42.42 AMU
= 62.53 AMU
STATIC ce and cf data have 16 mass bins (more mass resolution), but are only available in ~2015. After ~2015, at least d0
data should be available all of time (and d1 data should be available most of the time).
searchvector: [a,b,c]: vector in the MSO coordinate system. If set, the routine will mark which STATIC anode-deflector bins fall within
coneangle of this vector.
coneangle: float: STATIC bins that lie within this angle of searchvector are plotted. Units of degrees. Default is 35 degrees if not set.
OUTPUTS:
flagout: If trange is set as a single timestamp, or two element array of start and stop times, the keyword flagout will contain the
STA FOV flag variables for the user specified mass and energy ranges. The default value of flagout is NaN, if not flag value
was calculated (success=0).
If trange is set as a two element array as a time range, the tplot variable mvn_sta_FOV_flag_mrA_B_erC_D will
be produced, where A and B are the AMU mass range, and C and D are the energy range, specified by the user. This tplot
variable contains the FOV flag for those ions.
The flag values are below. Data with flag=0 data can be used with confidence. Data with flag=1 and
flag=2 may have FOV issues, and if used, should be used with caution. Data with flag=3 has FOV issues and should not be used.
0 : FOV should be ok - ok to use data.
1 : Possible FOV issues - this is based on data without mass resolution. Use with caution.
2 : Possible FOV issues: the beam lies at the edge of the FOV. Finer resolution data show the beam to be within the FOV,
but these data don't resolve mass. Use with caution.
3 : FOV issues: the beam is at the edge of the FOV, and / or the spacecraft is blocking part of the beam. Don't use.
EGS:
You must first load STATIC d0 or d1 data, and c8 data:
timespan, '2018-07-06', 1.
mvn_sta_l2_load, sta_apid=['d1', 'c8'], /tplot_vars_create
window, 0
tplot, [some variables]
ctime, t0 ;select a single time, or a range of times.
mvn_sta_fov_snap, trange=t0, tpnum=0, sta_apid='d1', species='o' ;this will plot the results for a single click, or output them for a range.
mvn_sta_fov_snap, tpnum=0, sta_apid='d1', erange=[1000., 30000.] ;this will allow the user to move the cursor across the tplot window and set the results at each timestep.
mvn_sta_fov_snap, sta_apid='d1', zrange=[1e6, 1e10], top_c=240 ;set colorbar range, and restrict color indices IDL can use when plotting.
.r /Users/cmfowler/IDL/STATIC_routines/FOV_routines/mvn_sta_fov_snap.pro
(See projects/maven/sta/l2analysis/FOV/mvn_sta_fov_snap.pro)