# obspy.io.mseed - MiniSEED read and write support for ObsPy

This module provides read and write support for the MiniSEED (and the data part of full SEED) waveform data format and some other convenient methods to handle MiniSEED files. It utilizes libmseed, a C library by Chad Trabant.

See also

The format is defined in the SEED Manual.

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

## Reading

Reading MiniSEED (and the data part of full SEED files) is handled by using ObsPy’s standard `read()` function. The format is detected automatically.

    >>> from obspy import read
    >>> st = read("/path/to/test.mseed")
    >>> st
    <obspy.core.stream.Stream object at 0x...>
    >>> print(st)
    1 Trace(s) in Stream:
    NL.HGN.00.BHZ | 2003-05-29T02:13:22.043400Z - ... | 40.0 Hz, 11947 samples
    >>> print(st[0].stats)
             network: NL
             station: HGN
            location: 00
             channel: BHZ
           starttime: 2003-05-29T02:13:22.043400Z
             endtime: 2003-05-29T02:18:20.693400Z
       sampling_rate: 40.0
               delta: 0.025
                npts: 11947
               calib: 1.0
             _format: MSEED
               mseed: ...

MiniSEED specific metadata is stored in `stats.mseed`.

    >>> for k, v in sorted(st[0].stats.mseed.items()):
    ...     print("'%s': %s" % (k, str(v)))
        'byteorder':  >
        'dataquality': R
        'encoding': STEIM2
        'filesize': 8192
        'number_of_records':  2
        'record_length': 4096

The actual data is stored as a `ndarray` in the `data` attribute of each trace.

    >>> print(st[0].data)
    [2787 2776 2774 ..., 2850 2853 2853]

Several key word arguments are available which can be used for example to only read certain records from a file or force the header byteorder: `starttime`, `endtime`, `headonly`, `sourcename`, `reclen`, `details`, and `header_byteorder`. They are passed to the `_read_mseed()` method so refer to it for details to each parameter.

## Writing

Write data back to disc or a file like object using the `write()` method of a `Stream` or `Trace` object.

    >>> st.write('Mini-SEED-filename.mseed', format='MSEED')

You can also specify several keyword arguments that change the resulting Mini-SEED file: `reclen`, `encoding`, `byteorder`, `flush`, and `verbose`. They are are passed to the `_write_mseed()` method so refer to it for details to each parameter.

Refer to the `_write_mseed()` method for details to each parameter.

So in order to write a STEIM1 encoded Mini-SEED file with a record length of 512 byte do the following:

    >>> st.write('out.mseed', format='MSEED', reclen=512,
    ...          encoding='STEIM1')

Many of these can also be set at each Trace`s `stats.mseed` attribute which allows for per Trace granularity. Values passed to the `read()` function have priority.

## Encoding Support

MiniSEED is a format with a large variety of different blockettes, byte order issues, and encodings. The capabilities of `obspy.io.mseed` largely coincide with the capabilities of `libmseed`, which is the de-facto standard MiniSEED library and used internally by ObsPy.

In regards to the different encodings for the data part of MiniSEED files this means the following:

- Read support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats, STEIM 1 + 2, all GEOSCOPE encodings, the CDSN encoding, the SRO encoding, and the DWWSSN encoding
- Write support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats, and STEIM 1 + 2
- Unsupported: 24 bit integers, US National Network compression, Graefenberg 16 bit gain ranged encoding, IPG - Strasbourg 16 bit gain ranged encoding, STEIM 3, the HGLP encoding, and the RSTN 16 bit gain ranged encoding

## Utilities

This module also contains a couple of utility functions which are useful for some purposes. Refer to the documentation of each for details.

`get_start_and_end_time()` | Fast way of getting the temporal bounds of a well-behaved MiniSEED file.
`get_flags()` | Returns information about the flags and timing quality in a file.
`shift_time_of_file()` | Shifts the time of a file preserving all blockettes and flags.
`get_record_information()` | Returns record information about given files and file-like object.
`set_flags_in_fixed_headers()` | Updates a given miniSEED file with some fixed header flags.

## Modules

`core` | MSEED bindings to ObsPy core module.
`util` | MiniSEED specific utilities.

## Scripts

`scripts.recordanalyzer` | A command-line tool to analyze Mini-SEED records.

### 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)