GAMIT/GLOBK MATLAB TOOLS

 

Thomas Herring and Simon McClusky, MIT

 

Last Updated 1/26/06 2:43 PM

Comments should be sent to tah@mit.edu

This software is covered by the standard GAMIT/GLOBK License agreement.

Content

Overview

Vers

Introduction to the tool box

Installation

 

Instructions for installing and running programs either in Matlab Ver 6 or stand-alone programs

Modifications

 

History of changes to the programs

Velview

2.00

Velocity field viewing tool including profiling and interface to tsview

Tsview

2.00

Time series viewing, editing and interface to GLOBK

 

 

 

 

GAMIT/GLOBK MATLAB TOOLS

Content

Overview

Installation

Running under Matlab

Running as standalone programs

Modifications

velview

tsview

Velview

General comments

Primary Velocity Field

Time Series DIR

Secondary Velocity Field

Ensum file: Not implemented in Ver 1.0

Feature Files

Long/Lat limits

The Load Options

Pan buttons:

Zoom buttons.

Redraw button

Profile Buttons

Profile Figure:

Offset row

Alignment row

RmDups and Stats

ID Points

SWAP

Print and Page setup 

In Figure Actions:

Tsview

Basic Operation

Dir button

Center column buttons:

Load:

Append:

Difference

Detrend:

Edit:

Block Edit:

Break:

Exponent:

Logarithmic:

Edit Breaks:

Zoom:

Span:

Save:

Max Outlier (n-sigma):

Max Sigma (mm):

Keep Breaks:

Brk on Append:

Report Edits:

Delete Breaks:

Parameter Set:

+Annual

+Semiannual

Exp/Ln Rates

Linear Only Resid

RealSigma

DisplayFit

Average

Hide Error Bars

Input ENS file:

Print and Page Setup:

Example screen view and output

Example 1

Example 2

 

Overview

 

These tools are provided as a means to help users understand the quality of the results being obtained from GLOBK analyses of GPS data.  There primary aim is improve the quality and understanding of the results from large GPS analysis projects.  Version 2 of tsview and velview are able to read Plate Boundary Observatory (PBO) time series and velocity field files.   These formats are described at  http://pboweb.unavco.org/?pageid=88 with gps_timeseries_format.pdf and gps_velocity_format.pdf giving the details of each format.  The PBO time series files must have names that end with "_frame.pos"  e.g., LDES.pbo.final_frame.pos.  Only one type of time series file can be in a single directory (i.e., mb_* and *_frame.pos files must be in separate directories.) PBO results can be obtained from ftp://data-out.unavco.org/pub/products/position/pbo.final_frame.pos.tar.gz

Installation

 

The GAMIT/GLOBK Tools are available as a UNIX tar file GGMatlab_mfiles.tar containing just the Matlab M-files and  GGMatlab.tar that contains both the M-files and Linux executables.  To run velview and tsview without running Matlab, the latter tar file should be downloaded.  The tar file contains a directory called matlab.  In the standard GAMIT/GLOBK distribution, this directory should be placed at the same level as the gamit, kf, and library directories, although it can be installed anywhere in the system.  Also available is an example case saved as Example.tar.  The examples below use the data in the Example directory.  This directory can be placed anywhere in your system.

 

Instructions: In the directory where you plan installing the matlab directory (we will refer to this directory as <matlab dir>.  < Download Directory> is the directory where the GGMatlab.tar is located.

% tar xvf <Download Directory>/GGMatlab.tar

 

Running under Matlab

To run with Matlab Version 6.0 or later.

Either add the paths to your startup.m in the matlab directory of your home directory by adding:

addpath <matlab dir>/velview

addpath <matlab dir>/tsview

 

or at the Matlab prompt after starting matlab type the above two lines.

 

>> velview

or

>> tsview

at the Matlab prompt will start the programs (See notes below on being in the correct directory when starting tsview.)

 

Running as standalone programs

The current distribution only includes executables for Linux glibc version 6.3 or later.

 

Two steps need to be taken to run the executable versions of velview and tsview.

(1) Add path the executables in your .cshrc file (or equivalent).

 set path = ($path <matlab dir>/bin)

 

(2) Add the load library path to your .cshrc file.

You should find the bin directory where matlab is located (which matlab will tell you this).  If this directory is <matlab_r12>/bin, then in your .cshrc file add:

setenv LD_LIBRARY_PATH <matlab_r12>/extern/lib/glnx86/:<matlab_r12>/bin/glnx86/

The executable versions are made with Matlab Ver 6.5, Release 12 and the <matlab_r12> must point to the libraries from this version of Matlab.  If you cannot find these directories or you now longer have Version 6.5 Matlab libraries, then adding

setenv LD_LIBRARY_PATH  <matlab dir>/lib

should also work.  (If you already have a LD_LIBRARY_PATH set then these new entries should be added to that path.

 

NOTE: Not all features work in the executable versions.  The general function entry system in the profile tool will not work; use the SS function for a strike-slip fault.  The features option does not work in the exectuable

 

Velview can be run from any directory but to use the feature that allows time series to be plotted, it should be pointed to in a directory containing the mb_ files generated by program multibase from the ensum values files or to PBO times series files  available from http://pboweb.unavco.org/?pageid=88  The figures in this document were generated running velview in the Example directory.

 

Modifications

Velview

From Version 1.00

 

From Version 1.01

 

From Version 1.01

 

From Version 1.02 to 2.00

 

Tsview

From Version 1.00

 

From Version 1,01

 

From Version 1.02 to 2.00

 

Notes on running tsview in Matlab Version 7.0:  There are possible problems with the Monospaced font in Matlab 7 being more widely spaced than the font size would suggest.  If this is a problem then the parameter estimate window generated in tsview when data are trended will not fit correctly in its window in the upper right hand corner of the screen.  If this is a problem, use the Matlab Font Preferences to select a narrower font for the desktop.

Velview

 

Aim:  The primary aim of velview is to view and assess the quality the velocities fields generated by GLOBK. 

 

Typing velview at the Matlab prompt or from a terminal window generates the new figure shown below.  Not all the features are implemented in Version 1.0 (specifically the ensum file and the Features Files are not implemented.  All of the other buttons work and have tips shown when the cursor is passed over them).

 

 

NOTE: Some of the figures below are from previous versions of velview.

 

Basic uses of velview.

General comments

Velview allows many levels of interactions with the displaying velocity fields and multiple changes to the display can be made at one time.  As a general rule, if multiple changes are made at the same time, use the redraw button to ensure that the figure rendered correctly.

The current version of velview has problems crossing the zero longitude line, i.e., longitudes near 360 degrees are not converted to negative values.  If needed the CLEAR ALL button should remove most of the plot, allowing it then to be re-constructed.

 

Primary Velocity Field

The first action when velview is started to type the name of a GLOBK velocity field file in the Primary Velocity Field box and then click the Load button next to it.  (Hitting return in the text box will NOT load the field.  Use of the Load button is required). This action will read the velocity field information from the file named and plot the velocities with the default conditions.  (Since the figure is auto-scaled to fit with velocity vectors shown at “real” scale (i.e., 10 mm/yr will be 10 mm on the computer screen), you should careful that there are not excessively large values in the velocity estimates).

 

In the Examples directory, using the EX1_TEST.vel file will generate the following plot. (The Features option and Time Series DIR has also been used on this plot)

 

 

Time Series DIR

The directory name in this box will be used to find the times series files for plotting with tsview when a velocity vector is selected and the time series requested.

 

Secondary Velocity Field

The Name of secondary velocity field can be specified in the text box and the Load button clicked.  In Ver 1.0, the Redraw button must then be clicked to render the two velocities fields in the same frame.  In Ver 1.01, the scales of the secondary field are made the same as the primary field on load.

 

Ensum file: Not implemented in Ver 1.0

 

Output Velocity File:

The name is entered in the box and Save pressed.  Entries in the primary and secondary fields are written to the output but duplicates in the secondary file are written as comments.

 

Feature Files

When velview is run under Matlab control, features can be added at the Matlab prompt.  Included in the Example directory are several Matlab readable files that contain the California Coast (CCVelV.xy), major faults (CF3VelV.xy), and earthquake locations of magnitudes >2, >3 and >4 since 1996.  These can be plotted on the figure and will remain there until the CLEAR ALL button is pressed.  Subsequent figures have these features plotted (cc shown with black line (LBlack) and faults shown with green lines (LGreen), and earthquakes with brown dots (DBrown).  Feature files can be selected and the line/dot style changed or cleared.  A number of feature files are included in the maps directory of gamit/globk.  File names end in .xy

 

Long/Lat limits

If this box is left blank then the limits are automatically calculated to show all sites and their velocity vectors.  (There can be problems with the algorithm used for very large velocity vectors).  The Get button will copy the limits on the current plot to the box and future Loads will display with these limits.  The Clear button a convenient way of erasing the values in the box.  The Long/Lat limits only affect loading of data.

 

The Load Options

The first two load options have effects only when data is loaded (Sig Limit and Error Scaling).  The other options can be changed and bought into effect by clicking the Redraw button.

Sig Limit : Limits on the velocity uncertainties when the data is loaded.  If the V box (see below is set), then both the horizontal and vertical velocities must satisfy the conditions.  The limits are checked before Error Scaling.

Error Scaling: Multiplier on the sigmas in the data file.  Both the Sig Limit and Error Scaling may be changed between loads of the primary and secondary fields.

Confidence Int: Changes the confidence intervals for the error ellipses and vertical velocity error bars.  May be updated with the Redraw button.

Arrow Length: Scaling between the plotted lengths of vectors and height velocities and approximately real size on computer screen (depends on monitor size).

Arrow Head Size: Sets the size of the arrow heads in millimeters relative to millimeters of vector length (e.g, with 1 mm arrow heads, a 1 mm/yr velocity would be the same length as the arrow head.  Redraw causes the update.

Display: Sets the contents of the figure:  If checked then, N selects site names, H selects horizontal velocities and V selects vertical velocities.  Redraw caused the update.

 

Pan buttons:

These four buttons pan the view by half the width or height depending the button pressed (e.g., ^ shows sites at higher latitudes).  The fifth button in the center, zooms the figure out by 50% while retaining the vector lengths.

 

Zoom buttons.

Velview uses two types of zooms.  The Zoom In and Zoom out buttons act like the normal Matlab zoom in that the vectors will increase in size with zoom in.  (The Arrow length box updates to show the new length of the arrows).  After the first Zoom in, the Zoom out button turns green and clicking it will reverse the sequence of Zoom Ins.

Vec Zoomin and Vec Zoom Out preserve the vector length on zooms.  Again the Vec Zoom Out button turns green when it can be used and reverses the sequence of Vec ZoomIn.  Strange arrow lengths can result if the Zoom Out buttons are used in an order different to the Zoom in sequence.  A new arrow length can be typed in the Arrow Length Box and Redraw will bring the vectors back to the known length.   (The arrow length box should give the actual value being used but it might be a strange value.)

For both zoom in buttons, the sequence is to click the Zoom In or Vec Zoom In button, and then in the figure window, click and drag (i.e., move while keeping the mouse button pressed) the area to be viewed in detailed.  This sequence can be repeated as many times as needed.  The Zoom Out buttons then reverse the sequences.  Note: An area larger than the figure can be selected and the Zoom In then acts like a Zoom Out.

 

Redraw button

Clicking this button redraws the plots with the current settings in the Load Options.  After multiple changes in the settings of the figure, this button should always be used to ensure that the figure rendered correctly.

 

Profile Buttons

The Profile line of buttons control setting up profiles to be displayed and evaluated.  By default, velocity vectors will be projected into a direction along the profile and at 90 degrees (counter clockwise) to the profile.  However the azimuth for the projection can be set in one of two ways: (a) A value can be typed into the box to the right of the Az button or (b) the Az button can be clicked which allows graphical input.  After the Az button is pressed, click in the figure window and drag the direction you want the vector projected onto.  When the mouse button is released a dark blue line will appear for a second showing the azimuth selected and the value will be written into the Az box.

The velocities shown in the profiles are only from the primary field and do not have the offsets removed that may be applied to

To select the profile: click the Profile button and then move to the figure window.  Click where you would like the profile to start and drag out the centerline of the profile.  When the centerline is in the correct location, release the mouse button and click again.  Drag away from the centerline to make a box that will expand to show the area to be included in the profile.  When the mouse is released the second time,  sites in the profile will be marked by yellow circles; the characteristics and list of sites in the profile box will be written to the Matlab window; and a Profile Figure will pop-up.

The velview selection and the profile figure are shown below.

 

Profile Figure:

The figure below has a number of the features of the profile module already used.

The main features of the Profile Figure are:

ID: Allows point to be identified (information appears on the left hand side of the figure.  By using right-button-click, multiple points can be identified.

Delete: Allows points to be deleted.  An X is over printed on the point to show that it has been deleted and a message (in red) appears at the bottom-left corner of the window.

Fit: Allows functions to be fitted to the profile.  The functions to be fitted are typed in the Fitting Functions boxes when velview is run from within Matlab.  When velview is run as an executable, only the SS function, as shown above can be used.  The SS function is a Okada model for a strike slip fault and is the equivalent to

SS(D,H) = 1/2+atan((x-D)/H)/pi,

where x is the distance along the profile,  D is the distance to the fault and H is depth of the locked portion of the fault.

The estimates appear on the left side of the screen for the Azimuth directions shown on the plots.  The WRMS is in mm, and the NRMS is the square root of chi squared per degree of freedom.  FCN0 is always an offset, and FCN1-5 are the parameters of the functions typed in.  The estimates text may be removed by right-clicking them.  (Multiple estimates will stack in the same location on the plot.)

File and Save buttons allow the information about the profile to be saved.  The lines in these files start with certain strings so that the file can be grep’d (to generate input to GMT for example).  The output of the above profile can be found here. (EX1_prof.dat)

Other Profile buttons:

POP and PIP button remove the profile boxes from the main velocity field figure.  POP removes the last one plotted, while PIP removes the initial one plotted.  The POP stays green while ever there are profiles still plotted on the figure.

 

Offset row

Clicking the Offset button will remove offsets from the primary and secondary velocity fields (same offset for both fields in Ver 1.0).  If there are numerical values in the box next to the Offset button, these will be applied to the field (for example after a field is loaded).  If the original velocity fields are in different frames the GLOBK utility program velrot can be used to align them before viewing in velview. If the box is empty, either by erasing its contents or by using the clear button), a click and drag box is used to select a square region from which the weighted-average value will be computed.  A text window appears on the figure showing the statistics of the fit plus these results are written to the Matlab window.  Right clicking the text box will remove it from the screen.

 

Alignment row

The align button computes offsets between the secondary and primary velocity fields as simple additions to the North, East and Up velocities.  For small areas, these offsets will account for frame differences between the two fields.  For larger areas, the velrot program should be used before hand to bring the fields into alignment.  If the box next to the button is empty, a click-drag technique us used to select the area in which the alignment parameters are computed.   If the site names match the secondary and primary fields, these sites are used to compute the alignment.  For sites in the area that do not have matching site names, sites within the separation distance are used.  If the site separation is set to zero then only sites with the same names will be used in the alignment.  The output written to the figure window can be removed with a right-click.

 

RmDups and Stats

The RmDups button is used to remove duplicate site names that are within specified separation and that have the same velocity.  (Results from using the equate option in GLORG).  The duplicate sites are removed and will not appear in output files.

The Stats button computes the statistics of the differences in velocity for nearby sites (with the separation distance) and writes the results to the Matlab window.  Only the sites in current view are used to compute the statistics of the differences.  A file, Diff.vel, is automatically created with differences given in a velocity field format.

 

ID Points

Allows the identification of points inside a “click and drag” box on the velocity plot.  The screen output may be removed by clicking on it.

 

SWAP

Allows the primary and secondary velocity fields to be swapped.   This is useful when making profiles since only the primary field velocities are shown on the profile plots.

 

Print and Page Setup:

These buttons allow the page setup (paper orientation, fitting of the figure on the page) to be set.  The print button prints the figure using the arguments given in the box next to it.  Some typical options are:

-d<device> with device being psc for color post script; png for portable network graphics; jpeg of jpeg image

-r<NN> sets resolution for image formats.  NN is dots per inch with 72 being appropriate from screen resolution.

-P<queue> to set the printer queue to be used

<filename> the last argument can be a file name to which the print is sent.

Example: -djpeg –r72 Test.jpg outputs figures to jpeg file.

When run under Matlab, the functionality of these boxes is available under the file menu.

 

In Figure Actions

The velocity vectors plotted by velview are active in that clicking on a vector brings up a menu box that can be used to get information about the velocity vectors.

 

The menu items here each have an action.  The top line shows the site name and the field it is from F1 is the primary, F2 is the secondary.  Clicking on the site name will make the box disappear and no other actions will take place.

LabelOnFig will write information about the site position and velocity on the figure near the site name.  Clicking on this label will make it disappear.

LabelPopUp will write the same information but on a new window that will appear in the upper right corner of the computer screen.  This window may be destroyed using the normal close window techniques.

TimeSeries will launch tsview for this station (see Tsview section).  The time series files will be searched in the Time Series DIR location.  If this field is blank then the current directory will be used.

Delete will delete the site from the velocity field and the figure.  There is no undo feature.  If a site is accidentally deleted, the field will need to be re-Loaded.

Tsview

 

Aim: The primary aim of tsview is to assess the quality of time series generated by GLRED runs and to generate control files for GLOBK that will delete bad site position estimates and account for jumps in time series.

 

tsview normally is run from a directory containing mb_ time series files generated by multibase with the –year option selected.  The current version is not meant to be used to compare time series from different analyses that are stored in different directories.  (Future versions will probably have this feature). 

 

Starting tsview in the Example directory generates a new figure: (We used the page setup option to make the plot the same size as the screen).

 

Figure 1: tsview startup screen

NOTE: Some of the figures below are from previous versions of tsview.

 

If tsview is launched from velview than the time series of the station selected will be loaded initially provided the directory is set correctly.

 

Basic Operation

The basic sequence in tsview is to select a site in left window, then Load, possibly Append another site, and then Detrend.  The edit buttons can remove bad data and the break button can be used to add breaks.  For the editing and breaks to be used in GLOBK, the edit and break information is Saved to the Edit File.

 

There are tool-tips on the buttons to help users with the operation of the program.

 

Dir button

The top of the screen allows the specification of a directory where mb_ files are located.  PBO time series files need to have names that end in frame.pos. The name is typed in text box and dir pressed to load the names of the sites in the directory.

 

Center column buttons:

Load:

This loads the data from the selected site.  Data is in the output format from multibase.  An example of an mb_file is shown below. There are three header lines on the file and second line is used to determine total value of the component being plotted.  The entries in the time series are the <10-meter part of the component being plotted.  The format of the file name (i.e., mb_ABCD_XYZ.datN where ABCD_XYZ is the site name, and the N at the end of the name is used to denoted component with 1 being North, 2 being East and 3 being height.

Globk Analysis

AZU1_GHT to N Solution  1 +   3798890.892 m

 

 1999.7931       0.8572   0.0017

. . .

 2002.7767       0.9247   0.0020

 2002.7795       0.9241   0.0020

PBO time series files have all components in the one file

Append:

Appends another sites data onto previously loaded data.  This option may be used multiple times to append several site names.  Most often append is used to re-connect sites that have different names due to earthquakes and renames in GLOBK.  Other buttons on the screen determine the precise operations during appends. By default, Break on Append (Brk on Append button) is set which means that a break is automatically added at the end of the last data set loaded or appended.  For this feature to work correctly, data must be loaded and appended in time order.  Since the symbols used to plot the data change with each append, the breaks in data can be found by looking at the symbols.  The other option on append is to check the O box next to the append button which will calculate and remove an offset between the original and appended data based on overlapping data times.  Statistics of the overlap are written to the Matlab Window.  Normally Break on Append would be turned off during this operation. 

When PBO time series are appended, any difference in the reference position will be accounted for provided the sites are within 1 meter of each other.  A message is printed to the Matlab or terminal window reporting the size of the offset applied.

All data is displayed during the load and append steps.

Difference:

This button will difference the selected data set from the one that is currently being displayed.  If the absolute difference is within 1 meter no offset is removed; for larger differences a mean difference is removed before plotting.  The error bar on the differences is the sum-squared sigmas from the two input time series.  All the normal detrend features can be used with the difference plots.  There is a 1-hour time difference tolerance, centered on whole hours, between times that will be co