This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Apr 1 11:58:51 2022.
FUNCTION:
atan2
PURPOSE:
Utility routine to calculate the arc tangent. This routine is currently
used by the ELFIN orbit plots
KEYWORDS:
yin: y variable
xin: x variable
degrees: set this flag to output results in degrees. if not set the
result will be in radians
full_circle: if set, output is 0-360 degs, if not it is +-180 degs
OUTPUT:
arc tangent
AUTHOR: Jiang Liu
(See projects/elfin/plots/atan2.pro)
Procedure: batch_procedure_error_handler Purpose: This routine catches errors for procedure calls, to prevent individual routine failures from killing the whole process Inputs: proc_name: is a string naming the procedure to be called date: The date for the call(positional argument is common to all calls being error handled _extra: is used to allow any set of keyword parameters for the call arg0-arg9: Support for up to 10 positional parameters. How many are used depends upon the procedure Example: check_state_files_error_handler,'map_themis_state_south_t96','2007-03-23',/gifout,noview=noview,/move $LastChangedBy: jimm $ $LastChangedDate: 2016-03-14 12:22:36 -0700 (Mon, 14 Mar 2016) $ $LastChangedRevision: 20440 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/thmsoc/asi/batch_procedure_error_handler.pro $
(See projects/elfin/plots/batch_procedure_error_handler.pro)
FUNCTION:
elf_calc_sci_zone_att
PURPOSE:
Calculates the science attitude vector and determines which auroral crossing
(science zone name)
KEYWORDS:
trange: time frame to be used for calculation
(format can be time string '2020-03-20'
or time double). Example: trange=['2020-03-20;,'2020-03-21']
probe: probe name, probes include 'a' and 'b'
lat: lattitude (used to determine which zone)
lshell: lshell used to determine whether IBO or OBO
obo: set this keyword to get inner belt att
OUTPUT:
creates a tplot variable 'el'+probe+'_spin_att_ang' that contains the following
data={x:times, y:colats, z:zone_names}
(See projects/elfin/plots/elf_calc_sci_zone_att.pro)
PROCEDURE:
elf_convert_state_gei2sm
PURPOSE:
Convert previously loaded state data from gei coordinates to SM. This is a
utility routine. This coordinate conversion occurs frequently in ELFIN code
KEYWORDS:
probe: spacecraft probe name 'a' or 'b'
(See projects/elfin/plots/elf_convert_state_gei2sm.pro)
PROCEDURE:
elf_load_epd_fast_segments
PURPOSE:
Loads the EPD fast segment intervals into a bar that can be plotted
KEYWORDS:
tplotname: name of tplot variable (should be ela_epdef or elb_ela_epdif)
nodownload: set this flag to force routine to load local data only (no download)
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 09:33:48 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/elf/common/data_status_bar/elf_load_fast_segments.pro $
(See projects/elfin/plots/elf_load_epd_fast_segments.pro)
PROCEDURE:
elf_load_epd_survey_segments
PURPOSE:
Loads the EPD survey segment intervals into a bar that can be plotted
KEYWORDS:
tplotname: name of tplot variable (should be ela_epdes or elb_ela_epdis)
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 09:33:48 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/elf/common/data_status_bar/elf_load_fast_segments.pro $
(See projects/elfin/plots/elf_load_epd_survey_segments.pro)
PROCEDURE:
elf_load_fgm_fast_segments
PURPOSE:
Loads the FGM fast segment intervals into a bar that can be plotted
KEYWORDS:
tplotname: name of tplot variable (should be ela_fgf or elb_fgf)
probe: elfin spacecraft name, 'a' or 'b'
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 09:33:48 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/elf/common/data_status_bar/elf_load_fast_segments.pro $
(See projects/elfin/plots/elf_load_fgm_fast_segments.pro)
PROCEDURE:
elf_load_fgm_survey_segments
PURPOSE:
Loads the FGM survey segment intervals into a bar that can be plotted
KEYWORDS:
tplotname: name of tplot variable (should be ela_fgs or elb_fgs)
no_download: set this flag to use local data only
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 09:33:48 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/elf/common/data_status_bar/elf_load_fast_segments.pro $
(See projects/elfin/plots/elf_load_fgm_survey_segments.pro)
PROCEDURE:
elf_load_science_times
PURPOSE:
Get science data for FGM and EPD and load into tplot vars
Return science collection times structure (for elfin a and b)
This routine is used by elf_map_state_t96_intervals.
KEYWORDS:
tdate: time of interest (start time) with the format
'YYYY-MM-DD'
dur: duration of time frame in factional days. default value is 1
pred: use this flag if you want to check predicted data
(See projects/elfin/plots/elf_load_science_times.pro)
PROCEDURE:
elf_load_sun_shadow_bar
PURPOSE:
Loads the survey segment intervals into a bar that can be plotted
KEYWORDS:
tplotname: name of tplot variable (should be ela_pos_sm or ela_pos_sm)
no_download: set this flag to force
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 09:33:48 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/elf/common/data_status_bar/elf_load_fast_segments.pro $
(See projects/elfin/plots/elf_load_sun_shadow_bar.pro)
PROCEDURE:
elf_make_geo_grid
PURPOSE:
Create a geographic grid for orbit plots
KEYWORDS:
None
(See projects/elfin/plots/elf_make_geo_grid.pro)
PROCEDURE:
elf_make_sm_grid
PURPOSE:
Create SM latitude rings and longitude spokes, expresented in GEO.
(for use with ELFIN orbit plots)
KEYWORDS:
tdate: time to be used for calculation
(format can be time string '2020-03-20'
or time double)
south: use this flag for grids in southern hemisphere
OUTPUT:
sm_grids: structure with lat rings, lon spokes, and poles
EXAMPLE:
sm_grid = elf_make_sm_grid('2020-03-20')
sm_grid = elf_make_sm_grid('2020-03-20', /south)
(See projects/elfin/plots/elf_make_sm_grid.pro)
PROCEDURE:
elf_make_spin_att_string
PURPOSE:
Utility routine to construct the attitude string displayed on
ELFIN Orbit plots.
KEYWORDS:
probe: spacecraft identifier 'a' or 'b'
OUTPUT:
spin attitude string
EXAMPLE:
spin_str=elf_make_spin_att_string('a')
NOTE:
This routine assumes that the spin attitude angle tplot variable exists
(See projects/elfin/plots/elf_make_spin_att_string.pro)
polar orbit
JWu change south pole position in GEO plot
NAME:
ELF_MAP_STATE_T96_INTERVALS
PURPOSE:
map ELFIN spacecraft to their magnetic footprints
CATEGORY:
None
CALLING SEQUENCE:
elf_map_state_t96_intervals,'2018-11-10/00:00:00'
INPUTS:
tstart start time for the map
KEYWORD PARAMETERS:
gifout generate a gif image at output
south use southern hemisphere (otherwise, north)
noview do not open window for display
model specify Tsyganenko model like 't89' or 't01', default is 't96'
dir_move directory name to move plots to
quick_trace run ttrace2iono on smaller set of points for speed
tstep use this to turn on tick marks and set the frequency in seconds
clean obsolete (parameter should be removed)
no_trace set this flag if you already have the data in hand and calculated in
a previous run
one_hour_only: set this flag to only plot the first orbit
hires set this flag to create a higher resolution plot
sm set this keyword for footprint in SM coordinates, default is GEO
bfirst set this keyword for probe b footprint on top (default is for a on top)
note that this keyword is only used if the coordinates are in SM
pred set this flag to use predicted state data
insert_stop set this flag to stop after the first plot (used for debugging)
OUTPUTS:
GIF images
EXAMPLE:
elf_map_state_t96_intervals,'2018-11-10/00:00:00' ; this will defer to defaults and plot only
; northern hemisphere, geographic grids in
; normal resolution
MODIFICATION HISTORY:
Written by: C L Russell May 2020
VERSION:
$LastChangedBy:
$LastChangedDate:
$LastChangedRevision:
$URL:
(See projects/elfin/plots/elf_map_state_t96_intervals.pro)
Procedure: elf_map_state_t96_wrapper
PURPOSE:
Routine just wraps elf_map_state_t96(north and south tracing variants). Making separate
calls for each type of overview interval. Mainly used to reprocess.
INPUT:
Date: date for plot creation, if not set, assumes current date and duration counts backwards(ie last N days from today)
KEYWORDS:
dur: If set, number of days to process, default is 1
south_only: If set, does tracing to southern hemisphere only
north_only: If set, does tracing to northern hemisphere only
The default value is to plot both north and south
pred: Set this flag to use predicted data and title to predicted
sm: Set this flag to create plots in sm coordinates (default is geo)
bfirst: Set this flag to plot b on top of a (default is a on top of b)
do_all: Set this flag to create all plots (north, south, geo, sm, a on b, and b on a)
$LastChangedBy: pcruce $
$LastChangedDate: 2012-07-31 14:50:02 -0700 (Tue, 31 Jul 2012) $
$LastChangedRevision: 10758 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/thmsoc/asi/map_themis_state_t96_wrapper.pro $
(See projects/elfin/plots/elf_map_state_t96_intervals_wrapper.pro)
Procedure: elf_mlt_l_lat Purpose: subroutine to calculate mlt,l,mlat under dipole configuration Inputs: variable_state: tplot variable containing position data in sm coordinates Keywords: mlt0: l0: lat0: Latitude Example: elf_mlt_l_lat,probe='a',date='2007-03-23' Notes: Based on a routine by Qianli Ma (qianlima@atmos.ucla.edu) $LastChangedBy:$ $LastChangedDate:$ $LastChangedRevision:$ $URL:$
(See projects/elfin/plots/elf_mlt_l_lat.pro)
PROCEDURE:
elf_plot_attitude
PURPOSE:
Create attitude plots (3 panels - att_gei vector, theta, phi) with timebars for maneuvers
KEYWORDS:
trange: time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
EXAMPLES:
elf> elf_plot_attitude, trange=['2019-07-01', '2019-11-01']
NOTES:
(See projects/elfin/plots/elf_plot_attitude.pro)
NAME: elf_plot_orbit_conjunctions_test
PURPOSE: create ELFIN, THEMIS, MMS, ERG orbit plots in GSM coordinates for web site
INPUT: tstart like '2009-12-01'
OUTPUT: gif files may be generated
KEYWORDS: gifout = gif images are generated
file = specify file if not reading THEMIS ephemeris
insert = insert stop at end of program
rbsp_too = if set, overlay RBSP orbits
mms_too = if set, overlay MMS orbits
erg_too = if set, overlay ERG orbigts
model = name of Tsyganenko model ('t89', 't96', 'ta15'). default is 't96' (Not yet implemented)
HISTORY: original file in March 2007, hfrey
MODIFICATIONS: 2010-01-14, hfrey, new definition of plot area
REQUIREMENTS: compile two programs for instance in
.r /home/sfrey/themis/MOC/pro/mpause_2
.r /home/sfrey/themis/MOC/pro/bshock_2
VERSION:
$LastChangedBy: jimm $
$LastChangedDate: 2020-11-18 13:03:02 -0800 (Wed, 18 Nov 2020) $
$LastChangedRevision: 29359 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/thmsoc/asi/themis_orbits.pro $
(See projects/elfin/plots/elf_plot_orbit_conjunctions.pro)
PROCEDURE:
elf_plot_sci_zone_lat
PURPOSE:
This routine will plot the latitude values at the start and end times of science zones
Scienc zone panels are separated by science zone North Ascending, South Ascending, North
Descending, and South Descending
KEYWORDS:
tstart: start time to be used for the plot
(format can be time string '2020-03-20'
or time double)
dur: duration in days
probe: probe name, probes include 'a' and 'b'
instrument: instrument name, insturments include 'epd', 'fgm', 'mrm'
OUTPUT:
EXAMPLE:
elf_update_data_availability_table, '2020-03-20', probe='a', instrument='epd'
(See projects/elfin/plots/elf_plot_sci_zone_lat.pro)
PROCEDURE:
epde_plot_overviews
PURPOSE:
Loads EPDE, performs pitch angle determination and plotting of energy and pitch angle spectra
Including precipitating and trapped spectra separately. EPDI can be treated similarly, but not done yet
Regularize keyword performs rebinning of data on regular sector centers starting at zero (rel.to the time
of dBzdt 0 crossing which corresponds to Pitch Angle = 90 deg and Spin Phase angle = 0 deg.).
If the data has already been collected at regular sectors there is no need to perform this.
KEYWORDS:
trange - time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
probe - 'a' or 'b'
no_download - set this flag to not download data from the server and use local files only
sci_zone - if set this flag will plot epd overview plots by science zone (rather than by day)
TO DO:
elb can be done similarly but the code has not been generalized to either a or b yet. But this is straightforward.
(See projects/elfin/plots/epde_plot_overviews.pro)
PROCEDURE:
epde_plot_wigrf_multispec_overviews
PURPOSE:
Loads EPDE, performs pitch angle determination and plotting of energy and pitch angle spectra
Including precipitating and trapped spectra separately. EPDI can be treated similarly, but not done yet
Regularize keyword performs rebinning of data on regular sector centers starting at zero (rel.to the time
of dBzdt 0 crossing which corresponds to Pitch Angle = 90 deg and Spin Phase angle = 0 deg.).
If the data has already been collected at regular sectors there is no need to perform this.
KEYWORDS:
trange - time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
probe - 'a' or 'b'
no_download - set this flag to not download data from the server and use local files only
sci_zone - if set this flag will plot epd overview plots by science zone (rather than by day)
TO DO:
elb can be done similarly but the code has not been generalized to either a or b yet. But this is straightforward.
(See projects/elfin/plots/epde_plot_wigrf_multispec_overviews.pro)
PROCEDURE:
find_interval
PURPOSE:
This routine looks for intervals of consecutive indices in an index array
and determines start and end index of each interval.
INPUT:
index: index array usually from where function
OUTPUT:
istart: index of first element of an interval
iend : index of last element of an interval
AUTHOR:
v1.0 S.Frey 12-30-03
(See projects/elfin/plots/find_interval.pro)
PROCEDURE:
find_orbits
PURPOSE:
Procedure returns indices of perigees and apogees. Apsides are determined as
the local minima and maxima based on x,y,z orbit coordinates only. Orbit sets
are split into single orbits by node crossings. If nodes are close to or at local
minima then cutoffs are shifted to meet local minima and maxima conditions.
For orbits sets, arcs that are ascending or decsending only determination of
first and last apsides is based on average orbit length and can be off by orbit
variation. For a partial orbit this method works only if apside is well
insight the arc. This indicated by message 'Orbit is not complete, apogee might
not be true'.
INPUT
x
y Components preferrably in GEI
z
KEYWORDS:
info: if set some details are printed
tolerance: Flag to pick orbit variation, period perturbations make orbit size
varying from one orbit to another, and
different time resolutions might call for different tolerances
(orbit length/[3.,10.]) <[100,8]
tolerance=3 picks smaller value (low resolution)
tolerance>3 picks higher value (high resolution)
This has some heritage
halt: flag to stop
test: selects three test cases (=1,=2,=3)
nostop: flags to not stop if different orbits sizes cause
stop if max(abs(diff2),ibad) gt round(median(abs(dstart-astart))/10.)
should not be set for maneuver calculation but is helpful when
all statevectors from archive are put into one structure and then
processed for visualization such as in plot_elements, helps to keep
automation as orbits go into final size
OUTPUT:
ind_pg ; index of perigee passes
ind_ap ; index of apogee passes
ind_asnode: index of ascending node
orbitnumber: orbit count starts at 1, increments at ascending node
norbits: numbers of orbits
ag,pg : flag to indicate which one is first
AUTHOR:
S. Frey, UCB, SSL
(See projects/elfin/plots/find_orbits.pro)
PROCEDURE:
get_elf_science_zone_start_end
PURPOSE:
This routine searches a specified time range for science zone collections and returns a
structure sci_zones={starts:sz_starttimes, ends:sz_endtimes}
This is a utility routine used by some of the plot routines but can be used standalong
KEYWORDS:
trange: time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
probe: spacecraft specifier, 'a' or 'b'. default value is 'a'
instrument: string containing name of instrument to find the science zone
time frame. 'epd' is the only instrument implemented in this routine
'fgm' needs to be added
OUTPUT:
sci_zones={starts:sz_starttimes, ends:sz_endtimes}
AUTHOR:
v1.0 S.Frey 12-30-03
(See projects/elfin/plots/get_elf_science_zone_start_end.pro)
FUNCTION
get_vec_angle
PURPOSE:
determines angle between two vectors
INPUT:
vec1, vec2: either 2d or 3d vectors, arrays possible,
one array, one vector also possible
vec[0,*]-x component
vec[1,*]-y component
vec[2,*]-z component
OUTPUT:
ang: angle between vec1,vec2
mag1,mag2: Optional output of magnitude of vectors
dot_product: scalar product between the two vectors (Optional)
sfrey v1.0
05-19-08 sfrey added dot_product
02-23-16 sfrey made it work for 2 or 3 dimensions with one being a vector and theother an array
this did only work for 3 dims in the past
03-03-16 sfrey replaced !d.radeg by 180.d/!dpi
moved header to top of file
01-09-17 sfrey No more return of modified input
(See projects/elfin/plots/get_vec_ang.pro)
PROCEDURE: elf_make_att_gif, filename
NAME:
makegif
PURPOSE:
Creates a GIF file from the currently displayed image. This is a modified version of
makegif.pro that does not create a png file in addition to a gif file. This creates
only a gif file.
PARAMETERS:
filename filename of gif file to create. Defaults to 'plot'. Note:
extension '.gif' is added automatically
KEYWORDS:
ct Index of color table to load. Note: will have global
consequences!
multiple Write multiple gifs to a single file. Subsequent calls to
makegif with same filename argument will append to the file.
Use /close to close.
close close the gif file. Useful when writing multiple gifs to
a single file. Does not write any image to the file.
no_expose Don't print index of current window.
Restrictions:
Current device should have readable pixels (ie. 'x' or 'z')
Created by: Davin Larson
FILE: makegif.pro
VERSION: 1.11
LAST MODIFICATION: 02/11/06
(See projects/elfin/plots/elf_make_att_gif.pro)
PROCEDURE:
ovalget
PURPOSE:
reads oval files and returns values for poleward/equatorward lon/lat (arrays)
INPUT:
qindx
OUTPUT
pwdboundlonlat: p for poleward longitude and latitude (nx2)
ewdboundlonlat: e for equatorward longitude and latitude (nx2)
(See projects/elfin/plots/ovalget.pro)
PROCEDURE: plot_science_zone_mlat PURPOSE: This routine plots the magnetic latitudes whenever data is collected during a science zones KEYWORDS: This was a one off routine but seems useful. Keywords should be added to this routine OUTPUT: AUTHOR: v1.0 S.Frey 12-30-03
(See projects/elfin/plots/plot_science_zone_mlat.pro)
NAME:
WHERE_ARRAY
PURPOSE:
Return the indices where vector B exists in vector A.
Basically a WHERE(B EQ A) where B and A are 1 dimensional arrays.
CATEGORY:
Array
CALLING SEQUENCE:
result = WHERE_ARRAY(A,B)
INPUTS:
A vector that might contains elements of vector B
B vector that we would like to know which of its
elements exist in A
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
iA_in_B return instead the indices of A that are in
(exist) in B
OUTPUTS:
Index into B of elements found in vector A. If no
matches are found -1 is returned. If the function is called
with incorrect arguments, a warning is displayed, and -2 is
returned (see SIDE EFFECTS for more info)
OPTIONAL OUTPUTS:
COMMON BLOCKS:
None
SIDE EFFECTS:
If the function is called incorrectly, a message is displayed
to the screen, and the !ERR_STRING is set to the warning
message. No error code is set, because the program returns
-2 already
RESTRICTIONS:
This should be used with only Vectors. Matrices other then
vectors will result in -2 being returned. Also, A and B must
be defined, and must not be strings!
PROCEDURE:
EXAMPLE:
IDL> A=[2,1,3,5,3,8,2,5]
IDL> B=[3,4,2,8,7,8]
IDL> result = where_array(a,b)
IDL> print,result
0 0 2 2 3 5
SEE ALSO:
where
MODIFICATION HISTORY:
Written by: Dan Carr at RSI (command line version) 2/6/94
Stephen Strebel 3/6/94
made into a function, but really DAN did all
the thinking on this one!
Stephen Strebel 6/6/94
Changed method, because died with Strings (etc)
Used ideas from Dave Landers. Fast TOO!
Strebel 30/7/94
fixed checking structure check
(See projects/elfin/plots/where_array.pro)