[SAC-HELP] polezero option -- correct file this time

[Arthur Snoke]

Unfortunately, the file I sent was the unaltered "transfer' help file, 
rather than my revised "polezero" subset of that file.  The desired file 
(I hope) is attached.

---------- Forwarded message ----------
Date: Fri, 24 Apr 2009 14:36:39 -0400 (EDT)
From: Arthur Snoke <snoke at vt.edu>
To: SAC-help Listserv <sac-help at iris.washington.edu>
Subject: [SAC-HELP] polezero option

We are preparing the next update for SAC, and I have been looking at some 
"help" files called from within SAC (and in the computer accessible manual), 
and have changed a few.  Because there were several e-mail exchanges regarding 
the polezero option of transfer, I looked closely at

SAC> help transfer

I am attaching my first draft for a replacement of that section of the transfer 
help command.  Please share comments/corrections, etc.

Others I have already worked on are 04graphics, 09file_format, begindevices, 
enddevices.

If there are others you think need updating, please share.  It is more likely 
they will be included if you send me a suggested revision!

Finally, I have written a C program for doing endian swapping for .sgf files 
(SAC Graphics Format files).  I have tested it on several platforms, but if 
someone would like to try it -- or just want an advance copy -- let me know.

Arthur Snoke
snoke at vt.edu
-------------- next part --------------

POLEZERO OPTION:

POLEZERO is an instrument type that can be used to put in or take out the 
(analog) seismometer response.  A good reference is Appendix C in the SEED
manual.  The current version can be downloaded from IRIS at URL
<http://www.iris.edu/software/downloads/seed_tools/>, and a good way to get a
polezero file in the correct format is to download data as a SEED volume and use
program rdseed to extract the data, the polezero file(s) and the response file. 
Program rdseed can be downloaded from the same Web site.  The response file for
a specified channel/station is useful to see the "response in" and "response
out" units for the transfer function.  Typically, the "response in" listed in
the response file is velocity, in m/s, but the polezero file has a "response in"
of displacement.

      A polezero file is a listing of complex zeros and poles of a causal filter
that represents the seismometer.  The transfer function is of the form

(s-z1)(s-z2)...*s-zn)
_____________________

s-p1))(s-p2)...*s-pm) 

where the z1 ... zn are the N zeros and the p1 ... pm are the m poles of the
transfer function.  The convention used is a Laplacian transform, with  s = 2\pi
i f with f the frequency in Hz.  The sign convention is e^{-st} for the forward
transform (from the t domain to the s domain). 
      Here is a polezero file for the LHZ channel from station JCC returned by program rdseed for a 28 June 2007 teleseism:

ZEROS 3
POLES 5
-0.0370  0.0370
-0.0370  -0.0370
-118.7520  423.4880
-118.7520  -423.4880
-251.3270  0.0000
CONSTANT 3.056572e+16

For this transfer function, there are five poles, for which the complex values
are listed on the five lines following the line POLES 5.  Also there are three
zeros.  None are listed, and the convention is that an unlisted zero has the
value of zero.  Hence if there were five zeros, for which three were actually
zero, one could either write out five lines for which three of them would be
0.00 0.00 and the other two the complex, nonzero values, or one could have ZEROs
5 with only the two nonzero zeros explicitly written out.  In the response file
for this channel, there are only two zeros because the "response in" is velocity
but rdseed "knows" that the user wants to work with waveforms corrected to
displacement. The CONSTANT is a multiplicative factor that rescales the
"response in" units to the "response out" units at the normalization frequency. 
The derivation of CONSTANT is described in the SEED manual and can be pieced
together for a particular channel from that channel's response file.  

     The default for CONSTANT is 1.0, the options can be written in any order,
and one can add a comment line by starting that line with a * (asterisk).

      To use this option you specify the type to be POLEZERO and the subtype to
be the name of the file.  This may be a file in the current directory or in some
other directory if you specify the absolute or relative pathname.  It may also
the the name of a global file contained in the sac subdirectory
sac/aux/polezero/.  By putting a file in this global directory, anyone on your
system can easily use it. 

EXAMPLE:  suppose the file was named sro.pz and you want to remove the
instrument response from station ABC.Z.  

      u:  READ ABC.Z

      u:  TRANSFER FROM POLEZERO SUBTYPE SRO.PZ TO NONE