# obspy.io.sac - SAC read and write support for ObsPy

This module provides read and write support for ASCII and binary SAC-files as defined by IRIS (https://ds.iris.edu/files/sac-manual/).

copyright: | The ObsPy Development Team (devs@obspy.org) & C. J. Ammon & J. MacCarthy
license: | GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

The SAC implementation in ObsPy is a modified version of `PySac` (https://github.com/LANL-Seismoacoustics/pysac), developed under U.S. Government contract DE-AC52-06NA25396 for Los Alamos National Laboratory (LANL) and copyrighted for Los Alamos National Security, LLC under LA-CC-15-051.

## Reading

Similar to reading any other waveform data format using `read()`:

    >>> from obspy import read
    >>> st = read('/path/to/test.sac', debug_headers=True)
    >>> st
    <obspy.core.stream.Stream object at 0x...>
    >>> print(st)
    1 Trace(s) in Stream:
    .STA..Q | 1978-07-18T08:00:10.000000Z - ... | 1.0 Hz, 100 samples

The format will be determined automatically. As SAC-files can contain only one data trace (as opposed to Mini-SEED or GSE2), the length of ‘st’ will be one. ‘st[0]’ will have a stats attribute containing the essential meta data (station name, channel, location, start time, end time, sampling rate, number of points). Additionally, when reading a SAC-file it will have one additional attribute, ‘sac’, which contains all SAC-specific attributes (SAC header values).

    >>> print(st[0].stats)
             network:
             station: STA
            location:
             channel: Q
           starttime: 1978-07-18T08:00:10.000000Z
             endtime: 1978-07-18T08:01:49.000000Z
       sampling_rate: 1.0
               delta: 1.0
                npts: 100
               calib: 1.0
             _format: SAC
                 sac: AttribDict({...})
    >>> print(st[0].stats.sac.dist)
    -12345.0

The data is stored in the data attribute.

    >>> st[0].data
    array([ -8.74227766e-08,  -3.09016973e-01,..., 3.09007347e-01], dtype=float32)

## Writing

Writing is also straight forward. All changes on the data as well as in stats and stats[‘sac’] are written with the following command to a file:

    >>> st.write('tmp.sac', format='SAC')

You can also specify a `byteorder` keyword argument to set the endianness of the resulting SAC-file. It must be either `0` or `'<'` for LSBF or little-endian, `1` or `'>'` for MSBF or big-endian. Defaults to little endian.

## Modules

`core` | SAC bindings to ObsPy core module.
`sacpz` | obspy.io.sac.sacpz - SACPZ write support for ObsPy
`header` | SAC header specification, including documentation.
`arrayio` | Low-level array interface to the SAC file format.
`sactrace` | Python interface to the Seismic Analysis Code (SAC) file format.
`util` | SAC module helper functions and data.

### Thank you!

We would like to thank our contributors, whose efforts make this software what it is. These people have helped by writing code and documentation, and by testing. They have created and maintained this product, its associated libraries and applications, our build tools and our web sites.

#### Contributors

- Ackerley, Nick
- Allgeyer, Sebastien
- Ammon, Charles J.
- Antunes, Emanuel
- Arnarsson, Ólafur St.
- Bank, Markus
- Barsch, Robert
- Behr, Yannik
- Bernardi, Fabrizio
- Bernauer, Felix
- Bes de Berc, Maxime
- Beyreuther, Moritz
- Boltz, Shawn
- Bonaimé, Sébastien
- Carothers, Lloyd
- Chamberlain, Calum
- Chambers, Derrick
- Chen, Zhao
- Clark, Adam
- Danecek, Peter
- Egdorf, Sven
- Engels, Fabian
- Ermert, Laura
- Eulenfeld, Tom

- Fabbri, Tommaso
- Falco, Nicholas
- Fee, Jeremy
- Grellier, Clément
- Grunberg, Marc
- Hammer, Conny
- Heimann, Sebastian
- Heiniger, Lukas
- Hope, Gaute
- Igel, Heiner
- Inza, Adolfo
- Isken, Marius
- Ketchum, David
- Koymans, Mathijs
- Kremers, Simon
- Kress, Victor
- Krieger, Lars
- Krischer, Lion
- Kula, Damian
- Käufl, Paul
- Köhler, Andreas
- Lecocq, Thomas
- Leeman, John
- Legovini, Paride

- Lesage, Philippe
- Li, Yulin
- Lomax, Anthony
- Lopes, Rui L.
- MacCarthy, Jonathan
- Maggi, Alessia
- Martin, Henri
- Medlin, Andrew
- Megies, Tobias
- Meschede, Matthias
- Michelini, Alberto
- Miller, Nathaniel C.
- Morgenstern, Bernhard
- Nof, Ran Novitsky
- Panning, Mark P.
- Parker, Tom
- Pestourie, Romain
- Rapagnani, Giovanni
- Reyes, Celso
- Ringler, Adam
- Rothenhäusler, Nicolas
- Russo, Emiliano
- Sales de Andrade, Elliott

- Satriano, Claudio
- Saul, Joachim
- Scheingraber, Chris
- Schneider, Simon
- Sippl, Christian
- Snoke, Arthur
- Stange, Stefan
- Stähler, Simon C.
- Sullivan, Benjamin
- Tian, Dongdong
- Trabant, Chad
- Trani, Luca
- Uieda, Leonardo
- Walker, Andrew
- Walther, Marcus
- Wassermann, Joachim
- Williams, Mark C.
- Winkelman, Andrew
- Zaccarelli, Riccardo
- Zad, Seyed Kasra Hosseini
- Zhu, Lijun
- van Driel, Martin
- van Wijk, Kasper

#### Funds

ObsPy was partially funded by the

- German Science Foundation (DFG) via grant DFG IG 16/9-1
- German Ministry for Education and Research (BMBF), GEOTECHNOLOGIEN grant 03G0646H.
- NERA project (Network of European Research Infrastructures for Earthquake Risk Assessment and Mitigation) under the European Community's Seventh Framework Programme (FP7/2007-2013) grant agreement n° 262330
- Leibniz Institute for Applied Geophysics (LIAG)
- VERCE EU-FP7 project (no. 283543)