3. Working with SAC files¶

The psymo.core.sac package consists of two modules, which provide:

The python class SacIO, to read and write SAC files.

Functions which operate on the SacIO class.

class pysmo.core.sac.SacIO(**kwargs)¶

Bases: object

The SacIO class reads and writes data and header values to and from a SAC file. Additonal class attributes may be set, but are not written to a SAC file (because there is no space reserved for them there). Class attributes with corresponding header fields in a SAC file (for example the begin time b) are checked for a valid format before being saved in the SacIO instance.

Read and print data:

>>> from pysmo import SacIO
>>> my_sac = SacIO.from_file('file.sac')
>>> data = my_sac.data
>>> data
[-1616.0, -1609.0, -1568.0, -1606.0, -1615.0, -1565.0, ...

Read the sampling rate:

>>> delta = my_sac.delta
>>> delta
0.019999999552965164

Change the sampling rate:

>>> newdelta = 0.05
>>> my_sac.delta = newdelta
>>> my_sac.delta
0.05

Read from IRIS services:

>>> from pysmo import SacIO
>>> my_sac = SacIO.from_iris(
>>>             net="C1",
>>>             sta="VA01",
>>>             cha="BHZ",
>>>             loc="--",
>>>             start="2021-03-22T13:00:00",
>>>             duration=1 * 60 * 60,
>>>             scale="AUTO",
>>>             demean="true",
>>>             force_single_result=True)
>>> my_sac.npts
144001

There are a lot of header fields in a SAC file, which are all called the same way when using SacIO. They are all listed below.

a¶: First arrival time (seconds relative to reference time.)

az¶: Event to station azimuth (degrees).

b¶: Beginning value of the independent variable.

baz¶: Station to event azimuth (degrees).

cmpaz¶: Component azimuth (degrees clockwise from north).

cmpinc¶: Component incident angle (degrees from vertical).

data¶

First data section:

dependent variable
amplitude
real component

Second data section (if it exists):

independent variable unevenly spaced
phase
imaginary component

If there is only one data section, it is returned as a list of floats. Two data sections result in returning a list of tuples.

delta¶: Increment between evenly spaced samples (nominal value).

depmax¶: Maximum value of dependent variable.

depmen¶: Mean value of dependent variable.

depmin¶: Minimum value of dependent variable.

dist¶: Station to event distance (km).

e¶: Ending value of the independent variable.

evdp¶: Event depth below surface (kilometers – previously meters)

evel¶: Event elevation (meters). [not currently used]

evla¶: Event latitude (degrees, north positive).

evlo¶: Event longitude (degrees, east positive).

f¶: Fini or end of event time (seconds relative to reference time.)

fmt¶: Internal

classmethod from_buffer(buffer)¶: Create a new SacIO instance from a SAC data buffer.

classmethod from_file(filename)¶: Create a new SacIO instance from a SAC file.

classmethod from_iris(net, sta, cha, loc, force_single_result=False, **kwargs)¶

Create a list of SacIO instances from a single IRIS request using the output format as “sac.zip”.

Parameters:	force_single_result (bool) – If true, the function will return a single SacIO object or None if the requests returns nothing.

gcarc¶: Station to event great circle arc length (degrees).

idep¶: Type of dependent variable

ievreg¶: Event geographic region. [not currently used]

ievtyp¶: Type of event

iftype¶: Type of file

iinst¶: Type of recording instrument. [not currently used]

imagsrc¶: Source of magnitude information

imagtyp¶: Magnitude type

iqual¶: Quality of data [not currently used]

istreg¶: Station geographic region. [not currently used]

isynth¶: Synthetic data flag [not currently used]

iztype¶: Reference time equivalence

ka¶: First arrival time identification.

kcmpnm¶: Channel name. SEED volumes use three character names, and the third is the component/orientation. For horizontals, the current trend is to use 1 and 2 instead of N and E.

kdatrd¶: Date data was read onto computer.

kevnm¶: Event name.

kf¶: Fini identification.

khole¶: Nuclear: hole identifier; Other: location identifier.

kinst¶: Generic name of recording instrument.

knetwk¶: Name of seismic network.

ko¶: Event origin time identification.

kstnm¶: Station name.

kt0¶: User defined time pick identification.

kt1¶: User defined time pick identification.

kt2¶: User defined time pick identification.

kt3¶: User defined time pick identification.

kt4¶: User defined time pick identification.

kt5¶: User defined time pick identification.

kt6¶: User defined time pick identification.

kt7¶: User defined time pick identification.

kt8¶: User defined time pick identification.

kt9¶: User defined time pick identification.

kuser0¶: User defined variable storage area.

kuser1¶: User defined variable storage area.

kuser2¶: User defined variable storage area.

kzdate¶: ISO 8601 format of GMT reference date.

kztime¶: Alphanumeric form of GMT reference time.

lcalda¶: TRUE if DIST, AZ, BAZ, and GCARC are to be calculated from station and event coordinates.

leven¶: TRUE if data is evenly spaced

lovrok¶: TRUE if it is okay to overwrite this file on disk.

lpspol¶: TRUE if station components have a positive polarity (left-hand rule).

mag¶: Event magnitude.

nevid¶: Event ID (CSS 3.0)

norid¶: Origin ID (CSS 3.0)

npts¶: Number of points per data component

nsnpts¶: Internal.

nvhdr¶: Header version number.

nwfid¶: Waveform ID (CSS 3.0)

nxsize¶: Spectral Length (Spectral files only)

nysize¶: Spectral Length (Spectral files only)

nzhour¶: GMT hour.

nzjday¶: GMT julian day.

nzmin¶: GMT minute.

nzmsec¶: GMT millisecond.

nzsec¶: GMT second.

nzyear¶: GMT year corresponding to reference (zero) time in file.

o¶: Event origin time (seconds relative to reference time.)

odelta¶: Observed increment if different from nominal value.

read(filename)¶: Read data and header values from a SAC file into an existing SacIO instance.

read_buffer(buffer)¶: Read data and header values from a SAC byte buffer into an existing SacIO instance.

resp0¶: Instrument response parameter 0 (not currently used)

resp1¶: Instrument response parameter 1 (not currently used)

resp2¶: Instrument response parameter 2 (not currently used)

resp3¶: Instrument response parameter 3 (not currently used)

resp4¶: Instrument response parameter 4 (not currently used)

resp5¶: Instrument response parameter 5 (not currently used)

resp6¶: Instrument response parameter 6 (not currently used)

resp7¶: Instrument response parameter 7 (not currently used)

resp8¶: Instrument response parameter 8 (not currently used)

resp9¶: Instrument response parameter 9 (not currently used)

sb¶: Internal.

scale¶: Multiplying scale factor for dependent variable (not currently used)

sdelta¶: Internal.

stdp¶: Station depth below surface (meters). (not currently used)

stel¶: Station elevation above sea level (meters). (not currently used)

stla¶: Station latitude (degrees, north positive)

stlo¶: Station longitude (degrees, east positive).

t0¶: User defined time pick or marker 0 (seconds relative to reference time).

t1¶: User defined time pick or marker 1 (seconds relative to reference time).

t2¶: User defined time pick or marker 2 (seconds relative to reference time).

t3¶: User defined time pick or marker 3 (seconds relative to reference time).

t4¶: User defined time pick or marker 4 (seconds relative to reference time).

t5¶: User defined time pick or marker 5 (seconds relative to reference time).

t6¶: User defined time pick or marker 6 (seconds relative to reference time).

t7¶: User defined time pick or marker 7 (seconds relative to reference time).

t8¶: User defined time pick or marker 8 (seconds relative to reference time).

t9¶: User defined time pick or marker 9 (seconds relative to reference time).

unused10¶: Unused.

unused11¶: Unused.

unused12¶: Unused.

unused15¶: Unused.

unused16¶: Unused.

unused19¶: Unused

unused20¶: Unused

unused21¶: Unused

unused22¶: Unused

unused23¶: Unused

unused24¶: Unused

unused25¶: Unused

unused26¶: Unused

unused27¶: Unused

unused6¶: Unused.

unused7¶: Unused.

unused8¶: Unused.

unused9¶: Unused.

user0¶: User defined variable storage area

user1¶: User defined variable storage area

user2¶: User defined variable storage area

user3¶: User defined variable storage area

user4¶: User defined variable storage area

user5¶: User defined variable storage area

user6¶: User defined variable storage area

user7¶: User defined variable storage area

user8¶: User defined variable storage area

user9¶: User defined variable storage area

write(filename)¶: Write data and header values to a SAC file

xmaximum¶: Maximum value of X (Spectral files only)

xminimum¶: Minimum value of X (Spectral files only)

ymaximum¶: Maximum value of Y (Spectral files only)

yminimum¶: Minimum value of Y (Spectral files only)

3.1. pysmo.SacIO¶

Python module for reading/writing SAC files using the SacIO class.

class pysmo.core.sac.sacio.SacIO(**kwargs)¶

Bases: object

The SacIO class reads and writes data and header values to and from a SAC file. Additonal class attributes may be set, but are not written to a SAC file (because there is no space reserved for them there). Class attributes with corresponding header fields in a SAC file (for example the begin time b) are checked for a valid format before being saved in the SacIO instance.

Read and print data:

>>> from pysmo import SacIO
>>> my_sac = SacIO.from_file('file.sac')
>>> data = my_sac.data
>>> data
[-1616.0, -1609.0, -1568.0, -1606.0, -1615.0, -1565.0, ...

Read the sampling rate:

>>> delta = my_sac.delta
>>> delta
0.019999999552965164

Change the sampling rate:

>>> newdelta = 0.05
>>> my_sac.delta = newdelta
>>> my_sac.delta
0.05

Read from IRIS services:

>>> from pysmo import SacIO
>>> my_sac = SacIO.from_iris(
>>>             net="C1",
>>>             sta="VA01",
>>>             cha="BHZ",
>>>             loc="--",
>>>             start="2021-03-22T13:00:00",
>>>             duration=1 * 60 * 60,
>>>             scale="AUTO",
>>>             demean="true",
>>>             force_single_result=True)
>>> my_sac.npts
144001

There are a lot of header fields in a SAC file, which are all called the same way when using SacIO. They are all listed below.

a¶: First arrival time (seconds relative to reference time.)

az¶: Event to station azimuth (degrees).

b¶: Beginning value of the independent variable.

baz¶: Station to event azimuth (degrees).

cmpaz¶: Component azimuth (degrees clockwise from north).

cmpinc¶: Component incident angle (degrees from vertical).

data¶

First data section:

dependent variable
amplitude
real component

Second data section (if it exists):

independent variable unevenly spaced
phase
imaginary component

If there is only one data section, it is returned as a list of floats. Two data sections result in returning a list of tuples.

delta¶: Increment between evenly spaced samples (nominal value).

depmax¶: Maximum value of dependent variable.

depmen¶: Mean value of dependent variable.

depmin¶: Minimum value of dependent variable.

dist¶: Station to event distance (km).

e¶: Ending value of the independent variable.

evdp¶: Event depth below surface (kilometers – previously meters)

evel¶: Event elevation (meters). [not currently used]

evla¶: Event latitude (degrees, north positive).

evlo¶: Event longitude (degrees, east positive).

f¶: Fini or end of event time (seconds relative to reference time.)

fmt¶: Internal

classmethod from_buffer(buffer)¶: Create a new SacIO instance from a SAC data buffer.

classmethod from_file(filename)¶: Create a new SacIO instance from a SAC file.

classmethod from_iris(net, sta, cha, loc, force_single_result=False, **kwargs)¶

Create a list of SacIO instances from a single IRIS request using the output format as “sac.zip”.

Parameters:	force_single_result (bool) – If true, the function will return a single SacIO object or None if the requests returns nothing.

gcarc¶: Station to event great circle arc length (degrees).

idep¶: Type of dependent variable

ievreg¶: Event geographic region. [not currently used]

ievtyp¶: Type of event

iftype¶: Type of file

iinst¶: Type of recording instrument. [not currently used]

imagsrc¶: Source of magnitude information

imagtyp¶: Magnitude type

iqual¶: Quality of data [not currently used]

istreg¶: Station geographic region. [not currently used]

isynth¶: Synthetic data flag [not currently used]

iztype¶: Reference time equivalence

ka¶: First arrival time identification.

kcmpnm¶: Channel name. SEED volumes use three character names, and the third is the component/orientation. For horizontals, the current trend is to use 1 and 2 instead of N and E.

kdatrd¶: Date data was read onto computer.

kevnm¶: Event name.

kf¶: Fini identification.

khole¶: Nuclear: hole identifier; Other: location identifier.

kinst¶: Generic name of recording instrument.

knetwk¶: Name of seismic network.

ko¶: Event origin time identification.

kstnm¶: Station name.

kt0¶: User defined time pick identification.

kt1¶: User defined time pick identification.

kt2¶: User defined time pick identification.

kt3¶: User defined time pick identification.

kt4¶: User defined time pick identification.

kt5¶: User defined time pick identification.

kt6¶: User defined time pick identification.

kt7¶: User defined time pick identification.

kt8¶: User defined time pick identification.

kt9¶: User defined time pick identification.

kuser0¶: User defined variable storage area.

kuser1¶: User defined variable storage area.

kuser2¶: User defined variable storage area.

kzdate¶: ISO 8601 format of GMT reference date.

kztime¶: Alphanumeric form of GMT reference time.

lcalda¶: TRUE if DIST, AZ, BAZ, and GCARC are to be calculated from station and event coordinates.

leven¶: TRUE if data is evenly spaced

lovrok¶: TRUE if it is okay to overwrite this file on disk.

lpspol¶: TRUE if station components have a positive polarity (left-hand rule).

mag¶: Event magnitude.

nevid¶: Event ID (CSS 3.0)

norid¶: Origin ID (CSS 3.0)

npts¶: Number of points per data component

nsnpts¶: Internal.

nvhdr¶: Header version number.

nwfid¶: Waveform ID (CSS 3.0)

nxsize¶: Spectral Length (Spectral files only)

nysize¶: Spectral Length (Spectral files only)

nzhour¶: GMT hour.

nzjday¶: GMT julian day.

nzmin¶: GMT minute.

nzmsec¶: GMT millisecond.

nzsec¶: GMT second.

nzyear¶: GMT year corresponding to reference (zero) time in file.

o¶: Event origin time (seconds relative to reference time.)

odelta¶: Observed increment if different from nominal value.

read(filename)¶: Read data and header values from a SAC file into an existing SacIO instance.

read_buffer(buffer)¶: Read data and header values from a SAC byte buffer into an existing SacIO instance.

resp0¶: Instrument response parameter 0 (not currently used)

resp1¶: Instrument response parameter 1 (not currently used)

resp2¶: Instrument response parameter 2 (not currently used)

resp3¶: Instrument response parameter 3 (not currently used)

resp4¶: Instrument response parameter 4 (not currently used)

resp5¶: Instrument response parameter 5 (not currently used)

resp6¶: Instrument response parameter 6 (not currently used)

resp7¶: Instrument response parameter 7 (not currently used)

resp8¶: Instrument response parameter 8 (not currently used)

resp9¶: Instrument response parameter 9 (not currently used)

sb¶: Internal.

scale¶: Multiplying scale factor for dependent variable (not currently used)

sdelta¶: Internal.

stdp¶: Station depth below surface (meters). (not currently used)

stel¶: Station elevation above sea level (meters). (not currently used)

stla¶: Station latitude (degrees, north positive)

stlo¶: Station longitude (degrees, east positive).

t0¶: User defined time pick or marker 0 (seconds relative to reference time).

t1¶: User defined time pick or marker 1 (seconds relative to reference time).

t2¶: User defined time pick or marker 2 (seconds relative to reference time).

t3¶: User defined time pick or marker 3 (seconds relative to reference time).

t4¶: User defined time pick or marker 4 (seconds relative to reference time).

t5¶: User defined time pick or marker 5 (seconds relative to reference time).

t6¶: User defined time pick or marker 6 (seconds relative to reference time).

t7¶: User defined time pick or marker 7 (seconds relative to reference time).

t8¶: User defined time pick or marker 8 (seconds relative to reference time).

t9¶: User defined time pick or marker 9 (seconds relative to reference time).

unused10¶: Unused.

unused11¶: Unused.

unused12¶: Unused.

unused15¶: Unused.

unused16¶: Unused.

unused19¶: Unused

unused20¶: Unused

unused21¶: Unused

unused22¶: Unused

unused23¶: Unused

unused24¶: Unused

unused25¶: Unused

unused26¶: Unused

unused27¶: Unused

unused6¶: Unused.

unused7¶: Unused.

unused8¶: Unused.

unused9¶: Unused.

user0¶: User defined variable storage area

user1¶: User defined variable storage area

user2¶: User defined variable storage area

user3¶: User defined variable storage area

user4¶: User defined variable storage area

user5¶: User defined variable storage area

user6¶: User defined variable storage area

user7¶: User defined variable storage area

user8¶: User defined variable storage area

user9¶: User defined variable storage area

write(filename)¶: Write data and header values to a SAC file

xmaximum¶: Maximum value of X (Spectral files only)

xminimum¶: Minimum value of X (Spectral files only)

ymaximum¶: Maximum value of Y (Spectral files only)

yminimum¶: Minimum value of Y (Spectral files only)

3.2. pysmo.sacfunc¶

Useful functions to use with SacIO objects.

pysmo.core.sac.sacfunc.calc_az(name, ellps='WGS84')¶

Calculate azimuth (in DEG) from a SacIO object. The default ellipse used is ‘WGS84’, but others may be specified. For more information see:

http://trac.osgeo.org/proj/ http://code.google.com/p/pyproj/

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. ellps (string) – Ellipsoid to use for azimuth calculation
Returns:	Azimuth
Return type:	float

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> azimuth = sacfunc.calc_az(sacobj) # Use default WGS84.
>>> azimuth = sacfunc.calc_az(sacobj, ellps='clrk66') # Use Clarke 1966

pysmo.core.sac.sacfunc.calc_baz(name, ellps='WGS84')¶

Calculate backazimuth (in DEG) from a SacIO object. The default ellipse used is ‘WGS84’, but others may be specified. For more information see:

http://trac.osgeo.org/proj/ http://code.google.com/p/pyproj/

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. ellps (string) – Ellipsoid to use for backazimuth calculation
Returns:	Backazimuth
Return type:	float

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> backazimuth = sacfunc.calc_baz(sacobj) # Use default WGS84.
>>> backazimuth = sacfunc.calc_baz(sacobj, ellps='clrk66') # Use Clarke 1966 ellipsoid.

pysmo.core.sac.sacfunc.calc_dist(name, ellps='WGS84')¶

Calculate the great circle distance (in km) from a SacIO object. The default ellipse used is ‘WGS84’, but others may be specified. For more information see:

http://trac.osgeo.org/proj/ http://code.google.com/p/pyproj/

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. ellps (string) – Ellipsoid to use for distance calculation
Returns:	Great Circle Distance
Return type:	float

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> distance = sacfunc.calc_dist(sacobj) # Use default WGS84.
>>> distance = sacfunc.calc_dist(sacobj, ellps='clrk66') # Use Clarke 1966 ellipsoid.

pysmo.core.sac.sacfunc.detrend(name)¶

Remove linear and/or constant trends from SacIO object data.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function.
Returns:	Detrended data.
Return type:	numpy.array

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> detrended_data = sacfunc.detrend(sacobj)

pysmo.core.sac.sacfunc.envelope(name, Tn, alpha)¶

Calculate the envelope of a gaussian filtered seismogram.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. Tn (float) – Center period of Gaussian filter [in seconds] alpha (float) – Set alpha (which determines filterwidth)
Returns:	numpy array containing the envelope

Example:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> Tn = 50 # Center Gaussian filter at 50s period
>>> alpha = 50 # Set alpha (which determines filterwidth) to 50
>>> envelope = sacfunc.envelope(sacobj, Tn, alpha)

pysmo.core.sac.sacfunc.gauss(name, Tn, alpha)¶

Return data vector of a gaussian filtered seismogram.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. Tn (float) – Center period of Gaussian filter [in seconds] alpha (float) – Set alpha (which determines filterwidth)
Returns:	numpy array containing filtered data

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> Tn = 50 # Center Gaussian filter at 50s period
>>> alpha = 50 # Set alpha (which determines filterwidth) to 50
>>> data = sacfunc.gauss(sacobj, Tn, alpha)

pysmo.core.sac.sacfunc.plotsac(name, outfile=None, showfig=True)¶

Simple plot of a single sac file.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. outfile (bool) – If specified, save figure to this file. showfig – Specifies if figure should be displayed.

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> sacfunc.plotsac(sacobj)

pysmo.core.sac.sacfunc.resample(name, delta_new)¶

Resample SacIO object data using Fourier method.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. delta_new – New sampling rate.
Returns:	Resampled data.
Return type:	numpy.array

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> delta_old = sacobj.delta
>>> delta_new = delta_old * 2
>>> data_new = sacfunc.resample(sac, delta_new)

pysmo.core.sac.sacfunc.sac2xy(name, retarray=False)¶

Return time and amplitude from a SacIO object.

Parameters:	name (SacIO) – Name of the SacIO object passed to this function. retarray (bool) – True: return numpy array False: return list (default)
Returns:	Time and amplitude of a SacIO object.
Return type:	numpy.array or list

Example usage:

>>> from pysmo import SacIO, sacfunc
>>> sacobj = SacIO.from_file('sacfile.sac')
>>> time, vals = sacfunc.sac2xy(sacobj, retarray=True)