Introduction to the BX Program

     The BX program is designed to simplify the analysis of magnetic field data obtained in
space plasmas.  It allows the user to examine the three components of the vector magnetic field
and the total magnetic field as a function of time.  Once the interesting segment of data has been
identified, the program enables the user to apply any one of a series of standard analysis tools
to the data.  Characteristics of the data can be used to choose more natural coordinate systems
in which to display the data.  The data may be filtered, Fourier analyzed, polarization analyzed
etc.  The goal is to enable the researcher to spend his or her time thinking about the properties
of the observations and their implications rather than of the details of the analysis procedure. 
The program is intended to allow the user to test ideas quickly.

     
General Procedures

Log On 
     
     Type in  BX' (uppercase) to initiate the program.  When the logo appears position the
cursor on the  file' button and press the right hand button.  A pull down menu will appear listing
several options.  Select examples.  A further menu will appear with a list of sample data files. 
Use the scroll bar on the right to move the menu up and down.  When you see your desired file,
position the cursor on it and click the left hand button.  The selected file should now appear 
as a dark bar.  Position the cursor on the  open' button at the bottom of this pull down menu,
click the left hand button of the mouse and a plot of the file should appear on the screen.  You
may move the plot to the right or left with the use of the scroll bar at the bottom of the screen.

File Selection

     If you do not choose one of the example files, enter the directory and file name by first
moving the cursor to the end of the appropriate line, click the left hand mouse button and erase
by back spacing as necessary.  Then type the desired file name and press the open button.  The
first part of the file should now be displayed.

Print

     Select your printer from the print menu obtained under the file button.  You can choose
2 different printers for high quality and draft quality listings.  Once the printer is selected from
the list using the right hand mouse button, you may press print to dump your plot. If "High Quality"
print output is selected then a postscript file of the print will be save in the "$SCRATCH" directory.
The postscript file name will be "$SCRATCH/BX_PS_<username>.ps". Where <username> is the login ID
of the user running the BX program.

Writing a File

     The pull down menu under the file button allows you to select a file into which to write. 
Enter the name as described above under file selection.




Moving Windows

     Windows may be dragged around the screen using the cursor by positioning the cursor
on the side of the window depressing the left hand move button and dragging the window to its
new location.  Windows may be closed by clicking on the tack in the upper left hand corner so
that it  pulls out  of the screen.  If it is already out, a click will reinsert it so that it can be pulled
out.  

Log Off 

     To terminate the program move the cursor to the file button in the main screen, depress
the right hand mouse button, and select the  quit' button.  The screen should clear.

Viewing Data

     The pull down menus under the View button allow you to vary the time interval selected,
to alter the columns selected from the file, to zoom in on a set of data and to focus on a set of
data.

Time Interval Selection

     One can change the time intervals displayed by selecting the time scale selection menu. 
Choose whether you want to change the start or stop time and whether it should be increased or
decreased.  Then select a unit to be changed and wait until the right amount of time appears. 
The start and stop time of the entire file appears on top and the start and stop time of the plot
appears underneath on the second line.

Zoom

     The zoom option allows you to view a subset of the time series with larger temporal and
vertical resolution.

Focus

     The focus option allows you to view a subset of the time series with greater temporal
resolution but with the same vertical scale.

Power/Coherence

     While some processes have distinctive signatures in the time domain, other processes are
more distinct in the frequency domain.  In order to identify periodic signals and how energy is
distributed across the frequency spectrum, it is useful to calculate the power spectral density of
signals as a function of frequency.  This is done by Fourier analysis at all frequencies from the
lowest to the highest in a time interval.  The lowest frequency or fundamental is set by the length
of the time series selected.  The highest frequency, Nyquist frequency, is half the sample rate. 
Generally we sum the Fourier components (after squaring) over bands of frequencies for
increased statistical accuracy.

     When the power/coherence option is chosen one can pick whether the spectrum chosen
is stored in location A, B, C or D.  One also selects the time interval from the screen using the
cursor.  This spectrum has a default bandwidth of 3 estimates.  One can now push the view
button above the spectrum and get a pull down menu that allows one to reset the bandwidth. 
One can also press a second button to select a new time interval.

Rotation Options

     Often data are acquired in a coordinate system that is not the natural coordinate system
of the phenomenon.  For example a wave might cause magnetic perturbations that are confined
to a plane but the magnetometer that measures the wave might be oriented in an arbitrary
orientation with respect to this plane.  In order to understand the properties of the process under
study, it is important to be able to convert the data into the natural coordinate system of the
process.  One also needs mechanisms to determine the orientation of the natural coordinate
system relative to the measurement system so that the data may be rotated into the natural
coordinate system.  The rotation option of the BX program allows this to be done.

     When the rotate button is pushed by clicking the left hand mouse button a rotation matrix
pull down menu appears.  If the right hand mouse button is clicked, then a series of options
appears: rotations by an arbitrary matrix; rotation into a minimum variance coordinate system;
rotation into a boundary normal coordinate system; rotation into a shock coplanarity coordinate
system; and rotation into a tangential discontinuity coordinate system.  Each of these rotations
is most appropriate in a different situation.

Matrix Rotation

     The matrix rotation option can be selected by clicking either the right hand or left hand
mouse button with the cursor on the rotate button at the top of the time series panel.  Four
different matrices can be created and stored: A, B, C, and D.  Row 1 of this matrix is the
direction of the "x-axis" of the new coordinate system expressed in the original coordinate
system.  Row 2 of this matrix is the direction of the new "y-axis" in the original coordinate
system.  Row 3 of this matrix is the direction of the new "x-axis" in the original coordinate
system.  These axes will be displayed in the new plot from top to bottom with the total field at
the very bottom of the plot.  The total field, of course, is invariant under rotation.

     A rotation matrix may be created in several ways.  One can write matrix elements into
the temporary matrix in the middle of the window by moving the mouse to any element of the
matrix, clicking on the right hand side of the element, erasing with the back space key and typing
in the element of the matrix.  For pure rotations the rows and columns should have unit
magnitude and be orthogonal.  The third row or column should be the cross product of the first
two taken in cyclic order to maintain a right handed system.  One can also create a rotation
matrix by choosing an axis and a angle of rotation about that axis.

     Once the desired matrix is written into the temporary matrix, it can be moved into the A,
B, C, or D matrix register or it can be used to rotate the current matrix by the temporary matrix. 
The current matrix also can be copied to the location of the temporary matrix.

Minimum Variance

     The variability of the data as a function of direction can be used to determine a coordinate
system, by finding the three principal directions in which the variance of the data is a maximum,
an intermediate value and a minimum.  This is also often called the minimum variance coordinate
system.  The resulting directions are the eigenvectors of the matrix of variances and cross-
variances.  The eigenvalues are the variances in each of the three principal directions.  The signs
of the vectors are arbitrary and are chose to from a right hand orthogonal set such that the third
vector (k) has a positive x component and the first vector (l) has a positive z component.  If the
eigenvectors have three very distinct values the three axis will each be will determined.  If the
two maximum eigenvalues are nearly equal then there is much uncertainty in the direction of
these two directions about the direction of minimum variance.  If the two smaller eigenvalues
are nearly equal, then only the direction of maximum variance is well determined.

     The minimum variance technique is useful for determining the direction of the wave
normal of waves and the normal to the magnetopause and other such boundaries that have a clear
rotation of the field within the boundary.  In general it should not be used on shocks that have
a linear variation of field through the boundary.

     The minimum variance rotation option can be selected by clicking the right hand mouse
button with the cursor on the rotate button.  Then select the minimum variance option from the
pull down menu.  The next pull down menu that appears allows you to select time using the
cursor and clicking the left hand mouse button on the data screen at the beginning and end of
the desired interval.

Boundary Normal Rotation

     This option allows you to calculate a normal to the boundary from the location of the
spacecraft and a formula for the position and shape of the boundary.  The formula of the
boundary is a conic surface of revolution about the x-direction.  The eccentricity of the ellipse
can be varied.  The data set must contain the location of the spacecraft in x, y, z coordinates, the
same coordinate system as the magnetic field.

Shock Coplanarity Rotation

     It is possible to find the normal to a shock front using the cross product (B1-B2) x (B1xB2)
when B1 and B2 are the upstream and downstream magnetic fields.  Ideally these would be
measured simultaneously.  Using successive measurements on a single spacecraft in an
approximation, which is valid only if the upstream conditions remain constant.  Thus in general
the upstream and downstream valves should be measured as closely together in time as possible. 
Waves can propagate at an angle to the shock normal.  Hence, in the coplanarity analysis the
effect of waves should be avoided as much as possible.  Averaging across an integral number of
wave cycles is one way to do this.

     To select the shock coplanarity option press the  rotate' button on the screen using the
right hand button on the mouse.  A pull down menu will appear.  Select the shock coplanarity
button by positioning the cursor on it and depressing the left hand mouse button.  A new pull
down menu will appear entitled  shock coplanarity rotation'.  Move the cursor to the left hand
bar marked  select time'.   Click the left hand button.  Now move the cursor to the plot and
center it just upstream of the shock.  Click the left hand mouse button to select the start of your
upstream average.  Move the cursor further from the shock to select the end of the averaging
interval (with a click of the left hand mouse button).  Return cursor to pull down menu, place
it over second (right hand)  select time' bar and click left hand mouse button.  This enables you
to select an averaging interval for the downstream magnetic field.  Move cursor back to plot and
select an averaging interval downstream of the shock front using 2 clicks of the left hand mouse
button.  Return to the pull down menu.  Press the matrix button.  A rotation matrix should appear
in the lower box in the center.  Click left hand mouse button with cursor over the apply button
on the screen.  The plot should now change, to contain rotated data in the  shock normal'
coordinate system.

     In the shock normal coordinate system, the n direction is along the shock normal.  In this
direction the strength of the field should be constant except for changes associated with waves
that are not propagating along the shock normal.  The l direction is in the shock plane parallel
to the projection of the upstream field on the shock.  The m direction is also in the shock plane
so that lmn form a right handed set of basis vectors.  The program displays the l, m and n
vectors as the rows of the rotation matrix.  One may also enter the components of the upstream
and downstream vectors directly by moving the cursor to the right of the components, clicking
the left hand mouse button, backspacing to erase and then typing in the new component. 
Pressing the matrix button at the bottom of the plot will recalculate the matrix.

     Note that the angle between the two vectors as well as the angle of the upstream field to
the shock normal is given.  For most purposes the polarity of the magnetic field at the shock is
unimportant so that if the angle is greater than 90  you may just subtract it from 180  to
determine your shock normal angle.  We note that for quasiparallel and quasiperpendicular shocks
the upstream and downstream magnetic fields are nearly parallel.  In these cases there is the most
uncertainty in the cross products used in the calculation.  Thus, the magnetic coplanarity
calculation is most uncertain for nearly parallel and nearly perpendicular shocks.

     For some purposes it is interesting to examine how the angle of the upstream magnetic
field to the shock normal varies with time.  Such a plot may be displayed by depressing the
button marked  theta vs time .

Tangential Discontinuity Rotation

     If one believes a boundary is a tangential discontinuity with no normal component across
it, one can find the normal to the boundary by calculating the direction orthogonal to the two
magnetic field directions on either side of the boundary.  This is often useful in the solar wind
and at the magnetopause.  This option can be entered by the pull down menu obtained by
clicking the right hand mouse button on the rotate button on the time series screen.  One can
select time intervals by pushing the select time button for the magnetosphere vector or the
magnetosheath vector and the clicking twice on the screen.  Once one has two vectors selected
one should calculate the matrix by pressing the matrix button and then apply the rotation to the
data.  The resulting coordinate system is defined so that the normal vector (N) has a positive x
component as measured in the original coordinate system and the l direction is along the
magnetospheric magnetic field.  The cyclic triad l m n forms a right handed set.

Filtering

Detrend