This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/elfin/plots

- ATAN2
  Utility routine to calculate the arc tangent. This routine is currently
- BATCH_PROCEDURE_ERROR_HANDLER
- ELF_CALC_SCI_ZONE_ATT
  Calculates the science attitude vector and determines which auroral crossing
- ELF_CONVERT_STATE_GEI2SM
  Convert previously loaded state data from gei coordinates to SM. This is a
- ELF_CREATE_INSTRUMENT_ALL
  This procedure will download data availability files by auroral zone and instrument. All data availability
- ELF_GET_EISCAT_POSITIONS
  This routine will return the position (latitude and longitude) of
- ELF_GET_VLF_POSITIONS
  This routine will return the position (geo latitude/longitude and mag latitude/longitude)
- ELF_LOAD_EPD_FAST_SEGMENTS
  Loads the EPD fast segment intervals into a bar that can be plotted
- ELF_LOAD_EPD_SURVEY_SEGMENTS
  Loads the EPD survey segment intervals into a bar that can be plotted
- ELF_LOAD_FGM_FAST_SEGMENTS
  Loads the FGM fast segment intervals into a bar that can be plotted
- ELF_LOAD_FGM_SURVEY_SEGMENTS
  Loads the FGM survey segment intervals into a bar that can be plotted
- ELF_LOAD_SCIENCE_TIMES
  Get science data for FGM and EPD and load into tplot vars
- ELF_LOAD_SUN_SHADOW_BAR
  Loads the survey segment intervals into a bar that can be plotted
- MAKEGIF[1]
  Creates a GIF file from the currently displayed image. This is a modified version of
- ELF_MAKE_GEO_GRID
  Create a geographic grid for orbit plots
- ELF_MAKE_SM_GRID
  Create SM latitude rings and longitude spokes, expresented in GEO.
- ELF_MAKE_SPIN_ATT_STRING
  Utility routine to construct the attitude string displayed on
- ELF_MAP_STATE_T96_INTERVALS[2]
  map ELFIN spacecraft to their magnetic footprints
- ELF_MAP_STATE_T96_INTERVALS[1]
  map ELFIN spacecraft to their magnetic footprints
- ELF_MAP_STATE_T96_INTERVALS_WRAPPER
  Routine just wraps elf_map_state_t96(north and south tracing variants). Making separate
- ELF_MLT_L_LAT
- ELF_PLOT_ATTITUDE
  Create attitude plots (3 panels - att_gei vector, theta, phi) with timebars for maneuvers
- ELF_PLOT_MULTISPEC_OVERVIEWS
  Routine just wraps epde_plot_wigrf_multispec_overviews. Mainly used for processing.
- ELF_PLOT_ORBIT_CONJUNCTIONS
- ELF_PLOT_SCI_ZONE_LAT
  This routine will plot the latitude values at the start and end times of science zones
- EPDE_PLOT_OVERVIEWS
  Loads EPDE, performs pitch angle determination and plotting of energy and pitch angle spectra
- EPDE_PLOT_OVERVIEWS_SOLO
  Loads EPDE, performs pitch angle determination and plotting of energy and pitch angle spectra
- EPDE_PLOT_WIGRF_MULTISPEC_OVERVIEWS
  Loads EPDE, performs pitch angle determination and plotting of energy and pitch angle spectra
- EPDI_PLOT_OVERVIEWS
  Loads EPDE and EPDI performs pitch angle determination and plotting of energy and pitch angle spectra
- FIND_INTERVAL
  This routine looks for intervals of consecutive indices in an index array
- FIND_ORBITS
  Procedure returns indices of perigees and apogees. Apsides are determined as
- GET_ELF_SCIENCE_ZONE_START_END
  This routine searches a specified time range for science zone collections and returns a
- GET_VEC_ANG
  determines angle between two vectors
- OVALGET
  reads oval files and returns values for poleward/equatorward lon/lat (arrays)
- PLOT_SCIENCE_ZONE_MLAT
  This routine plots the magnetic latitudes whenever data is collected during a science zones
- WHERE_ARRAY
  Return the indices where vector B exists in vector A.

# Routine Descriptions

## ATAN2

[Next Routine] [List of Routines]

     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)

## BATCH_PROCEDURE_ERROR_HANDLER

[Previous Routine] [Next Routine] [List of Routines]

    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)

## ELF_CALC_SCI_ZONE_ATT

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_CONVERT_STATE_GEI2SM

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_CREATE_INSTRUMENT_ALL

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
             elf_create_instrument_all

     PURPOSE:
             This procedure will download data availability files by auroral zone and instrument. All data availability
             from all zones is writen to a file for all

     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 probe name 'a' or 'b'
             instrument:   name of instrument, 'epd', 'fgm', 'mrm'
             nodownload:   set this flag to read files from the local disk and not from the server
                           (this is used by cronjobs when automatically running procedures)
             update:       set this flag to force the update of the data availability flag

(See projects/elfin/plots/elf_create_instrument_all.pro)

## ELF_GET_EISCAT_POSITIONS

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION: elf_get_eiscat_positions

     PURPOSE:
         This routine will return the position (latitude and longitude) of
         three EISCAT stations (incoherent radar scattering)
         Stations include: Tromso_UHF, Tromso_VHF, Svalbard

     KEYWORDS:
         None

     OUTPUT:
        eiscat_pos - a structure containing the station names, latitudes, and longitudes.
                     ** Structure <28f7a620>, 3 tags, length=72, data length=72, refs=1:
                     NAME            STRING    Array[3]
                     LAT             FLOAT     Array[3]
                     LON             FLOAT     Array[3]

     EXAMPLE:
        eiscat_pos = elf_get_eiscat_positions()

(See projects/elfin/plots/elf_get_eiscat_positions.pro)

## ELF_GET_VLF_POSITIONS

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION: elf_get_vlf_positions

     PURPOSE:
         This routine will return the position (geo latitude/longitude and mag latitude/longitude)
         of seven VLF stations (incoherent radar scattering)
         stations include: 'IST', 'OUJ', 'MAM', 'GAK', 'ATH', 'KAP', 'KAN'

     KEYWORDS:
         None

     OUTPUT:
        vlf_pos - a structure containing the station names, geo and magh lat/lon.
                  ** Structure <3d936c30>, 5 tags, length=224, data length=224, refs=1:
                  NAME            STRING    Array[7]
                  GLAT            FLOAT     Array[7]
                  GLON            FLOAT     Array[7]
                  MLAT            FLOAT     Array[7]
                  MLON            FLOAT     Array[7]

     EXAMPLE:
        vlf_pos = elf_get_vlf_positions()

(See projects/elfin/plots/elf_get_vlf_positions.pro)

## ELF_LOAD_EPD_FAST_SEGMENTS

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_LOAD_EPD_SURVEY_SEGMENTS

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_LOAD_FGM_FAST_SEGMENTS

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_LOAD_FGM_SURVEY_SEGMENTS

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_LOAD_SCIENCE_TIMES

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_LOAD_SUN_SHADOW_BAR

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_MAKE_GEO_GRID

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
             elf_make_geo_grid

     INPUTS:
             mlat: magnetic latitude
             mlon: magnetic longitude
             height: elevation in km
             glat: geographic latitude
             glon: geographic longitude

     OUTPUTS:
             geo_grid: returns a structure with geographic grid

     PURPOSE:
             Create a geographic grid for orbit plots

     KEYWORDS:
             None

(See projects/elfin/plots/elf_make_geo_grid.pro)

## ELF_MAKE_SM_GRID

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_MAKE_SPIN_ATT_STRING

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_MAP_STATE_T96_INTERVALS[1]

[Previous Routine] [Next Routine] [List of Routines]

    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_eom.pro)

## ELF_MAP_STATE_T96_INTERVALS[2]

[Previous Routine] [Next Routine] [List of Routines]

    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)

## ELF_MAP_STATE_T96_INTERVALS_WRAPPER

[Previous Routine] [Next Routine] [List of Routines]

    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)

## ELF_MLT_L_LAT

[Previous Routine] [Next Routine] [List of Routines]

    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)

## ELF_PLOT_ATTITUDE

[Previous Routine] [Next Routine] [List of Routines]

     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)

## ELF_PLOT_MULTISPEC_OVERVIEWS

[Previous Routine] [Next Routine] [List of Routines]

    Procedure: elf_plot_multispec_overviews

    PURPOSE:
      Routine just wraps epde_plot_wigrf_multispec_overviews. Mainly used for processing.

    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
      probe: 'a' or 'b'
      no_download: If set no files will be downloaded
      sci_zone: If set this flag will create overplots by science zone rather than by hour
      quick_run: set this flag to reduce the resolution of the data for a quicker run
      one_zone_only: set this flag to plot only the first zone (this is for debug purposes)

(See projects/elfin/plots/elf_plot_multispec_overviews.pro)

## ELF_PLOT_ORBIT_CONJUNCTIONS

[Previous Routine] [Next Routine] [List of Routines]

     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
               goes_too = if set, GOES 15 and 16 orbits are overlaid
                   (NOTE: need to modify to handle any goes orbits)
               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)

## ELF_PLOT_SCI_ZONE_LAT

[Previous Routine] [Next Routine] [List of Routines]

     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)

## EPDE_PLOT_OVERVIEWS

[Previous Routine] [Next Routine] [List of Routines]

    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)
                not yet implemented
     quick_run - set this flag to reduce the resolution of t89/ttrace2equator (from 1 sec to 1 min)
     one_zone_only - set this keyword to only plot the first sci zone (this is a kluge for the pink plots)
     regularize - set this keyword to use the regularize keyword when calling elf_getspec

    TO DO:
     implement plots by sci zone only

(See projects/elfin/plots/epde_plot_overviews.pro)

## EPDE_PLOT_OVERVIEWS_SOLO

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      epde_plot_overviews_solo

    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)
                not yet implemented
     quick_run - set this flag to reduce the resolution of t89/ttrace2equator (from 1 sec to 1 min)
     one_zone_only - set this keyword to only plot the first sci zone (this is a kluge for the pink plots)
     regularize - set this keyword to use the regularize keyword when calling elf_getspec

    TO DO:
     implement plots by sci zone only

(See projects/elfin/plots/epde_plot_overviews_solo.pro)

## EPDE_PLOT_WIGRF_MULTISPEC_OVERVIEWS

[Previous Routine] [Next Routine] [List of Routines]

    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)

## EPDI_PLOT_OVERVIEWS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      epdi_plot_overviews

    PURPOSE:
     Loads EPDE and EPDI performs pitch angle determination and plotting of energy and pitch angle spectra
     Including precipitating and trapped spectra separately.
     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/epdi_plot_overviews.pro)

## FIND_INTERVAL

[Previous Routine] [Next Routine] [List of Routines]

    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)

## FIND_ORBITS

[Previous Routine] [Next Routine] [List of Routines]

    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)

## GET_ELF_SCIENCE_ZONE_START_END

[Previous Routine] [Next Routine] [List of Routines]

    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)

## GET_VEC_ANG

[Previous Routine] [Next Routine] [List of Routines]

    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)

## MAKEGIF[1]

[Previous Routine] [Next Routine] [List of Routines]

    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)

## OVALGET

[Previous Routine] [Next Routine] [List of Routines]

     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)

## PLOT_SCIENCE_ZONE_MLAT

[Previous Routine] [Next Routine] [List of Routines]

    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)

## WHERE_ARRAY

[Previous Routine] [List of Routines]

     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)