MSEED2SAC(1)

NAME
mseed2sac - miniSEED to SAC converter

SYNOPSIS
mseed2sac [options] file1 [file2 file3 ...]

DESCRIPTION
mseed2sac converts miniSEED waveform data to SAC format. The output SAC file can be either ASCII or binary (either byte-order), the default is binary with the same byte-order as the host computer. By default all aspects of the input files are automatically detected.

If an input file name is prefixed with an '@' character the file is assumed to contain a list of input data files, see INPUT LIST FILES below.

A separate output file is written for each continuous time-series in the input data. Output file names are of the form:

"Net.Sta.Loc.Chan.Qual.YYYY,DDD,HHMMSS.SAC"

For example:
"TA.ELFS..LHZ.R.2006,123,153619.SAC"

Files that would have the same file name due to having the same start time will be kept separate by adding a digit to file name. The -O argument changes this behavior to allow overwriting of existing file names.

If the input file name is "-" input miniSEED records will be read from standard input.

The SAC header variable KHOLE is used synonymously with the SEED location code. Any location codes found in the input miniSEED or metadata file are put into the KHOLE variable.

OPTIONS

-V  Print program version and exit.

-h  Print program usage and exit.

-H  Print extended program usage with all options and exit.

-v  Be more verbose. This flag can be used multiple times ("-v -v" or "-vv") for more verbosity.

-O  Overwrite an existing files instead of generating new file names.

-k lat/lon
    Specify station coordinates to put into the output SAC file(s). The argument format is "Latitude/Longitude" e.g. "47.66/-122.31". Coordinates specified with this option override any coordinates found in the metadata file.

-m metafile
    Specify a file containing metadata such as coordinates, elevation, component orientation, scaling factor, etc. For each time-series written any matching metadata will be added to the SAC header. See METADATA FILES below.

-M metaline
    Specify a "line" of metadata in the same format as expected for the METADATA FILES. This option may be specified multiple times.

-msi
    Convert any component inclination values in a metadata file from SEED (dip) to SAC convention, this is a simple matter of adding 90 degrees.

-E event
    Specify event parameters to add to the SAC file in the following format:

    "Time[/Lat][/Lon][/Depth][/Name]"

    For example:
    "2006,123,15:27:08.7/-20.33/-174.03/65.5/Tonga"

    The parameters later in the string are optional.

-l selectfile
    Limit to miniSEED records that match a selection in the specified file. The selection file contains parameters to match the network, station, location, channel, quality and time range for input records. This option only trims data to SEED record granularity, not sample granularity. For more details see the SELECTION FILE section below.

-f format
    The default output format is binary SAC with the same byte order as the host computer. This option forces the format for every output file:

    1 : Alphanumeric SAC format
    2 : Binary SAC format, host byte order (default)
    3 : Binary SAC format, little-endian
    4 : Binary SAC format, big-endian

-N netcode
    Specify the network code to use, overriding any network code in the input miniSEED.

-S station
    Specify the station code to use, overriding any station code in the input miniSEED.

-L location
    Specify the location code to use, overriding any location code in the input miniSEED.

-C channel
    Specify the channel code to use, overriding any channel code in the input miniSEED.

-r bytes
    Specify the miniSEED record length in bytes, by default this is autodetected.

-i  Process each input file individually. By default all input files are read and all data is buffered in memory before SAC files are written. This allows time-series spanning mutilple input files to be merged and written in a single SAC file. The intention is to use this option when processing large amounts of data in order to keep memory usage within reasonable limits.

-ic Process each input channel individually. Similar to the -i option, except this instructs the program to create write SAC files for each channel (determined when the input channel changes). Data should be well ordered by channel for best results. This option can be used to reduce memory usage for very large input files containing many channels.

-dr Use the sampling rate derived from the start and end times and the number of samples instead of the rate specified in the input data. This is useful when the sample rate in the input data does not have enough resolution to represent the true rate.

-z zipfile
    Create a ZIP archive containing all SAC files instead of writing individual files. Each file is compressed with the deflate method. Specify "-" (dash) to write ZIP archive to stdout.

-z0 zipfile
    Same as "-z" except do not compress the SAC files. Specify "-" (dash) to write ZIP archive to stdout.

METADATA FILES
A metadata file contains a list of station parameters, some of which can be stored in SAC but not in miniSEED. Each line in a metadata file should be a list of parameters in the order shown below. Each parameter should be separated with a comma or a vertical bar (|). DIP CONVENTION: When comma separators are used the dip field (CMPINC) is assumed to be in the SAC convention (degrees down from vertical up/outward), if vertical bars are used the dip field is assumed to be in the SEED convention (degrees down from horizontal) and converted to SAC convention.

Metdata fields:
Network (KNETWK)
Station (KSTNM)
Location (KHOLE)
Channel (KCMPNM)
Latitude (STLA)
Longitude (STLO)
Elevation (STEL), in meters [not currently used by SAC]
Depth (STDP), in meters [not currently used by SAC]
Component Azimuth (CMPAZ), degrees clockwise from north
Component Incident Angle (CMPINC), degrees from vertical
Instrument Name (KINST), up to 8 characters
Scale Factor (SCALE)
Scale Frequency, unused
Scale Units, unused
Sampling rate, unused
Start time, used for matching
End time, used for matching

Example with comma separators (with SAC convention dip):

------------------
#net,sta,loc,chan,lat,lon,elev,depth,azimuth,SACdip,instrument,scale,scalefreq,scaleunits,samplerate,start,end
IU,ANMO,00,BH1,34.945981,-106.457133,1671,145,328,90,Geotech KS-54000,3456610000,0.02,M/S,20,2008-06-30T20:00:00,2599-12-31T23:59:59
IU,ANMO,00,BH2,34.945981,-106.457133,1671,145,58,90,Geotech KS-54000,3344370000,0.02,M/S,20,2008-06-30T20:00:00,2599-12-31T23:59:59
IU,ANMO,00,BHZ,34.945981,-106.457133,1671,145,0,0,Geotech KS-54000,3275080000,0.02,M/S,20,2008-06-30T20:00:00,2599-12-31T23:59:59
IU,ANMO,10,BH1,34.945913,-106.457122,1767.2,48.8,64,90,Guralp CMG3-T,32805600000,0.02,M/S,40,2008-06-30T20:00:00,2599-12-31T23:59:59
IU,ANMO,10,BH2,34.945913,-106.457122,1767.2,48.8,154,90,Guralp CMG3-T,32655000000,0.02,M/S,40,2008-06-30T20:00:00,2599-12-31T23:59:59
IU,ANMO,10,BHZ,34.945913,-106.457122,1767.2,48.8,0,0,Guralp CMG3-T,33067200000,0.02,M/S,40,2008-06-30T20:00:00,2599-12-31T23:59:59
------------------

Example with vertical bar separators (with SEED convention dip):

------------------
#net|sta|loc|chan|lat|lon|elev|depth|azimuth|SEEDdip|instrument|scale|scalefreq|scaleunits|samplerate|start|end
IU|ANMO|00|BH1|34.945981|-106.457133|1671|145|328|0|Geotech KS-54000|3456610000|0.02|M/S|20|2008-06-30T20:00:00|2599-12-31T23:59:59
IU|ANMO|00|BH2|34.945981|-106.457133|1671|145|58|0|Geotech KS-54000|3344370000|0.02|M/S|20|2008-06-30T20:00:00|2599-12-31T23:59:59
IU|ANMO|00|BHZ|34.945981|-106.457133|1671|145|0|-90|Geotech KS-54000|3275080000|0.02|M/S|20|2008-06-30T20:00:00|2599-12-31T23:59:59
------------------

As a special case '--' can be used to match an empty location code.

For each time-series written, metadata from the first line with matching source name parameters (network, station, location and channel) and time window (if specified) will be inserted into the SAC header. All parameters are optional except for the first four fields specifying the source name parameters.

Simple wildcarding: for the source name parameters that will be matched a '*' character in a field will match anything. The BHZ metadata lines above, for example, can be (almost) summarized as:

IU,ANMO,*,BHZ,34.9459,-106.4571,1671,145,0,0,Geotech KS-54000,3456610000,0.02,M/S,20,2008-06-30T20:00:00,2599-12-31T23:59:59

SELECTION FILE
A selection file is used to match input data records based on network, station, location and channel information. Optionally a quality and time range may also be specified for more refined selection. The non-time fields may use the '*' wildcard to match multiple characters and the '?' wildcard to match single characters. Character sets may also be used, for example '[ENZ]' will match either E, N or Z. The '#' character indicates the remaining portion of the line will be ignored.

Example selection file entires (the first four fields are required)
#net sta  loc  chan  qual  start             end
IU   ANMO *    BH?
II   *    *    *     Q
IU   COLA 00   LH[ENZ] R
IU   COLA 00   LHZ   *     2008,100,10,00,00 2008,100,10,30,00

INPUT LIST FILES
If an input file is prefixed with an '@' character the file is assumed to contain a list of file for input. Multiple list files can be combined with multiple input files on the command line. The last, space separated field on each line is assumed to be the file name to be read.

An example of a simple text list:

TA.ELFS..LHE.R.mseed
TA.ELFS..LHN.R.mseed
TA.ELFS..LHZ.R.mseed

ABOUT SAC
Seismic Analysis Code (SAC) is a general purpose interactive program designed for the study of sequential signals, especially timeseries data. Originally developed at the Lawrence Livermore National Laboratory the SAC software package is also available from IRIS.

AUTHOR
Chad Trabant
IRIS Data Management Center