INTRODUCTION

Performs deconvolution to remove an instrument response and convolution to apply another instrument response.

SYNTAX

[TRANS]FER {FROM type {options}} , {TO type {options}} ,
      {FREQlimits f1 f2 f3 f4} , {PREWhitening ON|OFF|n},

INPUT

FROM type:	Instrument deconvolution using spectral division, EVALRESP, POLEZERO, or FAPfile EVALRESP, POLEZERO, and FAPfile are described below.
TO type:	Insert the instrument type by convolution using spectral multiplication. The allowed instrument types and their options for both TO and FROM are listed in a table below.
FREQLIMIS:	Default is it is not used. See discussion below
PREWHITENING ON:
	Turns on prewhitening in the time domain before spectral operations, and compensating dewhitening in the time domain after spectral operations.
PREWHITENING OFF:
	Turns off prewhitening.
PREWHITENING n:	Turns on prewhitening and change the prewhitening order to n. If the user turns it on without specifying the order, it will default to n=6, unless the order has been changed in the WHITEN command.
DEFAULT VALUES:	TRANS FROM NONE TO NONE PREWHITENING OFF

DESCRIPTION

The default input and output "instrument" in TRANSFER is displacement, which in SAC is designated as NONE. Hence, if a FROM type or a TO type is not specified, SAC assumes it to be NONE. If the output instrument is NONE, IDEP in the SAC header is set to DISPLACEMENT (NM) - SAC's convention for displacement. If TRANSFER uses TO VEL or TO ACC, the header variable IDEP is changed accordingly for all waveforms in memory.

If the TO type is specified as anything other than NONE, VEL, or ACC, the waveforms in memory are transformed to that instrument type. If the FROM instrument type is NONE, then no instrument is removed, and the original trace is presumed to be a displacement. This is useful for adding instrument responses to synthetic seismograms (example below).

Care must be taken when calling TRANSFER a second time within a single SAC session, because in the second call TRANSFER will use the same arguments for FROM, TO, FREQ, etc. as in the first call unless an alternative argument is explicitly provided.

Many of the instruments have options that further specify the response. The most common of these options is the instrument subtype. A few instruments require that certain numerical parameters be specified and do not use the subtype option. For a list of instruments and a list of the instruments that use subtypes or other parameters, see the table below.

When TRANSFER was introduced more than 20 years ago, the data acquisition systems were much simpler. The seismometers in the list at the end of this message include the most popular ones used previously. The evolution of data handling by IRIS is described in DATA ACCESS.

The EVALRESP program calculates the complete system response from response (RESP) files produced by commands given in RESPONSE or programs such as RDSEED. The code used in SAC does not recognize all the options available in the current version of EVALRESP (v5.0, August 2019). If one wants an option only available in the full program, one can first run EVALRESP with a FAP output option and use the FAP option (see below) to correct the SAC data file. The source code for program EVALRESP can be downloaded from URL <http://ds.iris.edu/ds/nodes/dmc/software/downloads/>.

The SAC sign convention for Laplace/Fourier transforms is the same as that used in SEED and EVALRESP: phase for a causal response decreases with increasing frequency. For displacements, the SAC convention is nm, while RESP files use meters. NOTE: The EVALRESP option in TRANSFER converts the output to the SAC convention. For other options (FAP, PZ) it may be necessary to manually change the units. (See examples below.)

FREQLIMITS f1 f2 f3 f4 All seismometers have zero response at zero frequency. When deconvolving and not convolving with another response (e.g. "TO NONE"), it is therefore necessary to modify the response at very low frequencies. At high frequencies, the signal-to-noise ratio is often low, so it may be desirable to dampen the response. FREQLIMITS serves this purpose within SAC. FREQLIMITS has both a low-pass and a high-pass taper. It is necessary that f1 < f2 < f3 < f4. The taper is unity between f2 and f3 and zero below f1 and above f4. Frequencies f1 and f2 specify the high-pass filter at low frequencies, while frequencies f3 and f4 specify the low-pass filter at high frequencies. Both f3 and f4 should be less than the Nyquist frequency: 0.5/DELTA. The filters applied between f1 and f2 and between f3 and f4 are quarter cycles of a cosine wave. To avoid ringing in the output time series, a suggested rule-of-thumb is f1 <= f2/2 and f4 >= 2*f3.

If you want to do a low-pass filter but have no filtering at low frequencies, one way is to set f1=-2 and f2=-1. If you want to do a high-pass filter but have no filtering at the high frequencies, for a Nyquist frequency of 0.5, set f3=10. and f4=20.

Note that because this filter has zero phase, it is not causal. As a result, if npts is not a power of 2, the output amplitude will not be zero outside the interval (f1,f4). If it is important to have the number of points an exact power of 2, the help file for CUT explains how to modify your file within SAC.

NOTE that the default has no FREQLIMITS. It is strongly advised that one includes FREQLIMITS if one is doing a deconvolution.

Prewhitening can be used to flatten the spectrum of the input time series before transforming in the frequency domain. This should reduce the dynamic range of the spectral values, and improve the accuracy of the overall operation at high frequencies for seismic data. The default for prewhitening is off. See command WHITEN for further information.

FROM EVALRESP

This option enables the application of transfer functions extracted from SEED data volumes using the EVALRESP code (Version 3.3.3). To use this option, one needs a RESP file. The RESP files must be in the current directory or must be specified by full path and name.

There is no formal documentation for the RESP files themselves, but since they refer directly to the SEED format, please refer to the SEED manual to learn more about the values.

To identify the correct RESP file and to extract the proper transfer function from that file, EVALRESP uses information from the SAC headers. The fields are station (KSTNM), channel (KCMPNM), date and time (KZDATE & KZTIME), network (KNETWK), and location ID (KHOLE). Outside of SAC, location ID is referred to as LOCID; it commonly distinguishes between multiple instruments with the same network, station and channel names, operating at the same time. Data received from IRIS in SAC format (or converted to SAC with RDSEED) will have KHOLE set to a valid LOCID if one is necessary. If the user is informed of real LOCIDs in the EVALRESP file, the user can set KHOLE with CHNHDR. SAC will use KHOLE as LOCID if it is a two character alpha-numeric string (padded with spaces or not).

It is possible to override the header values by specifying additional options to EVALRESP. The possible options are:

STATION, CHANNEL, NETWORK, DATE, TIME, LOCID, FNAME

and each option must be followed by an appropriate value. If DATE is not set in the header and is not specified as an option, then the current date is used in the search. If TIME is not set in the seismogram header and is not specified as an option, then the current system time is used in the search. If network is not specified, then the search for a transfer function defaults to use any network. If LOCID is not set at the command line or in KHOLE/LOCID, then the search for the transfer function defaults to use any LOCID. To force TRANSFER to use a specific SEED response file use the FNAME option followed by the filename.

If the FNAME option is not specified EVALRESP will attempt to identify the correct file in the current working directory using the general form:

RESP.<NET>.<STA>.<LOCID>.<CHAN>

for example: "RESP.IU.ANMO..BHZ"

The embedded version of EVALRESP is configured to always produce a displacement response in SI units (i.e. displacement in meters), which SAC scales internally by a factor of 1.0e9 to nanometers, the SAC convention for displacement units.

EVALRESP EXAMPLE

To remove the instrument response from the seismogram in memory (assuming a response file exists):

SAC> r 2006.253.14.30.24.0000.TA.N11A..LHZ.Q.SAC
SAC> RTR
SAC> TAPER
SAC> TRANS FROM EVALRESP TO NONE freq 0.004 0.007 0.2 0.4

To remove the instrument response from the same waveform but using a response contained in file /tmp/Responses/RESP.TA.N11A..LHZ:

SAC> SETBB RESP "/tmp/Responses/RESP.TA.N11A..LHZ"
SAC> r 2006.253.14.30.24.0000.TA.N11A..LHZ.Q.SAC
SAC> RTR
SAC> TAPER
SAC> TRANSFER FROM EVALRESP FNAME %resp TO NONE FREQLIM 0.004 0.007 0.2 0.4

To remove the instrument response from 16.42.05.5120.TS.PAS.BHZ.SAC and apply the response from station COL, channel BHZ for the same time period:

SAC> R 16.42.05.5120.TS.PAS.BHZ.SAC
SAC> RTR
SAC> TAPER
SAC> TRANS FROM EVALRESP TO EVALRESP STATION COL

To display the instrument response in units of displacement for station COL, channel BHZ, network IU, for the date 1992/02 and time 16:42:05:

SAC> FG IMPULSE NPTS 16384 DELTA .05 BEGIN 0.
SAC> TRANS TO EVALRESP STATION COL CHANNEL BHZ NETWORK IU DATE 1992/2 TIME 16:42:05
SAC> FFT
SAC> PSP AM

COMMENTS: rtr removes any trend and offset. Because the FFT called by TRANSFER pads with zeroes to a power of 2 number of points, TAPER eliminates any large jumps at the ends of the time series. FREQLIMITS is necessary for deconvolution TO NONE because the instrument has zero response at zero frequency.

FROM POLEZERO

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.

A polezero file as written may be for displacement, velocity, or acceleration, and the units of the output should be known in advance. If the polezero file was written by program RDSEED 5.0 or later, this information is included in the file (see example below).

The transfer function, H(s), is the Laplace transform of the linear system impulse response of the seismometer. The Laplace variable s = 2*pi*i*f, where f is the frequency in Hz.

The response H(w) is the ratio of the product of the difference between s and each of the np poles and nz zeros:

       (s-z )*(s-z )*...*(s-z  )
           1      2          nz
H(s) = -------------------------
       (s-p )*(s-p )*...*(s-p  )
           1      2          np

The options in the file (poles, zeros, constant, and comment lines) are keyword driven and numbers are in free format. CONSTANT is a scaling factor. (See IRIS DMC's SAC PZ web service <http://service.iris.edu/irisws/sacpz/> or the SEED manual for how it is defined.) The default for CONSTANT is 1.0 if one omits this line. one specifies the number of poles by putting a line in the file with the keyword "POLES" followed by an integer number (np in the above example). The next np lines in the file, each containing two floating-point numbers, are the poles for this instrument. One specifies the zeros with a line starting with "ZEROS" followed by an integer specifying the number of zeros (nz). Because a typical polezero file has one or more zeros that are (0.0,0.0), SAC does not require one to write out a line for a zero equal to (0.0,0.0), so the number of zeros lines can be less than nz. One may specify up to 30 poles and 30 zeros.

The original SAC polezero files only contained poles, zeroes, and a constant. About ten years ago it was decided that supplying formatted comments as a header in the polezero file helps users organize and understand the origins of the coefficients presented. For this reason, since 2011 SAC supports the annotated polezero file, produced by RDSEED (starting with v5.2, October 2011) or available for the IRIS SACPZ archive. Depending on the request format, a polezero file returned by sacpz may include multiple polezero files covering more than one time epoch as well as more than one station and/or channel. A call to TRANSFER using such a file will work satisfactorily for all waveforms in memory with annotation values that match the header values.

Options for specifying the NETWORK, STATION, LOCID, CHANNEL, DATE, TIME are available for the POLEZERO option as they are in the EVALRESP option.

The polezero file below was written by program RDSEED (v5.2):

* **********************************
* NETWORK   (KNETWK): II
* STATION    (KSTNM): PFO
* LOCATION   (KHOLE): 00
* CHANNEL   (KCMPNM): BHZ
* CREATED           : 2011-08-11T00:24:07
* START             : 2010-07-30T18:50:00
* END               : 2599-12-31T23:59:59
* DESCRIPTION       : Pinon Flat, California, USA
* LATITUDE          : 33.610700
* LONGITUDE         : -116.455500
* ELEVATION         : 1280.0
* DEPTH             : 5.3
* DIP               : 0.0
* AZIMUTH           : 0.0
* SAMPLE RATE       : 20.0
* INPUT UNIT        : M
* OUTPUT UNIT       : COUNTS
* INSTTYPE          : Streckeisen STS-1 Seismometer with Metrozet E300
* INSTGAIN          : 3.314400e+03 (M/S)
* COMMENT           : S/N #119005
* SENSITIVITY       : 5.247780e+09 (M/S)
* A0                : 7.273290e+01
* **********************************
ZEROS       6
-7.853982e+01       +0.000000e+00
-1.525042e-01       +0.000000e+00
-1.525042e-01       +0.000000e+00
POLES       6
-1.207063e-02       +1.224561e-02
-1.207063e-02       -1.224561e-02
-1.522510e-01       +9.643684e-03
-1.522510e-01       -9.643684e-03
-4.832398e+01       +5.817080e+01
-4.832398e+01       -5.817080e+01
CONSTANT    3.816863e+11

For this transfer function, there are six poles, for which the complex values are listed on the six lines following the line POLES 6. There are six zeros, but because only three are listed, the three not listed have the value of (0.0,0.0).

The INPUT UNIT for any polezero produced by sacpz or evalresp will be "M", so seismometers and accelerometers perform a simple conversion to address integration. An accelerometer will add two "zeros" to the beginning of a channel's zero response to step down to displacement. For velocity, the program just adds one "zero". The number of zeros in stage 0 in the RESP file may differ from the number in the polezero file because INPUT UNIT in the polezero is fixed while "Response in units" in the RESP file is not.

Note that when one compares the SAC waveform file to the polezero file, the SAC header value COMPINC differs by 90 degrees from the polezero DIP: CMPINC is degrees from the upward vertical, and DIP is the downward positive angle from horizontal. The polezero AZIMUTH uses the same convention as the SAC header CMPAZ.

To use this option, one specifies the type to be POLEZERO and the [S]ubtype is the name of the file. This may be a file in the current directory or in some other directory if one specifies the absolute or relative pathname.

POLEZERO SEARCH

If a SUBTYPE with FILENAME is not set, SAC will search the current directory for SAC Polezero files named like:

SAC_PZs_NETWORK_STATION_CHANNEL_LOCID_*

where NETWORK, STATION, CHANNEL, LOCID are either those defined in the SAC Header or specified on the command like, e.g.:

TRANSFER from POLEZERO NETWORK BK STATION CMB to NONE

Matching files will be searched for the correct response using the associated metadata. The first file found with the correct metadata will be used for the response. Files with no associated metadata are assumed to be the correct response.

Use the DIR option to specify an alternative search directory, for example:

TRANSER from POLEZERO DIR resp to NONE

will search for responses like:

resp/SAC_PZs_NET_STAT_CHAN_LOC_*

An simple example of the automatic polezero search option would be to remove the responses for all files in memory, assuming the responses are in the current directory

SAC> READ *.XT.*.BHZ.SAC
  XT.ATAT.01.BHZ.M.2001.255.084837.SAC
  XT.DAWA.01.BHZ.M.2001.255.084837.SAC
SAC>
SAC> rtrend
SAC> transfer from POLEZERO  to  NONE   FREQLIMITS (1/120) (1/60)  6 7
 Using polezero response for ATAT, BHZ, XT, 01 from SAC_PZs_XT_ATAT_BHZ_01_
 Station (ATAT    ), Channel (BHZ     )
 Using polezero response for DAWA, BHZ, XT, 01 from SAC_PZs_XT_DAWA_BHZ_01_
 Station (DAWA    ), Channel (BHZ     )

If the responses are instead in a directory named responses, a DIR responses should be added to the FROM part section, e.g.:

SAC> transfer from POLEZERO DIR responses to  NONE   FREQLIMITS (1/120) (1/60)  6 7
 Using polezero response for ATAT, BHZ, XT, 01 from responses/SAC_PZs_XT_ATAT_BHZ_01_
 Station (ATAT    ), Channel (BHZ     )
 Using polezero response for DAWA, BHZ, XT, 01 from responses/SAC_PZs_XT_DAWA_BHZ_01_
 Station (DAWA    ), Channel (BHZ     )

POLEZERO EXAMPLES

The PZ file SAC_PZs_XC_OR075_LHZ is the correct one to remove the instrument response from waveform OR075_LHZ.SAC:

SAC> SETBB pzfile "SAC_PZs_XC_OR075_LHZ"
SAC> READ OR075_LHZ.SAC
SAC> RTR
SAC> TAPER
SAC> TRANS FROM POLEZERO S %pzfile TO NONE FREQ 0.008 0.016 0.2 0.4
SAC> MUL 1.0e9
SAC> w OR075.z

The MUL 1.0e9 command converts the displacement output from the POLEZERO meters to the SAC default of nanometers.

For the above example, suppose one had not used SAC_PZs_XC_OR075_LHZ but instead has used an inappropriate PZ file: SAC_PZs_wrong. The following procedure shows how one can use one call to TRANSFER to take out the incorrect response and put in the correct response:

SAC> READ OR075.z
SAC> write OR075.zbad
SAC> SETBB pzo "SAC_PZs_wrong"
SAC> SETBB pzn "SAC_PZs_XC_OR075_LHZ"
SAC> TRANS FROM POLEZERO S %pzn TO POLEZERO S %pzo FREQ 0.008 0.015 0.2 0.4
SAC> write OR075.z

The first write statement makes a copy of the original file.

As a final example we consider the case for which one has several stations and BH* channels for waveforms from an event in the calling directory written by RDSEED v5.2. Assume one has made a call to sacpz or concatenated all the BH* PZ files for this event into a single file named event.pz. The following sequence will read all the BH* waveforms into memory and overwrite those files in memory with instrument-corrected waveforms:

SAC> r *BH*SAC
SAC> rtr;taper
SAC> TRANS FROM POLEZERO S event.pz freq 0.05 0.1 10.0 15.0

FROM FAPfile

Reintroduced into SAC in version 101.4, is the FAPfile option. A FAPfile is an ascii file in which each line has three entries: a frequency (in HZ), an amplitude, and a phase (in degrees that will decrease with increasing frequency). This FROM option will deconvolve the waveform over the frequency range from the frequency in the first line to the frequency in the last line. The frequencies need not be equally spaced. When applying the correction, for frequencies less that the frequency in the first line, the amplitude and phase of that first line are used. Similarly, for frequencies greater than that in the last line, the amplitude and phase for the frequency in the last line are used.

As of version 3.3.2 in EVALRESP, a FAPfile output can be generated. An advantage of using a FAPfile generated by EVALRESP rather than a POLEZERO file generated from the same RESP file is that one can include additional stages of the instrument response and/or control more explicitly the frequency range over which the correction is applied. Historically, a FAPfile was used because one did not have a polezero file for the instrument or the full response included analog stages.

The format of a FAPfile is consistent with that produced by the standalone program EVALRESP, but is different from the format used by (pre-200S) SAC2000.

FAPfile EXAMPLES

Suppose one has a FAPfile fap.n11a.lhz_0.006-0.2, where the name is a short-hand for the fact that the frequency range is fro m0.006 HZ to 0.2 HZ, and one wants to remove the instrument response from waveform 2006.253.14.30.24.0000.TA.N11A..LHZ.Q.SA.

SAC> READ 2006.253.14.30.24.0000.TA.N11A..LHZ.Q.SAC
SAC> RTR
SAC> TAPER
SAC> TRANSFER FROM FAP S fap.n11a.lhz_0.006-0.2 FREQ 0.004 0.006 0.1 0.2
SAC> MUL 1.0e9

COMMENTS: As with the EVALRESP and POLEZERO options, one should accompany the instrument correction with a FREQLIMITS option to handle the highest and lowest frequencies. (The Nyquist for this LHZ file is 0.5 Hz.). As discussed above, if FAP comes from EVALRESP, the units need to be converted from SI units (meters for displacement) to the SAC convention.

AVAILABLE INSTRUMENT TYPES

NOTE [ + ] ACC, VEL, and NONE do not refer to actual seismometer specifications but to acceleration, velocity, and displacement respectively. When these are specified as the TO type, IDEP is set accordingly.

NOTE [ ++ ] EVALRESP and POLEZERO do not refer to actual seismometer specifications. They are described in greater detail above.

INSTRUMENT TYPE OPTIONS

EXAMPLES

To remove the instrument response from the RSTN station NYKM.Z and apply the instrument response for DSS without prewhitening (which is the default):

SAC> READ NYKM.Z
SAC> TRANS FROM RSTN SUBTYPE NYKM.Z TO DSS PREW OFF

To remove the LLL broadband instrument response and apply the SRO instrument response with frequency tapering and prewhitening:

SAC> READ ABC.Z
SAC> TRANS FROM LLL TO SRO FREQ .02 .05 1. 2. PREW 2

The passband of the resulting trace will be flat from .05 Hz to 1 Hz and will be zero below .02 Hz and above 2 Hz. Prewhitening of order 2 is applied in the time domain before deconvolution and the effect is removed in the time domain after convolution.

To transfer from the electromagnetic instrument response to displacement:

SAC>  READ XYZ.Z
SAC>  TRANSFER FROM ELMAG FREEP 15. MAG 750. TO NONE

ACKNOWLEDGEMENTS

Roger Hanscom did the original conversion of Keith Nakanishi's TRANSFER program. George Randall added the prewhitening option and was a major contributor to the testing and documentation of this command. Doug Dodge included the EVALRESP option.

HEADER CHANGES

• idep
• depmin, depmax, depmen

LATEST REVISION

Version 102.0