This page was created by the IDL library routine mk_html_help2.

Last modified: Mon Oct 31 12:42:20 2011.


Directory Listing of Routines


Routine Descriptions

PLOT_PART_SLICE2D

[Next Routine] [List of Routines]
Procedure: plot_part_slice2d

Purpose: Create plots for 2D particle slices.

Calling Sequence:
  Single slice
  plot_part_slice2d, part_slice, xgrid, ygrid, slice_info, $
                     nlines=nlines, olines=olines

  (IN DEVELOPMENT)
  Two slices - the second slice is plotted over the first
  plot_part_slice2d, part_slice, xgrid, ygrid, slice_info, $
                     o_part_slice, o_xgrid, o_ygrid, o_slice_info, $
                     nlines=nlines, olines=olines


Arguments:
 PART_SLICE: 2D array of values to plot 
 XGRID: X location of data points 
 YGRID: Y location of data points
 SLICE_INFO: structure passed out of thm_part_slice2d containing
             information for labels and range for plotting

(overplots - IN DEVELOPMENT)
 O_PART_SLICE: 2D array of values to overplot 
 O_XGRID: X location of overplot data points 
 O_YGRID: Y location of overplot data points
 O_SLICE_INFO: structure passed out of thm_part_slice2d containing
             information for labels and range for plotting
 
 
Other Parameters:
 RANGE: Two-element array specifying zaxis range (units vary)
 NLINES: Number of color contour levels to plot (default is 60)
 OLINES: Number of contour lines to plot (default is 0)

Keywords:
 LOGPLOT: Boolean indicating plot should be log-scaled (set by default)
 SUNDIR: Boolean to plot sun direction vector (set by default)
 ECIRCLE: Boolean to plot circle(s) designating min/max energy 
          from distribution (set by default)
 PLOTAXES: Boolean to plot zero axes (set by default)
 CLABELS: Boolean to annotate contour lines.
 SCALE: Numerical value to scale O_PART_SLICE by. 
 [XYZ]TICKS: Integer(s) specifying the number of ticks for each axis 
 CHARSIZE: Specifies character size of annotations (1 is normal)
 APRECISION: Integer specifying annotation precision (sig. figs.).
             Set to zero to truncate printed values to inegers.
 ASTYLE: Integer specifying annotation style:
         Set to 0 (default) for style to be chosen automatically. 
         Set to 1 for decimal annotations only ('0.0123') 
         Set to 2 for scientific notation only ('1.23e-2')
 

Created by Bryan Kerr
Largely modified by A. Flores

(See themis/spacecraft/particles/slices/plot_part_slice2d.pro)


THM_PART_DIST_ARRAY

[Previous Routine] [Next Routine] [List of Routines]
Procedure: thm_part_dist_array

Purpose: Returns and array of particle distributions for use by THM_PART_SLICE2D.

Details: This is basically a wrapper for THM_PART_DIST that will create an
         array of particle distribution structures sorted by increasing time.
         

Keywords:
 FORMAT: A string denoting the data that is desired: options are:
           'tha_peif': Full Esa mode data, ions, probe A
           'tha_peef': Full Esa mode data, electrons, probe A
           'tha_peir': Reduced Esa mode data, ions, probe A
           'tha_peer': Reduced Esa mode data, electrons, probe A
           'tha_peir': Burst Esa mode data, ions, probe A
           'tha_peer': Reduced Esa mode data, electrons, probe A
           'tha_psif': Full Sst mode data, ions, probe A
           'tha_psef': Full Sst mode data, electrons, probe A
           'tha_psir': Reduced Sst mode data, ions, probe A
           'tha_pser': Reduced Sst mode data, electrons, probe A
         For other probes, just replace 'tha' with the appropriate string,
         'thb', 'thc', 'thd', 'the'.  If this is not set, then the string is
         constructed from the type and probe keywords.
 TRANGE: Time range of interest (2 element array).
 TYPE: Four character string denoting the type of data that you need,
       e.g., 'peif' for full mode esa data.
 PROBE: The THEMIS probe, 'a','b','c','d','e'.
 MAG_DATA: Tplot variable containing magnetic field data that you want added
           to the dat structures.
 VEL_DATA: Tplot variable containing velocity data that you want added to dat
           structure under the tag name 'velocity'.  Overrides VEL_AUTO keyword.
           The velocity data will be intpolated to the cadence of the particle
           distributions.
 VEL_AUTO: Automatically calculates velocity at each time sample using V_3D.PRO
           and adds it to the dat structure with the tag name 'velocity'.

See Also: THM_PART_SLICD2D, THM_CRIB_PART_SLICE2D, THM_PART_MAKE_DIST,
          THM_PART_DIST_VELS, TINTERPOL_MXN, ADD_MAGF, V_3D

Created by Bryan Kerr

(See themis/spacecraft/particles/slices/thm_part_dist_array.pro)


THM_PART_DIST_VELS

[Previous Routine] [Next Routine] [List of Routines]
Procedure: thm_part_dist_vels

Purpose: Calculate bulk particle velocities from a structure array of particle
         distrubutions and store in a tplot variable.

Arguments:
  DIST_ARR: An array of data structures as returned by one of the get_th?_p???
            routines (or THM_PART_DIST_ARRAY).
  OUT_NAME: Name of tplot variable in which to store the velocities.

See Also: THM_PART_DIST_ARRAY, V_3D

Created by Bryan Kerr

(See themis/spacecraft/particles/slices/thm_part_dist_vels.pro)


THM_PART_SLICE2D

[Previous Routine] [Next Routine] [List of Routines]
Procedure: thm_part_slice2d

Purpose: Returns a 2-D slice of the 3-D THEMIS ESA/SST ion or electron distribution
         function.  The 2-D slice is returned via the PART_SLICE, XGRID, YGRID, and 
         SLICE_INFO keywords.
         
         This procedure works in conjunction with thm_part_dist_array.pro and 
         plot_part_slice2d.pro.  The corresponding crib is thm_crib_part_slice2d.pro 

   There are currently three methods of generating slices for plotting:

   2D Nearest Neighbor (default):
     A slice of data with user defined width is projected onto the slice plane 
     and interpolated onto a regular grid using the nearest neighbor method.  

   2D Interpolation (from thm_esa_slice2d):
     Datapoints within the specified theta or z-axis range are projected onto 
     the slice plane and linearly interpolated onto a regular 2d grid.

   3D Interpolation:
     The entire 3-dimensional distribution is linearly interpolated onto a 
     regular 3d grid and a this slice is extracted.  The slice will consist of
     up to resolution^2 datapoints from within 0.866/resolution of the total 
     velocity range along the normal. This method works best with dense data.
       Note: - Not all points within the aforemention range will be used.
             - Interpolation may occure across data gaps or areas with recorded zeroes
             - Higher resolution regridding will severely slow this method
    
     
    *X,Y-range values determined slightly differently for 2D Interpolation


Arguments:
 DATARRAY: An array of data structures as returned by one of the get_th?_p???
            routines (or thm_part_dist_array.pro).  The structure must have
            a magf field containing a three-component magnetic field vector.

Input Keywords:
 SLICE_TIME: Beginning of time window in seconds since Jan. 1, 1970.  If
             CENTER_TIME keyword set, then TIME is the center of the time widow
             specified by the TIMEWIN keyword.
 CENTER_TIME: Flag that, when set, centers the time window around the time 
              specified by SLICE_TIME keyword.
 TIMEWIN: Length in seconds over which to compute the slice.
 COORD: A string designating what coordinate system the slice will be based off.
        Default is 'DSL', but can also be 'GSE' or 'GSM'
 SLICE_ORIENT: (ignored for 2D interpolation) 
               [x, y, z, vel] A four-element array that specifies the
               orientation of the slice plane.  The first three elements
               specify the direction of the plane's normal vector.  The fourth
               element is the distance of the slice plane's center from the
               origin along the plane's normal vector in units of meters/sec.
               Default = [0,0,1,0]
 UNITS: A string designating the desired units ('Counts','DF','Rate','CRate',
        'Flux','EFlux','E2Flux','E3Flux') - (DF by default)
 RESOLUTION: A single integer specfying the resolution of each dimension of the
             slice (as well as the interpolated volume in the the 3d case).
 REGRID: A three element array specifying regrid dimensions in phi, theta, and 
         energy respectively. If set, all distributions' data will first be 
         spherically interpolated using the nearest neighbor method. For example  
         the default [32,16,128] will yield distributions with 32x16 points per 
         energy, and 128 energy bins). Increasing the regridding resolution will
         slow slice production, particularly if using 3D interpolation. 
 ROTATION: suggesting the x and y axis, which can be specified as the following:
   'BV': The x axis is parallel to B field; the bulk velocity defines the x-y plane. (DEFAULT)
   'BE': The x axis is parallel to B field; the B x V(bulk) vector defines the x-y plane.
   'xy'/'xyz': The x axis is V_x and the y axis is V_y.
   'xz': The x axis is V_x and the y axis is V_z.
   'yz': The x axis is V_y and the y axis is V_z.
   'xvel': The x axis is V_x; the y axis is defined by the bulk velocity. 
   'perp': The x axis is the bulk velocity projected onto the plane normal to the B field; y is B x V(bulk)
   'perp_xy'/'perp_xyz': Geometric xy coordinates projected onto the plane normal to the B field.
   'perp_xz': Geometric xz coordinates projected onto the plane normal to the B field.
   'perp_yz': Geometric yz coordinates projected onto the plane normal to the B field.
 ERANGE: Two element array specifying the energy range to be used
 SUBTRACT: Flag to subtract the bulk velocity before plot.  The exact quantity 
           to use can be specified in the call to thm_part_dist_array.
 SLICE_WIDTH: (2d nearest neighbor only)
              Specifies width of the slice in % of the total range
 SMOOTH: An odd integer >=3 specifing the width of the smoothing window in # 
         of points. Even entries will be incrimented, 0 and 1 are ignored.
 THETARANGE: (2D interpolation only)
             Angle range, in degrees [-90,90], used to calculate slice.
             Default is [-20,20], will override ZDIRRANGE. 
 ZDIRRANGE: (2D interpolation only)
            Z-Axis range, in km/s, used to calculate slice.
            Ignored if called with THETARANGE.

Output variables for plotting:
 PART_SLICE: The 2-D data array to be plotted (the slice).
 XGRID: Array of x-locations for the slice.
 YGRID: Array of y-locations for the slice.
 SLICE_INFO: Structure to be passed to plot_part_slice2d to determine plot labels.
      {
       probe: string containing the probe
       dist: string containing the type of distribution used
       coord: string describing the coordinate system used for the slice
       rot: string describing the user specified rotation (N/A for 2D interp)
       units: string describing the units
       twin: string describing the time window of the slice
       range: array containing the range of the un-interpolated data 
       erange: array containing the energy range used
       trange: array countaining the numerical time range
       ndists: number of distributions used
       qmass: factor for plotting [(J/eV) / particle mass]
       coord_m: Rotation matrix from original data's coordinates (DSL) to
                those specified by the COORD keyword.
       rot_m: Rotation matrix from the the specified coordinates to those 
            defined by ROTATION (column matrix of new coord's basis).
            (N/A for 2D interp)
       orient_m: Rotation matrix from the coordinates defined by ROTATION to 
                 the arbitrary coordinates defined by SLICE_ORIENT 
                 (column matrix of new coord's basis).
                 (N/A for 2D interp)
       }

CAVEATS: Due to IDL software constraints areas of no data are assigned zeros
         instead of NaNs. This yields a degeneracy between data gaps and 
         measured zeros for both plots and numerical data.
         (Such degeneracy would always exist in any logarithmic plot made
         with the contour procedure)

CREATED BY: Bryan Kerr based on Arjun Raj original thm_esa_slice2d.pro
            Modified by A. Flores

EXAMPLES:  see the crib file: thm_crib_part_slice2d.pro

(See themis/spacecraft/particles/slices/thm_part_slice2d.pro)


THM_PART_SLICE_EXTRACT

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

Procedure: thm_part_slice_extract

Purpose: Returns a 2-D slice of a scattered 3-D distribution along 
         the designated plane.  Points near the slice plane are 
         projected onto the plane and then interpolated onto a regular 
         grid using the nearest neighbor method.

Arguments:
 DATA: An array of N datapoints to be used.
 VECTORS: An array of N x 3 datapoints designating, respectively, 
          the x,y,z values for each point in DATA 
 RESOLUTION: The number of points along each dimention of the 
             interpolated slice

Input Keywords:
 CENTER: A vector designating the slice plane's center, default = [0,0,0]
 NORMAL: A vector designating the slice plane's normal, default = [0,0,1]
 XVEC: A vector whose projection into the slice plane will form its
       x-axis. The data's x-axis is used by default, if no projection 
       exists an error will be returned
 SLICE_WIDTH: The width of the slice given in % (of data range) 

Output Keywords:
 XGRID: Array of x-locations for the slice.
 YGRID: Array of y-locations for the slice.
 FAIL: This keyword will contain a message in the event of an error

(See themis/spacecraft/particles/slices/thm_part_slice_extract.pro)


THM_UI_SLICE2D

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  thm_ui_slice2d

PURPOSE:
  Front end window allowing user to create and view "2D" slices 
  of velocity distributions.

CALLING SEQUENCE:
  thm_ui_slice2d [, gui_ID=gui_ID [, historywin=historywin]]

INPUT:
  gui_id: group leader widget if opening from THEMIS GUI
  historywin: history window object if opening from THEMIS GUI
;
OUTPUT:
  N/A  

NOTES: For command line use see:
         plot_part_slice2d.pro
         thm_part_slice2d.pro
         thm_part_dist_array.pro
  

(See themis/spacecraft/particles/slices/thm_ui_slice2d.pro)


THM_UI_SLICE2D_BAR__DEFINE.PRO

[Previous Routine] [List of Routines]
NAME:
 thm_ui_slice2d_bar__define.pro

PURPOSE:
 Object created for the 2d slices interface. Allows scrolling back
 and forth over a temporal series of slices.

CALLING SEQUENCE:
 sb = obj_new('THM_UI_SLICE2D_BAR', parentID, xScreenSize, (windowStorage, loadedData, drawObject,) $
                                   statusbar=statusbar, value = 500, range = [0,1000])

ATTRIBUTES:
 id: slider widget's ID
 parent: parent widget's ID
 xsize: screen size, in pixels, of the slider bar
 range: the numerical integer range about which the slider can move (in sec), [0,1000] by default
 value: the current value of the slider, zero (fully left) in the absence of data

PUBLIC METHODS:
 getValue: Allows retrieval of value, range, and xsize
 setValue: Allows setting of value and xsize, mainly for the purpose of gui resize events
 update: (Will be called most often) Update procedure to be called any time changes have 
         been made.

NOTES:
 Created 4-02-10
 
 Behavior:
   
   

HISTORY:
 Initial version: 4-??-10

(See themis/spacecraft/particles/slices/thm_ui_slice2d_bar__define.pro)