Directory Listing of Routines

themis/state/cotrans

THM_COTRANS
THM_FAC_MATRIX_MAKE
THM_GSM2LMN_WRAP
Wrapper transforms THEMIS-generated vector field from GSM to LMN (boundary-normal)

Routine Descriptions

THM_COTRANS

Procedure: thm_cotrans
Purpose: Transform between various THEMIS and geophysical coordinate systems
keywords:
probe = Probe name. The default is 'all', i.e., transform data for all
available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be transformed, can take any of the values
allowed for datatype for the various thm_load routines. You
can use wildcards like ? and [lh].
'all' is not accepted. You can use '*', but you may get unexpected
results if you are using suffixes.
in_coord = 'spg', 'ssl', 'dsl', 'gse', 'gsm','sm', 'gei','geo', 'sse' or 'sel'
coordinate system of input.
This keyword is optional if the dlimits.data_att.coord_sys attribute
is present for the tplot variable, and if present, it must match
the value of that attribute. See cotrans_set_coord,
cotrans_get_coord
out_coord = 'spg', 'ssl', 'dsl', 'gse', 'gsm', 'sm', 'gei','geo', 'sse' or 'sel'
coordinate system of output. This keyword is optional if
out_suffix is specified and last 3 characters of suffix specify
the output coordinate system.
in_suffix = optional suffix needed to generate the input data quantity name:
'th'+probe+'_'datatype+in_suffix
out_suffix = optional suffix to add to output data quantity name. If
in_suffix is present, then in_suffix will be replaced by out_suffix
in the output data quantity name.
valid_names:return valid coordinate system names in named varibles supplied to
in_coord and/or out_coord keywords.
support_suffix: if support_data is loaded with a suffix you can
specify it here

out_vars: return a list of the names of any transformed variables

ignore_dlimits: set this keyword to true so that an error will not
be produced if the internal label of the coordinate system clashed
with the user provided coordinate system.
interpolate_state: use interpolation on 1-minute state CDF spinper/spinphase
samples for despinning instead of spin model

no_update_labels: Set this keyword if you want the routine to not update the labels automatically

Optional Positional Parameters:
in_name Name(s) of input tplot variable(s) (or glob patern)
(space-separated list or array of strings.). If the in_name
parameter is provided, the probe and datatype
keywords will be ignored. However, if the input name
is not of format 'th[a-e]_*', use the probe keyword to indicate
which probe's state data should be used for each input variable.
out_name Name(s) of output tplot variable(s). glob patterns not accepted.
Number of output names must match number of input names (after glob
expansion of input names). (single string, or array of strings.)

Examples:
thm_load_state, /get_support

thm_cotrans, probe='a', datatype='fgl', out_suffix='_gsm'

; or equivalently

thm_cotrans, 'tha_fgl', 'tha_fgl_gsm', out_coord='gsm'

; to transform all th?_fg?_dsl to th?_fg?_gsm

thm_cotrans, 'th?_fg?', in_suffix='_dsl', out_suffix='_gsm'

; for arbitrary input variables, specify in_coord and probe:

thm_cotrans,'mydslvar1 mydslvar2 mydslvar3', $
in_coord='dsl', probe='b c d', out_suff='_gse'

$LastChangedBy: bsadeghi $
$LastChangedDate: 2012-02-28 13:39:11 -0800 (Tue, 28 Feb 2012) $
$LastChangedRevision: 9890 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_00/idl/themis/state/cotrans/thm_cotrans.pro $

(See themis/state/cotrans/thm_cotrans.pro)

THM_FAC_MATRIX_MAKE

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

Procedure: thm_fac_matrix_make

Purpose:  generates a field aligned coordinate transformation matrix
from an input B vector array(and sometimes a position vector array)
then stores it in a tplot variable.

This code has been modified from fac_matrix_make to handle input data that are
in DSL coordinates.

Arguments:
   mag_var_name=the name of the tplot variable storing the magnetic field
   vectors to be used in transformation matrix generation
   pos_var_name(optional)=the name of the tplot variable storing the position
   vectors to be used in transformation matrix generation
   newname(optional)=the name of the tplot variable in which to store
   the output
   error(optional) = named variable that holds the error state of the
   computation 1 = success 0 = failure
   other_dim(optional) = the second axis for the field aligned
   coordinate system.
   /DEGAP: Set to call TDEGAP to remove any gaps from the data. See TDEGAP for
           for other options that can be invoked using the _extra keyword.
           E.g. thm_fac_matrix_make, 'tha_fgs', other_dim='xgse', /degap, dt=3

   ************For all transformations Z = B************

   Warning about coordinate systems:
   B field tplot variable must be in gse,gsm, or dsl coordinates,
   depending on what transformation has been selected.
   Position tplot variable must be in gei coordinates. Gei is the default coordinate
   system of thm_load_state.

   Warning:  The resulting transformation matrices will only correctly
   transform data from the coordinate system of the input variable to
   the field aligned coordinate system.  So if mag_var_name is in dsl
   coordinates then you should only use the output matrices to transform
   other data in dsl coordinates.


   valid second coord(other_dim) options:

         'Xgse', (DEFAULT) translates from gse or gsm into FAC
                    Definition(works on GSE, or GSM):
                    X Axis = on plane defined by Xgse - Z
                    Second coordinate definition: Y = Z x X_gse
                    Third coordinate, X completes orthogonal RHS
                    (right hand system) triad: XYZ
                    Note: X_gse is a unit vector pointing in direction from
                          earth to the sun
         'Rgeo',translate from geo into FAC using radial position vector
                    Rgeo is radial position vector, positive radialy outwards.
                    Second coordinate definition: Y = Z x Rgeo (eastward)
                    Third coordinate, X completes orthogonal RHS XYZ.
         'mRgeo',translate into FAC using radial position vector
                    mRgeo is radial position vector, positive radially inwards.
                    Second coordinate definition: Y = Z x mRgeo (westward)
                    Third coordinate, X completes orthogonal RHS XYZ.
         'Phigeo', translate into FAC using azimuthal position vector
                    Phigeo is the azimuthal geo position vector, positive Eastward
                    First coordinate definition: X = Phigeo x Z (positive outwards)
                    Second coordinate, Y ~ Phigeo (eastward) completes orthogonal RHS XYZ
         'mPhigeo', translate into FAC using azimuthal position vector
                    mPhigeo is minus the azimuthal geo position vector; positive Westward
                    First coordinate definition: X = mPhigeo x Z (positive inwards)
                    Second coordinate, Y ~ mPhigeo (Westward) completes orthogonal RHS XYZ
         'Phism', translate into FAC using azimuthal Solar Magnetospheric vector.
                 Phism is "phi" vector of satellite position in SM coordinates.
                 Y Axis = on plane defined by Phism-Z, normal to Z
                 Second coordinate definition: X = Phism x Z
                 Third completes orthogonal RHS XYZ
         'mPhism', translate into FAC using azimuthal Solar Magnetospheric vector.
                 mPhism is minus "phi" vector of satellite position in SM coordinates.
                 Y Axis = on plane defined by Phism-Z, normal to Z
                 Second coordinate definition: X = mPhism x Z
                 Third completes orthogonal RHS XYZ
         'Ygsm', translate into FAC using cartesian Ygsm position as other dimension.
                 Y Axis on plane defined by Ygsm and Z
                 First coordinate definition: X = Ygsm x Z
                 Third completes orthogonal RHS XYZ
         'Zdsl', translates from dsl into FAC
                    Definition:
                    X Axis = on plane defined by Zdsl - Z
                    Second coordinate definition: X = Z x Zdsl 
                    Third coordinate, Y completes orthogonal RHS
                    (right hand system) triad: XYZ
 Example:
  fac_matrix_make,'tha_fgs',other_dim='Xgse',pos_var_name='tha_pos',out_var_name='tha_fgs_fac_mat'

(See themis/state/cotrans/thm_fac_matrix_make.pro)

THM_GSM2LMN_WRAP

[Previous Routine] [List of Routines]

 NAME:
     THM_GSM2LMN_WRAP

 PURPOSE:
	Wrapper transforms THEMIS-generated vector field from GSM to LMN (boundary-normal)
	coordinate system for magnetopause with help of routine gsm2lmn.pro.
	It gets the necessary solar wind data with help of routine
	get_sw_data.pro and passes all necessary keywords to it.
	In distinction of GSM2LMN_WRAP, it finds space-time coordinates using
	reference to a THEMIS probe.

 CATEGORY:
	Coordinate Transformation

 CALLING SEQUENCE:
	thm_gsm2lmn_wrap,data_in,data_out,probe,SWkeywords

 INPUTS:
	data_in: structure {x:time, y:data}
	probe: string specify which spacecraft caught data_in.

 KEYWORDS: Solarwind_load.pro keywords (Any combination of keywords defining
           output of solarwind_load.pro)

 PARAMETERS: none

 OUTPUTS:
	data_out: structure {x:time, y:transformed_data}

 DEPENDENCIES: gsm2lmn.pro, solarwind_load.pro. Intermediate-level part of LMN 
		transform package.

 MODIFICATION HISTORY:
     Written by: Liu Jiang 09/21/2007
	Modified for new background routines by: Vladimir Kondratovich 2007/12/28

(See themis/state/cotrans/thm_gsm2lmn_wrap.pro)