SUMMARY

Defines the amount of a data file to be read. As discussed below, CUT can be preceded by CUTERR, which controls errors if the chosen amount includes times outside B to E. The syntax will then be CUTERR {CUTERR option} ; CUT {CUT options}. CUT does not act on data currently in memory: a call to CUT must be followed by a READ or FUNCGEN to take effect.

SYNTAX

CUT {ON|OFF|pdw|SIGNAL}

INPUT

ON:	Turn cut option on but don't change pdw (see below).
OFF:	Turn cut option off.
pdw:	Turn cut option on and enter/change pdw. A pdw is a partial data window. It consists of a starting and a stopping value of the independent variable, usually time, which defines the segment of a file one wishes to read. The most general form of a pdw is ref offset ref offset, where ref is a number or a reference value that is one of the following: B|E|O|A|F|Tn, where n=0,1...9, and N, the number of points. The reference values are defined in SAC data file format and reviewed below.
offset:	A positive or negative number that is added to the reference value.
SIGNAL:	Equivalent to typing: A -1 F +1.

DEFAULT VALUES

CUT OFF (equivalent to CUT b e)

CUTERR FILLZ for signal stacking subprocess, USEBE for others

DESCRIPTION

The CUT command simply sets cut points and does not change the file in memory. For the command to take effect, CUT must be followed by a READ. This is in contrast with command CUTIM, which carries out cut (or cuts) on the data currently in memory.

If the start or stop offset is omitted it is assumed to be zero. If the start reference value is omitted it is assumed to be zero. If the stop reference value is omitted it is assumed to be the same as the start reference value.

With CUT off, the entire file is read. With CUT on, only that portion of the file between the starting and stopping cut values is read. These are values in terms of the independent variable in the data file, normally time. (See SAC data file format for a discussion of dependent and independent variables.) The following header variables are used to represent certain values of the independent variable:

B:	Disk file beginning value;
E:	Disk file ending value;
O:	Event origin time;
A:	First arrival time;
F:	Signal end time;
Tn:	User defined time picks (n = 0,1...9)

B and E are required for each data file in memory. O, A, F, and Tn can be defined for a data file in memory using the CHNHDR command. If one want to select the same time window from a group of data files that have different reference times, one must use the SYNCHRONIZE command before executing the CUT command. SYNCHRONIZE modifies the headers so that each file has the same reference time. It also adjusts all of the relative times, including B and E. Then when the files are cut, they will have the same time reference values. Since CUT is applied to the headers on disk, you must use the WRITEHDR command after the SYNCHRONIZE command and before the READ command to get the correct set of files before applying CUT.

CUTERR is entered only if one wants to do something other than the default for an error.

For CUT (but not for CUTIM) an option for the stop value is to enter N, which is the offset in the number of points from the start reverence value.

EXAMPLES

The macro below demonstrates several possible uses of CUT. The macro cut_runs.m, is in the SAC macros directory: ${SACHOME}/macros/. It, along with the results from entering m ${SACHOME}/macros/cut_runs.m after starting SAC. It is suggested that one runs this macro and compares the results with those from the macro in the help filefor CUTIM:

** ${SACHOME}/macros/cut_runs.m
echo on

* no cutting
cut off
fg seismo
lh b e a kztime

* begin to end---same as no cutting.
lh b e a kztime

* First 3 secs of the file
cut B 0 3
fg seismo
lh b e a kztime

* From 0.5 secs before to 3 secs after first arrival
cut A -0.5 3
fg seismo
lh b e a kztime

* From 10 to 15 secs relative to zero
cut 10 15
fg seismo
lh b e a kztime

* From 0.5 to 5 secs relative to disk file start.
cut b 0.5 5
fg seismo
lh b e a kztime
fg seismo

* First 3 secs of the file and next 3 sec
cut b 0 3
fg seismo
write tmp.1

cut b 3 6
fg seismo
write tmp.2

cut off
read tmp.?
lh b e a kztime
title "top: cut b 0 3; bottom: cut b 3 6"
p1
save cut-test.pdf
\rm tmp.*

* Examples using CUTERR_

cut off
fg seismo
lh b e a npts kztime

cut a -0.5 15
fg seismo
lh b e a npts kztime

cuterr usebe ; cut a -0.5 15
fg seismo
lh b e a npts kztime

cuterr fillz ; cut a -0.5 15
fg seismo
lh b e a npts kztime

Note that one can a pad the beginning or end of a file with zeros by turning on the FILLZ option in the CUTERR command, defining a cut that extends beyond the current limits of the file, and then reading the file into memory using the READ command.

ERROR MESSAGES

• 1322: Undefined starting cut for file
  • undefined reference value in the header record.
  • this error can be controlled by use of CUTERR command.
  • when this error is off, the disk begin value is used.
• 1323: Undefined stop cut for file
  • undefined reference value in the header record.
  • this error can be controlled by use of CUTERR command.
  • when this error is off, the disk end value is used.
• 1324: Start cut less than file begin for file
  • bad CUT parameters.
  • this error can be controlled by use of CUTERR command.
  • when this error is off, the disk begin value is used or zeros are insertedat the beginning of the data.
• 1325: Stop cut greater than file end for file
  • bad CUT parameters.
  • this error can be controlled by use of CUTERR command.
  • when this error is off, the disk end value is used or zeros are inserted at the end of the data.
• 1326: Start cut greater than file end for file
  • bad CUT parameters.
  • this error cannot be turned off.

SPECIAL NOTE

Since this is a parameter-setting command, the above errors will not appear until the READ command is executed. Also, some of the above errors can be converted to warnings by the use of the CUTERR command.

LIMITATIONS

There is currently no provision for cutting unevenly-spaced files or spectral files.

SEE COMMANDS

READ, APK, PLOTPK, SYNCHRONIZE, CUTERR, CUTIM

LATEST REVISION

April 21, 2010 (Version 101.4)