SUMMARY
Metadata is data about data content and is critical for analysis of timeseries data such as seismic data. IRIS has various web-based tools that allow users to query, view, and download metadata. This command allows one to insert available metadata into SAC data files.
SYNTAX
METADATA {catalog:eventid}
{file metadata_file}
{ph5}
{verbose}
INPUT
catalog:eventid: Set the event to use when specifying event metadata. An eventid can be obtained using from the EVENT command file metadata_file: Use the metadata from a file. The file may be either a text file or an xml file. There are important differences between xml and text files. Input metadata files must have channel level metadata, see the STATION command. ph5: Get additional data from the IRIS PH5 Web service. This option provides access to active-source data sets and their associated stations with high sample rates and time-limited deployments. VERBOSE: Watch the details of the metadata insertion process
DEFAULT VALUES
METADATA
DESCRIPTION
Insert metadata into files currently in memory. Metadata, i.e. sac headers, is only added for the station if the station id (Network Station Location and Channel) are defined in the sac header. Metadata for the event is only added if the event is specified as an command option.
Metadata for the station includes
- stla: Station Latitude
- stlo: Station Longitude
- stel: Station Elevation (in meters)
- stdp: Station Depth (always 0.0)
- cmpaz: Component Azimuth (degrees clockwise from North)
- cmpinc: Component Inclination (See discussion below)
Metadata for the event includes
- evla: Event Latitude
- evlo: Event Longitude
- evel: Event Elevation (always 0.0)
- evdp: Event Depth in km
- origin time: (kzdate and kztime)
- iztype: set to IO
- kevnm: (if short enough)
Setting of kzdate, kztime and iztype is eqivalent to the following SAC commands:
SAC> ch o gmt 1994 160 00 33 16 230 SAC> ch iztype IO SAC> ch allt (-1.0 * &1,o)
EXAMPLE
Adding Station Metadata
For data files missing station metadata, it is straightforward to insert this information by reading in the data and issuing the METADATA command. For this to work, station identifiers (KNETWK, KSTNM, KHOLE, KCMPNM) need to be defined:
SAC> read BK.BRK.00.BHZ.Q.2010.235.000000.sac
SAC> lh kcmpnm kstnm khole kcmpnm stlo stla stel stdp cmpaz cmpinc columns 2
FILE: BK.BRK.00.BHZ.Q.2010.235.000000.sac - 1
-----------------------------------------
kcmpnm = BHZ kstnm = BRK
khole = 00 kcmpnm = BHZ
SAC> metadata
Working on file: BK.BRK.00.BHZ.Q.2010.235.000000.sac [ OK ]
SAC> lh kcmpnm kstnm khole kcmpnm stlo stla stel stdp cmpaz cmpinc columns 2
FILE: BK.BRK.00.BHZ.Q.2010.235.000000.sac - 1
-----------------------------------------
kcmpnm = BHZ kstnm = BRK
khole = 00 kcmpnm = BHZ
stlo = -1.222610e+02 stla = 3.787352e+01
stel = 4.940000e+01 stdp = 2.700000e+00
cmpaz = 0.000000e+00 cmpinc = 0.000000e+00
Adding Station Metadata from a file
If the metadata exists in a .txt or .xml file, this information can be applied to existing data files. Input data files must have channel level metadata.
SAC> read YE.SPOLE..BHZ.M.2013.304.000000.sac
SAC> lh kcmpnm kstnm khole kcmpnm stlo stla stel stdp cmpaz cmpinc columns 2
FILE: YE.SPOLE..BHZ.M.2013.304.000000.sac - 1
-----------------------------------------
kcmpnm = BHZ kstnm = SPOLE
khole = kcmpnm = BHZ
SAC> metadata file station_info.xml
Working on file: YE.SPOLE..BHZ.M.2013.304.000000.sac [ OK ]
SAC> lh kcmpnm kstnm khole kcmpnm stlo stla stel stdp cmpaz cmpinc columns 2
FILE: YE.SPOLE..BHZ.M.2013.304.000000.sac - 1
-----------------------------------------
kcmpnm = BHZ kstnm = SPOLE
khole = kcmpnm = BHZ
stlo = 1.444400e+02 stla = -8.993000e+01
stel = 2.850000e+03 stdp = 0.000000e+00
cmpaz = 0.000000e+00 cmpinc = 0.000000e+00
Adding Event Metadata
Event metadata can be added to a data file by issuing the metadata command with a specified eventid, here we use an eventid of gcmt:3279407. (See EVENT for a discussion of EventID.) Stationmetadata will also automatically be added:
SAC> event time now -10y mag 9 gcmt
Origin Lat. Lon. Depth Mag. Agency EventID
2011-03-11T05:47:32 37.52 143.05 20.00 9.10 MW GCMT/- GCMT gcmt:3279407
SAC> data gcmt:3279407 net II sta BORG cha BHZ loc '00' dur 1min miniseed
Data Center: IRISDMC,http://ds.iris.edu
Writing data to fdsnws.2019.11.01.15.56.00.IRISDMC.mseed [ 8.00 KiB]
SAC> read fdsnws.2019.11.01.15.56.00.IRISDMC.mseed
SAC> metadata gcmt:3279407
Working on file: II.BORG.00.BHZ.M.2011.070.054732.sac [ OK ]
SAC> lh stlo stla evlo evla kevnm
FILE: II.BORG.00.BHZ.M.2011.070.054732.sac - 1
------------------------------------------
stlo = -2.132680e+01 stla = 6.474740e+01
evlo = 1.430500e+02 evla = 3.752000e+01
kevnm = gcmt:3279407
Alternatively, event metadata can be added at the time of downloaning data by specifying an eventid and converting to SAC or reading the data into memory. The example below uses the eventid gcmt:3279407:
SAC> data gcmt:3279407 net II sta BORG cha BHZ loc '00' dur 1min read
Data Center: IRISDMC,http://ds.iris.edu
SourceID Start sample End sample Gap
XFDSN:II_BORG_00_B_H_Z 2011-03-11T05:47:32.019900 2011-03-11T05:48:31.969900 ==
Working on file: II.BORG.00.BHZ.M.2011.070.054732.sac [ OK ]
SAC> lh stlo stla evlo evla kevnm
FILE: II.BORG.00.BHZ.M.2011.070.054732.sac - 1
------------------------------------------
stlo = -2.132680e+01 stla = 6.474740e+01
evlo = 1.430500e+02 evla = 3.752000e+01
kevnm = gcmt:3279407
PH5 Example: Given a SAC file missing station metadata where that metadata exists in the PH5 Web service and not in the IRIS Web service, the PH5 option must be specified to obtain and insert the metadata. The PH5 options is appropriate for active source stations:
SAC> read 9A.22770..DPZ.D.2012.227.000000.sac SAC> lh stlo stla FILE: 9A.22770..DPZ.D.2012.227.000000.sac - 1 ------------------------------- SAC> metadata Error 204 (HTTP): SAC> metadata ph5 Working on file: 9A.22770..DPZ.D.2012.227.000000.sac [ OK ]
COMPONENT INCLINATION
The component inclination is defined differently between SAC and SEED/miniSEED. Sac defined the inclination as degrees from vertical, what is typically thought of as an inclination. SEED/miniSEED defines the component inclincation as a component dip, defined as degrees from horizontal down into the Earth.
| Value | SEED / miniSEED | SAC |
|---|---|---|
| Horizontal | 0.0 | 90.0 |
| Up | -90.0 | 0.0 |
| Down | 90.0 | 180.0 |
Data retrieved automatically is handled correctly and the conversion is seamless. For metadata from a file specified by the file metadata_file command option, the type of file determines if the component is define as a dip (miniSEED) or inclination (SAC). This is the same convection used in mseed2sac <https://seiscode.iris.washington.edu/projects/mseed2sac> for consistency.
| File Type | Separator | Convention | Conversion Value |
|---|---|---|---|
| text | , (comma) | SAC / Inclination | 0 |
| text | '|' (bar) | SAC / Inclination | 90 |
| xml | n/a | miniSEED / Dip | 90 |
METADATA FORMAT
Metadata in xml format adheres to the FDSN Station format found at http://www.fdsn.org/xml/station/, but it is easier to create the metadata file format using the STATION command with a channel option.
Metadata in text format is defined as one channel per line separated by either ',' (commas) or '|' (bars). The value of the columns are in the following order (the same as mseed2sac)
- Network
- Station
- Location
- Channel
- Station Latitude
- Station Longitude
- Station Elevation
- Station Depth
- Component Azimuth (North = 0, East = 90)
- Component Inclination - Coordinate system is defined by the delimiter, see note above
- Instrument Name/Type
- Scale Factor (ignored)
- Scale Frequency (ignored)
- Scale Units (ignored)
- Sample Rate (ignored)
- Start time
- End time
LATEST REVISION
Version 102.0