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

Last modified: Wed Aug 27 18:18:07 2025.

# Directory Listing of Routines

# projects/maven/sta/l2analysis/general

- CONTOUR4D_EDIT
  Produces contour plots of energy-mass distributions from 4D data structures.
- MVN_STA_ANC_DETERMINE_SPICE_KERNELS
- MVN_STA_ANC_EPHEMERIS
- MVN_STA_BYTSCL2
- MVN_STA_CAC6_ENERGY_PEAK
- MVN_STA_CHECKFILESAVE
- MVN_STA_CK_CHECK
- MVN_STA_CNT_BKG_FLAG
- COLORBAR[1]
- MVN_STA_TRANSFORM_VELOCITY
- MVN_STA_CONVERT_VFRAME[1]
- MVN_STA_CONVERT_VFRAME[2]
- MVN_STA_CONVERT_VFRAME: BASED ON CONVERT_VFRAME, WHICH IS FOR ELECTRONS. MVN_STA_CONVERT_VFRAME IS MODIFIED FOR IONS. SOME
- MVN_STA_CTIME[1]
- MVN_STA_CTIME[2]
  Interactively uses the cursor to select a time (or times)
- MVN_STA_ENERGY_PEAK
- MVN_STA_FRAME_TRANSFORM
- MVN_STA_GET_COUNT_RATE
- MVN_STA_GET_COUNTS
- MVN_STA_GET_MRANGE
- MVN_STA_MAKEDIR
- MVN_STA_SCALE_ARRAY

# Routine Descriptions

## COLORBAR[1]

[Next Routine] [List of Routines]

     NAME:
       COLORBAR

     PURPOSE:

           The purpose of this routine is to add a color bar to the current
           graphics window.

     AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com/

     CATEGORY:

           Graphics, Widgets.

     CALLING SEQUENCE:

           COLORBAR

     INPUTS:

           None.

     KEYWORD PARAMETERS:

           BOTTOM:       The lowest color index of the colors to be loaded in
                         the bar.

           CHARSIZE:     The character size of the color bar annotations. Default is 1.0.

           COLOR:        The color index of the bar outline and characters. Default
                         is !P.Color..

           DIVISIONS:     The number of divisions to divide the bar into. There will
                         be (divisions + 1) annotations. The default is 6.

           FONT:         Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.

           FORMAT:       The format of the bar annotations. Default is '(I5)'.

           INVERTCOLORS: Setting this keyword inverts the colors in the color bar.

           MAXRANGE:     The maximum data value for the bar annotation. Default is
                         NCOLORS.

           MINRANGE:     The minimum data value for the bar annotation. Default is 0.

           MINOR:        The number of minor tick divisions. Default is 2.

           NCOLORS:      This is the number of colors in the color bar.

           POSITION:     A four-element array of normalized coordinates in the same
                         form as the POSITION keyword on a plot. Default is
                         [0.88, 0.10, 0.95, 0.90] for a vertical bar and
                         [0.10, 0.88, 0.90, 0.95] for a horizontal bar.
    ;
           RANGE:        A two-element vector of the form [min, max]. Provides an
                         alternative way of setting the MINRANGE and MAXRANGE keywords.

           RIGHT:        This puts the labels on the right-hand side of a vertical
                         color bar. It applies only to vertical color bars.

           TICKNAMES:    A string array of names or values for the tick marks.

           TITLE:        This is title for the color bar. The default is to have
                         no title.

           TOP:          This puts the labels on top of the bar rather than under it.
                         The keyword only applies if a horizontal color bar is rendered.

           VERTICAL:     Setting this keyword give a vertical color bar. The default
                         is a horizontal color bar.

     COMMON BLOCKS:

           None.

     SIDE EFFECTS:

           Color bar is drawn in the current graphics window.

     RESTRICTIONS:

           The number of colors available on the display device (not the
           PostScript device) is used unless the NCOLORS keyword is used.

     EXAMPLE:

           To display a horizontal color bar above a contour plot, type:

           LOADCT, 5, NCOLORS=100
           CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
              C_COLORS=INDGEN(25)*4, NLEVELS=25
           COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]

     MODIFICATION HISTORY:

           Written by: David W. Fanning, 10 JUNE 96.
           10/27/96: Added the ability to send output to PostScript. DWF
           11/4/96: Substantially rewritten to go to screen or PostScript
               file without having to know much about the PostScript device
               or even what the current graphics device is. DWF
           1/27/97: Added the RIGHT and TOP keywords. Also modified the
                way the TITLE keyword works. DWF
           7/15/97: Fixed a problem some machines have with plots that have
                no valid data range in them. DWF
           12/5/98: Fixed a problem in how the colorbar image is created that
                seemed to tickle a bug in some versions of IDL. DWF.
           1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
           3/30/99: Modified a few of the defaults. DWF.
           3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
           3/30/99: Added the RANGE keyword. DWF.
           3/30/99: Added FONT keyword. DWF
           5/6/99: Many modifications to defaults. DWF.
           5/6/99: Removed PSCOLOR keyword. DWF.
           5/6/99: Improved error handling on position coordinates. DWF.
           5/6/99. Added MINOR keyword. DWF.
           5/6/99: Set Device, Decomposed=0 if necessary. DWF.
           2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
           8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
           8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
           10/10/99. Modified the program so that current plot and map coordinates are
                saved and restored after the colorbar is drawn. DWF.
           3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
           4/28/00. Made !P.Font default value for FONT keyword. DWF.
           9/26/00. Made the code more general for scalable pixel devices. DWF.
           1/16/01. Added INVERTCOLORS keyword. DWF.
           5/11/04. Added TICKNAME keyword. DWF.

(See projects/maven/sta/l2analysis/general/mvn_sta_colorbar.pro)

## CONTOUR4D_EDIT

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

    .r /Users/cmfowler/IDL/STATIC_routines/Generic/contour4d_edit.pro
    Original routine from Jim McFadden. CMF edited some keywords, and now uses it in plot_c6, etc.

    PROCEDURE: contour4d,data
    PURPOSE:
     Produces contour plots of energy-mass distributions from 4D data structures.
    INPUTS:
       data   - structure containing 4d data  (obtained from get_mvn_?() routine)
       e.g. "get_mvn_c6, get_mvn_ce, etc."
    KEYWORDS:
     LIMITS - A structure containing limits and display options.
                 see: "options", "xlim" and "ylim", to change limits
     UNITS  - convert to given data units before plotting
     TITLE - Title to be plotted,
       - set title=' ' for NO Title!
       - set title='1' for just the time in the title
     XTITLE - xtitle to be plotted,
       - set xtitle=' ' for NO xtitle!, default determined by VEL keyword
     YTITLE - ytitle to be plotted,
       - set ytitle=' ' for NO ytitle!, default=data.units_name
     ZTITLE - ztitle to be plotted,
       - set ztitle=' ' for NO ytitle!, default='Log!D10!N('+y_units+')'
     RETRACE - set to number of retrace steps removed,
       - default set to 0
     VEL - If set, x-axis is velocity km/s  -- Default is Energy (eV)

     NCONT - Number of contours to be plotted, default = 8
     LEVELS - Explicit contour levels, default levels spaced down
              from max by 10^.5
     FILL - If set, contours are filled with solid color or gray scale
     BW - If set, contours are white, no affect on fill plots
     PURE - If set, 6 pure colors are cycled through for levels
     ROTATE - Exchanges x and y axes for non-polar plots
     LABEL - Labels the contour levels
           XMARGIN - Change xmargin from default
     YMARGIN - Change ymargin from default
     POINTS - adds data points to plot
    top_c, bottom_c: top and bottom indices to use in the colorbar. Default if not set is bottom=0, top=254.
    See "conv_units" to change units.

    CREATED BY:  J. McFadden  14-02-07
    FILE:  contour4d.pro
    VERSION 1.
    MODIFICATIONS:

(See projects/maven/sta/l2analysis/general/contour4d_edit.pro)

## MVN_STA_ANC_DETERMINE_SPICE_KERNELS

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

    Determine whether SPICE kernels are loaded in to IDL memory, and if so, which ones. Returns a data structure with this information in.

    For testing:
    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_anc_determine_spice_kernels.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_anc_determine_spice_kernels.pro)

## MVN_STA_ANC_EPHEMERIS

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

    Routine based on CMF mvn_sta_anc_spacecraft.pro, to obtain MAVEN sc ephemeris info. This routine is lighter than the LPW version - it
    only calculates a handful of parameters, which can be specified as keywords. This makes the routine quicker. The routine also uses kernels
    loaded in by mvn_spice_kerneles(/load), rather than mvn_sta_anc_get_spice_kernels.pro. This reduces some complexities.

    For checking kernel coverage, this routine requires the full directories to the SPICE kernels loaded. These can be input as a keyword,
    or are loaded automatically within the routine. Timespan must be set for this to happen.

    The routine will check whether the SPICE kernels cover each of the requested timestamps, and should gracefully use NaNs if coverage is
    not present. There are two tplot flag variables produced for checking SPICE coverage (see below).

    INPUTS:

    unix_in: double precision UNIX timestamps. Ephemeris data are calculated at these values.

    KEYWORDS / OUTPUTS:
    spicekernels: if you have already loaded SPICE using kk=mvn_spice_kernels(/load), set spicekernels=kk. If you haven't run SPICE,
                  don't set this keyword, and this routine will run it for you.

    Set /qc to use qualcolors (M. Chaffins colorbar software). If not set, routine assumes IDL color table 39. Tplot colors can be changed
           later by the user as well.

    The following flag variables are produced showing which timestamps are covered by SPICE (there can sometimes be gaps in the SPICE kernels):

    mvn_sta_anc_ck_flag: 0 means MAVEN pointing information is available, 1 means it is not.

    mvn_st_anc_spk_flag: 0 means MAVEN position information is available, 1 means it is not.

    The following keywords produce tplot variable outputs for the requested parameters, at the time steps sent in under "unix_in":

    Set /mvn_pos to generate MAVENs position in the MSO frame. The output variable has size [N,4], where N is the same length as unix_in,
       and the four rows are: X, Y, Z, total. Units of Mars radii.

    Set /mvn_vel to generate MAVENs velocity in the MSO frame. The output variable has size [N,4], where N is the same length as unix_in,
       and the four rows are: X, Y, Z, total. Note that mvn_pos and mvn_vel are generated from the same SPICE call, so requesting one will also
       generate the other. Units of km/s.

    Set /mvn_alt to generate MAVENs altitude in the IAU frame. This represents Mars as the flattened ellipsoid. Units of km.

    Set /mvn_lonlat to generate MAVENs altitude in east longitude planetary frame. Size is [N,2], where the top row is longitude (0 => 360) and
       bottom row is latitude (90 (north) => -90 (south)). Units of degrees. This parameter requires pos_mso and vel_mso to also be generated.

    Set /mvn_sza to generate MAVEN SZA values, based on its MSO position at Mars. If set, /mvn_pos is also set, to obtain the required data.
       Calculated SZA are all positive. If you wish to split up dawn versus dusk, use the position tplot variable to find times where Ymso is
       negative (dawn) versus positive (dusk).

    Set /mars_ls to generate Mars' Ls value about the Sun. Units of degrees.

    NOTES:
    1 Mars radius = 3376.km in all conversion carried out here.
    This routine will not clear SPICE kernels from IDL memory after it runs, regardless of whether you set the spicekernels keyword or not.

    EGS:
    ## Generate MAVEN position, without loading in SPICE prior to call:
    timespan, '2017-01-01', 1.
    get_data, 'mvn_sta_c6_E', data=dd   ;get STATIC timestamps
    mvn_sta_anc_ephemeris, dd.x, /mvn_pos   ;generate ephemeris data (routine calls SPICE internally).

    ## Generate MAVEN position after calling SPICE prior to call:
    timespan, '2017-01-01', 1.
    kk = mvn_spice_kernels(/load)
    get_data, 'mvn_sta_c6_E', data=dd
    mvn_sta_anc_ephemeris, dd.x, spicekernels=kk, /mvn_pos

    Author: CM Fowler (cmfowler@berkeley.edu). First written 2019-11-08.

(See projects/maven/sta/l2analysis/general/mvn_sta_anc_ephemeris.pro)

## MVN_STA_BYTSCL2

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

    CMF bytscl routine that includes a bottom color bar indice keyword.

    INPUTS:
    data: array to be scaled.

    minv, maxv: min and max data values to be considered. Any values below min are set to min; any above max are set to max.

    top, bottom: top and bottom color bar indices to be used. MAx range is 0 - 255 (the default). Top > bottom.

    Routine ignores NaNs in data.

    NOTES:
    data must contain at least two real numbers.

    .r /Users/cmfowler/IDL/my_routines/mvn_sta_bytscl2.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_bytscl2.pro)

## MVN_STA_CAC6_ENERGY_PEAK

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

    Routine uses c6 and c8 data to produce two tplot variable products. The routine finds the peak eflux bin at each timestep, and produces:

    mvn_sta_ca_anode_perc: three rows: top: the % of eflux in the peak eflux bin; middle: the % of eflux in the top two eflux bins;
                           bottom: the % of eflux in the top three eflux bins. This is a function of energy only, eflux is summed over all masses.

    mvn_sta_c6_energypeak: the energy (in eV) that the peak eflux lies in at each timestep. Again, eflux is summed over all masses.

    mvn_sta_ca_anode_peak: the anode INDEX that the peak energy flux lies in. I believe STATIC anodes start at zero as well.

    trange: [a,b]: UNIX double start and stop times to calculate parameters over. If not set, entire time range available is used.

    Routine requires ca and c6 data to be loaded into tplot (mvn_sta_ca_A and mvn_sta_c6_E).

    EG:
    timespan, '2019-01-01', 1.
    mvn_sta_l2_load, sta_apid=['c6', 'ca']
    mvn_sta_l2_tplot
    mvn_sta_c6_energy_peak

    Testing only:
    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_cac6_energy_peak.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_cac6_energy_peak.pro)

## MVN_STA_CHECKFILESAVE

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

    Check if a file is saved; print answer to terminal.

    fname: string: full directory and filename including extension.

(See projects/maven/sta/l2analysis/general/mvn_sta_checkfilesave.pro)

## MVN_STA_CK_CHECK

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

    Routine to check whether SPICE kernels exist so that pointing information for STATIC can be converted from instrument to MSO
    frame. This is needed for, eg, the sta flow routines.

    Code written using help from Boris Semenov from JPL NASA.

    Give this routine an array of UNIX times; the routine uses SPICE to check whether there is ck and spk coverage for each timestamp.
    The calls to SPICE are all hard coded, so the only inputs are the timestamps required.

    The tplot variable produced will have value zero if kernels are present, or 1 if flagged as not present. For 1, SPICE cannot be used to
    get STATIC pointing in the MSO Frame.
       mvn_sta_ck_check  :  0 = ok, 1 = flag - no SPICE coverage for this timestep.

    INPUTS:
    unix_in: UNIX double precision array of timetamps. The routine will check SPICE coverage at each timestep.

       NOTES ON INPUTS: SPICE information for MAVEN is found at https://lasp.colorado.edu/maven/sdc/public/data/anc/spice/fk/maven_v05.tf.
                        the SPICE coverage routines will only work for frames and objects that are CK based (ie can change over time).
                        each MAVEN object is described in the above weblink, saying whether it's ck based or not. All frames etc are hard
                        coded here, so the user doesn't need to worry about this, but it's useful if you're using SPICE for other things.

    OUTPUTS:
    success: 0: routine failed to make the checkes - it should throw an error if this happens.
             1: checks completed.

    tplot variables: mvn_lpw_anc_ck_flag: flag for s/c pointing for each timestep, 1 = no data, 0 = data present
                     mvn_lpw_anc_spk_flag: flag for s/c position for each timestep, as above.

    OPTIONS:
    Set /loadspice to load the SPICE kernels using mvn_spice_kernels(/load). This will assume timespan is already set.

    Set /clearspice to remove SPICE kernels from IDL memory once checking is complete. If not set, routine will leave them in IDL memory.

    EGS:
    time = dindgen(86400)+time_double('2014-12-08')  ;make a UNIX time array, or use get_data to grab a time array...
    timespan, '2014-12-08', 1.
    kk = mvn_spice_kernels(/load)   ;find SPICE kernels and load into IDL.
    mvn_sta_ck_check, time
                                             ;check ck and spk coverage, for MAVENs position in the MSO frame.
                                             ;As of 2019-07-31, there is ~an hour of missing ck coverage for this date, if
                                             ;you want to check the code is working.

    NOTES:
    CMF worked out by hand how many MAVEN clock ticks represent one second: 65535.964843750000. This is hard coded below.
    2020-01-14: CMF: routine will crash if only 1 timestamp input. I need to fix this.

    VERSIONS:
    Created: 2019-08-01: Chris Fowler (cmfowler@berkeley.edu): code copied from mvn_lpw_anc_spacecraft.pro to be stand alone.

    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_ck_check.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_ck_check.pro)

## MVN_STA_CNT_BKG_FLAG

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

    Routine extracts bkg counts and counts for a specified sta_apid and mass range. These are each saved into separate tplot variables.
    The routine then flags when counts ~< bkg, for the specified threshold.

    Flag=0 means ok, flag=1 means background counts are significant compared to counts.

    INPUTS:
    massrange: [a,b]: floats: AMU mass range to look at.

    sta_apid: string: 'c6', 'd1', etc. Apid to look at.

    KEYWORDS:
    trange: [a,b] : double UNIX time: time range to look at. If not set, routine looks at full time range in the relevant common block.
    tplotname: string: the base tplotname to use for the output variables. Variables will have the format:
               tplotname_tot_cnts - total dat.cnts
               tplotname_bkg_cnts - total dat.bkg
               tplotname_flag_cnts - 0 if dat.cnts is statistically significant compared to dat.bkg; 1 if this is not the case.
               If not set, tplotname will be set to 'sta_cnts'.

    REQUIREMENTS:
    Load STATIC data into common blocks before hand.

    EXAMPLES:
    timespan, '2020-01-01', 1.
    mvn_sta_l2_load, sta_apid='c6'
    mvn_sta_cnt_bkg_flag, massrange=[12., 20.], sta_apid='c6', tplotname='mvn_sta_c6'

    For testing:
    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_cnt_bkg_flag.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_cnt_bkg_flag.pro)

## MVN_STA_CONVERT_VFRAME: BASED ON CONVERT_VFRAME, WHICH IS FOR ELECTRONS. MVN_STA_CONVERT_VFRAME IS MODIFIED FOR IONS. SOME

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

    NAME:
    	mvn_sta_convert_vframe: based on convert_vframe, which is for electrons. mvn_sta_convert_vframe is modified for ions. Some
    	of the fancy bells and whistles have been removed to keep things simple.

    	Notes: the routine will convert the input data structure to units of df to do the frame conversion. The routine will then
    	convert units back to the inputs ones on output.

    FUNCTION:  convert_vframe ,  dat,  velocity
    PURPOSE:   Change velocity frames
    INPUT:
      tdata: 3d STATIC data structure, from eg mvn_sta_get_d0() (must be ce, cf, d0, d1)
      velocity: velocity vector in the STATIC isntrument frame, to be used in the frame transformation [VX,VY,VZ].
                This can be the spacecraft velocity, the plasma flow velocity, or both combined. Units of km/s.
    OUTPUT:  3d data structure.  Data will be in the coordinate frame based upon the input vframe.
             - The Mars frame if spacecraft velocity is used.
             - The plasma frame if spacecraft velocity and plasma bulk flow velocity are used.
        (frame transform is done in units of df, but the output is put back to the input units)

    KEYWORDS:

    CREATED BY:	Davin Larson, edited by CMF

(See projects/maven/sta/l2analysis/general/mvn_sta_convert_vframe.pro)

## MVN_STA_CONVERT_VFRAME[1]

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

    Calculate ion velocity using mass and energy.

    INPUTS:
    energy: data.energy array from a STATIC data structure. Units of eV.
    mass: data.mass_arr from a STATIC data structure. Units of AMU. Matching dimensions to energy.

    OUTPUT:
    Total velocity (from E=0.5*m*v^2) in the same array dimension as data.energy. Units of km/s.

    KEYWORDS:
    reverse: if set, provide velocities as the "energy" input, and routine will return the corresponding energies in eV. In this
             case, input velocities in units of km/s.

(See projects/maven/sta/l2analysis/general/mvn_sta_convert_vframe.pro)

## MVN_STA_CONVERT_VFRAME[2]

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

    PROCEDURE:   transform_velocity,  vel, theta, phi,  deltav
    PURPOSE:  used by the convert_vframe routine to transform arrays of velocity
        thetas and phis by the offset deltav
    INPUT:
      vel:  array of velocities
      theta: array of theta values
      phi:   array of phi values
      deltav: [vx,vy,vz]  (transformation velocity)
    KEYWORDS:
    	vx,vy,vz:	return vx,vy,vz separately as well as in vector form

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	2020-03-26 CMF

(See projects/maven/sta/l2analysis/general/mvn_sta_convert_vframe.pro)

## MVN_STA_CTIME[1]

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

    This is the CMF edited version of the ctime routine; when routine_name is used, cal_procedure has been replaced by execute, so that
    keywords can be passed to this routine within ctime. CMF has changed the names of all sub routines in this .pro file, so that they are
    not considered duplicates to those in the original ctime.pro routine.

    NOTES:
    To feed in the timestep at the cursor in the tplot window, set the time variable to t.

    For example, if mvn_imf_angle has a keyword tt, which is the timestep, set it to t. Note that the entire call, inputs and keywords,
    must be in a string:

    EG:
    mvn_sta_ctime, tr, routine_name='mvn_sta_fov_snap, tpnum=0, wnum=2, trange=t, sta_apid="d1", mrange=[12., 20.]'

    Make sure I have a stop in the sub-routine, as ctime doesn't - it will go into an infinite loop if not.

(See projects/maven/sta/l2analysis/general/mvn_sta_ctime.pro)

## MVN_STA_CTIME[2]

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

    PROCEDURE:   ctime,time,y,z
    INPUT:
        time: Named variable in which to return the selected time (seconds
              since 1970)
        y:    Named variable in which to return the y value
        z:    Named variable in which to return the z value
    KEYWORDS:
        PROMPT:  Optional prompt string
        NPOINTS: Max number of points to return
        PSYM:    If set to a psym number, the cooresponding psym is plotted at
                 selected points
        SILENT:  Do not print data point information
        PANEL:   Set to a named variable to return an array of tplot panel numbers
                 coresponding to the variables points were chosen from.
        XNORM:   Set to a named variable to return an array of normalized x
                 coordinates of each button-click.
        YNORM:   Set to a named variable to return an array of normalized y
                 coordinates of each button-click.
        APPEND:  If set, points are appended to the input arrays,
                 instead of overwriting the old values.
        VNAME:   Set to a named variable to return an array of tplot variable names,
                 cooresponding to the variables points were chosen from.
        COLOR:   An alternative color for the crosshairs.  0<=color<=!d.n_colors-1
        SLEEP:   Sleep time (seconds) between polling the cursor for events.
                 Defaults to 0.1 seconds.  Increasing SLEEP will slow ctime down,
                 but will prevent ctime from monopolizing cpu time.
        INDS:    Return the indices into the data arrays for the points nearest the
                 recorded times to this named variable.
        VINDS:   Return the second dimension of the v or y array.
                 Thus  TIME(i) is  data.x(INDS(i))           and
                       Y(i)    is  data.y(INDS(i),VINDS(i))  and
                       V(i)    is  data.v(VINDS(i)) or data.v(INDS(i),VINDS(i))
                 for get_data,VNAME(i),data=data,INDS=INDS,VINDS=VINDS
        EXACT:   Get the time,y, and (if applicable) z values from the data
                 arrays.  If on a multi-line plot, get the value from the line
                 closest to the cursor along y.
        NOSHOW:  Do not show the plot window.
        DEBUG:   Avoids default error handling.  Useful for debugging.
        DAYS, HOURS, MINUTES, SECONDS: Sets time granularity.  For example
                 with MINUTES=1, CTIME will find nearest minute to cursor
                 position.
    PURPOSE:
       Interactively uses the cursor to select a time (or times)
    NOTES:       If you use the keyword EXACT, ctime may run noticeablly slower.
             Reduce the number of time you cross panels, especially with
             tplots of large data sets.
    Mac Os users:
             You might need to set preferences on your X11 display:
             Within X11 program go to X11 -> preferences -> Windows: check box labeled "Click=through Inactive Windows"
             also:                    X11 -> preferences -> Input:  check box labeled "Emulate three button mouse"
    SEE ALSO:  "crosshairs"

    CREATED BY:    Davin Larson & Frank Marcoline   ;### edited by CMF
    LAST MODIFICATION:     @(#)ctime.pro   1.44 02/11/01
    WARNING!
      If ctime crashes, you may need to call:
      IDL> device,set_graph=3,/cursor_crosshair

(See projects/maven/sta/l2analysis/general/mvn_sta_ctime.pro)

## MVN_STA_ENERGY_PEAK

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

    Routine uses an apid data to produce a tplot variable containing the energy of the bin that the peak eflux is in at each timestep.
    Mass keyword can be set.

    mvn_sta_[apid]_energypeak: the energy (in eV) that the peak eflux lies in at each timestep.

    trange: [a,b]: UNIX double start and stop times to calculate parameters over. If not set, entire time range available is used.

    mrange: AMU mass range [a,b]. Default is all masses [0, 50] if not set.
    m_int: assumed mass, default is average of mrange if mrange is set and m_int is not. If mrange is not set, m_int=32. Note, I don't think
           this matters for this routine.

    sta_apid: string: STATIC apid to use. Default is c6 if not set.

    output: the output data as a named variable.

    Set /scpot to correct peak energy for the spacecraft potential. This routine assumes that mvn_scpot has been run, and will use these values.
       If this routine has not been run, it will be run automatically.
       mvn_scpot will be run based on the current timespan set, so ensure this covers the date range you require.

    EG:
    timespan, '2019-01-01', 1.
    mvn_sta_l2_load, sta_apid=['c6', 'ca']
    mvn_sta_l2_tplot
    mvn_sta_c6_energy_peak

    Testing only:
    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_energy_peak.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_energy_peak.pro)

## MVN_STA_FRAME_TRANSFORM

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

    Routine that can be used to subtract the MAVEN spacecraft velocity, and/or plasma flow velocity, from a STATIC data structure,
    to transform to a new reference frame.

    One can input the spacecraft velocity vector and/or plasma flow velocity, which will be subtracted from the data structure. This
    routine can also calculate the spacecraft velocity vector using SPICE, but it will not calculate the plasma flow vector, as this
    requires assumptions about the dominant species, whether multiple populations exist, etc, that must be made by the user.

    INPUTS:
    ddd: STATIC data structure for a single timestamp. Obtained by using e.g. dat=mvn_sta_get_c6()

    KEYWORDS:
    sc_vector: float: 3D vector containing the spacecraft velocity vectory in the MSO coordinate system (known as "MAVEN_MSO"
               in SPICE). This is the spacecraft velocity that will be used to transform to the local frame. If not set, this routine
               will calculate this vector using the timestamp in the input ddd STATIC data structure. One can also set sc_vector=1,
               and this routine will calculate sc_vector for you using SPICE (you must have set timespan beforehand though). sc_vector
               must have units of km/s.

    flow_vector: float: 3D vector containing the plasma flow vector in the MSO coordinate system (known as "MAVEN_MSO" in SPICE).
                 if set, this vector will be subtracted from the STATIC data, transforming the data to the plasma rest frame.
                 flow_vector must have units of km/s.

    scpot: float: force the spacecraft potential to this value (units of eV). If not set, use the default value in the STATIC data
                  structures (determined from the STATIC data). IT IS STRONGLY RECOMMENDED that you use the default value.

    success: set this keyword to a variable. On return, 0 = routine was not successful; 1 = it was.

    CAVEATS:

(See projects/maven/sta/l2analysis/general/mvn_sta_frame_transform.pro)

## MVN_STA_GET_COUNTS

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

    Get total count rate for STATIC apid, trange and mass range. Return the result as an IDL data structure consisting of
       result = {x: timestamps, y: count rate for the specified apid and mass range}.

    INPUTS:
    sta_apid: string: apid: eg 'c6'. Default is 'c6' if not set.

    trange: [a,b]: UNIX double time range to get count rates between. Default is entire common block if not set.

    massrange: [a,b]: calculate count rate for this AMU mass range. If not specified, all masses are included.

    species: string: specify which mass ranges to use using default settings: 'h', 'he', 'o', 'o2', 'co2'.

    tstore: set /tstore to store the result as a tplot variable. Note, this keyword can only be set if the species keyword
            is also set (to simplify tplot variable naming). The output tplot variable will have the form
            'mvn_sta_'+sta_apid+'_'+species+'_tot_counts', eg mvn_sta_c6_o_tot_counts.

    OUTPUTS:
    result = {x: timestamps, y: count rate for the specified apid and mass range}

    For testing:
    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_get_counts.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_get_counts.pro)

## MVN_STA_GET_COUNT_RATE

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

    Get counts for a specified STATIC apid, mass and energy range, and plot in tplot.

    INPUTS:
    trange: double array: [a,b]: time range over which to get count rate. If not set, full time range available is used.
    sta_apid: string, eg 'c6' - STATIC apid to use. Must be set.
    mrange: float array: [a,b]: mass range in AMU. IF not set, default [0., 60.] is set (all masses).
    erange: float array: [a,b]: energy range in eV. If not set, default [0., 1E6] is set (all energies).
    species: string: 'h', 'he', 'o', 'o2', 'co2': use the default mrange values for this species. Overwrites mrange if both are set.
    tplotname: string: the name to give the created tplot variable that contains the number counts at each timestep. The default name if
               not set is "mvn_sta_cnts_m[A,B]_e[C,D]", where A,B and C,D are the mass and energy ranges respectively.

    NOTES:
    Routine doesn't yet distinguish angle, but it could do...
    For apids that don't have mass resolution (eg c8), dat.nmass = 1. In these cases, the mrange and species keywords are ignored
    and all counts are returned. Energy is still filtered for.

    You must load STATIC data for the requested apid into common blocks using mvn_sta_l2_load, sta_apid='c6'.

    .r /Users/cmfowler/IDL/STATIC_routines/Generic/mvn_sta_get_count_rate.pro

(See projects/maven/sta/l2analysis/general/mvn_sta_get_count_rate.pro)

## MVN_STA_GET_MRANGE

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

    Hard code mass ranges for the key ions. These are what Jim uses. Returns a structures for each major mass (H+, He+, O+, O2+, CO2+).
    Masse ranges are not necessarily symmetric - remember to m_int keywords where needed.

(See projects/maven/sta/l2analysis/general/mvn_sta_get_mrange.pro)

## MVN_STA_MAKEDIR

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

    Routine for STATIC L3 data processing. Create a new directory if the requested one is not present. Directory will have the format

    basedir/year/month/

    Where baserdir is the base directory and must already be present. Year and month sub folders are then checked for, and created
    if not present.

    Current setting is to use

    file_mkdir, checkdir
    file_chmod, '775'o, checkdir
    spawn, 'chgrp maven '+checkdir  ;via keyword /group

    To set permissions and group settings.

    INPUTS:
    basedir: string: baser directory that must already be present (you must include the final '/')

    year: string: eg '2015'
    month: string, eg '03' or '11'. Note, month must be two characters, so months < 10 must have 'zero' as the first character.

    KEYWORDS:
    set /group to also set the MAVEN group permission on any created folder. Default is to not do this.

    EXAMPLE:
    mvn_sta_makedir, '/users/user/data/', '2020', '01'   ;NOTE: you must include the final '/' in basedir.

(See projects/maven/sta/l2analysis/general/mvn_sta_makedir.pro)

## MVN_STA_SCALE_ARRAY

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

    Input a mxn array. Rescale it to a larger set of pixels, for plotting using tv.

    arrayin: data array to be up scaled [mxn]
    factor: the scaling factor by which to multiply arrayin. Must be an integer. Eg, if input array is [4x16], with factor=2,
            the output array will be 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.

    e.g.
    array1 = fltarr(4,8)
    mvn_sta_scale_array, array1, 2, output=array2

(See projects/maven/sta/l2analysis/general/mvn_sta_scale_array.pro)

## MVN_STA_TRANSFORM_VELOCITY

[Previous Routine] [List of Routines]

    NAME:
    	mvn_sta_transform_velocity

    	NOTES: 2020-03-26: The routine converts the STATIC energy table to velocities, using the mass value in the data structure. The routine then
    	calculates the vx, vy and vz components of each energy step, in the STATIC instrument frame. The sc velocity components (vx, vy, vz) are then
    	subtracted from these. The routine then re-calculates phi and theta, so that "rammed ions" in the ram direction are moved to the back end of the
    	instrument, once the sc velocity is accounted for. The total velocity is then re-calculated for each energy step. This then means that the minimum
    	velocity obseved in the RAM direction is the (spacecraft velocity - min original energy table). In the anti-ram direction, the minimum velocity is
    	(spacecraft velocity + min original energy table).
    	This means that instead of the total velocity descending each sweep, there is a minimum for the RAM direction, and the velocity increases
    	again at the lowest energies. The velocities remain descending in the anti-ram direction, where the sc velocity acts to "increase" the energy
    	of observed ions. This can cause weird things when plotting, because plots typically compress across the phi and theta directions, leading to
    	weird looking energy tables.

    	Notes:
    	This is based on convert_vframe, which is written for electrons. This routine will work for ions, and will use the data.mass_arr
    	structure when calculating velocities so that they are mass dependent.

    	Note - for the above case when the sc velocity is greater than the ion energy (eg at periapsis), this code should be not be used
    	- uncertainties are large.

    EXAMPLE:

(See projects/maven/sta/l2analysis/general/mvn_sta_convert_vframe.pro)