This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Jun 24 12:41:17 2009.
PROCEDURE: append_array, a0, a1
PURPOSE:
Append an array to another array. Can also copy an array into a
subset of another.
INPUT:
a0: Array to modify.
a1: Array to append to, or copy into, a0.
KEYWORDS:
index: Index of a0 at which to append or copy a1. If index is
greater than the number of elements of a0, then
a0 is enlarged to append a1. Returns the index of the first
element of a0 past the section copied from a1.
done: If set, make a0 equal to the first index elements of a0.
CREATED BY: Davin Larson
LAST MODIFIED: @(#)append_array.pro 1.6 98/08/13
(See ssl_general/misc/append_array.pro)
FUNCTION array_cross(l1,l2)
Purpose:
returns a 2*n array, where n = n_elements(l1)*n_elements(l2)
each pair is a combination of l1 and l2
the total list represents all possible pairings of l1 and l2
Written by Patrick Cruce
$LastChangedBy: pcruce $
$LastChangedDate: 2009-03-11 11:10:36 -0700 (Wed, 11 Mar 2009) $
$LastChangedRevision: 5255 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/array_cross.pro $
(See ssl_general/misc/array_cross.pro)
FUNCTION: average_str(data, res) PURPOSE: Average data in res second time segments. INPUTS: DATA: array of structures. One element of structure must be TIME. RES: resolution in seconds. KEYWORDS: NAN: If set, treat the IEEE NAN value as missing data. CREATED BY: Davin Larson LAST MODIFIED: %W% %E%
(See ssl_general/misc/average_str.pro)
NAME:
avsig
PURPOSE:
Average and dispersion of an array, zeros can be not included,
handles NaN values correctly
CALLING SEQUENCE:
xbar = Avsig(x, sigma = sigma, no_zeros = no_zeros, $
sig_mean = sig_mean, dimension = dimension, $
fractional = fractional, median = median, $
_extra = _extra)
INPUT:
x = an array
OUTPUT:
xbar = mean, total(x)/n_elements(x)
KEYWORDS:
no_zeros= if set, strip out zeros
get_sigma = if set, calculate the standard deviation
sigma = standard deviation, sqrt(total((x-xbar)^2/(nx-1)))
sig_mean = if set return sigma/sqrt(nx), the standard deviation of the
mean of the array,
dimension = the dimension of the array to find the mean in,
passed into the total command, it must be a scalar.
fractional = if set, the fractional error is passed out as sigma,
don't use this if zero is a valid value of xbar...
median = if set, use the median instead of the mean for xbar, it
is not recommended fo sigma calculations
HISTORY:
12-9-94, jmm, jimm@ssl.berkeley.edu
2-13-95, jmm, added dimension keyword, switched from ok_zeros to no_zeros
5-sep-1996, jmm, switched to double precision
7-oct-2008, jmm, ignores NaN values, added median keyword
(See ssl_general/misc/tsub_average.pro)
Procedure: bin1d
Purpose:
Uses histogram to bin data according to array binarr. The elements in binarr
that are in a specific bin correspond to elements in other arrays (like
density, temperature etc) and the averages of those are computed within
each bin. The arrays to be averaged within each bin are passed in
arrs2bin(NXM) where N is the number of elements of the binarr and M is the
number of quantities.
Output: kinbin is K-array of elements (K=number of bins) containing
number of points within each bin, bincenters a K-array with center
of bins, averages is KXM array with averages (zero if no points)
stdevs an KXM array with stdevs about the mean and medians is
KXM array of medians within each bin
If any of the keywords maxvarvec or minvarvec is set to a name
then it is assumed that the first two
elements of the array "arrs2bin" correspond to the X,Y coordinates of
a "flow" field. The corresponding data in each cell will be rotated
in a max/min variance direction. The maxvariance direction will
be in 2D vector maxvarvec for each cell. The minvariance direction
will be in 2D vector minvarvec for each cell. The vector norm is the
variance in the max/min direction, i.e.,
lambda_i=sqrt(maxvarvec(*,0)^2+maxvarvec(*,1)^2).
if keyword flag4nodata is set, then points with no data are flags set equal
to the value passed in, not zeros.
Usage:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
bin1D,Ygse,[[Ni],[Ti],[Vx],[fx],[Qx],[Eylep]],-15.,15.,1.,kinbin,Ycntrs,avrg,std,med
Niavg=avrg(*,0)&Tiavg=avrg(*,1)&Vxavg=avrg(*,2)&fxavg=avrg(*,3)&Qxavg=avrg(*,4)&Eylepavg=avrg(*,5)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
$LastChangedBy: pcruce $
$LastChangedDate: 2007-10-03 14:49:09 -0700 (Wed, 03 Oct 2007) $
$LastChangedRevision: 1661 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/idl_socware/trunk/external/IDL_GEOPACK/t01/t01.pro $
(See ssl_general/misc/bin1d.pro)
Procedure: bin2d
Purpose:
A slightly simpler wrapper for vassilis's routine for 2-d binning
NOTE: despite the fact that they are keywords either binsize or
binnum must be set for the proceedure to function
Inputs:
x: the x components for the bins. Should be
an N length array.
y: the y components for the bins. Should be an
N length array.
arrs2bin: the arrays to be binned should be an NxM
sized array or an N sized array
(Note: Interpolation to match the N component
of input arrays is the responsibility of the
user.)
Keywords:
binsize: a number or a 2 element array. If a single number
it will be treated as size of the bins for the x dimension
and the y dimension. If it is a two element array, the
first element will be the size of the bins on the x
axis and the second element will be the size of the
bins on the y axis.
Warning: Either Binsize or binum must always be set.
binum: a number of 2 element array. If a single number it
will be treated as the number of bins on for both
axes. If a 2 element array, the first element is
number of bins on the x-axis and the second element is
the number of bins on the y-axis. (Note: The number of
bins actually produced may vary by +- 1) Bins will be
evenly spaced over xrange and yrange if provided, and
over the range of the data if not.
Warning: Either Binsize or binum must always be set.
xrange,yrange(optional): a 2 element array specifying the min
and the max over which binning will occur for the
respective axis(default: all data)
flagnodata(optional): set this keyword to a flag to replace
output values with if there is no data. (default: 0)
averages(output): outputs 2-d array in which the bin averages
are stored
medians(output): outputs 2-d array in which the bin medians are stored
stdevs(output): outputs 2-d array in which the bin stdevs are stored.
binhistogram(output): a 2-d histogram of the number of elements
used for constructing each cell
xcenters,ycenters(output): 1-d array of the centers for the bins
on each axis.
minvarvec,maxvarvec(output): Either of these are set arrs2bin
will must have dimension M >= 2. The first 2 arrays
of the M dimension(ie arrs2bin[*,0] and arrs2bin[*,1]
will be treated as corresponding elements of an X,Y flow
field. The maxvariance direction will be a 2D vector in
maxvarvec for each cell. The minvariance direction
will be a 2D vector in minvarvec for each cell. The
vector norm is the variance in the max/min direction, i.e.,
lambda_i=sqrt(maxvarvec(*,0)^2+maxvarvec(*,1)^2).
Notes and Warnings:
1. Interpolation to match the N component of input arrays is the
responsibility of the user.
2. The number of bins actually produced may vary by +- 1 from the
number requested by binum
3. Either binsize or binum must always be set.
4. If both binsize and binum, binsize will take precedent.
SEE ALSO: bin1d.pro,plotxyz.pro,thm_crib_plotxyz.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2008-02-06 13:43:58 -0800 (Wed, 06 Feb 2008) $
$LastChangedRevision: 2352 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $
(See ssl_general/misc/bin2d.pro)
FUNCTION: bytescale(array)
PURPOSE: Takes an array or image and scales it to bytes
INPUT: array of numeric values.
KEYWORDS:
RANGE: Two element vector specifying the range of array to be used.
Defaults to the min and max values in the array.
ZERO: Forces range(0) to zero
TOP: Maximum byte value (default is !d.table_size-2)
BOTTOM: Minimum byte value (default is 1)
MIN_VALUE: autoranging ignores all numbers below this value
MAX_VALUE: autoranging ignores all numbers above this value
MISSING: Byte value for missing data. (values outside of MIN_VALUE,
MAX_VALUE range) If the value is less than 0 then !p.background is used.
LOG: sets logrithmic scaling
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)bytescale.pro 1.22 02/04/17
(See ssl_general/misc/bytescale.pro)
PROCEDURE: cart_to_sphere, x, y, z, r, theta, phi
PURPOSE:
transform from cartesian to spherical coordinates
INPUTS: x, y, z (array or scalar)
OUTPUTS: r, theta, phi (same as x,y,z)
KEYWORDS: ph_0_360: if positive, 0<=phi<=360, if zero, -180<=phi<=180,
***if negative, best guess phi range returned***
ph_hist: a two element array of max and min values for phi.
eg: if ph_0_360 is not set, and ph_hist=[-220,220]
then if d(phi)/dt is positive near 180, then
phi => phi+360 when phi passes the 180/-180
discontinuity until phi reaches 220.
CO_LATITUDE: If set theta will be in co-latitude. (0<=theta<=180)
MIN_VALUE:
MAX_VALUE:
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)cart_to_sphere.pro 1.13 02/04/17
NOTES:
-90 < theta < 90 (latitude not co-lat)
(See ssl_general/misc/cart_to_sphere.pro)
FUNCTION: cdf_file_names
PURPOSE:
Returns an array of filenames within a timerange.
USAGE:
files=cdf_file_names(FORMAT,trange=trange,/verbose)
INPUT:
FORMAT is a string that will be interpreted as one of two things:
CASE 1:
e.g. FORMAT = '/home/wind/dat/wi/3dp/k0/????/wi_k0_3dp*.cdf'
if FORMAT contains * or ? then filenames are returned that match that
pattern and for which YYYYMMDD falls within the specified timerange.
for example:
(UNIX only)
CASE 2:
e.g. FORMAT = 'fa_k0_ees_files'
The name of an indexfile that associates filenames with start and
end times. If his file is not found, then the environment variable
getenv('CDF_INDEX_DIR') is prepended and searched for.
See "make_cdf_index" for information on producing this file.
SPECIAL NOTE:
If strupcase(FORMAT) is the name of an environment varible. Then
the value of that environment variable is used instead.
KEYWORDS:
TRANGE:
Two element array specifying the time range for which data files should
be returned. If not provided then "timerange" is called to provide
the time range. See also "timespan".
NFILES:
Named variable that returns the number of files found.
VERBOSE:
Set to print some useful info.
FILEINFO: OBSOLETE!
Set to a named variable that will return a table of file info.
NOTES:
UNIX only!
(See ssl_general/misc/cdf_file_names.pro)
NAME: code_fragment PURPOSE: takes a string, where input variables are defined as array_elements 'qq' and creates a set of tplot commands using those data CALLING SEQUENCE: code_fragment, inp_string, otp_string HISTORY: 13-jun-2007, jmm, jimm@ssl.berkeley.edu
(See ssl_general/misc/tuserdef.pro)
COMMON BLOCK colors_com WARNING! Don't rely on this file to remain stable! USE "get_colors" to get color information. SEE ALSO: "get_colors","bytescale","loadct2" CREATED BY: Davin Larson File: 96/08/30 Version: 1.2 Last Mod: colors_com.pro
(See ssl_general/misc/colors_com.pro)
Function: csvector
Purpose: This procedure implements the create,add, and read
methods for a traditional computer science
data structure: the vector.The vector
list of elements of any type and of any length.
Advantages over array:
1. store heterogenous elements of any type in a list.
2. Lists can grow as large as memory and you don't
need to know how big it will be in advance
3. You don't need to worry about how the data is stored
Disadvantages over array:
1. You can't directly apply operations to the data
structure
2. You are forced to use abstraction
Inputs: arg1:the meaning of the argument varies with syntax
arg2:the meaning of the argument varies with syntax
Keywords: read(optional): set this if you want
to read an element
length(optional): set this if you want
to read the length
free(optional): set this if you want to free the
vector's memory without
creating a leak, it will return
the number of elements free'd
Outputs: a vector, the internal representation is
abstracted, use the methods to access this data structure
Syntax(each method is followed by examples):
create:
v = csvector(some_element)
v = csvector(1)
v = csvector([1,2])
v = csvector({a:1,b:2})
add:
vector = csvector(some_element,vector)
v = csvector(1,v)
v = csvector('a',v)
v = csvector([1,2],v)
read:
element = csvector(element_index,vector,/read)
e = csvector(0,v,/read) ;first element
e = csvector(csvector(v,/L)-1,v,/r) ;last element
length:
length = csvector(vector,/length)
l = csvector(v,/l)
l = csvector(v,/length)
free:
num = csvector(vector,/free)
temp = csvector(v,/free)
NOTES: in the event of overflow during add the vector.a
component will double in size
Add/Create stores a copy of the element not the element itself
If you want to do manual lengths and reads you can look
at the code, but I would recommend against cause you are
violating abstraction which means the internal representation
could change and invalidate your code.
This might be worth writing in O.O. idl as well
To get type flexibility it uses a pointer for every object
Thus if you aren't careful this function will eat your
system memory for breakfast. Use heap_gc to clean up if you
are running out of memory.
(See ssl_general/misc/csvector.pro)
NAME: day_to_year_doy PURPOSE: determines year and day of year given day since 0000 AD USAGE: day_to_year_doy,daynum,year,doy INPUT: daynum: (long int) day since 0 AD OUTPUT: year: year (0 <= year <= 14699 AD) doy: day of year (1 <= doy <= 366) NOTES: This procedure is reasonably fast, it works on arrays and works from 0 AD to 14699 AD CREATED BY: Davin Larson Oct 1996 FILE: day_to_year_doy.pro VERSION: 1.2 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/day_to_year_doy.pro)
FUNCTION: dimen(x) PURPOSE: Returns the dimensions of an array as an array of integers. INPUT: matrix RETURNS: vector of dimensions of matrix. If the input is undefined then 0 is returned. if the input is a scaler then 1 is returned. SEE ALSO: "dimen", "data_type", "dimen1", "dimen2" CREATED BY: Davin Larson LAST MODIFICATION: @(#)dimen.pro 1.6 96/12/16
(See ssl_general/misc/dimen.pro)
FUNCTION: dimen1 INPUT: matrix RETURNS: scaler int: size of first dimension (1 if dimension doesn't exist) CREATED BY: Davin Larson LAST MODIFICATION; @(#)dimen1.pro 1.3 95/08/24
(See ssl_general/misc/dimen1.pro)
FUNCTION: dimen2 INPUT: matrix RETURNS: scaler int: size of second dimension (1 if dimension doesn't exist) CREATED BY: Davin Larson LAST MODIFICATION; @(#)dimen2.pro 1.3 95/08/24
(See ssl_general/misc/dimen2.pro)
FUNCTION: dimen_shift(x,shift) NAME: dimen_shift PURPOSE: Rotate dimensions of a multidimensional array. This function is very similar to transpose but works on multi-dimensional arrays to shift the dimensions around. It has no effect on scalars and one dimensional arrays. INPUT: x multi-dimensional array of any type shift: 1 or -1 direction of shift. CREATED BY: Davin Larson LAST MODIFICATION: @(#)dimen_shift.pro 1.4 98/07/09
(See ssl_general/misc/dimen_shift.pro)
PROCEDURE: divide_data
PURPOSE:
Divides successive channels of SST data by powers of 'factor', to
separate the traces. Also, optionally, multiplies data by an overall factor,
'conv_factor', to convert units.
INPUT: in_name (string), the name of the input TPLOT variable
structure.
out_name (string), the name of the output TPLOT variable
structure.
KEYWORDS: factor (float), by which fluxes in successive channels are
divided.
conv_factor (optional float), by which fluxes in all channels
are multiplied.
CREATED BY: Ted Freeman
FILE: divide_data.pro
LAST MODIFIED: @(#)divide_data.pro 1.2 99/09/01
NOTES: "LOAD_3DP_DATA" and "GET_SPEC" must be called first.
(See ssl_general/misc/divide_data.pro)
PROCEDURE: doy_to_month_date, year, doy, month, date NAME: doy_to_month_date PURPOSE: Determines month and date given the year and day of year. fast, vector oriented routine that returns the month and date given year and day of year (1<=doy<=366) CREATED BY: Davin Larson Oct 1996 FILE: doy_to_month_date.pro VERSION: 1.2 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/doy_to_month_date.pro)
NAME:
dpwrspc
PURPOSE:
Called with times time and data quantity, dpwrspc returns a dps
spectrum at frequencies fdps. A Hanning window is applied to the
input data, and its power is divided out of the returned
spectrum. A straight line is subtracted from the data to reduce
spurious power due to sawtooth behavior of a background. UNITS
ARE (UNITS)^2 WHERE UNITS ARE THE UNITS OF time. fdps is in
Hz. THUS THE OUTPUT REPRESENTS THE MEAN SQUARED AMPLITUDE OF THE
SIGNAL AT EACH SPECIFIC FREQUENCY. THE TOTAL (SUM) POWER UNDER
THE CURVE IS EQUAL TO THE MEAN (OVER TIME) POWER OF THE
OSCILLATION IN TIME DOMAIN. NOTE: IF KEYWORD notperhz IS SET,
THEN POWER IS IN UNITS OF NT^2 ELSE IT IS IN UNITS OF NT^2/HZ.
CALLING SEQUENCE:
dpwrspc, time, quantity, tdps, fdps, dps, nboxpoints = nboxpoints, $
nshiftpoints = nshiftpoints, bin = bin, tbegin = tbegin,$
tend = tend, noline = noline, nohanning = nohanning, $
notperhz = notperhz
INPUT:
time = the time array
quantity = the function for which you want to obtain a power
spectrum
OUTPUT:
tps = the time array for the dynamic power spectrum
fdps = the frequency array (units =1/time units)
dps = the power spectrum, (units of quantity)^2/frequency_units
KEYWORDS:
nboxpoints = the number of points to use for the hanning window, the
default is 256
nshiftpoints = the default is 128
bin = a binsize for binning of the data, the default is 3
tbegin = a start time, the default is time[0]
tend = an end time, the default is time[n_elements(time)-1]
noline = if set, no straight line is subtracted
nohanning = if set, then no hanning window is applied to the input
notperhz = if set, the output units are simply the square of the
input units
fail = if set to a named variable, returns 1 if an error occurs, 0 otherwise
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/dpwrspc.pro)
NAME:
dydt_spike_test
PURPOSE:
This function checks an array for spikes based on its time
derivative. This is designed mostly for THEMIS GMAG spikes that
persist over multiple data points, but should work on single data
point spikes too.
CALLING SEQUENCE:
flag = dydt_spike_test(t0, y0, dydt_lim = dydt_lim, $
sigma_y = sigma_y, nsig = nsig, $
no_degap = no_degap, pad=pad, $
degap_margin = degap_margin, $
degap_dt = degap_dt, _extra = _extra)
INPUT:
t0 = a time array
y0 = a data aray, same number of elements as t0
OUTPUT:
flag = a bytarr(n_elements(t0)), set to 1 for spikes, 0 for ok data,
note that NaN values are automatically set to 1
KEYWORDS:
dydt_lim = a value for the max. allowed derivative, the default is
to calculate a limiting value from the uncertainty in
the data.
sigma_y = if known, an estimate of the standard deviation in y0
values. The default is to use sqrt(y), as if you have a
photon count for data. If you do not know
this uncertainty in Y, it might be a good idea to use
dydt_lim.
nsig = the number of uncertainties in dydt that will be used to
obtain the limit value at each data point.
pad = pad the spike flag on either side by this many data points.
no_degap = By default, the program calls xdegap and xdeflag routines
to deal with gaps in the data. Set this keyword to avoid
this.
DEGAP KEYWORDS:
nowarning = if set, suppresses warnings
maxgap = the maximum gap size filled, in seconds
degap_dt = a time_interval for the degap process, the default is to
use the minimum of the time resolutions in the data,
i.e., min(t0[1:*]-t0)
degap_margin = a margin value for the degap call, the default is to
use the minimum of the time resolutions in the data,
i.e., min(t0[1:*]-t0)
HISTORY:
7-apr-2008, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: jimm $
$LastChangedDate: 2008-04-14 10:44:44 -0700 (Mon, 14 Apr 2008) $
$LastChangedRevision: 2705 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/dydt_spike_test.pro $
(See ssl_general/misc/dydt_spike_test.pro)
PROCEDURE: extract_tags, newstruct, oldstruct
PURPOSE: takes the named tag elements from oldstruct and puts them into
newstruct. This procedure is very useful for creating a structure that
can be passed onto the PLOT or OPLOT subroutines using the _EXTRA keyword.
If no tag keywords are included then all tag elements of oldstruct are
added to newstruct. The mode keyword PRESERVE is used to prevent the
overwritting of an existing keyword.
INPUTS:
newstruct: new structure to be created or added to.
oldstruct: old structure from which elements are extracted.
KEYWORDS: Only one of the following should be given:;
(TAG KEYWORDS)
TAGS: array of strings. (tag names) to be taken from oldstruct and put in
newstruct
EXCEPT: array of strings. Tag names not to be copied from old to new.
OPLOT: (flag) If set, then TAGS is set to an array of valid keywords
for the OPLOT subroutine.
PLOT: (flag) If set, then TAGS is set to an array of valid keywords
for the PLOT subroutine.
CONTOUR: (flag) If set, then TAGS is set to an array of valid keywords
for the CONTOUR procedure. (might not be complete)
If no KEYWORDS are set then all elements of oldstruct are put into newstruct
(MODE KEYWORDS)
PRESERVE: (flag) Prevents the overwritting of an existing, non-null keyword.
Adds tags to newstruct that were not already there, or if they were there
and their values were either "" or 0.
CREATED BY: Davin Larson
FILE: extract_tags.pro
VERSION 1.21
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/extract_tags.pro)
Procedure: file_copy2
(See ssl_general/misc/file_copy2.pro)
Procedure: FILE_DAILYNAMES Author: Davin Larson
(See ssl_general/misc/file_dailynames.pro)
WARNING: the interface to this routine is not yet solidified. Use the wrapper routine:
file_retrieve instead. This routine is still under development.
NAME:
file_http_copy
PURPOSE:
Downloads file(s) from http servers.
Also performs Searches without download.
Copies the file to a user specified local directory.
By default, files are only downloaded if the remote file is newer than
the local file (based on mtime) or if the files differ in size.
This routine is intended for use with simple HTTP file servers.
Wildcard matching and recursive file searching can be used as well.
CALLING SEQUENCE: There are two methods:
Method 1:
FILE_HTTP_COPY, pathnames, SERVERDIR=serverdir, LOCALDIR=localdir
where:
pathnames = (input string(s), scaler or array) Relative path name of file to download.;
serverdir = (scaler input string) Root name of source URL, must
begin with: 'http://' and end with '/'
localdir = (scaler input string) Root name of local directory, typically
ends with '/'
Note: The source is at: serverdir + pathnames
The destination is: localdir + pathnames
Method 2:
FILE_HTTP_COPY, URL
URL = full URL(S) of source file
Directory structure is not retained with this procedure
Example:
FILE_HTTP_COPY, 'ssl_general/misc/file_http_copy.pro', $
SERVERDIR='http://themis.ssl.berkeley.edu/data/themis/socware/bleeding_edge/idl/' $
localdir = 'myidl/'
Note: Unix style directory separaters '/' should be used throughout. This convention will still
work with WINDOWS.
Alternate calling sequence:
FILE_HTTP_COPY,URL
where URL is an input (string) such as: URL = '
INPUTS:
URL - scalar or array string giving a fully qualified url
OPTIONAL KEYWORDS:
NO_CLOBBER: (0/1) Set this keyword to prevent overwriting local files.
IGNORE_FILESIZE: (0/1) Set this keyword to ignore file size when
evaluating need to download.
NO_DOWNLOAD: (0/1) Set this keyword to prevent file downloads (url_info
is still returned)
URL_INFO=url_info: (output) Named variable that returns information about
remote file such as modification time and file size as determined
from the HTML header. A zero is returned if the remote file is
invalid.
FILE_MODE= file_mode: If non-zero, sets the permissions for downloaded files.
DIR_MODE = dir_mode: Sets permissions for newly created directories
(Useful for shared directories)
ASCII_MODE: (0/1) When set to 1 it forces files to be downloaded as ascii text files (converts CR/LF)
Setting this keyword will force ignore_filesize keyword to be set as well because
files will be of different sizes typically.
VERBOSE: (input; integer) Set level of verboseness: Uses "DPRINT"
0-nearly silent; 2-typical messages; 4: debugging info
Examples:
;Download most recent version of this file to current directory:
FILE_HTTP_COPY,'http://themis.ssl.berkeley.edu/data/themis/socware/bleeding_edge/idl/ssl_general/misc/file_http_copy.pro'
OPTIONAL INPUT KEYWORD PARAMETERS:
PATHNAME = pathname ; pathname is the filename to be created.
If the directory does not exist then it will be created.
If PATHNAME does not exist then the original filename is used
and placed in the current directory.
;
RESTRICTIONS:
PROXY: If you are behind a firewall and have to access the net through a
Web proxy, set the environment variable 'http_proxy' to point to
your proxy server and port, e.g.
setenv, 'http_proxy=http://web-proxy.mpia-hd.mpg.de:3128'
The URL *MUST* begin with "http://".
PROCEDURE:
Open a socket to the webserver and download the header.
EXPLANATION:
FILE_HTTP_COPY can access http servers - even from behind a firewall -
and perform simple downloads. Currently,
Requires IDL V5.4 or later on Unix or Windows, V5.6 on
Macintosh
EXAMPLE:
IDL> FILE_HTTP_COPY,'http://themis.ssl.berkeley.edu/themisdata/thg/l1/asi/whit/2006/thg_l1_asf_whit_2006010103_v01.cdf'
IDL> PRINTDAT, file_info('thg_l1_asf_whit_2006010103_v01.cdf')
or
MINIMUM IDL VERSION:
V5.4 (uses SOCKET)
MODIFICATION HISTORY:
Original version: WEBGET()
Written by M. Feldt, Heidelberg, Oct 2001 <mfeldt@mpia.de>
Use /swap_if_little_endian keyword to SOCKET W. Landsman August 2002
Less restrictive search on Content-Type W. Landsman April 2003
Modified to work with FIRST image server- A. Barth, Nov 2006
FILE_HTTP_COPY: New version created by D Larson: March 2007.
Checks last modification time of remote file to determine need for download
Checks size of remote file to determine need to download
Very heavily modified from WEBGET():
May/June 2007 - Modified to allow file globbing (wildcards).
July 2007 - Modified to return remote file info (without download)
July 2007 - Modified to allow recursive searches.
August 2007 - Added file_mode keyword.
April 2008 - Added dir_mode keyword
$LastChangedBy: jwl $
$LastChangedDate: 2009-06-16 11:07:41 -0700 (Tue, 16 Jun 2009) $
$LastChangedRevision: 6208 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/file_http_copy.pro $
(See ssl_general/misc/file_http_copy.pro)
Procedure FILE_OPEN,type,name
Purpose: wrapper for OPENW, OPENU, OPENR, FILE_MKDIR
type must be one of: 'w', 'u', 'r', 'd' (write, update, read, directory)
This procedure performs the functions of creating/opening files and creating directories.
It has several useful features which the regular procedures do not have:
1) Non-existant directories are created automatically (with optional mode setting)
2) If a non-existant file is opened for update, it is created with OPENW instead of producing an error.
3) Files (or directories) can be tested to see if they can be created before actually opening (or creating)
them (use the TEST keyword). (The returned structure INFO will have the WRITE element set)
Example 1: Creating a file for write access:
FILE_OPEN,'w','/dir1/dir2/dir3/file.tmp',unit=u ; Will create the director tree if it does not already exist.
Example 2: Creating new directories with defined modes:
FILE_OPEN,'d','/dir1/dir2/dir3', dir_mode="777 ,
All newly created directories will have the given permissions (Octal 777)
Example 3:
FILE_OPEN,'w','/dir1/dir2/dir3/file.tmp',/test,info=info ;This will test if the file
can be created (with given file system permissions) without actually creating the file.
The returned info stucture can potentially have info.exists eq to 0 and info.write eq 1
Example 4:
(See ssl_general/misc/file_open.pro)
FUNCTION file_retrieve(pathnames,local_data_dir=local_data_dir)
Keywords:
local_data_dir: local data directory; 'must end with a '/'
remote_data_dir: remote data directory: 'must end with a '/'
$LastChangedBy: jwl $
$LastChangedDate: 2009-06-11 14:55:13 -0700 (Thu, 11 Jun 2009) $
$LastChangedRevision: 6150 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/file_retrieve.pro $
(See ssl_general/misc/file_retrieve.pro)
Procedure: file_retrieve_v Purpose: Wrapper for file_retrieve that searches for highest available version first, with no need to retrieve remote-index. Keywords: relpathnames: the list of relative pathnames that are being searched version_list(optional): if the user wants to override the default version priority list so this function prioritizes versions differently, a different version list can be passed in $LastChangedBy: kenb-mac $ $LastChangedDate: 2007-08-21 08:33:59 -0700 (Tue, 21 Aug 2007) $ $LastChangedRevision: 1463 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/file_retrieve_v.pro $
(See ssl_general/misc/file_retrieve_v.pro)
Function: file_source_dirname Purpose: Returns the directory path of the source file which calls this function. This is useful for determining the directory of associated data files. Warning: May not work for a precompile version of code. Author: D Larson 2008
(See ssl_general/misc/file_source_dirname.pro)
Procedure: FIND_CONST_INTERVALS Purpose: Find intervals within the input array where the data are constant to some tollerance, and return the begin and end indices into the original array for those intervals. Calling Sequence: x = [ 1, 1, 3, 3, 4, 1, 1, 1, 1] ctol = 0.01 find_const_intervals, x, nint=nint, ibeg=ibeg, iend=iend, ctol=ctol Arguements: X, ARRAY or any type; will be cast to FLOAT for comparison. NINT, LONG, number of intervals of constantcy found in X. IBEG, IEND, LONG[ nint], arrays of array indices to the begin and end of each constant interval. CTOL, FLOAT, tollerance for constancy of data; ABS(dX) lt CTOL for data to be "constant". Notes: None. $LastChangedBy: pcruce $ $LastChangedDate: 2007-06-27 13:16:28 -0700 (Wed, 27 Jun 2007) $ $LastChangedRevision: 904 $ $URL $
(See ssl_general/misc/find_const_intervals.pro)
**** OBSOLETE!!! Please use "str_element"instead! *** FUNCTION: find_str_element PURPOSE: find an element within a structure Input: struct, generic structure name, string (tag name) Purpose: Returns index of structure tag. Returns -1 if not found Returns -2 if struct is not a structure KEYWORDS: If VALUE is set to a named variable then the value of that element is returned in it. CREATED BY: Davin Larson LAST MODIFICATION: @(#)find_str_element.pro 1.6 95/10/06
(See ssl_general/misc/find_str_element.pro)
PROCEDURE: fname_to_time, fname, time PURPOSE: To translate the name of a standard WIND data file into the starting time of the data. INPUT: fname: filename (string) to be translated time: variable in which to return time (double) CREATED BY: Peter Schroeder LAST MODIFICATION: %W% %E%
(See ssl_general/misc/fname_to_time.pro)
FUNCTION: get_colors PURPOSE: returns a structure containing color pixel values INPUT: none KEYWORDS: NOCOLOR: forces all colors to !d.table_size-1. Written by: Davin Larson 96-01-31 FILE: get_colors.pro VERSION: 1.2 LAST MODIFICATION: 99/04/07
(See ssl_general/misc/get_colors.pro)
PROCEDURE: get_file_names, fnames
PURPOSE:
Gets an array of filenames within a time range
INPUT:
fnames: named variable in which the output array of filenames is placed.
KEYWORDS:
TIME_RANGE: Two element vector (double or string) specifying the time range.
If time range is not set, then "GET_TIMESPAN" will be called
to get a time range.
MASTERFILE: Use this keyword to pass in one of the following:
1) Name of a masterfile that contains times and associated
filenames. The file should have the format:
yyyy-mm-dd/hh:mm:ss yyyy-mm-dd/hh:mm:ss fullpathfilename
with one line for each file.
(Hint: for CDF files, the masterfile can be created using the
UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
2) Full path/file names with wildcard characters to search for
relevant files. Input should be in the form:
/path/xxx* for files of form /path/xxx_date.
3) The name of a previously defined environment variable containing
data in the form of 1 or 2 above.
ROOT_DIR: Optional root_directory of the masterfile. This will properly
manage operating system dependancies.
CREATED BY: Davin Larson
MODIFIED BY: Peter Schroeder
VERSION: 1.26 00/10/04 get_file_names.pro
(See ssl_general/misc/get_file_names.pro)
PROCEDURE: get_file_names_ind, fnames
PURPOSE:
Gets an array of filenames within a masterfile within a time range
INPUT:
fnames: named variable in which the output array of filenames is placed.
KEYWORDS:
TIME_RANGE: Two element vector (double or string) specifying the time range.
If time range is not set, then "GET_TIMESPAN" will be called
to get a time range.
MASTERFILE: Name of a masterfile that contains times and associated
filenames. The file should have the format:
yyyy-mm-dd/hh:mm:ss yyyy-mm-dd/hh:mm:ss fullpathfilename
with one line for each file.
(Hint: for CDF files, the masterfile can be created using the
UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
ROOT_DIR: Optional root_directory of the masterfile. This will properly
manage operating system dependancies.
NO_DUPLICATES: (N; integer)
when set the first N characters of file names are compared and only
the highest version is returned.
CREATED BY: Davin Larson
VERSION: @(#)get_file_names_ind.pro 1.1 97/06/23
(See ssl_general/misc/get_file_names_ind.pro)
Procedure: Grad
Purpose: Calculates the gradient of a 2d or 3d grid in one of two ways.
In 2d:
Method1(default):
gradientX = (grid[x+1,y] - grid[x,y] + grid[x+1,y+1] - grid[x,y+1]) / (2*dx)
gradientY = (grid[x,y+1] - grid[x,y] + grid[x+1,y+1] - grid[x+1,y]) / (2*dy)
Method2(leftright):
gradientX = (grid[x+1,y] - grid[x,y] + grid[x,y] - grid[x-1,y]) / (2*dx)
gradientY = (grid[x,y+1] - grid[x,y] + grid[x,y] - grid[x,y-1]) / (2*dy)
This method is actually equivalent to:
gradientX = (grid[x+1,y] - grid[x-1,y]) / (2*dx)
gradientY = (grid[x,y+1] - grid[x,y-1]) / (2*dy)
In 3d:
Method1(default):
gradientX = (grid[x+1,y,z] - grid[x,y,z] + grid[x+1,y+1,z] - grid[x,y+1,z] +
grid[x+1,y,z+1] - grid[x,y,z+1] + grid[x+1,y+1,z+1] - grid[x,y+1,z+1])
/ (4*dx)
gradientY = (grid[x,y+1,z] - grid[x,y,z] + grid[x+1,y+1,z] - grid[x+1,y,z] +
grid[x,y+1,z+1] - grid[x,y,z+1] + grid[x+1,y+1,z+1] - grid[x+1,y,z+1])
/ (4*dy)
gradientZ = (grid[x,y,z+1] - grid[x,y,z] + grid[x+1,y,z+1] - grid[x+1,y,z] +
grid[x,y+1,z+1] - grid[x,y+1,z] + grid[x+1,y+1,z+1] - grid[x+1,y+1,z])
/ (4*dz)
Method2(leftright):
gradientX = grid[x+1,y,z] - grid[x-1,y,z] / (2*dx)
gradientY = grid[x,y+1,z] - grid[x,y-1,z] / (2*dy)
gradientZ = grid[x,y,z+1] - grid[x,y,z-1] / (2*dz)
Method1 will produce an output that is one element smaller in each dimension
and whose element centers are offset by half the nominal spacing of the grid.
Method2 will have the same centers and same number of elements as the original
grid(if the original grid had regular spacing).
Example:
Inputs: grid: an NxM grid of points, if it contains NaNs the output may be
unpredictable.(or an NxMxP)
x(optional): An N length array specifying the positions of the grid points on the x-axis
xc should be monotonic and should contain no NaNs. If unset this routine will
assume dx = 1.0
y(optional): An M length array specifying the positions of the grid points on the y-axis
yc should be monotonic and should contain no NaNs. If unset this routine will
assume dy = 1.0
z:(optional) a P length array specifying the positions of the grid points on
the z-axis. zc should be monotonic and should contain no NaNs. If unset this routine will
assume dz = 1.0
Keywords:
grad: The gradient is output through this keyword as an NxMx2 array
of points. grad[*,*,0] is the x gradient & grad[*,*,1] is the y gradient
xout: The positions of the gradient outputs on the x axis are output through this
keyword as an N length array
yout: The positions of the gradient outputs on the y axis are output through this
keyword as an M length array
xy: The positions for each output point are passed out as pairs through this
keyword. The output array will have dimensions N*Mx2,(N times M by 2)
dxy: The gradient for each point is passed out as pairs through this
keyword. The output array will have dimensions N*Mx2,(N times M by 2)
leftright: Set this keyword if you want to use the second method
of gradient calculation.
Notes:
1. This procedure is not particularly tolerant of NaNs in the input, so
you should remove them before passing them into this routine.
2. The output may have slightly different centers/ dimensions as the input.
This is will definitely be the case if the input array had irregular dimensions.
3. xy,dxy are useful output format keywords for the plotxyvec routine
While grad,xout, & yout may be easier for other tasks.
(See ssl_general/misc/grad.pro)
NAME:
high_pass_filter
PURPOSE:
subtracts running average from a data array
CALLING SEQUENCE:
y = high_pass_filter(array, time_array, no_time_interp=no_time_interp)
INPUT:
array = a data array
time_array = a time array (in units of seconds)
dt = the averaging time (in seconds)
no_time_interp = if set, do *not* interpolate the data to the
minimum time resolution. The default procedure is
to interpolate the data to a regularly spaced grid,
and then use ts_smooth to get the running
average. This alternative can be slow, but it may
save a lot of memory.
double = if set, do calculation in double precision
regardless of input type. (If input data is double
calculation is always done in double precision)
interp_resolution = If time interpolation is being used, set this
option to control the number of seconds between
interpolated samples. The default is to use
the value of the smallest separation between
samples. Any number higher than this will sacrifice
output resolution to save memory. (NOTE: This option
will not be applied if no interpolation is being
performed because either (1) no_time_interp is set or
(2) the sample rate of the data is constant)
interactive_warning = if keyword is set pops up a message box if there are memory problems and asks
the user if they would like to continue
interactive_varname = set this to a string indicating the name of the quantity to be used in the warning message.
warning_result = assign a named variable to this keyword to determine the result of the computation
OUTPUT:
y = the data array where at each point an average of the data for
the previous dt has been subtracted.
HISTORY:
14-jan-2008, jmm, jimm@ssl.berkeley.edu
06-feb-2008, teq, teq@ssl.berkeley.edu
13-mar-2008, jmm, added the default behavior using interpolation
17-mar-2008, jmm, Gutted and rewritten to use smooth_in_time program
23-apr-2008, pcruce, Added padding for no_time_interp option, added _extra keyword
28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
mod to guarantee that precision of output is at least as
large as precision of input
$LastChangedBy: jimmpc $
$LastChangedDate: 2009-05-29 15:09:16 -0700 (Fri, 29 May 2009) $
$LastChangedRevision: 6003 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/high_pass_filter.pro $
(See ssl_general/misc/high_pass_filter.pro)
FUNCTION:
H=histbins(R,XBINS)
Purpose:
Returns the histogram (H) and bin locations (XBINS) for an array of numbers.
Examples:
r = randomn(seed,10000)
plot,psym=10, xbins, histbins(r,xbins) ;Use all defaults.
plot,psym=10, xbins, histbins(r,xbins ,/shift) ;shift bin edges.
plot,psym=10, xbins, histbins(r,xbins, binsize=.2)
plot,psym=10, xbins, histbins(r,xbins, binsize=.2 ,/shift)
plot,psym=10, xbins, histbins(r,xbins, range=[-10,10])
NOTE:
XBINS is an output, not an input!
Keywords: (All optional) Defaults are based on the size and range of input.
BINSIZE: Size of bins.
NBINS: force the output array to have this number of elements. (Use with RANGE)
RANGE: Limits of histogram
SHIFT : Keyword that controls the location of bin edges.
This has no effect if RANGE is defined.
NORMALIZE: Set keyword to return a normalized histogram (probability distribution).
REVERSE: See REVERSE keyword for histogram
RETBINS: If set then an array of bins (same size as r) is returned instead.
See also: "average_hist", "histbins2d"
(See ssl_general/misc/histbins.pro)
Function: h = histbins2d(x,y,xval,yval) Input: x, y, random variables to bin. Output: h number of events within bin xval, yval, center locations of the bins.
(See ssl_general/misc/histbins2d.pro)
FUNCTION: interp(y,x,u)
PURPOSE:
Linearly Interpolates vectors with an irregular grid.
INTERP is functionally the same as INTERPOL, however it is typically
much faster for most applications.
USAGE:
result = interp(y,x,u)
INPUTS:
Y: The input vector can be any type except string.
X: The absicissae values for Y. This vector must have same # of
elements as Y. The values MUST be monotonically ascending
or descending.
U: The absicissae values for the result. The result will have
the same number of elements as U. U does not need to be
monotonic.
KEYWORDS:
NO_CHECK_MONOTONIC: set this keyword to skip the check for monotonic data.
INDEX: Set to named variable to return the index of the closest x less than u.
(same dimensons as u)
NO_EXTRAPOLATE: Set this keyword to prevent extrapolation.
INTERP_THRESHOLD: Set to minimum allowed gap size.
CREATED BY: Davin Larson 4-30-96
FILE: interp.pro
VERSION: 1.15
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/interp.pro)
PROCEDURE: makegif, filename
NAME:
makegif
PURPOSE:
Creates a GIF file from the currently displayed image.
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 ssl_general/misc/makegif.pro)
PROCEDURE: makepng, filename
NAME:
makepng
PURPOSE:
Creates a PNG file from the currently displayed image.
PARAMETERS:
filename filename of png file to create. Defaults to 'plot'. Note:
extension '.png' is added automatically
KEYWORDS:
ct Index of color table to load. Note: will have global
consequences!
multiple Does nothing.
close Does nothing.
no_expose Don't print index of current window.
mkdir If set, make the parent directory/directories of the
file specified by filename.
Restrictions:
Current device should have readable pixels (ie. 'x' or 'z')
Created by: Davin Larson
FILE: makepng.pro
VERSION: 1.11
LAST MODIFICATION: 02/11/06
(See ssl_general/misc/makepng.pro)
NAME:
makeps.pro
PURPOSE:
OBSOLETE: please use tprint or popen and pclose
A simple function to reliably and consistently do postscript export
Right now it will export whatever your last tplot command was(ie
current plot)
CALLING SEQUENCE:
makeps
-or-
makeps,'filename'
INPUT:
a filename or nothing
OUTPUT:
a postscript file to the specified location
errors, grays out all buttons while processing
NOTES: Will append a .ps to your filename whether you like it or not
TODO: add an argument to accept a list of variables
$LastChangedBy: pcruce $
$LastChangedDate: 2008-04-14 15:50:24 -0700 (Mon, 14 Apr 2008) $
$LastChangedRevision: 2719 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/makeps.pro $
(See ssl_general/misc/makeps.pro)
FUNCTION: minmax,array PURPOSE: returns a two element array of min, max values INPUT: array KEYWORDS: MAX_VALUE: ignore all numbers greater than this value MIN_VALUE: ignore all numbers less than this value POSITIVE: forces MINVALUE to 0 CREATED BY: Davin Larson LAST MODIFICATION: @(#)minmax.pro 1.2 02/04/17
(See ssl_general/misc/minmax.pro)
NAME:
MK_HTML_HELP2
PURPOSE:
Creates a html document from a list of IDL procedures.
Given a list of IDL procedure files (.PRO), VMS text library
files (.TLB), or directories that contain such files, this procedure
generates a file in the HTML format that contains the documentation
for those routines that contain a DOC_LIBRARY style documentation
template. The output file is compatible with World Wide Web browsers.
This version is enhanced over the routine supplied by IDL, It will
also cross reference, print the purpose, and add links to the source
code.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
MK_HTML_HELP, Sources, Outfile
INPUTS:
Sources: A string or string array containing the name(s) of the
.pro or .tlb files (or the names of directories containing
such files) for which help is desired. If a source file is
a VMS text library, it must include the .TLB file extension.
If a source file is an IDL procedure, it must include the .PRO
file extension. All other source files are assumed to be
directories. If not provided, searches down directory tree
from current directory for files.
Outfile: The name of the output file which will be generated without
HTML extension.
If no inputs are given: All directories in the current directory tree
are used with the exception of: directories named: 'obsolete'
or 'SCCS.' (UNIX only)
KEYWORDS:
TITLE: If present, a string which supplies the name that
should appear as the Document Title for the help.
FILENAME: Alternative method of specifying Outfile (see above)
VERBOSE: Normally, MK_HTML_HELP does its work silently.
Setting this keyword to a non-zero value causes the procedure
to issue informational messages that indicate what it
is currently doing. !QUIET must be 0 for these messages
to appear.
STRICT: If this keyword is set to a non-zero value, MK_HTML_HELP will
adhere strictly to the HTML format by scanning the
the document headers for characters that are reserved in
HTML (",&,"). These are then converted to the appropriate
HTML syntax in the output file. By default, this keyword
is set to zero (to allow for faster processing).
CROSSLINK:If this keyword is set MK_HTML_HELP will create a cross
reference between library files.
CLTURBO: If this keyword is set to a single character string, then the
cross reference procedure will only cross reference lines that
contain the character given in CLTURBO. This greatly increases
the speed of the routine. By default the double quote (") is
used
PRINT_PURPOSE: If this keyword is set then the first line after PURPOSE:
is printed in the output file.
MASTLIST: If set, create master list only. Do not create subdirectory
file listings.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A help file with the name given by the Outfile argument is
created.
RESTRICTIONS:
The following rules must be followed in formatting the .pro
files that are to be searched.
(a) The first line of the documentation block contains
only the characters ";+", starting in column 1.
(b) There must be a line which contains the string "NAME:",
which is immediately followed by a line containing the
name of the procedure or function being described in
that documentation block. If this NAME field is not
present, the name of the source file will be used.
(c) The last line of the documentation block contains
only the characters ";-", starting in column 1.
(d) Every other line in the documentation block contains
a ";" in column 1.
Note that a single .pro file can contain multiple procedures and/or
functions, each with their own documentation blocks. If it is desired
to have "invisible" routines in a file, i.e. routines which are only
for internal use and should not appear in the help file, simply leave
out the ";+" and ";-" lines in the documentation block for those
routines.
No reformatting of the documentation is done.
MODIFICATION HISTORY:
July 5, 1995, DD, RSI. Original version.
July 13, 1995, Mark Rivers, University of Chicago. Added support for
multiple source directories and multiple documentation
headers per .pro file.
July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
At the end of each description block in the HTML file,
added a reference to the source .pro file.
July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
Changed calling sequence to accept .pro filenames, .tlb
text librarie names, and/or directory names.
Added code to set default subject to name of file if NAME
field is not present in the doc header.
September, 1995, D. Larson. SSL Berkeley. Added crosslink, print_purpose
clturbo.
October 4, 1995, D. Larson. SSL Berkeley. Added link to source file.
October 3, 1996, F. Marcoline. SSL Berkeley. Added Alphabet Jumpline.
October 10, 1996, D. Larson. Added Listing by Directory.
October 1, 2007, J. McTiernan, allow to work with more than 28
directories, dropped obsolete /stream keywords from
openw calls.
FILE: mk_html_help2.pro
VERSION 1.26
LAST MODIFICATION: 99/04/22
(See ssl_general/misc/mk_html_help2.pro)
FUNCTION: ndimen PURPOSE: Returns the number of dimensions in an array. INPUT: array RETURNS number of dimensions (0 for scalers,-1 for undefined) SEE ALSO: "dimen", "data_type" CREATED BY: Davin Larson LAST MODIFICATION: @(#)ndimen.pro 1.6 97/03/10
(See ssl_general/misc/ndimen.pro)
NAME: nn
PURPOSE: Find the index of the data point(s) nearest to the specified time(s)
CALLING SEQUENCE: ind=nn(data,time)
INPUTS: data: a data structure, a tplot variable name/index,
or a time array
time: (double) seconds from 1970-01-01, scalar or array
if not present, "ctime" is called to get time(s)
OPTIONAL INPUTS: none
KEYWORD PARAMETERS: x, y, & v: set to named keywords to return the values
of the x, y, & v arrays, if applicable
OUTPUTS: a long scalar index or long array of indicies
on failure, returns: -2 if bad inputs,
-1 if nearest neighbor not found
EXAMPLE: ctime,times,npoints=2
inds=nn('Np',times)
get_data,'Np',data=dens & get_data,'Tp',data=temp
plot,dens.y(inds(0):inds(1)),temp(inds(0):inds(1))
LAST MODIFICATION: @(#)nn.pro 1.8 02/04/17
CREATED BY: Frank Marcoline
(See ssl_general/misc/nn.pro)
PROCEDURE: oplot_err, x, low, high PURPOSE: Plot error bars over a previously drawn plot.
(See ssl_general/misc/oplot_err.pro)
PROCEDURE: pclose INPUT: none PURPOSE: Close postscript file opened with popen, and change device back to default. If common block string 'printer_name' is set, then file is sent to that printer. SEE ALSO: "print_options" "popen" CREATED BY: Davin Larson LAST MODIFICATION: @(#)pclose.pro 1.10 99/02/18
(See ssl_general/misc/pclose.pro)
FUNCTION: plot_positions PURPOSE: Procedure that will compute plot positions for multiple plots per page. Created by Davin Larson
(See ssl_general/misc/plot_positions.pro)
PROCEDURE: popen, filename
PURPOSE:
Change plot device to postscript.
INPUT: optional; if:
string : string used as filename, '.ps' extension is added automatically
integer X: filename set to 'plotX.ps'. value of x is incremented by 1.
none: filename set to 'plot.ps'
KEYWORDS: See print_options for info.
COPY: pass COPY keyword to set_plot
INTERP: pass INTERP keyword to set_plot (default is to have interp off)
XSIZE: postscript plot size in the x direction
YSIZE: postscript plot size in the y direction
UNITS: plot size units (inches or cm)
SEE ALSO: "pclose",
"print_options",
"popen_com"
HISOTRY:
4-apr-2008 cg, added optional keywords for postscript plot size
units for plot size variables
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)popen.pro 1.21 98/06/23
(See ssl_general/misc/popen.pro)
COMMON BLOCK: popen_com PURPOSE: Common block for print routines SEE ALSO: "popen","pclose", "print_options" CREATED BY: Davin Larson LAST MODIFICATION: @(#)popen_com.pro 1.10 97/12/05
(See ssl_general/misc/popen_com.pro)
PROCEDURE: printdat,[x] PURPOSE: Displays information and contents of a data variable. (Very similar to HELP procedure but much more verbose.) This routine is most useful for displaying contents of complex data structures. If printdat is called without arguments then information on all variables within the calling routine are displayed. POINTER occurences are recursively displayed as well. (only non-null pointers are listed) Keywords: FULL Set this keyword to display full variable output. NAMES = string: Optional list of variables to display (Same as for HELP) WIDTH: Width of screen (Default is 120). MAX: Maximum number of array elements to print. (default is 30) NSTRMAX Maximum number of structure elements to print. (default is 3) NPTRMAX Maximum number of structure elements to print. (default is 5) OUTPUT=string : named variable in which the output is dumped. VARNAME=string : [optional] name of variable to be displayed. (useful if input is an expression instead of a variable) RECURSEMAX = integer : Maximum number of levels to dive into. (Useful for limiting the output for heavily nested structures or pointers) Written by Davin Larson, May 1997. $LastChangedBy: davin-win $ $LastChangedDate: 2008-02-29 11:40:28 -0800 (Fri, 29 Feb 2008) $ $LastChangedRevision: 2431 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/printdat.pro $
(See ssl_general/misc/printdat.pro)
PROCEDURE: print_options
PURPOSE: controls postscript printing options
KEYWORDS:
PORT: print pages in portrait format (default)
LAND: print pages in landscape format
BW: Use black and white mode (untested)
COLOR: Use Color postscript (default)
XSIZE: plot size dimension in the x direction
YSIZE: plot size dimension in the y direction
UNITS: plot size units (inches or cm)
FUTURE OPTIONS:
Ecapsulated postscript format
changing plotting area
HISOTRY:
4-apr-2008 cg, added optional keywords for postscript
file size and file size units
SEE ALSO: "popen","pclose"
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)print_options.pro 1.16 97/05/30
(See ssl_general/misc/print_options.pro)
FUNCTION: PTRACE()
PURPOSE: Returns a string that provides the current program location.
KEYWORDS:
OPTION: The value of the option is retained in a common block
OPTION=0 : returns null string
OPTION=1 : returns highest level routine name.
OPTION=2 : returns highest level routine name (indented).
OPTION=3 : returns all levels
Usage: Generally useful for debugging code and following code execution.
Example:
if keyword_set(verbose) then print,ptrace(),'X=',x
Written: Jan 2007, D. Larson
(See ssl_general/misc/ptrace.pro)
NAME: ptr_extract Function: ptrs = ptr_extract(p,EXCEPT=EXCEPT) Purpose: Recursively searches the input (of any type) and returns an array of all pointers found. This is useful for freeing pointers contained within some complicated structure heirachy or pointer list. if no pointers are found then a scaler null pointer is returned. This routine ignores object pointers! Keywords: EXCEPTPTRS = an array of pointers that should not be included in the output. Created by Davin Larson. May 2002.
(See ssl_general/misc/ptr_extract.pro)
NAME:
pwrspc
PURPOSE:
Called with times time and data quantity, PWRSPC returns a power
spectrum power at frequencies freq. A Hanning window is applied to
the input data, and its power is divided out of the returned
spectrum. A straight line is subtracted from the data to
reduce spurius power due to sawtooth behavior of a background.
UNITS ARE (UNITS)^2 WHERE UNITS ARE THE UNITS OF quantity. freq
is in 1/timeunits.
THUS THE OUTPUT REPRESENTS THE MEAN SQUARED AMPLITUDE OF THE SIGNAL
AT EACH SPECIFIC FREQUENCY. THE TOTAL (SUM) POWER UNDER THE CURVE IS
EQUAL TO THE MEAN (OVER TIME) POWER OF THE OSCILLATION IN TIME DOMAIN.
NOTE: IF KEYWORD notperhz IS SET, THEN POWER IS IN UNITS^2. If notset
power is (as normal) in UNITS^2/Hz.
CALLING SEQUENCE:
pwrspc, time, quantity, freq, power, noline = noline, $
nohanning = nohanning, bin = bin, notperhz = notperhz
INPUT:
time = the time array
quantity = the function for which you want to obtain a power
spectrum
OUTPUT:
freq = the frequency array (units =1/time units)
power = the power spectrum, (units of quantity)^2/frequency_units
KEYWORDS:
noline = if set, no straight line is subtracted
nohanning = if set, then no hanning window is applied to the input
bin = a binsize for binning of the data, the default is 3
notperhz = if set, the output units are simply the square of the
input units
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/pwrspc.pro)
PROCEDURE: setbp, module
This procedure will set BREAKPOINTS at all lines within a program module
file that contain the string: ";bp"
A conditional break point is set with ;bpif condition statement
Input: module (string)
Purpose: This is a DEBUGGING tool that is used to set breakpoints.
Keywords:
/FUNCTION Set this keyword if module is a function.
Author: Davin Larson 2007
(See ssl_general/misc/setbp.pro)
PROCEDURE:
share_colors
PURPOSE:
Procedure that allows multiple IDL sessions to share the same color table.
The procedure should be called in each session before any
windows are created.
USAGE:
Typically this procedure will be put in a startup routine. such as:
share_colors,first=f
if f then loadct,39
KEYWORDS:
FIRST Named variable that will be set to 1 if this is the
first session, and set to 0 otherwise.
SIDE EFFECTS:
Creates a temporary file with the name 'idl_cmap:NAME' on the users home
directory where NAME is the name of the display machine.
This file is deleted upon exiting IDL.
The procedure is only useful on UNIX for users with a common home directory.
(See ssl_general/misc/share_colors.pro)
NAME:
smooth_in_time
PURPOSE:
Runs ts_smooth for irregular grids, after regularising grid
CALLING SEQUENCE:
ts = smooth_in_time(array, time_array, dt, /backward, /forward,
/double, /no_time_interp)
INPUT:
array = a data array, can be 2-d (ntimes, n_something_else), the
first index is smoothed or averaged.
time_array = a time array (in units of seconds)
dt = the averaging time (in seconds)
backward = if set, perform an average over the previous dt, the
default is to average from t-dt/2 to t_dt/2
forward = if set, perform an average over the next dt
double = if set, do calculation in double precision
regardless of input type. (If input data is double
calculation is always done in double precision)
no_time_interp = if set, do *not* interpolate the data to the
minimum time resolution. The default procedure is
to interpolate the data to a regularly spaced grid,
and then use ts_smooth to get the running
average. This alternative can be slow.
smooth_nans = if set, replace Nan values in the input array with the
average values calculated using the ts_smooth
process. This has not been implemented for the
no_time_interp option.
true_t_integration = if set, subtract 1/2 of the end points of the
integration from each value, to obtain the
value for an integration over time of the
appropriate interval. This has not been
implemented for the no_time_interp option.
Ths is created for the high_pass_filter.
interp_resolution = If time interpolation is being used, set this
option to control the number of seconds between
interpolated samples. The default is to use
the value of the smallest separation between
samples. Any number higher than this will sacrifice
output resolution to save memory. (NOTE: This option
will not be applied if no interpolation is being
performed because either (1) no_time_interp is set or
(2) the sample rate of the data is constant)
interactive_warning = if keyword is set pops up a message box if there are memory problems and asks
the user if they would like to continue
interactive_varname = set this to a string indicating the name of the quantity to be used in the warning message.
warning_result = assign a named variable to this keyword to determine the result of the computation
OUTPUT:
ts = the data array smoothed or averaged
HISTORY:
13-mar-2008, jmm, jimm@ssl.berkeley.edu, hacked from
high_pass_filter.pro and added ts_smooth as the default
13-mar-2008, ts_smooth is way too slow, just uses smooth.pro now
6-may-2008, jmm, added sort for input data for cases with
non-monotonic time_arrays
23-apr-2008, pcruce, Added padding for no_time_interp option, added _extra keyword
28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
mod to guarantee that precision of output is at least as
large as precision of input
$LastChangedBy: jimmpc $
$LastChangedDate: 2009-05-29 15:09:16 -0700 (Fri, 29 May 2009) $
$LastChangedRevision: 6003 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/smooth_in_time.pro $
(See ssl_general/misc/smooth_in_time.pro)
Procedure: space_bar
Purpose: generates a horizontal bar stored in a tplot variable
that is used to adjust the spacing between tplot variables
in plots
Arguments:
n(positional,required): a double representing the height
of the space bar
newname(keyword,optional): the name you want the bar to
have(default: 'space_bar')
$LastChangedBy: pcruce $
$LastChangedDate: 2008-01-17 14:37:52 -0800 (Thu, 17 Jan 2008) $
$LastChangedRevision: 2286 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $
(See ssl_general/misc/space_bar.pro)
NAME:
ssl_correlate_tplot
PURPOSE:
Identified the amount of shift required to correlate two
time series tplot variables and stores the result in a tplot
variable. Only compares 1-d to 1-d data at a time So for example you
can, compare the fge x and the fgl_x but can't do all three
at a time.
Works by binning the timeseries data, then calculating the
time shift required to maximally correlate each bin.
When too few points overlap bins are rejected.
CATEGORY:
THEMIS-SOC
CALLING SEQUENCE:
pro thm_correlate_tplot,var1_name, var1_y_dim, var2_name, var2_y_dim, store_name, correlation_floor = correlation_floor, point_number = point_number, lag_step_number = lag_step_number, time_step_size = time_step_size, bin_size = bin_size
INPUTS:
var1_name: the tplot name of the first variable to be compared
var1_y_dim: the numerical dimension of the first tplot y_var to look
at(from 0 to n-1)
var2_name: the tplot name of the second variable to be
compared
var2_y_dim: the numerical dimension of the second tplot y_var
to look at(from 0 to n-1)
store_name: the name of a tplot variable in which to store the result
correlation_floor: optional, if set filters all results where
the correlation between functions is too poor(default:.9)
point_number: optional, the minimum number of points of
overlap necessary to try correlating a bin(default:200)
lag_step_number: optional, checks plus or minus lag_steps * time steps
to correlate the vectors (default:64)
time_step_size: optional, the size of the time step to use when
interpolating and correlating the vectors, in
seconds(default:1/128 seconds)
bin_size: optional, the size of each bin in seconds
(default:60 seconds)
OUTPUTS:
stores the time and the shift values in the select tplot_var
KEYWORDS:
COMMENTS: This function will probably die horribly if time
values are not monotonic.
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
Written by: Patrick Cruce(pcruce@gmail.com)
2007-05-24 V1.0
;$LastChangedBy: pcruce $
$LastChangedDate: 2007-08-17 11:32:29 -0700 (Fri, 17 Aug 2007) $
$LastChangedRevision: 1439 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/ssl_correlate_tplot.pro $
KNOWN BUGS:
(See ssl_general/misc/ssl_correlate_tplot.pro)
NAME:
ssl_correlation_shift
PURPOSE:
Calculates the shift required to correlate two tme series of
data. Does this by binning the timeseries data, then
calculating the time shift required to maximally correlate each
bin. When too few points overlap bins are rejected.
CATEGORY:
THEMIS-SOC
CALLING SEQUENCE:
lag_time_series = thm_correlation_shift(var1_time_series,var2_time_series)
INPUTS:
var1_time_series: a 2xn matrix(column major) of n time/value pairs for var1
var2_time_series: a 2xn matrix(column major) of n time/value pairs for var2
n_pts: optional, the minimum number of points of overlap necessary to
try correlating a bin
lag_steps: optional, checks plus or minus lag_steps * time steps
to correlate the vectors
time_step: optional, the size of the time step to use when
interpolating and correlating the vectors
bin_size: optional, the size of each bin in seconds
OUTPUTS:
an 3xn matrix(column major) of time/shift/correlation triplets
or -1L on failure,
the output n is the number of bins constructed
KEYWORDS:
COMMENTS: This function will probably die horribly if time
values are not monotonic.
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
Written by: Jim Lewis
2007-04-19 Initial version
Updated by: Patrick Cruce(pcruce@gmail.com)
2007-05-22 V2.0
$LastChangedBy: pcruce $
$LastChangedDate: 2007-08-17 11:32:29 -0700 (Fri, 17 Aug 2007) $
$LastChangedRevision: 1439 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/ssl_correlation_shift.pro $
(See ssl_general/misc/ssl_correlation_shift.pro)
Purpose: Calculates the complement of l2 - l1
(ie set difference)
Arguments: l1 subset,l2 superset
Notes: empty set is -1L
all inputs must be empty set or arrays
all outputs will be empty set or arrays
Arrays must be of homogenous type
(See ssl_general/misc/ssl_set_complement.pro)
Purpose: Performs an intersection of two sets
Parameters: l1,l2 sets(arrays) for which the intersection is
calculated
Returns: -1L on empty set, otherwise intersection of the two sets
Notes: empty set is -1L
all inputs must be empty set or arrays
all outputs will be empty set or arrays
Arrays must be of homogenous type
(See ssl_general/misc/ssl_set_intersection.pro)
FUNCTION ssl_set_union(set1,set2)
Purpose: returns the union of two sets
Notes: empty set is -1L
all inputs must be empty set or arrays
all outputs will be empty set or arrays
Arrays must be of homogenous type
(See ssl_general/misc/ssl_set_union.pro)
PROCEDURE: ssl_time_check.pro PURPOSE: prints information about gaps between timestamps in cdf files INPUT: dir: The directory in which to search for cdfs out: the output directory for the limit files LIM: reassign the limit if you want it is a 2 element array MNEM: optional regex to filter timestamp mnems KEYWORDS: none COMMENTS: Will check all timestamps for all cdfs in the directory and output a seperate file for each type of timestamp. File format is: timestamp1 timestamp2 gap_size record_number currently it signals a gap if a gap is over 180 seconds or negative EXAMPLE: thm_time_check,'/','/dev/null' CREATED BY: Patrick Cruce (pcruce@gmail.com) $LastChangedBy: pcruce $ $LastChangedDate: 2007-08-17 11:32:29 -0700 (Fri, 17 Aug 2007) $ $LastChangedRevision: 1439 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/ssl_time_check.pro $
(See ssl_general/misc/ssl_time_check.pro)
FUNCTION str2time(string, informat=string)
INPUT: scaler string.
Returns seconds since 1970 given virtually any input string.
(Assumes the string is GMT)
The order of Year, Month, Date, hour, min, second is provided by INFORMAT
INFORMAT should be a 6 character string: "YMDhms" specifies Year/Mon/Date-hour:minute:second
examples: time = str2time(systime(),informat='MDhmsY')
time = str2time('tue, 04 jul 2006 19:00:04 gmt',informat='DMYhms')
(See ssl_general/misc/str2time.pro)
FUNCTION:
res = strfilter(stringarray,searchstring)
PURPOSE:
Returns the subset of stringarray that matchs searchstring
'*' will match all (non-null) strings
'' will match only the null string
Output can be modified with keywords
NOTE: this routine is very similar to the STRMATCH routine introduced in IDL 5.3
it has some enhancements that make it useful.
(i.e.: filterstring can also be an array)
INPUT:
stringarray: An array of strings to be filtered
searchstring: A string that may contain wildcard characters ("*")
(If searchstring is an array then results are OR'd together)
RETURN VALUE:
Either:
Array of matching strings.
or:
Array of string indices.
or:
Byte array with same dimension as input string.
Depends upon keyword setting (See below)
KEYWORDS:
FOLD_CASE: if set then CASE is ignored. (only IDL 5.3 and later)
STRING: if set then the matching strings are returned. (default)
INDEX: if set then the indices are returned.
BYTES: if set then a byte array is returned with same dimension as input string array (similar to STRMATCH).
NEGATE: pass only strings that do NOT match.
COUNT: A named variable that will contain the number of matched strings.
Limitations:
This function still needs modification to accept the '?' character
July 2000; modified to use the IDL strmatch function so that '?' is accepted for versions > 5.4
EXAMPLE:
Print,strfilter(findfile('*'),'*.pro',/negate) ; print all files that do NOT end in .pro
AUTHOR:
Davin Larson, Space Sciences Lab, Berkeley; Feb, 1999
VERSION: 01/10/08
(See ssl_general/misc/strfilter.pro)
NAME:
string_parser
PURPOSE:
Parse strings into components
CALLING SEQUENCE:
string_parser, inpx, parse_by, out, output_count
INPUT:
inpx strings to parse
parse_by character to parse by
OUTPUT:
out array of substrings
output_count number of substrings
HISTORY:
Updated 22-April-1993 by Terry Slocum
Fixed output_count bug, 28-mar-94, JMM
Gave the ability to use a parse_by string of more than one
character, jmm 13-jun-2007
(See ssl_general/misc/tuserdef.pro)
FUNCTION:
STRIPPATH
DESCRIPTION:
Function that strips off any directory components from a full
file path, and returns the file name and directory components
seperately in the structure:
{file_cmp_str,file_name:'file',dir_name:'dir'}
This is only implemented for UNIX at this time.
USAGE (SAMPLE CODE FRAGMENT):
; find file component of /usr/lib/sendmail.cf
stripped_file = STRIPPATH('/usr/lib/sendmail.cf')
The variable stripped_file would contain:
stripped_file.file_name = 'sendmail.cf'
stripped_file.dir_name = '/usr/lib/'
REVISION HISTORY:
$LastChangedBy: kenb-mac $
$LastChangedDate: 2006-12-15 08:13:48 -0800 (Fri, 15 Dec 2006) $
$LastChangedRevision: 97 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/strippath.pro $
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Oct. '92
Updated to use IDL 6.0 features for cross-platform usability.
(See ssl_general/misc/strippath.pro)
FUNCTION: struct_value(struc,name,default=default,index=index) PURPOSE: Returns the value of a structure element. Function equivalent to the procedure: "STR_ELEMENT" if "name" is an array then a new structure is returned with only the named values. Author: Davin Larson, 2006
(See ssl_general/misc/struct_value.pro)
PROCEDURE: str_element, struct, tagname, value
PURPOSE:
Find (or add) an element of a structure.
This procedure will not
Input:
struct, generic structure
tagname, string (tag name)
Output:
value, Named variable in which value of the structure element is returned.
Purpose:
Retrieves the value of a structure element. This function will not produce
an error if the tag and/or structure does not exist.
KEYWORDS:
SUCCESS: Named variable that will contain a 1 if the element was found
or a 0 if not found.
INDEX: a named variable in which the element index is returned. The index
will be -2 if struct is not a structure, -1 if the tag is not found,
and >= 0 if successful.
ADD_REPLACE: Set this keyword to add or replace a structure element.
DELETE: Set this keyword to delete the tagname.
CLOSEST: Set this keyword to allow near matchs (useful with _extra)
VALUE: (obsolete) alternate method of returning value. (Will not work with recursion)
Notes:
Value remains unchanged if the structure element does not exist.
If tagname contains a '.' then the structure is recursively searched and
index will be an array of indices.
If struct is an array then results may be unpredictable.
Examples:
Does an element exist?
str_element,my_str,'my_tag_name',SUCCESS=s
What is an element's value?
str_element,my_str,'my_tag_name',v
Add an element
str_element,my_str,'my_tag_name','value',/add
Modifications:
5/7/97: Added recursive searching of structure hierarchy. D. Larson
CREATED BY: Davin Larson
FILE: str_element.pro
VERSION 1.10
LAST MODIFICATION: 01/10/08
(See ssl_general/misc/str_element.pro)
FUNCTION: TAG_NAMES_R(STRUCTURE, [TYPE=dt] )
PURPOSE: Very similar to the TAG_NAMES function but recursively
obtains all structure names within imbedded structures as well.
INPUT: STRUCTURE: A structure typically.
If input is not a structure then a null string is returned
KEYWORDS:
TYPE=var; Named variable in which to return and array of data types.
RETURNS: Returns an array of strings
(See ssl_general/misc/tag_names_r.pro)
NAME:
tclip
PURPOSE:
wapper for xclip.pro allowing input of tplot variable names
CALLING SEQUENCE:
tclip, varnames, amin, amax, _extra=_extra
INPUT:
varnames = an array (or scalar) of tplot variable names
amin, amax = the minumum and maximum values
KEYWORDS:
flag = the value that clipped data are set to, the default is
-0.0/0.0 (NaN)
newname = if set,give these names to the clipped data, the
default is to append '_clip' to the input names and
pass out the names in the newname variables,
Unless /overwrite is set. This will not work for wild
card input.
overwrite = if set, write the new data back to the old tplot
variables, do not set this with newname
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tclip.pro)
NAME:
tdeflag
PURPOSE:
wapper for xdeflag.pro allowing input of tplot variable names
CALLING SEQUENCE:
tdeflag, varnames, method, newname=newname, $
overwrite = overwrite, _extra=_extra
INPUT:
varnames = an array (or scalar) of tplot variable names
method = set to "repeat", this will repeat the last good value.
set to "linear", then linear interpolation is used, but for
the edges, the closest value is used, there is no
extrapolation
KEYWORDS:
flag = the value that deflagged data will be set to, the default is
6.8792e28, Nan's, Inf's are also deflagged
maxgap = the maximum number of rows that can be filled? the default
is n_elements(t)
newname = if set,give these names to the deflagged data, the
default is to append '_deflag' to the input names and
pass out the names in the newname variables,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variables, do not set this with newname
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tdeflag.pro)
NAME:
tdegap
PURPOSE:
wrapper for xdegap.pro allowing input of tplot variable names
CALLING SEQUENCE:
tdegap, varnames, dt=dt, margin=margin, maxgap=maxgap,$
newname=newname, overwrite=overwrite
INPUT:
varnames = an array (or scalar) of tplot variable names
KEYWORDS:
dt = the nominal time resolution of the data that will be inserted,
the default is to choose the median of the input time array
margin = the margin used to determine if a gap is big enough, the
default is 0.25 seconds
maxgap = the maximum gap size that will be allowed to be filled, in
units of dt. the default is to set this to the max number
of data points
(TDEGAP degaps anything that is greater than dt+margin
and less than maxgap*dt)
newname = if set,give these names to the degapped data, the
default is to append '_degap' to the input names and
pass out the names in the newname variables,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variables, do not set this with newname
HISTORY:
9-apr-2007, jmm, jimm.ssl.berkeley.edu
10-oct-2008, jmm, Degaps v tags if necessary
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tdegap.pro)
Name: TDESPIKE_AE
Purpose: This routine removes artificial spikes. Note that it is
ONLY meant to be used for the calculation of the
'THEMIS AE index' in the overview plots.
Variable: lower = lower cutoff of spikes to be removed
upper = upper cutoff of spikes to be removed
Keywords: none
Example: tdespike_AE, -2000.0, 1500.0
Notes: Written by Andreas Keiling, 29 August 2007
$LastChangedBy: jimm $
$LastChangedDate: 2007-09-04 17:22:08 -0700 (Tue, 04 Sep 2007) $
$LastChangedRevision: 1537 $
$URL $
(See ssl_general/misc/tdespike_ae.pro)
NAME:
tdpwrspc
PURPOSE:
wapper for dpwrspc.pro allowing input of a tplot variable name
CALLING SEQUENCE:
tdpwrspc, varname, newname=newname,_extra=_extra
INPUT:
varname = one tplot variable name
KEYWORDS:
newname = if set,give this name to the new data, the
default is to append '_dpwrspc' to the input name and
pass out the name in the newname variable,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variable, do not set this with newname
HISTORY:
27-mar-2007, jmm, jimm.ssl.berkeley.edu
10-apr-2007, jmm, fixed 2 bugs wrt structure definition
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tdpwrspc.pro)
PROCEDURE: thigh_pass_filter, varname, dt, newname = newname
PURPOSE:
Uses high_pass_filter to calculate a running average of the input data and
store the data with the running average subtracted in an output tplot variable.
INPUT:
varname = variable passed to get_data, example - thg_mag_ccnv
dt = the averaging time (in seconds)
KEYWORDS:
newname: set output variable name
no_time_interp: Set to save memory by preventing interpolation of time
array when smoothing data before subtraction.
This option will probably be significantly slower.
double: Set so operation is performed at double precision
regardless of input type. (If input data is double
calculation is always done in double precision)
interp_resolution = If time interpolation is being used, set this
option to control the number of seconds between
interpolated samples. The default is to use
the value of the smallest separation between
samples. Any number higher than this will sacrifice
output resolution to save memory. (NOTE: This option
will not be applied if no interpolation is being
performed because either (1) no_time_interp is set or
(2) the sample rate of the data is constant)
interactive_warning = pops up a message box if there are memory problems and asks
the user if they would like to continue
warning_result = assign a named variable to this keyword to determine the result of the computation
HISTORY:
14-jan-2008, jmm, jimm@ssl.berkeley.edu
06-feb-2008, teq, teq@ssl.berkeley.edu
23-Apr-2009, pcruce, pcruce@igpp.ucla.edu, Added extra keyword support
28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
mod to guarantee that precision of output is at least as
large as precision of input
$LastChangedBy: jimmpc $
$LastChangedDate: 2009-05-29 15:09:16 -0700 (Fri, 29 May 2009) $
$LastChangedRevision: 6003 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/thigh_pass_filter.pro $
(See ssl_general/misc/thigh_pass_filter.pro)
Function: time_average
Calculates a bin based average over time series data
Uses a histogram internally so it should be pretty quick
Arguments:
time: the time array for the input timeseries
data: the data array for the input timeseries
newtime(optional): named variable in which to return the times
for each bin upon which an average is calculated
trange(optional): a time range over which the average is
performed
resolution(optional): the size of each bin in seconds
ret_total(optional): named variable in which totals for each
bin are returned
ret_min(optional): named variable in which mins for each bin
are returned
ret_med(optional): named variable in which medians for each
bin are returned
$LastChangedBy: pcruce $
$LastChangedDate: 2007-11-01 15:32:37 -0700 (Thu, 01 Nov 2007) $
$LastChangedRevision: 1911 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/time_average.pro $
(See ssl_general/misc/time_average.pro)
Procedure: time_clip
Purpose: clips a tplot variable between a start time and an end time
Inputs: tplot_var_name: the name of the variable to be clipped
start_time: the start time for the clipping(double or string)
end_time: the end time for the clipping(double or string)
Keywords:
newname(optional): the name of the output tplot variable
otherwise it will be tplot_var_name+'_tclip'
tvar(optional): set this keyword and start_time and
end_time will be interpreted as the names of tplot variables
The start and end times will then be taken from the first
and last component of the tplot variables listed
replace(optional): set this to replace the variable, rather than create
a new one
error(optional): set this to a named variable to return the
error status of the function, it will return 0 for no error
and 1 to signal an error. This may be set to true even if
the error was non fatal. Also if you are using globbing
to modify many tplot variables it will signal an error if
any of the variables failed
examples:
time_clip,'thb_fgs_gsm','2007-03-23/10:00:00','2007-03-23/12:00:00',newname='thb_fgs_gsm_10t12clip'
time_clip,'thb_peem_velocity','thb_fgs_gsm',thb_fgs_gsm',/tvar
$LastChangedBy: pcruce $
$LastChangedDate: 2008-01-03 13:53:59 -0800 (Thu, 03 Jan 2008) $
$LastChangedRevision: 2224 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/idl_socware/trunk/external/IDL_GEOPACK/trace/ttrace_crib.pro $
(See ssl_general/misc/time_clip.pro)
FUNCTION: time_double(time) NAME: time_double PURPOSE: A fast, vectorized routine that returns the number of seconds since 1970. INPUT: input can be any of the following types: double(s) seconds since 1970 (returns the input) string(s) format: YYYY-MM-DD/hh:mm:ss see "time_string" structure(s) format returned in "time_struct" long array (MUST be 2 dimensional!) PB5 time (req. by CDF) OUTPUT: double, number of seconds since 1970 (UNIX time) KEYWORDS: EPOCH: if set, it implies the input is double precision EPOCH time. SEE ALSO: "time_string", "time_struct", "time_epoch", "time_pb5" NOTE: This routine works on vectors and is designed to be fast. Output will have the same dimensions as the input Out of range values are interpreted correctly. ie. 1994-13-1/12:61:00 will be treated as: 1995-1-1/13:01:00 CREATED BY: Davin Larson Oct 1996 FILE: time_double.pro VERSION: 1.9 LAST MODIFICATION: 01/07/12
(See ssl_general/misc/time_double.pro)
NAME: time_epoch PURPOSE: Returns the EPOCH time required by CDF files. USAGE: epoch = time_epoch(t) NOT TESTED!!! CREATED BY: Davin Larson Oct 1996 FILE: time_epoch.pro VERSION: 1.1 LAST MODIFICATION: 96/10/16
(See ssl_general/misc/time_epoch.pro)
NAME: time_pb5 PURPOSE: Returns the PB5 time required by CDF files. USAGE: pb5 = time_pb5(t) OUTPUT: 2 dimensional long integer array with dimensions: (n,3) Where n is the number of elements in t Not fully TESTED!!!! CREATED BY: Davin Larson Oct 1996 FILE: time_pb5.pro VERSION: 1.3 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/time_pb5.pro)
PROCEDURE: time_stamp,charsize=charsize
PURPOSE:
Prints a time stamp along the lower right edge of the current plot box
KEYWORDS:
CHARSIZE: The character size to be used. Default is !p.charsize/2.
ON: if set, then timestamping is turned on. (No other action taken)
OFF: if set, then timestamping is turned off. (Until turned ON)
(See ssl_general/misc/time_stamp.pro)
FUNCTION: time_string(TIME)
NAME:
time_string
PURPOSE:
Converts time to a date string.
INPUTs:
TIME input can be a scalar or array of any dimension of type:
double(s) seconds since 1970
string(s) format: YYYY-MM-DD/hh:mm:ss
structure(s) format: given in "time_struct"
float(s)
longs(s)
values outside normal range will be corrected.
KEYWORDS:
LOCAL_TIME ; if set then local time is displayed.
TFORMAT: a format string such as: "YYYY-MM-DD/hh:mm:ss.ff DOW TDIFF"
the following tokens are recognized:
YYYY - 4 digit year
yy - 2 digit year
MM - 2 digit month
DD - 2 digit date
hh - 2 digit hour
mm - 2 digit minute
ss - 2 digit seconds
.fff - fractional seconds
MTH - 3 character month
DOW - 3 character Day of week
DOY - 3 character Day of Year
TDIFF - 5 character, hours different from UTC (useful with LOCAL keyword)
if TFORMAT is defined then the following keywords are ignored.
FORMAT: specifies output format.
FORMAT=0: YYYY-MM-DD/hh:mm:ss
FORMAT=1: YYYY Mon dd hhmm:ss
FORMAT=2: YYYYMMDD_hhmmss
FORMAT=3: YYYY MM dd hhmm:ss
FORMAT=4: YYYY-MM-DD/hh:mm:ss
FORMAT=5: YYYY/MM/DD hh:mm:ss
FORMAT=6: YYYYMMDDhhmmss
SQL: produces output format: "YYYY-MM-DD hh:mm:ss.sss"
(quotes included) which convenient for building SQL queries.
PRECISION: specifies precision
-5: Year only
-4: Year, month
-3: Year, month, date
-2: Year, month, date, hour
-1: Year, month, date, hour, minute
0: Year, month, date, hour, minute, sec
>0: fractional seconds
AUTOPREC If set PREC will automatically be set based on the array of times
DELTAT: (float) PREC set based on this precision.
DATE_ONLY: Same as PREC = -3
MSEC: Same as PREC = 3
OUTPUT:
string with the following format: YYYY-MM-DD/hh:mm:ss (Unless
modified by keywords.)
See Also: "time_double" , "time_struct" or "time_ticks"
NOTE:
This routine works on vectors and is designed to be fast.
Output will have the same dimensions as the input.
CREATED BY: Davin Larson Oct 1996
FILE: time_string.pro
VERSION: 1.14
LAST MODIFICATION: 02/11/01
(See ssl_general/misc/time_string.pro)
FUNCTION: time_struct(time) NAME: time_struct PURPOSE: A fast, vectorized routine that returns a time structure. INPUT: input can be any of the following types: double(s) seconds since 1970 string(s) format: YYYY-MM-DD/hh:mm:ss structure(s) similar to format below. OUTPUT: structure with the following format: ** Structure TIME_STRUCT, 11 tags, length=40: YEAR INT 1970 ; year (0-14699) MONTH INT 1 ; month (1-12) DATE INT 1 ; date (1-31) HOUR INT 0 ; hours (0-23) MIN INT 0 ; minutes (0-59) SEC INT 0 ; seconds (0-59) FSEC DOUBLE 0.0000000 ; fractional seconds (0-.999999) DAYNUM LONG 719162 ; days since 0 AD (subject to change) DOY INT 0 ; day of year (1-366) DOW INT 3 ; day of week (subject to change) SOD DOUBLE 0.0000000 ; seconds of day DST = INT = 0 ; Daylight saving time flag TZONE = INT = 0 ; Timezone (Pacific time is -8) TDIFF = INT = 0 ; Hours from UTC See Also: "time_double", "time_string", "time_epoch", "time_pb5" NOTE: This routine works on vectors and is designed to be fast. Output will have the same dimensions as the input CREATED BY: Davin Larson Oct 1996 FILE: time_struct.pro VERSION: 1.15 LAST MODIFICATION: 02/11/01
(See ssl_general/misc/time_struct.pro)
FUNCTION: time_tk_str = time_ticks(timerange,offset)
NAME:
time_ticks
PURPOSE:
Returns a structure that can be used to create time ticks for a plot.
See "timetick" for more info
INPUT:
timerange: Two element vector specifying the time range of the plot
this input can be obtained from: "time_double", "time_struct"
or "time_string"
offset: named variable in which offset time is placed.
KEYWORDS:
NUM_LAB_MIN: minimum number of labels for bottom axis.
OUTPUT:
a structure that can be used with the _EXTRA keyword of the PLOT routine
See Also: "box", "tplot"
NOTES:
The returned time_tk_str has tags named so that it can be used
with the special _EXTRA keyword in the call to PLOT or OPLOT.
The offset value that is returned from timetick must be
subtracted from the time-axis data values before plotting.
This is to maintain resolution in the PLOT routines, which use
single precision floating point internally. Remember that if
the CURSOR routine is used to read a cursor position from the
plot, this offset will need to be added back to the time-axis
value to get seconds since 1970-01-01/00:00:00.
NOTE:
This routine is an enhanced version of the routine "timetick"
See this routine for more info on usage
WARNING!:
This routine does not yet work on very small time scales.
CREATED BY: Davin Larson Oct 1996
FILE: time_ticks.pro
VERSION: 1.16
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/time_ticks.pro)
Procedure: tKm2Re
Purpose: Converts a variable to RE or KM
Inputs: name: a string naming the tplot variable to be modified
globbing may be used
Keywords:
newname: set this keyword to a string to store the
output in(only works when globbing is not used)
suffix: set this keyword to a string indicating the
suffix to be appended to the input variable(s)
/replace: set this option to replace the variable being modified
/KM : converts to KM from RE rather than to RE from KM
examples:
tKm2Re,'thb_state_pos'
tKm2Re,'thb_state_pos',/replace
tKm2Re,'thb_state_pos',/KM
tKm2Re,'thb_state_pos',newname='pos_in_re'
tKm2Re,'th?_state_pos',suffix='_converted'
NOTES: Uses conversion of 6374.4 KM/RE
By default output will be called: input_name+'_RE'
$LastChangedBy: pcruce $
$LastChangedDate: 2008-07-30 17:43:17 -0700 (Wed, 30 Jul 2008) $
$LastChangedRevision: 3320 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/tkm2re.pro $
(See ssl_general/misc/tkm2re.pro)
NAME:
tpwrspc
PURPOSE:
wapper for pwrspc.pro allowing input of a tplot variable name
CALLING SEQUENCE:
tpwrspc, varnames, newname=newname,_extra=_extra
INPUT:
varname = one tplot variable name
KEYWORDS:
newname = if set,give this name to the new data, the
default is to append '_pwrspc' to the input name and
pass out the name in the newname variable,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variable, do not set this with newname
HISTORY:
27-mar-2007, jmm, jimm.ssl.berkeley.edu
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tpwrspc.pro)
FUNCTION: trange_str,t1,t2 INPUT: t1,t2 doubles, seconds since 1970 OUTPUT: string with the format: 'YYYY-MM-DD/HH:MM:SS - HH:MM:SS' CREATED BY: Davin Larson LAST MODIFICATION: @(#)trange_str.pro 1.10 97/12/22
(See ssl_general/misc/trange_str.pro)
PROCEDURE: tsmooth_in_time, varname, dt, newname = newname PURPOSE: Calls smooth_in_time function on a plot variable INPUT: varname = variable passed to get_data, example - thg_mag_ccnv dt = the averaging time (in seconds) KEYWORDS: newname: set output variable name HISTORY: 11-apr-2008, jmm, jimm@ssl.berkeley.edu $LastChangedBy: jimm $ $LastChangedDate: 2008-04-14 10:45:33 -0700 (Mon, 14 Apr 2008) $ $LastChangedRevision: 2706 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/tsmooth_in_time.pro $
(See ssl_general/misc/tsmooth_in_time.pro)
NAME:
tsub_average
PURPOSE:
Subtracts average or median values from the data in a tplot
variable, returns a new variable, only one at a time for now
CALLING SEQUENCE:
tsub_average, varname, out_name, new_name=new_name,median=median
INPUT:
varname = a tplot variable name
OUTPUT:
out_name = variable name of the output tplot variable
KEYWORDS:
new_name = can be used to input the new variable name, if not input
the default is to add a '-d' to the input name (or '-m' for median
subtraction) and the name is passed out in this variable
HISTORY:
18-jul-2007, jmm, jimm@ssl.berkeley.edu
02-nov-2007, jmm, Fixed bug for variables with no data.
06-may-2008, jmm, Fixed problem, by changing non-float and
non-double datatypes to floats
$LastChangedBy: $
$LastChangedDate: $
$LastChangedRevision: $
$URL: $
(See ssl_general/misc/tsub_average.pro)
Procedure: tvectot(tplot vector total)
Purpose: Add or remove the magnitude of a vector to a tplot quantity
Inputs: name: a string naming the tplot variable to be modified, may
use regex
Keywords: /remove: set this keyword to remove the magnitude from
vector
newname: set this keyword to a string to store the(this
option will not work properly if regex is used)
output in a different variable instead of overwriting
tot: set this keyword to a named variable to store
the magnitude as an array or set it to a string to store
the magnitude as a tplot variable(this option will not
work properly if regex is used)
examples:
tvectot,'tha_fgs_dsl'
tvectot,'tha_fgs_dsl',/remove
tvectot,'tha_fg*_dsl'
tvectot,'tha_fgs_dsl',newname='tha_fgs_dsl_mag'
tvectot,'tha_fgs_dsl',tot=var
tvectot,'tha_fgs_dsl',tot='mag_t_var'
$LastChangedBy: pcruce $
$LastChangedDate: 2008-01-24 13:48:09 -0800 (Thu, 24 Jan 2008) $
$LastChangedRevision: 2312 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/tvectot.pro $
(See ssl_general/misc/tvectot.pro)
NAME:twavpol
PURPOSE:To perform polarisation analysis of three orthogonal component time
series data, using tplot variables.
EXAMPLE: twavpol,'in_data',prefix='in_data',freqline=fl
INPUTS: tvarname: the name of the tplot variable upon which it will
operate
prefix(optional): the prefix to be assigned to the tplot variables that will be
output, defaults to tvarname
Subroutine assumes data are in righthanded fieldaligned
coordinate system with Z pointing the direction
of the ambient magnetic field.
OUTPUTS:
error(optional): named variable in which to return the
error state of this procedure call. 1 = success, 0 = failure
freqline(optional): assign a named variable to this keyword
to store the frequencies of each y-index
timeline(optional): assign a named variable to this keyword
to store the times of each x-index
The program outputs five spectral results derived from the
fourier transform of the covariance matrix (spectral matrix)
This version stores these outputs as tplot variables with the
specified prefix
These are follows:
Wave power: On a linear scale, at this stage no units
Degree of Polarisation:
This is similar to a measure of coherency between the input
signals, however unlike coherency it is invariant under
coordinate transformation and can detect pure state waves
which may exist in one channel only.100% indicates a pure
state wave. Less than 70% indicates noise. For more
information see J. C. Samson and J. V. Olson 'Some comments
on the description of the polarization states
of waves' Geophys. J. R. Astr. Soc. (1980) v61 115-130
Wavenormal Angle:
the angle between the direction of minimum
variance calculated from the complex off diagonal
elements of the spectral matrix and the Z direction
of the input
ac field data. For magnetic field data in
field aligned coordinates this is the
wavenormal angle assuming a plane wave.
Ellipticity:The ratio (minor axis)/(major axis) of the
ellipse transcribed by the field variations of the
components transverse to the Z direction. The sign
indicates the direction of rotation of the field vector in
the plane. Negative signs refer to left-handed
rotation about the Z direction. In the field
aligned coordinate system these signs refer to
plasma waves of left and right handed
polarisation.
Helicity:Similar to Ellipticity except defined in terms of the
direction of minimum variance instead of Z. Stricltly the Helicity
is defined in terms of the wavenormal direction or k.
However since from single point observations the
sense of k cannot be determined, helicity here is
simply the ratio of the minor to major axis transverse to the
minimum variance direction without sign.
NOTES:
1. Although the input is in the form of a tplot variable, the
output is currently in the form of arrays
2. -If one component is an order of magnitude or more greater than
the other two then the polarisation results saturate and erroneously
indicate high degrees of polarisation at all times and
frequencies.
3. Time series should be eyeballed before running the program.
For time series containing very rapid changes or spikes
the usual problems with Fourier analysis arise.
Care should be taken in evaluating degree of polarisation results.
4. For meaningful results there should be significant wave power at the
frequency where the polarisation approaches
100%. Remembercomparing two straight lines yields 100% polarisation.
$LastChangedBy: pcruce $
$LastChangedDate: 2007-11-11 16:40:33 -0800 (Sun, 11 Nov 2007) $
$LastChangedRevision: 2025 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/special/fac/fac_matrix_make.pro $
(See ssl_general/misc/twavpol.pro)
NAME: undefined PURPOSE: Tests whether a variable is undefined CALLING SEQUENCE: if ~undefined(var) then print,'Hooray!' INPUT: var: A variable to be tested OUTPUT: 1 on success, 0 on fail $LastChangedBy: pcruce $ $LastChangedDate: 2008-07-28 11:53:49 -0700 (Mon, 28 Jul 2008) $ $LastChangedRevision: 3311 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/undefined.pro $
(See ssl_general/misc/undefined.pro)
NAME:wavpol
MODIFICATION HISTORY:Written By Chris Chaston, 30-10-96
:Modified by Vassilis, 2001-07-11
PURPOSE:To perform polarisation analysis of three orthogonal component time
series data.
EXAMPLE: wavpol,ct,Bx,By,Bz,timeline,freqline,powspec,degpol,waveangle,elliptict,helict
CALLING SEQUENCE: wavpol,ct,Bx,By,Bz,timeline,freqline,powspec,degpol,waveangle,elliptict,helict
INPUTS:ct,Bx,By,Bz, are IDL arrays of the time series data; ct is cline time
Subroutine assumes data are in righthanded fieldaligned
coordinate system with Z pointing the direction
of the ambient magnetic field.
threshold:-if this keyword is set then results for ellipticity,
helicity and wavenormal are set to Nan if below 0.6 deg pol
OUTPUTS: The program outputs five spectral results derived from the
fourier transform of the covariance matrix (spectral matrix)
These are follows:
Wave power: On a linear scale, at this stage no units
Degree of Polarisation:
This is similar to a measure of coherency between the input
signals, however unlike coherency it is invariant under
coordinate transformation and can detect pure state waves
which may exist in one channel only.100% indicates a pure
state wave. Less than 70% indicates noise. For more
information see J. C. Samson and J. V. Olson 'Some comments
on the description of the polarization states
of waves' Geophys. J. R. Astr. Soc. (1980) v61 115-130
Wavenormal Angle:
the angle between the direction of minimum
variance calculated from the complex off diagonal
elements of the spectral matrix and the Z direction
of the input
ac field data. For magnetic field data in
field aligned coordinates this is the
wavenormal angle assuming a plane wave.
Ellipticity:The ratio (minor axis)/(major axis) of the
ellipse transcribed by the field variations of the
components transverse to the Z direction. The sign
indicates the direction of rotation of the field vector in
the plane. Negative signs refer to left-handed
rotation about the Z direction. In the field
aligned coordinate system these signs refer to
plasma waves of left and right handed
polarisation.
Helicity:Similar to Ellipticity except defined in terms of the
direction of minimum variance instead of Z. Stricltly the Helicity
is defined in terms of the wavenormal direction or k.
However since from single point observations the
sense of k cannot be determined, helicity here is
simply the ratio of the minor to major axis transverse to the
minimum variance direction without sign.
RESTRICTIONS:-If one component is an order of magnitude or more greater than
the other two then the polarisation results saturate and erroneously
indicate high degrees of polarisation at all times and
frequencies. Time series should be eyeballed before running the program.
For time series containing very rapid changes or spikes
the usual problems with Fourier analysis arise.
Care should be taken in evaluating degree of polarisation results.
For meaningful results there should be significant wave power at the
frequency where the polarisation approaches
100%. Remembercomparing two straight lines yields 100% polarisation.
$LastChangedBy: pcruce $
$LastChangedDate: 2007-11-11 16:40:33 -0800 (Sun, 11 Nov 2007) $
$LastChangedRevision: 2025 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/special/fac/fac_matrix_make.pro $
(See ssl_general/misc/wavpol.pro)
PROCEDURE: wi, wnum PURPOSE: Switch or open windows. INPUT: wnum - the window number. CREATED BY: REE, 95-10-23 completely rewritten by DEL 2006 FILE: wi.pro VERSION: 1.6 LAST MODIFICATION: 97/06/03
(See ssl_general/misc/wi.pro)
xclip
PURPOSE:
Replaces with FLAGs the values of the array that are BEYOND
the limits specified.
CALLING SEQUENCE:
xclip, amin, amax, y, flag=flag, _extra=_extra
INPUT:
amin, amax = the minumum and maximum values
y = the input array
OUTPUT:
y = set to flag for points less than amin or greater than amax
KEYWORDS:
flag = the value that clipped data will be set to, the default is
-0.0/0.0 (NaN)
clip_adjacent = if set, then clip the vales adjacent to the bad
ones, as in tdespike_ae.pro
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis'
clip_deflag.pro
9-feb-2007, change big value to Nan
9-oct-2007, added option to clip the points adjacent to the bad
ones, as in tdespike_ae.pro
20-Oct-2007, Jmm, Added this comment to test commit comand
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/xclip.pro)
xdeflag
PURPOSE:
Replaces FLAGs in arrays with interpolated or other values
CALLING SEQUENCE:
xdeflag, method, t, y, flag=flag, _extra=_extra
INPUT:
method = set to "repeat", this will repeat the last good value.
set to "linear", then linear interpolation is used, but for
the edges, the closest value is used, there is no
extrapolation
t = time array, in any useable tplot format
y = the input array, n_elements(t) by n
OUTPUT:
y = either interpolated or repated, where the value is > 0.98*flag,
or NaN
KEYWORDS:
flag = the value that flagged data are set to, the default is
6.8792e28
maxgap = the maximum number of rows that can be filled? the default
is n_elements(t)
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis' clip_deflag.pro
$LastChangedBy: $
$LastChangedDate: $
$LastChangedRevision: $
$URL$
(See ssl_general/misc/xdeflag.pro)
NAME: xdegap PURPOSE: Locates gaps in data, and fills in with NaN This subroutine accepts the time array (can be cline time) t and the multi-dimensional array yarr that matches with the time array. It outputs the same arrays but with a different number of rows depending on how many rows were added. It then figures out where to add rows by checking which time differences are greater than or equal to deltat plus a margin and adds an array of rows of equispaced times of size tstep=gap/(number_of_points_that_fit_with_minimum_cumulative_error). The same number of rows is added to yarr with values equal to FLAGs. NOTE: ARRAYS AND STRUCTURES THAT NEED DEGAPPING ARE REDEFINED TO BE LARGER THAN BEFORE. THUS THE TIME COLUMN THAT HAS BEEN DEGAPPED WILL NOT CORRESPOND TO THE ELEMENTS OF AN ARRAY THAT HAS NOT BEEN DEGAPPED. CAUTION: DEGAP ALL ARRAYS OR STRUCTURES YOU ARE GOING TO USE TOGETHER, I.E., WITH ONE DEGAP CALL. ADDITIONAL NOTE: To conserve memory, see the ONENANPERGAP keyword. CALLING SEQUENCE: xdegap, dt, margin, ct, y, ct_out, y_out [,/nowarning] [,maxgap = <value>] [,iindices=<variable>] [,/onenanpergap] INPUT: dt = the time interval for tests margin = the margin ct = the input time array y = the input array, can be 1 or 2d (n_elements(ct), m) OUTPUT: ct_out = the output time array, y_out = the input time array KEYWORDS: nowarning = if set, suppresses warnings maxgap = the maximum gap size filled, in seconds iindicies = the indices in the output arrays that contain the original data onenanpergap = Fill gaps with only one NaN -> useful for conserving memory. Also, for reference concerning post-processing, the INTERPOL function propagates a single NaN just as it would many NaNs. HISTORY: From Vassilis' degap.pro, 2-apr-2007, jmm, jimm@ssl.berkeley.edu bug fix for undefined variable, jmm, 24-jun-2007 Switched maxgap to seconds, jmm, 26-oct-2007 Added comment to test svn version 4_00, jmm, 28-apr-2008 Added ONENANPERGAP kw, W.M.F., 5 May, 2009. $LastChangedBy$ $LastChangedDate$ $LastChangedRevision$ $URL$
(See ssl_general/misc/xdegap.pro)
NAME: fancompress PURPOSE: Decimates polylines in an aesthetically pleasing fashion. CALLING SEQUENCE: outidx = fancompress(inpts,err) INPUT: inpts: N x 2 dimension array, where inpts[*,0] are the x components of the polyline and inpts[*,1] are the y components of the polyline err: The amount of error allowed before including a point OUTPUT: An array of indexes into inpts. Indices will range from 0 to N-1. First and Last points are always included. NOTES: 1. Based almost entirely on the paper: Fowell, Richard A. and McNeil, David D. , “Faster Plots by Fan Data-Compression,” IEEE Computer Graphics & Applications, Vol. 9, No. 2,Mar. 1989, pp. 58-66. 2. One modification from published algorithm, handles NaNs by always including the point before a group of NaNs, 1 NaN and the point after the NaNs. This ensures that gaps will be drawn accurately. 3. Algorithm is fairly slow, because it requires 1 pass over all data points. Optimizing this algorithm by divide and conquer, vectorization, or dlm may be a worthwhile use of time in the future. $LastChangedBy: jimmpc $ $LastChangedDate: 2009-05-29 15:09:16 -0700 (Fri, 29 May 2009) $ $LastChangedRevision: 6003 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_5_1/misc/fancompress.pro $
(See ssl_general/misc/fancompress.pro)