Wind Library Description and Tutorial

Contents

This page is in html format and can be seen by running:
netscape $IDL_3DP_DIR/3dp_header.html &
This page is called from $IDL_3DP_DIR/help_central.html. Please view this document for other related information.

Created by: Davin Larson June 1995
HTML format by Jasper Helekas: August 1995
File: 3dp_header.html
Version: 1.9
Last Modified: 95/09/13

DESCRIPTION

This software package is a collection of functions and procedures that are written in IDL to facilitate the analysis of WIND 3DP data. It is NOT a self-contained program AND NEVER WILL BE! This software is designed to allow the user to be very close to the data, allowing for easy data manipulations that are essential for data analysis. This concept may make the software slightly more difficult to use for the casual data browser, but I believe the flexibility of this code will make it much easier for detailed analysis of the data as well as further code development.

IDL is an interactive, command based, language. This feature is retained with these software tools. It is assumed that the user of this software will have at least a superficial knowledge of how to use IDL. (Sorry, no spoon feeding is currently provided!) New commands can be easily created by writing new procedures. It is expected that the users of this package will contribute new commands. Command sequences can also be written to a file and executed in batch mode if desired.

This software has been written for UNIX only! Filenames follow the UNIX naming convention. It may be possible to make the code more portable, but don't expect this any time soon.

Good Luck!

Back to the top of this tutorial

GETTING STARTED

IDL can be started by typing: 
	idl start3dp
at the UNIX prompt. This will initialize some variables and give the prompt "3dp> ".

The following hints may aid you in your work:

HINT: I recommend using an "xterm" window that is running a "tcsh" shell. This is not required, but it makes text editing within IDL a little bit easier. To start an "xterm" window, type: 

	xterm &
at the UNIX prompt within a "cmdtool" or "shelltool" window. Alternatively, Your workspace can be modified to allow an "xterm" to be chosen from the "Programs" menu of the workspace. (The "xterm" window must be started prior to running IDL.)

HINT: If viewing this page using a browser, such as netscape or mosaic, you can click on any highlighted text to get documentation on that procedure.

HINT: If using openwindows, you can quickly run each example step if you have two windows open: One window should display this text (Using netscape or mosaic), the other window should be running IDL (using an xterm). This document has been written so that example text can first be selected by dragging the mouse across the desired line(s), and then pasted into the IDL window by pressing the middle mouse button when the arrow is within the idl command window.
Example text is always given on indented lines in the following tutorial.

HINT: Occasionally when an error is encountered, IDL is left running at the subroutine level and previously defined variables will "disappear". In order to return to the main level you will need to type: 

	retall
Your variables should then reappear.

Back to the top of this tutorial

LOADING DATA

Using for example, Feb 10, 1995, type the following after the prompt: 
	load_3dp_data,'95-2-10'
or
	load_3dp_data
	95-2-10
	24
or
	load_3dp_data,'95-2-10',4.  ; loads 4 hours of data
The last example will load only 4 hours worth of data instead of the default 24 hours. Data can be split over day boundaries as well.

Back to the top of this tutorial

TIME PLOTS

First get some data: 
	get_pmom  ;retrieve 24 hours of pesa moment data
plot the data: 
	tplot,['Np','Tp','Vp']
Other useful parameters can be plotted by first running the following procedures: 
	get_emom    ;gets esa moment data
	get_spec, string ('eh','el','ph','pl','so', or 'sf')
	get_swe     ;get SWE key parameter data
	get_mfi     ;get MFI key parameter data
	get_3dp     ;get 3DP key parameter data

Back to the top of this tutorial

CHANGING TIME PLOT LIMITS

To change the time limits: 

	tlimit,3,5    ;plot from 3 to 5 am.
or use the cursor to select a time span: 
	tlimit        ; Use the cursor.
To change the y-axis limits from .1 to 100 with a logrithmic scale: 
	ylim,'Np',.1,100, 1
You can use the cursor to select the upper and lower limits if ylim is called without any parameters: 
	ylim
Use the cursor to click below and then above the plot box to restore the autoranging ability.

Back to the top of this tutorial

CHANGING TIME PLOT OPTIONS

IDL has many useful plotting keywords that can be passed to the plot routine. These keywords can also be used in the tplot procedure as well. For example to change the plot symbol: 

	options,'Np','psym',-4  ; change the plotting symbol
to average over 5 points before plotting the data, set the nsum keyword: 
	options,'Np','nsum',5
See the IDL manual to learn about other plotting keywords.

Back to the top of this tutorial

SPECTROGRAM PLOTS

Instead of line plots, you can generate spectrograms of some kinds of data, also using the tplot procedure.: Get data: 
	get_spec,'el'
Tell the tplot routine that a spectrogram type plot is desired by adding the spec tag to the elspec structure with a value of 1: 
	options,'elspec','spec',1
Plot the spectrogram: 
	tplot,['elspec']
To see x and y profiles of the spectrogram, type: 
	cuts
Change the color range: 
	clim,'elspec',1e4,1e5,1 ;also changes to logrithmic color scale

Back to the top of this tutorial

SCATTER PLOTS

It is sometimes useful to make scatter plots to see correlations between diferent variables: 
	scat_plot,'Ne','Te'
To see the correlation between three variables, add a third variable, and the colors of the scatter plot will be scaled according to this variable. 
	scat_plot,'Ne','Np','Tp'
To have scat_plot plot points instead of lines: 
	options,lim,'psym',3
	scat_plot,'Ne','Np','Tp',limits = lim

Back to the top of this tutorial

CREATING YOUR OWN DATA QUANTITIES

It may be somewhat mysterious how data such as 'elspec' and 'Ne' is stored after you get it with the get_spec, get_emom or other such routines.

The data is actually stored in memory, but it is referenced by a name such as 'Ne' or 'elspec' which actually corresponds to a handle to the data.

So to directly manipulate the data, you need some way of getting it from these structures stored in memory and referenced by handles. There are procedures to get the data, manipulate it, and store it again in a format in which tplot can plot it.

For example, if you wanted to calculate thermal velocity from temperature: Get the data from where it is stored and put it in a structure called dat: 

	get_data,'Te', data = dat

The data will be something like this:
 	help,dat,/str
** Structure <1b40778>, 3 tags, length=39944, refs=2:
   YTITLE          STRING    'Te'
   X               DOUBLE    Array(3328)
   Y               FLOAT     Array(3328)

Here dat.x is time, and dat.y is temperature (energy)

Calculate velocity:
	vel = sqrt(2*dat.y/mass)

Store the new data as a different variable, but with same x element:
	dat2 = {ytitle:'Vth', x: dat.x, y:vel}
	store_data, 'Vth', data = dat2

Plot it up:
	tplot,['Vth']

At any time you can find what variables are stored and their time ranges:
	print_data_names

Back to the top of this tutorial

SELECTING A REFERENCE TIME

In order to get a single data sample. You must first select the time of interest. All time values are double precision floats representing the number of seconds since 1970. Type: 
	t = gettime('2:15')   ; set time to hour 2.25 (2:15 am) 
or
	t = gettime(2.25)
or      
        t = gettime(/key) ;  prompt for a time
        2:15
The previous commands will select a time based on the reference date set by the tplot_options procedure. This reference date is typically set by the procedure that loads the data. If you wish, the full date can be entered: 
	t= gettime('95-2-10/2:15')

If you have already plotted data using tplot, then you can use the cursor to select a time: 

	t = gettime(/curs)	;click on plot window for t
Conversion between double precision time and strings is accomplished with the subroutines time_to_str and str_to_time. ie.: 
	print,time_to_str(t)

Back to the top of this tutorial

GETTING 3D DATA

Define a new variable, "el", a structure that contains all necessary info for a single sample of 3d data. In this case eesa low data. type: 
	el = get_el(t)    ;  EESA LOW data
The get_el(t) routine will get the next data sample after "t" and then set "t" to the starting time of that sample. Repetitive calls of the type: 
	el = get_el(t)
Will get each succesive sample of data. functions similar to get_el(): 
	dat = get_pl(t)    ; PESA LOW data
	dat = get_ph(t)    ; PESA HIGH data
	dat = get_eh(t)    ; EESA HIGH data
        dat = get_sf(t)    ; SST FOIL
        dat = get_so(t)    ; SST OPEN

Back to the top of this tutorial

EXAMINING 3D DATA

To determine info on the structure variable "el", Use the IDL command: 
	help,el,/str
you will see something like: 
** Structure <1d32690>, 24 tags, length=30016, refs=1:
   PROJECT_NAME    STRING    'Wind 3D Plasma'
   DATA_NAME       STRING    'Eesa Low'
   UNITS_NAME      STRING    'Counts'
   TIME            DOUBLE       7.9238253e+08
   END_TIME        DOUBLE       7.9238253e+08
   INTEG_T         DOUBLE           3.0000000
   NBINS           INT             88
   NENERGY         INT             15
   MAP             INT       Array(32, 32)
   PT_LIMITS       FLOAT     Array(4)
   DATA            FLOAT     Array(15, 88)
   ENERGY          FLOAT     Array(15, 88)
   THETA           FLOAT     Array(15, 88)
   PHI             FLOAT     Array(15, 88)
   GEOM            FLOAT     Array(88)
   DENERGY         FLOAT     Array(15, 88)
   DTHETA          FLOAT     Array(88)
   DPHI            FLOAT     Array(88)
   DOMEGA          FLOAT     Array(88)
   EFF             FLOAT     Array(15)
   MASS            DOUBLE       5.6856593e-06                
   GEOMFACTOR      DOUBLE       0.00039375000
   VALID           LONG                 1
   UNITS_PROCEDURE STRING    'convert_esa_units'
These elements contain most of the pertinent information for a single time sample of 3d data. You may extract a portion of the data for your own purposes. For example to look at the counts in bin number 23 create a new variable 'y': 
	y = el.data(*,23)
now print it: 
	print,y
Now print the corresponding energy steps: 
	print,el.energy(*,23)

Back to the top of this tutorial

3D COLOR PLOTS

To look at surfaces of constant energy for the data set "el", type: 
	plot3d,el
or simply: 
	plot3d,get_el(t)
Repeat the previous command to view the next time sample. Edit out noisy bins: 
	edit3dbins,el,bins
Plot the new improved data: 
	plot3d,el,bins=bins
Change plotting options: 
	plot3d_options, map = 'cylindrical', smooth = 0 ;cylindrical map and no smoothing
To make a movie of these type of pictures, type: 
	movie_3d,'el'
You can also make movies of other data by substituting 'eh','ph', etc. for 'el'

Back to the top of this tutorial

PLOTTING ENERGY SPECTRA

To look at energy spectra type: 
	spec3d,el

SETTING PLOT LIMITS

Create a new variable, "lim", that contains plot limit inforamation. Type: 
	xlim, lim,  5 , 2000, 1
	ylim, lim,  0 ,    0, 1       ; still default but use log scale
Now plot it use the limits defined in "lim": 
	spec3d,el,limits = lim

CHANGING DATA UNITS

Using the same variable "lim" as above, type: 
	units, lim, "Flux"
to get flux units. the following units are recognized:
'Counts' , 'Ncounts' , 'Rate' , 'Eflux' , 'Flux' , 'DF'
plot the data: 
	spec3d,el,limit = lim
An alternative method is to change the units of the data before sending it to the plotting routine. Create a new variable newdat: 
	newdat = conv_units(elsum,'Flux')     ; set to flux
Once the units are changed from "Counts" they can not be changed to anything else. To plot it type: 
	spec3d,newel

Back to the top of this tutorial

SUMMING DATA

Data from multiple samples can be summed. For example, to create the variable "datsum", type: 
	datsum = 0
	datsum = sum3d(datsum,get_el(t))   ; 1 samples summed
	datsum = sum3d(datsum,get_el(t))   ; 2 samples summed
	datsum = sum3d(datsum,get_el(t))   ; 3 samples summed
	datsum = sum3d(datsum,get_el(t))   ; 4 samples summed
This can also be accomplished more easily by entering: 
	elsum = get_el(t, nsamp=4)

Back to the top of this tutorial

HELP

Get help on a subroutine: (All routines are now documented!) 
	doc_library,'tplot'
Or type: 
        help_3dp

Back to the top of this tutorial

HARDCOPY

Open a postscript file called 'test.ps' (default is 'idl.ps'): 
	popen,'test'
Then make the plot: 
	spec3d,el     ; for example
Then close the file: 
	pclose
Change printing options so that black and white portrait style plots are printed: 
	print_options,/port,/bw

Back to the top of this tutorial

ENVIRONMENT VARIABLES

Three UNIX environment variables need to be created: $IDL_3DP_DIR, $IDL_PATH and $WIND_DATA_DIR. This can be done automatically by sourcing a file similar to the file idl_3dp.init (included with the distribution)

$IDL_3DP_DIR should be set to the (full) pathname of the directory containing the idl source code. The code will expect to find a shareable object file with the name: "$IDL_3DP_DIR/lib/wind_lib.so"

The idl path variable $IDL_PATH needs to be set to include the 3dp software. Use: "setenv IDL_PATH ${IDL_PATH}:+$IDL_3DP_DIR" to add to an existing path.

$WIND_DATA_DIR should be set to the pathname of the directory containing the master files. See Data Files for a description of the contents of these master files.

Back to the top of this tutorial

DATA FILES

The software will automatically search for appropriate data file(s) for a given time period by looking in the following master files:

wi_lz_3dp_files (WIND 3-D Plasma level zero files)
wi_k0_3dp_files (WIND 3-D Plasma key parameter files)
wi_k0_swe_files (WIND Solar Wind Experiment key parameter files)
wi_k0_mfi_files (WIND Magnetic Field Instrument key parameter files)
wi_k0_wav_files (WIND WAVES key parameter files)
wi_k0_epa_files (WIND Energetic Particle Analyzer Key Parameter files)
wi_or_def_files (WIND Definitive Orbit files)
wi_at_def_files (WIND Definitive Attitude files)
wi_or_pre_files (WIND Predicted Orbit files)
wi_at_pre_files (WIND Predicted Attitude files)
i8_k0_mag_files (IMP-8 Magnetometer key parameter files)
i8_k0_pla_files (IMP-8 Plasma instrument key parameter files)

These master files should have one line for each data file. (Typically one line per day, but this is not required) Each line should have the format:

yyyy-mm-dd/hh:mm:ss yyyy-mm-dd/hh:mm:ss /fullpathname/datafilename

in which the date/times are the the starting and ending time of the data file. The entries must be in chronological order (without duplicated times). These files can be created using the programs "3dpfile" and "kpdfile" to produce the lz and the kpd files respectively. The typical usage is:

% 3dpfile LZPATHNAME/*.dat | sort > $WIND_DATA_DIR/lz_3dp_files
and
% kpdfile KPDPATHNAME/*.cdf | sort > $WIND_DATA_DIR/swe_files

(You must substitute the appropriate values for LZPATHNAME and KPDPATHNAME.) The actual location of the data directories is not important and files can even be split among several directories (or disks). At Berkeley, all data files are automatically transferred from the CDHF on a daily basis using a crontab process. The master files are updated whenever a new file is transferred. The scripts that do the automatic transfers are in the "bin" directory of the released code. Each user will need to edit these files for their own system.

Back to the top of this tutorial

A log of Instrument commands is available using anonymous ftp at: "aeolus.ssl.berkeley.edu". The log file is in the "pub" directory with the file name: wi_3dp_log