1# -*- coding: utf-8 -*-
2"""
3obspy.io.sac - SAC read and write support for ObsPy
4===================================================
5This module provides read and write support for ASCII and binary SAC-files as
6defined by IRIS (https://ds.iris.edu/files/sac-manual/).
7
8:copyright:
9    The ObsPy Development Team (devs@obspy.org) & C. J. Ammon & J. MacCarthy
10:license:
11    GNU Lesser General Public License, Version 3
12    (https://www.gnu.org/copyleft/lesser.html)
13
14The SAC implementation in ObsPy is a modified version of ``PySac``
15(https://github.com/LANL-Seismoacoustics/pysac), developed under U.S.
16Government contract DE-AC52-06NA25396 for Los Alamos National Laboratory
17(LANL) and copyrighted for Los Alamos National Security, LLC under
18LA-CC-15-051.
19
20Reading
21-------
22Similar to reading any other waveform data format using
23:func:`~obspy.core.stream.read()`:
24
25>>> from obspy import read
26>>> st = read('/path/to/test.sac', debug_headers=True)
27>>> st #doctest: +ELLIPSIS
28<obspy.core.stream.Stream object at 0x...>
29>>> print(st) #doctest: +ELLIPSIS
301 Trace(s) in Stream:
31.STA..Q | 1978-07-18T08:00:10.000000Z - ... | 1.0 Hz, 100 samples
32
33The format will be determined automatically. As SAC-files can contain only one
34data trace (as opposed to Mini-SEED or GSE2), the length of 'st' will be one.
35'st[0]' will have a stats attribute containing the essential meta data (station
36name, channel, location, start time, end time, sampling rate, number of
37points). Additionally, when reading a SAC-file it will have one additional
38attribute, 'sac', which contains all SAC-specific attributes (SAC header
39values).
40
41>>> print(st[0].stats)  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
42         network:
43         station: STA
44        location:
45         channel: Q
46       starttime: 1978-07-18T08:00:10.000000Z
47         endtime: 1978-07-18T08:01:49.000000Z
48   sampling_rate: 1.0
49           delta: 1.0
50            npts: 100
51           calib: 1.0
52         _format: SAC
53             sac: AttribDict({...})
54>>> print(st[0].stats.sac.dist)
55-12345.0
56
57The data is stored in the data attribute.
58
59>>> st[0].data #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
60array([ -8.74227766e-08,  -3.09016973e-01,..., 3.09007347e-01], dtype=float32)
61
62Writing
63-------
64Writing is also straight forward. All changes on the data as well as in
65stats and stats['sac'] are written with the following command to a file:
66
67>>> st.write('tmp.sac', format='SAC') #doctest: +SKIP
68
69You can also specify a ``byteorder`` keyword argument to set the
70endianness of the resulting SAC-file. It must be either ``0`` or ``'<'``
71for LSBF or little-endian, ``1`` or ``'>'`` for MSBF or big-endian.
72Defaults to little endian.
73"""
74from __future__ import (absolute_import, division, print_function,
75                        unicode_literals)
76from future.builtins import *  # NOQA
77
78from .sacpz import attach_paz, attach_resp
79from .util import SacError, SacIOError
80from .sactrace import SACTrace
81
82
83if __name__ == '__main__':
84    import doctest
85    doctest.testmod(exclude_empty=True)
86