See

discussions, stats, and author profiles for this publication at: https://www.researchgate.net/publication/226662178

MATLAB tools for viewing GPS velocities and

time series
Article in GPS Solutions January 2003
DOI: 10.1007/s10291-003-0068-0

CITATIONS

READS

78

562

1 author:
T. A. Herring
Massachusetts Institute of Technology
173 PUBLICATIONS 9,083 CITATIONS
SEE PROFILE

Available from: T. A. Herring

Retrieved on: 11 October 2016

GPS Tool Box

MATLAB Tools for viewing GPS

velocities and time series
Thomas Herring

Abstract Over the past decade, many Global Positioning System (GPS) networks have been installed to
monitor tectonic motions around the world. Some of
these networks contain hundreds of sites spread
across active tectonic margins where the differences
in velocities across the network can be 50100 mm/
year. For networks that have been running for a
number of years, the uncertainty in the velocity
estimates can be less than 1 mm/year. In some cases
the vertical motions can also be significant and of
importance. Often, the time series of the motions of
the GPS sites show complex non-linear behavior, and
in all cases the statistical model of the time series is
more complex than simple white noise. In this article,
we describe a set of Matlab tools developed for use
with the GAMIT/GLOBK GPS data analysis system
(King 2002; King and Herring 2002) that allow interactive viewing and manipulation of GPS velocities and
time series with a Matlab-based graphical user
interface (GUI). The formats of the data files used by
the tools are specific to GAMIT/GLOBK, but they are
simple ASCII files that can be generated from other
file formats. The tools are referred to as GGMatlab.

The GPS Toolbox is a column dedicated to highlighting algorithms

and source code utilized by GPS Engineers and scientists. If you
have an interesting program or software package you would like
to share with our readers, please pass it along; e-mail it to us at
gps-toolbox@ngs.noaa.gov/. To comment on any of the source
code discussed here, or to download source code, visit our website
at http://www.ngs.noaa.gov/gps-toolbox. This column is edited
by Stephen Hilla, National Geodetic Survey, NOAA, Silver Spring,
Maryland, and Mike Craymer, Geodetic Survey Division, Natural
Resources Canada, Ottawa, Ontario, Canada. For the sidebar, see
the Volume 6, Number 4, 2003 issue of the GPS Toolbox column.
Received: 10 August 2003 / Accepted: 18 August 2003
Published online: 1 October 2003
Springer-Verlag 2003
T. Herring
Department of Earth, Atmospheric and Planetary Sciences,
Massachusetts Institute of Technology, 77 Massachusetts Avenue,
Room 54-618, Cambridge, MA 02139, USA
E-mail: tah@mit.edu
Tel.: +1-617-2535941
Fax: +1-617-2531699

194

GPS Solutions (2003) 7:194199

Introduction
The generation of tectonic velocity fields with large numbers
of GPS sites and complicated time series is becoming common. The complications in the time series are often associated with geophysical effects such as offsets due to
earthquakes, postseismic transient behavior after earthquakes, and more noise-like phenomena such as the effects
of groundwater changes. Complications in time series can
also arise from offsets due to GPS antenna and receiver
changes and the addition or removal of antenna raydomes
from a GPS site. In some cases, GPS receivers fail in modes
that generate reasonable carrier-phase measurements but
corrupt position estimates. The GGMatlab tools are designed
to allow both the generators and users of large GPS velocity
fields to examine in detail the velocity fields and the time
series from which the velocities were generated. The tools are
documented and available from http://www-gpsg.mit.edu/
tah/GGMatlab. The current version is 1.02 but the tools are
still being developed and future versions are expected.
The GGMatlab toolbox currently contains two main
components: velview, which allows viewing and analysis of
velocity fields; and tsview, which allows viewing and
manipulation of time series. The time-series viewing tool
can be invoked from within velview by clicking on a
plotted velocity vector. Within velview, profiles of velocities across regions can be generated and functions fit to the
velocity changes along the profiles. Velview allows two
different velocity field files to be overlain and the statistics
of the differences and biases between them calculated.
All of the details of the options and installation of
GGMatlab are given on the Web page. Here, we describe
some of main features and the typical scenarios for using
the packages. The package is designed to work with Matlab
release 12 and greater. Linux executable versions (kernel
version 2.4.7 and greater) are also available. The executable versions do not support all the features available when
the package is run from within Matlab.

Velview
The primary aim of velview is to allow plotting, manipulation and comparison of velocity fields generated by
GLOBK or other programs if the appropriate format files
are generated. An example of a velview screen view is
shown in Fig. 1 with some of the features invoked. The
example shown is taken from the combined analysis of the

DOI 10.1007/s10291-003-0068-0

GPS Tool Box

Fig. 1
Example of a velview screen image. In this example, two velocity fields
have been loaded from the SCIGN analysis. The primary field is
displayed in red, and the secondary in blue. The Feature File option
has been used to add the California coast (black), the major faults in
the area (green lines) and the sesismicity (brown dots, earthquake
magnitudes greater than 2 since 1996). The velocity vector of
LDES_CHT has been labeled on the figure in a yellow box (box will be
removed if it is clicked on), and the vector options are shown for the
site ISLK_GHT (grey box; the grey box will disappear once an option
is selected or the site name clicked.)

GPS data from Southern California Integrated GPS

Network (SCIGN) (Watkins et al. 1997) (http://
www.scign.org). The velocities and time series shown here
are available from http://www-gpsg.mit.edu/tah/
SCIGN_MIT. (This web page is regularly updated as new
data are added to the analysis). The input velocity field
files for velview are simple ASCII files containing column
data in free format. Data lines start with at least one blank;
non-blank characters in column 1 denote comments. The
entries on each line are site longitude (positive east,
decimal degrees), latitude (decimal degrees), east velocity,
north velocity, the differences between the east and north
velocity and model values, standard deviations for the east
and north velocities, correlation between the east and
north velocities, the vertical velocity, difference between
the vertical velocity and a model, the standard deviation of
the vertical velocity, and the 8-character site name. All
units for the velocities are mm/year. There are 13 columns
in the format. In the current version of velview, the

difference columns are not used, but in future versions

they are likely to be used to display differences with respect to models rather than total motions. For GAMIT/
GLOBK users, the velocity field files can be extracted from
the GLOBK output files.
The main features of the velview program allow the
detailed analysis of velocity fields. Two velocity field files,
referred to as the primary and secondary velocity fields,
can be displayed and compared. A simple map projection
is used to display the site locations. The longitudes are
scaled to linear units by multiplying by the cosine of the
latitude in the center of the displayed region. (In polar
regions, this projection style will be problematic.) There is
no wrapping of the longitudes across the Greenwich
meridian. For work in this area, negative longitudes should
be used west of the Greenwich meridian. When velocities
are loaded, limits can be placed on the sigmas of the displayed data so that vectors with large uncertainties are not
displayed. If vertical rates are also being displayed, the
vertical rate sigma will also be checked. The vertical rates
are displayed as north or south lines (positive velocity
north) without arrowheads and with error bars. The scale
of the vectors can be set separately for horizontal and
vertical velocities and the velocity scale is displayed in the
lower left hand corner of the figure window. The nominal
scale of 1 will display the vectors at real scale on most
computer screens (this relationship is not exact because it
depends on screen resolution and physical size). The

GPS Solutions (2003) 7:194199

195

GPS Tool Box

length of the arrowheads is specified in millimeters, which

is useful for judging the size of very small velocities. The
number of sites being displayed for each of the velocity
fields is shown at the top of the figure.
Once the velocities fields are loaded, there are options for
viewing and manipulating the fields. There are two types of
zoom available. The Vec Zoomin feature allows a clickand-drag selection of an area to be viewed in detail while
the vectors maintain their original scaling. The Zoom In
feature rescales the vectors during the zoom so that their
lengths increase with zooming (this is the standard zoom
feature in Matlab). Both zoom features maintain a stack of
previous zooms in the zoom out buttons so that previous
views can be recovered by successive zoom outs. (If both
types of zooms are used, the zoom out feature should be
used in the reverse order of the zoom ins.) At anytime,
numerical values can be entered into the arrow length
boxes, and the redraw button used to return the vectors to
well-defined lengths. The Pan box arrows and minus
sign can be used to move the view by half the current
width and zoom out by 50% of the current size.
Manipulation of the velocity fields includes the ability to
apply offsets to the motions either by typing the values into
the box next to Offset or, when this box is empty, to clickand-drag a region in which the weighted mean velocities will
be zero after the offsets are applied. The offsets are computed from the primary velocity field and applied to both
primary and secondary (if being displayed) fields. A differential offset between the two velocity fields can be calculated from a click-and-drag region or specified directly in
the box next to the Align button. Both the offset and align
options display the results in boxes on the figure and as text
in the Matlab or terminal window. The boxes on the figure
can be removed by clicking on them. The offsets are applied
as simple additions to the velocity components. For large
areas, these offsets cannot adequately represent the effects of
rotations and translations between two reference frames. In
this case, the GLOBK utility programs cvframe and velrot or
the users own tools should be used to define reference
frames and to align velocity fields in different frames.
Other manipulations available in velview include the removal
of duplicate sites with exactly the same velocities and sigmas
and within the specified distance of each other (given in the
box next to the RmDups and Stats boxes). The removal
of duplicates is useful for GLOBK analyses where sites over
some intervals of time may have been renamed because of
possible changes in position, but the velocities of the multiple
site names have been forced to be equal. The Stats button
computes the weighted root mean square (WRMS) differences in velocities between sites within each velocity field
that are separated by less than the distance given in the
box next to the button. The ID Points list all sites in a
click-and-drag region and is useful when multiple sites are
overlaid on each other and clicking on a specific vector is
difficult. The list of sites appears both in a box at the top of
figure (removed by clicking on it) and in the terminal window.
The velocity vectors plotted by velview can be selected and
the grey popup menu (example shown in Fig. 1) can be used
to obtain information about the vector. If position time
series are available, they can be plotted using the tsview
196

GPS Solutions (2003) 7:194199

program. If the time series files are not in the same directory
from which velview was run, the name of the directory can
be specified in the box next to the Time Series label at the
top of the figure. Tsview is discussed below.
Another feature of velview is the ability to select a transect
across the velocity field for profiling where the velocities are
shown as a function of distance along the profile and are
projected into directions based on the azimuth given in the
box next to the AZ button. The azimuth of the projection
can be either typed into box, graphically selected by clicking
the AZ button when the box is empty, or default to along
the profile direction and normal to the profile direction. The
profile is selected by first drawing the profile centerline and
then by graphical selecting its width. The selected profile
box is displayed on the figure and the sites inside the box are
marked with yellow circles. The profile box information is
placed on a stack as profiles are selected. The boxes and site
markings on the figure can be removed from the top of the
stack using the POP button (most recent removed) or
from the bottom of the stack (earliest removed) using the
PIP button. Only results from the primary velocity field
are shown on the profiles. (The SWAP button at the bottom of the velview window can be used to exchange the
velocity fields thus allowing profiles for each field to be
plotted in separate windows). An example of the profile plot
is shown in Fig. 2. Part (a) of the figure shows the velview
window used to select the profile and part (b) shows the
profile figure itself. For this figure, the azimuth for the
projection of the velocities along the profile was graphically
selected to be parallel to the CICE velocity vector.
In Fig. 2b, we have used the Fitting Functions window to fit
a function to the profile velocities based on the co-seismic
strain accumulation for a locked strike-slip fault (the SS
function) (Okada 1985). When velview is run in Matlab, any
valid Matlab function, defined to be a function of distance
along the profile, can be used in the fitting functions. In the
executable version, only specific functions can be used with
the pre-defined SS function being available in both the
Matlab and executable versions. The green shaded boxes on
the left of the figure show the results of the fit in the direction
of the azimuth (labeled along track), normal to this
direction (labeled cross track) and for the vertical velocity.
Because space is limited in these text boxes, the units are not
given. For the weighted root mean square (WRMS) scatter
and the amplitudes of the estimated coefficients (FCN0 and
FCN1 in the figure), they are in mm/year. The FCN0 value is
the offset of the profile velocities. The normalized rootmean-square (NRMS) scatter is dimensionless and is the
ratio of the scatter to the expected scatter based on the
velocity error bars (square root of v2-per-degree-of-freedom). A single fault with a deep locking depth has been used
to fit the profile in the example but a better fit can be obtained
by fitting to multiple faults with shallower locking depths.
Individual sites may be deleted before the fitting functions
are estimated and they appear with a cross over the point.
The results of the fit and the profile information can be
saved to a file by putting the file name in the yellow File
box and clicking the save button. Information may be
extracted from this file so that it can be plotted in another
graphics program if desired.

GPS Tool Box

Fig. 2
a The velview window used to select the profile sites shown in Fig. 2b.
The solid straight-line shows the center of the profile and the dotted
lines mark the region of the sites to be included in the profile. The
profile starts in the northeast and ends in the southwest. b The profile
window generated by velview when the profile button is selected. The
SS function in the Fitting Functions models the behavior of an
infinite strike-slip fault. In the example, the fault is locked to a depth
of 20 km and crosses the profile 200 km from the start of the profile.
The blue line in each frame shows the model values and the red line in
each frame is the mean value of the velocities. The green boxes on the
left show the results of the fit and can be removed from the figure by
clicking on them. All error bars are one standard deviation

Tsview
Tsview is the time series viewing and manipulation module
in the GGMatlab toolbox. Tsview can be invoked by selecting TimeSeries in the popup menu that appears when a
velocity vector is clicked in velview or it can be run as a
stand-alone module. Tsview plots times series of GLOBK
north, east and height (NEU) coordinate estimates
contained in GLOBK time series files. The north coordinates
are the geodetic latitudes of the sites multiplied by the
WGS84 semi major axis, the east coordinates are the
distances from the Greenwich meridian along the small
circles at (quantized) latitudes of the sites, and the heights
are WGS84 ellipsoidal heights. The latitudes of the sites are
quantized for the east coordinate calculation so that the east

coordinate does not change as a site moves by small

amounts in latitude (the files are generated with the GAMIT/
GLOBK program multibase). An example of the tsview
window is shown in Fig. 3 after detrending the time series
and removing some outliers.
When tsview is run, it checks the directory in which is was
run and looks for files with names of the form
mb_XXXXXXXX.dat1 where XXXXXXX is an 8-character
GPS site name. This file naming convention is the standard
name given to the north coordinate time series files
generated by the suite of GLOBK programs. The east and
height components have the same style names and end
with the numerals 2 and 3. If tsview is invoked from within
velview, the same list is formed and tsview tries to match
the site name passed to it from velview. The time series
files are simple ASCII files with three header records (not
used by tsview) and data records that consist of a time in
decimal years, and a NEU coordinate and sigma in meters.
When invoked in stand-alone mode, a site name is selected
from the list on the left of the screen and load button is
used to load the time series. After a series is loaded, data
from another site name may be appended. The append
option can also be used when tsview is invoked from
velview. In standard GLOBK GPS processing, breaks in a
time series, due, for example to earthquakes or equipment
changes are accounted for by changing the last 2 or 3
characters of eight-character site name. Segmented time

GPS Solutions (2003) 7:194199

197

GPS Tool Box

Fig. 2 b
(Contd.)

series of this type can be shown as single time series in

tsview. Once a time series is loaded, there are numerous
options for manipulating the time series.
The primary aims of tsview are to assess the quality of time
series and to generate files that can be used to control the
treatment of data from specific sites at specific times when
data are combined in GLOBK. The center set of buttons in the
tsview window control editing and fitting of functions to the
time series. The function boxes in the lower left hand part of
the window control mainly the output files from tsview.
Breaks in time series can be treated in multiple ways in
tsview. The break can be a simple offset in the times series
or it can be an offset followed by either an exponential or
logarithmic functions to represent the time evolution after
the break. When exponential and logarithmic functions
are used, a change in the secular rate can also be estimated
after the break. The main use of these different function
forms is to study the behavior of time series after earthquakes. Annual and semiannual components in the time
series can also be estimated. By selecting the Linear Only
Residual option, the residuals to the fit can be displayed
with only the linear motions and offsets removed. In this
mode, a thick black line shows the time variations of the
estimated model parameters and the red model uncertainty lines are placed plus and minus one standard
deviation about this black line.
The uncertainties of the parameter estimates in tsview are
calculated using the sigmas of the coordinate estimates in

198

GPS Solutions (2003) 7:194199

the time series and the statistical properties of the time series
residuals with either white or correlated noise assumptions.
If the RealSigma (meaning realistic sigma) button is
unchecked, a white noise model is used. The white noise
assumption almost invariably generates very optimistic
estimates of the uncertainties of the parameter estimates.
When the RealSigma box is checked, a time-correlated noise
model is used to estimate the parameter uncertainties. With
this model, a correlation time of the residuals for each
coordinate component is estimated by computing the increase in the chi-squared-per-degree of freedom of successively longer time averages of the residuals. For a white noise
error model, the chi-squared-per-degree of freedom would
not depend on averaging time. With temporal correlations
in the time series, chi-squared-per-degree of freedom
increases as the residuals are averaged over successively
longer time intervals. The character of the averaged residual
can be viewed in tsview using the Average button. The
value in the box below the button gives the length of time in
days that will be averaged. The statistics of the averaged
residuals are shown in bold on the display. For the example
shown in Fig. 3, the realistic sigma estimates of the secular
velocity in each coordinate of this site are 3 to 5 times larger
than the white noise estimates. Thirty-day averages of the
coordinate residuals have scatters of 0.4 mm in the
horizontal components and 0.8 mm for the vertical
component. These scatters are only a factor 2 smaller for
horizontal coordinates and a factor 4 smaller for the vertical
coordinate than the scatters of daily values. If the residuals
were white noise, the scatters should have reduced by a
factor of 5.5 (square root of 30).

GPS Tool Box

Fig. 3
Example of a tsview screen image. The time series shown is for the site
DHLG which is one of the many sites in Southern California affected
by the October 1999 Hector Mine earthquake (Hudnut et al. 2002). In
the GLOBK processing, this site is divided into a pre-Hector mine
name (DHLG_GLA) and a post-Hector mine name (DHLG_GHT).
The plot shows positions from both site names appended together
with a break in late 1999 (1999/10/16). A logarithmic function is used
to model the behavior of the site position after the earthquake. The
green horizontal lines show the bounds of 3-times the WRMS scatter
of the residuals. The red, nearly horizontal lines near zero on the plots
show the 1-r limits of the model time series based on the standard
deviations of the parameter estimates with the contribution from the
overall mean value of the time series removed. (When only a rate is
estimated, this display forms a thin x cross shape that crosses zero
near the center of the plot.) The full set of parameter estimates and
their standard deviations are written to the Matlab workspace and to a
pop-up window in the upper right hand corner of the computer
screen. In this figure we have used the Realistic Sigma model
discussed in the text

they are used.) The edit file from tsview can be used in
GLOBK to remove edited sites from an analysis and to
implement discontinuities in time series through renaming
sites. The lowest box in this part of the figure allows an output
file from the GLOBK ensum program to be used to sort the
list of sites based on the statistics of their fits to linear motions with the poorest fit sites appearing at the top of the list.

References

Hudnut KW, King NE, Galetzka JE, Stark KF, Behr JA, Aspiotes A,
van Wyk S, Moffitt R, Dockter S, Wyatt F (2002) Continuous
GPS observations of postseismic deformation following the 16
October 1999 Hector Mine, California, earthquake (Mw 7.1),
Bull Seis Soc Am vol 92, no 4, pp 14031422
King RW (2002) Documentation for the GAMIT GPS analysis
software, MIT Internal Report, 206 pp (http://www-gpsg.mit.For users of GAMIT/GLOBK, the results from tsview can be edu/simon/gtgk/GAMIT.pdf)
King RW, Herring TA (2002) Global Kalman filter VLBI and GPS
used in later GLOBK analyses of the data set. The Save
analysis program, MIT Internal Report, 98 pp (http://wwwbutton in center column will save the results from the time
gpsg.mit.edu/simon/gtgk/GLOBK.pdf)
series being displayed in the files whose names are given in
Okada Y (1985) Surface deformation due to shear and tensile
the bottom part of the left-hand column. (The small W
faults in a half space. Bull Seismol Soc Am 75:11351154
buttons show the files to be written, and the E buttons
Watkins MM, Bock Y, Hudnut KW, Prescott WH (1997) The
indicate which files will be erased before they are written. The Southern California Integrated GPS Network: Status Report, Eos
Trans AGU, AGU Spring Meeting, 29 April 1997, p 105
erase buttons reset automatically to non-erase mode once

GPS Solutions (2003) 7:194199

199