NAME
antelope - Introduction to the Antelope Environmental Monitoring Software
DESCRIPTION
The software from Antelope provides a wide variety of tools for
managing and working with seismic data. In addition, it provides
documented interfaces for developing new tools in
C,
TCL/Tk, shell
script,
Fortran,
Perl,
Python, and
MATLAB. This man page provides a brief overview of
the more important programs. Please refer to
hier(5) for a description
of the filesystem hierarchy, and to
antelope(3) for an introduction to the
programming interface. The man page
antelopeenv(5) documents the environment
variables.
Most of the Antelope programs are built upon a relational database,
using a variation of the CSS 3.0 schema. The underlying Relational Database
Management System (RDBMS) is Datascope, and is part of the system.
Datascope represents tables as fixed-format, plain ASCII text files.
Waveform data is kept in external (outside the database) binary files
which may have a variety of formats. A tutorial introduction to Datascope
(in the doc directory of the distribution) has a lot more detail.
LICENSE
Antelope is licensed commercial software. The software license agreement
for Antelope may be found in the file
$ANTELOPE/license.txt
Antelope ships with several software elements derived from freely-available
sources. The licenses for these open-source elements may be found in the
directories
$ANTELOPE/data/licenses/
/opt/antelope/perl5.26.1/licenses/
/opt/antelope/python3.6.5/licenses/
/opt/antelope/tcltk8.4.19/licenses/
/opt/antelope/tcltk8.6.0/licenses/
where
$ANTELOPE is the root directory for the Antelope installation (see
antelopeenv(5)).
THIRD PARTY TOOLS
Every Antelope distribution includes a distribution of
Perl and
a distribution of
TCL/Tk.
Antelope uses both of these freely available programming languages
in various parts of the system.
TCL/Tk tends to be used where
a complex GUI is required (eg,
dbe(1) and
dbevents(1)).
Perl is often
used for administrative tasks (eg,
rtexec(1) and
rtdbclean(1)), and
increasingly in GUI tools like
rtdemo(1).
Perl
The
Perl distribution is version 5.26.1, with the
following extensions:
-
Bundle::CPAN
Utilities for accessing the CPAN (Comprehensive Perl Archive Network).
-
Bundle::LWP
-
Digest::SHA1
-
Expect
Similar to TCL/Tk expect, for automating interactive tools
-
Email::Sender
-
Email::Simple
-
MIME::Base64
-
Mail::Internet
-
Mail::Sender
All for mail related processing.
-
Net::DNS
-
Net::Telnet
-
HTML::Lint
-
Parse::RecDescent
-
Tk
-
Tk::JPEG
-
Tk::Graph
-
Tk::ErrorDump
Perl/Tk
-
Devel::ptkdb
A perl GUI debugger using Perl/Tk
-
Crypt::OpenSSL::DSA
-
HTTP::Server::Simple
-
HTTP::Server::Simple::Static
-
CGI::SSI
-
HTML::Parse
-
Devel::Symdump
-
Filter::Simple
-
Text::DelimMatch
-
Net::Ping::External
-
Tk::HTML
-
IO::Capture::Stdout;
TCL/Tk
The current distribution includes
TCL/Tk 8.6.0, without any extensions.
The
TCL/Tk distribution version 8.4.19 from previous Antelope releases
is also included. The following extensions are available for 8.4.19:
-
blt2.4
Used for 2d graphs; apparently not maintained. Deprecated.
-
itcl3.3
Used for object-oriented development; deprecated.
-
tclx8.4
A variety of useful extensions; however, this extension cannot
be compiled on Darwin. Deprecated.
Although these extensions are used in a variety of programs
within Antelope, our ultimate goal is to eliminate these extensions,
because of the maintenance problems they create.
Python
For details on the
Python interpreter included with Antelope, see the man-page
notes_python(5).
CONTRIBUTED CODE
Members of the Antelope User Community routinely develop additional programs and libraries based on Antelope and
designed to work in conjunction with Antelope utilities. Source-code and compiled binaries for these programs
and libraries may be downloaded separately from Antelope User Community sites, as described in the man-page
contrib(5).
PROGRAMS
Antelope programs fall into a few broad classes. This introduction
mentions some of the more important programs. Most
programs have man pages which should be consulted for more information.
You should also try running
% man -k
to find programs of interest.
Real Time System Programs
Most of these programs interact with an
orbserver(1),
reading or writing packet data
or other messages to a ring buffer. A less capable relation
is a
diskserver(1) which provides an
orb(3) interface to
a collection of packet files created using
orb2disk(1). An
orb2disk/
diskserver packet ring buffer can be much larger
than an
orbserver(1), but does not provide the performance or
some of the utility of an
orbserver(1).
rtexec(1) supervises the operation of a real time system, while
rtm(1) provides a visual interface for monitoring and manipulating
the system.
q3302orb(1), dbreplay(1) and stream2orb(1)
place data packets onto an orb.
orb2orb(1) and orbxchange(1) copy from one orbserver(1) to another.
orb2db(1) and orb2wf(1) assemble data packets from an orb into waveform files in
a CSS database. orb2dbt(1) copies database rows from an orb into a database.
Some processing programs both read and write to the orb: orbdetect(1),
and orbassoc(1) form the basis of real time detection and location.
orbevproc(1) can calculate
magnitudes (and other general purpose waveform processing) and
leave results back on the orb.
orbrtd(1) is useful for continuously viewing waveform data in the orb.
orbstat(1) provides a means of monitoring the status of a ring buffer, as
well as a method for interactively examining specific packets; it is
very useful for debugging certain kinds of processing problems.
There is the q3302orb(1) program for Quanterra dataloggers.
Similarly, for Kinemetrics K2 dataloggers, there is
altus2orb(1).
For commanding Kinemetrics or Quanterra dataloggers, the
program dlcmd(1) is used.
For monitoring datalogger status, the program dlmon(1) presents a
generalized interface which can be utilized by any program which reads
data from a datalogger and puts it onto an orb.
Import
These programs simplify the process of creating a CSS database from
the commonly used SEED format:
miniseed2db(1) and
seed2db(1).
In addition, for users who download and install the Antelope
contrib(5) code,
various additional programs such as
sac2db,
ah2db and
segy2css are available
for importing
SAC,
AH and
SEGY formats.
pde2origin(1) and qed2origin(1)
convert PDE and QED bulletins to CSS origin tables; however, the sources
of these bulletins regularly change the format of the data they provide,
so it is difficult to keep the programs up to date.
Waveform Display and Manipulation
The primary program for waveform display and interactive picking is
dbpick(1). This program has a wide range of viewing options, allows filtering,
measuring amplitude and period, association with existing catalogs,
and the display of predicted arrivals from an associated event.
dbap(1) performs array processing, including filtering and stacking,
the generation of beams, slowness-time grids, and a variety of display
options.
dbspgram(1) generates spectrograms.
The contributed program dbheli(1) (part of the separate contrib(5) software package)
creates plots that are similar to helicorder recordings and may be useful for quick screening of data.
dbrsec(1) generates record section plots.
trexcerpt(1) segments data, typically for excerpting sections
of interest from a continuous data stream.
The contributed program dbdec(1) (part of the separate contrib(5) software package) decimates data.
dbdetect(1) is an automated arrival picker with an onset estimation; it
adds arrival picks to the arrival table.
dbevproc(1) calculates magnitudes from amplitude measurements.
dbloc2(1) is an interactive program for bulletin preparation.
It allows interactively picking, grouping and associating arrivals, finding
locations and displaying waveforms and residuals.
Database Display and Manipulation
The primary tool for database manipulation is
dbe(1), which allows
displaying, modifying and manipulating database tables. It
can generate graphs, and waveform and response displays, and
can be extended to run other display programs.
An associated program,
dbhelp(1), is used to explore a database schema.
The
dbe(1) has been rewritten, with the original available as
dbe_dep(1).
Command line tools for performing common database operations are
dbcp(1), dbjoin(1), dbsubset(1), dbsort(1), dbdelete(1), dbcrunch(1),
dbtheta(1), dbselect(1), dbunjoin(1), and dbnojoin(1).
dbset(1) can be used to perform global changes in a database.
dbconvert(1) converts a database from one schema to another.
dbverify(1) checks on the internal consistency of a database.
dbdiff(1) compares two databases.
Export
Antelope directly supports exporting from
CSS databases into
SEED,
using
db2sd(1).
Contributed programs (separately downloaded, see
contrib(5))
support export into
SAC and
AH:
db2sac and
db2ah.
trexcerpt(1) segments waveforms and can output various formats, including
SAC and
AH.
dbwfexcerpt_dep(1) also has an option to generate
SAC files.
Miniseed
There are a host of programs for dealing with miniseed (
SEED data with
only waveform data, no parameter information like station location and responses).
miniseed2days(1) splits miniseed files into station/channel day volumes.
miniseed2orb(1) splits miniseed files into individual
SEED blocks, and puts
those blocks as packets onto an orb;
orbmsd2days(1) reads such packets and writes
them into station/channel day volumes, ala
miniseed2days(1).
log2miniseed(1) creates
miniseed from log files.
msdd(1) allows inspecting miniseed in some detail, and
extracting specific blocks.
patch_miniseed(1) can correct reverse integration
constants in miniseed;
alter_timestamps(1) can change the time stamps in miniseed.
db2msd(1) compresses the integer waveform files created by
orbmsd2days(1) into miniseed.
In addition, there are
C interfaces for reading and writing miniseed.
Utility
The
CSS database uses epoch times throughout; it's common to need
to convert from epoch time to a more readable format. The program
epoch(1) is useful for this purpose.
pfecho(1) and pfwhich(1) are useful for investigating parameter files.
gsregion(1) is an interactive program for finding seismic and geographic
region numbers from latitude and longitude. dbsetrgn(1) sets region
numbers in origin tables, and the Datascope expression calculator dbcalc(1)
also has geographic and seismic region functions.
ENVIRONMENT
Please refer to
antelopeenv(5).
LIBRARIES
The programs above are based upon an extensive set of libraries,
most of which are documented. These provide a powerful basis for
developing new tools. Please refer to
antelope(3) for more information.
BUGS AND CAVEATS
Please report bugs and questions to
support@brtt.com.
Please bear in mind that a complete description
of the problem, including an example of how to generate it, what you
expected and what you actually saw, and any
error messages generated is essential to diagnose and fix
problems. See bugs(5) for further suggestions on how to report
problems.
Do not send problem reports to individual email addresses at
BRTT: they will not be answered. To receive a response, only
use support@brtt.com. Requests sent to support@brtt.com
are read by multiple people and will be responded to in a timely manner.