1# -*- coding: utf-8 -*- 2""" 3obspy.io.mseed - MiniSEED read and write support for ObsPy 4========================================================== 5This module provides read and write support for the `MiniSEED 6<https://ds.iris.edu/ds/nodes/dmc/data/formats/#miniseed>`_ (and the 7data part of full SEED) waveform data format and some other convenient 8methods to handle MiniSEED files. It utilizes 9`libmseed <https://ds.iris.edu/ds/nodes/dmc/software/downloads/libmseed/>`_, 10a C library by Chad Trabant. 11 12.. seealso:: 13 14 The format is defined in the 15 `SEED Manual <https://www.fdsn.org/seed_manual/SEEDManual_V2.4.pdf>`_. 16 17:copyright: 18 The ObsPy Development Team (devs@obspy.org) & Chad Trabant 19:license: 20 GNU Lesser General Public License, Version 3 21 (https://www.gnu.org/copyleft/lesser.html) 22 23Reading 24------- 25 26Reading MiniSEED (and the data part of full SEED files) is handled by using 27ObsPy's standard :func:`~obspy.core.stream.read` function. The format is 28detected automatically. 29 30>>> from obspy import read 31>>> st = read("/path/to/test.mseed") 32>>> st #doctest: +ELLIPSIS 33<obspy.core.stream.Stream object at 0x...> 34>>> print(st) #doctest: +ELLIPSIS 351 Trace(s) in Stream: 36NL.HGN.00.BHZ | 2003-05-29T02:13:22.043400Z - ... | 40.0 Hz, 11947 samples 37>>> print(st[0].stats) # doctest: +ELLIPSIS 38 network: NL 39 station: HGN 40 location: 00 41 channel: BHZ 42 starttime: 2003-05-29T02:13:22.043400Z 43 endtime: 2003-05-29T02:18:20.693400Z 44 sampling_rate: 40.0 45 delta: 0.025 46 npts: 11947 47 calib: 1.0 48 _format: MSEED 49 mseed: ... 50 51MiniSEED specific metadata is stored in ``stats.mseed``. 52 53>>> for k, v in sorted(st[0].stats.mseed.items()): 54... print("'%s': %s" % (k, str(v))) # doctest: +NORMALIZE_WHITESPACE 55 'byteorder': > 56 'dataquality': R 57 'encoding': STEIM2 58 'filesize': 8192 59 'number_of_records': 2 60 'record_length': 4096 61 62The actual data is stored as a :class:`~numpy.ndarray` in the ``data`` 63attribute of each trace. 64 65>>> print(st[0].data) 66[2787 2776 2774 ..., 2850 2853 2853] 67 68 69Several key word arguments are available which can be used for example to 70only read certain records from a file or force the header byteorder: 71``starttime``, ``endtime``, ``headonly``, ``sourcename``, ``reclen``, 72``details``, and ``header_byteorder``. They are passed to the 73:meth:`~obspy.io.mseed.core._read_mseed` method so refer to it for details to 74each parameter. 75 76Writing 77------- 78Write data back to disc or a file like object using the 79:meth:`~obspy.core.stream.Stream.write` method of a 80:class:`~obspy.core.stream.Stream` or 81:class:`~obspy.core.trace.Trace` object. 82 83>>> st.write('Mini-SEED-filename.mseed', format='MSEED') #doctest: +SKIP 84 85You can also specify several keyword arguments that change the resulting 86Mini-SEED file: ``reclen``, ``encoding``, ``byteorder``, ``flush``, and 87``verbose``. 88They are are passed to the :meth:`~obspy.io.mseed.core._write_mseed` method so 89refer to it for details to each parameter. 90 91Refer to the :meth:`~obspy.io.mseed.core._write_mseed` method for details to 92each parameter. 93 94So in order to write a STEIM1 encoded Mini-SEED file with a record length of 95512 byte do the following: 96 97>>> st.write('out.mseed', format='MSEED', reclen=512, # doctest: +SKIP 98... encoding='STEIM1') 99 100Many of these can also be set at each Trace`s ``stats.mseed`` attribute which 101allows for per Trace granularity. Values passed to the 102:func:`~obspy.core.stream.read` function have priority. 103 104 105Encoding Support 106---------------- 107 108MiniSEED is a format with a large variety of different blockettes, 109byte order issues, and encodings. The capabilities of ``obspy.io.mseed`` 110largely coincide with the capabilities of ``libmseed``, which is the de-facto 111standard MiniSEED library and used internally by ObsPy. 112 113In regards to the different encodings for the data part of MiniSEED files 114this means the following: 115 116* Read support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats, 117 STEIM 1 + 2, all GEOSCOPE encodings, the CDSN encoding, the SRO encoding, 118 and the DWWSSN encoding 119* Write support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats, 120 and STEIM 1 + 2 121* Unsupported: 24 bit integers, US National Network compression, 122 Graefenberg 16 bit gain ranged encoding, IPG - Strasbourg 16 bit gain ranged 123 encoding, STEIM 3, the HGLP encoding, and the RSTN 16 bit gain ranged 124 encoding 125 126Utilities 127--------- 128 129This module also contains a couple of utility functions which are useful for 130some purposes. Refer to the documentation of each for details. 131 132+----------------------------------------------------------+--------------------------------------------------------------------------+ 133| :func:`~obspy.io.mseed.util.get_start_and_end_time` | Fast way of getting the temporal bounds of a well-behaved MiniSEED file. | 134+----------------------------------------------------------+--------------------------------------------------------------------------+ 135| :func:`~obspy.io.mseed.util.get_flags` | Returns information about the flags and timing quality in a file. | 136+----------------------------------------------------------+--------------------------------------------------------------------------+ 137| :func:`~obspy.io.mseed.util.shift_time_of_file` | Shifts the time of a file preserving all blockettes and flags. | 138+----------------------------------------------------------+--------------------------------------------------------------------------+ 139| :func:`~obspy.io.mseed.util.get_record_information` | Returns record information about given files and file-like object. | 140+----------------------------------------------------------+--------------------------------------------------------------------------+ 141| :func:`~obspy.io.mseed.util.set_flags_in_fixed_headers` | Updates a given miniSEED file with some fixed header flags. | 142+----------------------------------------------------------+--------------------------------------------------------------------------+ 143""" 144from __future__ import (absolute_import, division, print_function, 145 unicode_literals) 146from future.builtins import * # NOQA 147 148from obspy import ObsPyException, ObsPyReadingError 149 150 151class ObsPyMSEEDError(ObsPyException): 152 pass 153 154 155class ObsPyMSEEDReadingError(ObsPyMSEEDError, ObsPyReadingError): 156 pass 157 158 159class InternalMSEEDError(ObsPyMSEEDError): 160 pass 161 162 163class InternalMSEEDParseTimeError(InternalMSEEDError): 164 pass 165 166 167class InternalMSEEDWarning(UserWarning): 168 pass 169 170 171class ObsPyMSEEDFilesizeTooSmallError(ObsPyMSEEDReadingError): 172 pass 173 174 175class ObsPyMSEEDFilesizeTooLargeError(ObsPyMSEEDReadingError): 176 pass 177 178 179__all__ = ['InternalMSEEDError', 'InternalMSEEDWarning', 'ObsPyMSEEDError', 180 'ObsPyMSEEDFilesizeTooSmallError'] 181 182 183if __name__ == '__main__': 184 import doctest 185 doctest.testmod(exclude_empty=True) 186