# obspy.io.reftek - REFTEK130 read support for ObsPy

This module provides read support for the RefTek 130 data format.

Currently the low level read routines are designed to operate on waveform files written by RefTek 130 digitizers which are composed of event header/trailer and data packages. These packages do not store information on network or location code during acquisition. Furthermore, it is unclear how consistently the level of detail on the recorded channel codes is set in the headers (real world test data at hand recorded with a Reftek 130 do contain the information on the first two channel code characters, the band and instrument code but lack information on the component codes, i.e. ZNE, which with high likelihood were set in the acquisition parameters). Therefore, additional information on network and location codes should be supplied and ideally component codes should be supplied as well when reading files with `read()` (or should be filled in manually after reading). See the low-level routine `obspy.io.reftek.core._read_reftek130()` for additional arguments that can be supplied to `read()`. Currently, only event header/trailer (EH/ET) and data packets (DT) are implemented and any other packets will be ignored (a warning is shown if any other packets are encountered during reading). So far, only data encoding “C0” (STEIM 1 compressed data) is implemented due to the lack of test data in other encodings.

## Reading

Reading Reftek130 data is handled by using ObsPy’s standard `read()` function. The format is detected automatically and optionally can be explicitly set if known beforehand to skip format detection.

    >>> from obspy import read
    >>> st = read("/path/to/225051000_00008656")
    >>> st
    <obspy.core.stream.Stream object at 0x...>
    >>> print(st)
    8 Trace(s) in Stream:
    .KW1..EH0 | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3165 samples
    .KW1..EH0 | 2015-10-09T22:51:06.215000Z - ... | 200.0 Hz, 892 samples
    .KW1..EH0 | 2015-10-09T22:51:11.675000Z - ... | 200.0 Hz, 2743 samples
    .KW1..EH1 | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3107 samples
    .KW1..EH1 | 2015-10-09T22:51:05.925000Z - ... | 200.0 Hz, 768 samples
    .KW1..EH1 | 2015-10-09T22:51:10.765000Z - ... | 200.0 Hz, 2925 samples
    .KW1..EH2 | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3405 samples
    .KW1..EH2 | 2015-10-09T22:51:08.415000Z - ... | 200.0 Hz, 3395 samples

Network, location and component codes can be specified during reading:

    >>> st = read("/path/to/225051000_00008656", network="BW", location="",
    ...           component_codes="ZNE")
    >>> st
    <obspy.core.stream.Stream object at 0x...>
    >>> print(st)
    8 Trace(s) in Stream:
    BW.KW1..EHE | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3405 samples
    BW.KW1..EHE | 2015-10-09T22:51:08.415000Z - ... | 200.0 Hz, 3395 samples
    BW.KW1..EHN | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3107 samples
    BW.KW1..EHN | 2015-10-09T22:51:05.925000Z - ... | 200.0 Hz, 768 samples
    BW.KW1..EHN | 2015-10-09T22:51:10.765000Z - ... | 200.0 Hz, 2925 samples
    BW.KW1..EHZ | 2015-10-09T22:50:51.000000Z - ... | 200.0 Hz, 3165 samples
    BW.KW1..EHZ | 2015-10-09T22:51:06.215000Z - ... | 200.0 Hz, 892 samples
    BW.KW1..EHZ | 2015-10-09T22:51:11.675000Z - ... | 200.0 Hz, 2743 samples

Reftek 130 specific metadata (from event header packet) is stored in `stats.reftek130`.

    >>> print(st[0].stats)
             network: BW
             station: KW1
            location:
             channel: EHE
           starttime: 2015-10-09T22:50:51.000000Z
             endtime: 2015-10-09T22:51:08.020000Z
       sampling_rate: 200.0
               delta: 0.005
                npts: 3405
               calib: 1.0
             _format: REFTEK130
           reftek130: ...

Details on the individual packets can be retrieved with the low level `Reftek130` object:

    >>> from obspy.core.util.base import get_example_file
    >>> from obspy.io.reftek.core import Reftek130
    >>> rt = Reftek130.from_file(get_example_file("225051000_00008656"))
    >>> print(rt)
    Reftek130 (29 packets, file: ...225051000_00008656)
    Packet Sequence  Byte Count  Data Fmt  Sampling Rate      Time
      | Packet Type   |  Event #  | Station | Channel #         |
      |   |  Unit ID  |    | Data Stream #  |   |  # of samples |
      |   |   |  Exper.#   |   |  |  |      |   |    |          |
    0000 EH AE4C  0  416  427  0 C0 KW1    200         2015-10-09T22:50:51.000000Z
    0001 DT AE4C  0 1024  427  0 C0             0  549 2015-10-09T22:50:51.000000Z
    0002 DT AE4C  0 1024  427  0 C0             1  447 2015-10-09T22:50:51.000000Z
    0003 DT AE4C  0 1024  427  0 C0             2  805 2015-10-09T22:50:51.000000Z
    0004 DT AE4C  0 1024  427  0 C0             0  876 2015-10-09T22:50:53.745000Z
    0005 DT AE4C  0 1024  427  0 C0             1  482 2015-10-09T22:50:53.235000Z
    0006 DT AE4C  0 1024  427  0 C0             1  618 2015-10-09T22:50:55.645000Z
    0007 DT AE4C  0 1024  427  0 C0             2  872 2015-10-09T22:50:55.025000Z
    0008 DT AE4C  0 1024  427  0 C0             0  892 2015-10-09T22:50:58.125000Z
    0009 DT AE4C  0 1024  427  0 C0             1  770 2015-10-09T22:50:58.735000Z
    0010 DT AE4C  0 1024  427  0 C0             2  884 2015-10-09T22:50:59.385000Z
    0011 DT AE4C  0 1024  427  0 C0             0  848 2015-10-09T22:51:02.585000Z
    0012 DT AE4C  0 1024  427  0 C0             1  790 2015-10-09T22:51:02.585000Z
    0013 DT AE4C  0 1024  427  0 C0             2  844 2015-10-09T22:51:03.805000Z
    0014 DT AE4C  0 1024  427  0 C0             0  892 2015-10-09T22:51:06.215000Z
    0015 DT AE4C  0 1024  427  0 C0             1  768 2015-10-09T22:51:05.925000Z
    0016 DT AE4C  0 1024  427  0 C0             2  884 2015-10-09T22:51:08.415000Z
    0017 DT AE4C  0 1024  427  0 C0             1  778 2015-10-09T22:51:10.765000Z
    0018 DT AE4C  0 1024  427  0 C0             0  892 2015-10-09T22:51:11.675000Z
    0019 DT AE4C  0 1024  427  0 C0             2  892 2015-10-09T22:51:12.835000Z
    0020 DT AE4C  0 1024  427  0 C0             1  736 2015-10-09T22:51:14.655000Z
    0021 DT AE4C  0 1024  427  0 C0             0  892 2015-10-09T22:51:16.135000Z
    0022 DT AE4C  0 1024  427  0 C0             2  860 2015-10-09T22:51:17.295000Z
    0023 DT AE4C  0 1024  427  0 C0             1  738 2015-10-09T22:51:18.335000Z
    0024 DT AE4C  0 1024  427  0 C0             0  892 2015-10-09T22:51:20.595000Z
    0025 DT AE4C  0 1024  427  0 C0             1  673 2015-10-09T22:51:22.025000Z
    0026 DT AE4C  0 1024  427  0 C0             2  759 2015-10-09T22:51:21.595000Z
    0027 DT AE4C  0 1024  427  0 C0             0   67 2015-10-09T22:51:25.055000Z
    0028 ET AE4C  0  416  427  0 C0 KW1    200         2015-10-09T22:50:51.000000Z
    (detailed packet information with: 'print(Reftek130.__str__(compact=False))')
    >>> print(rt.__str__(compact=False))
    Reftek130 (29 packets, file: ...225051000_00008656)
    EH Packet
        packet_sequence: 0
        experiment_number: 0
        unit_id: AE4C
        byte_count: 416
        time: 2015-10-09T22:50:51.000000Z
        event_number: 427
        data_stream_number: 0
        data_format: C0
        flags: 0
        --------------------
        _reserved_2:
        _reserved_3:
        ...
        detrigger_time: None
        digital_filter_list:
        first_sample_time: 2015-10-09T22:50:51.000000Z
        last_sample_time: None
        position:
        ...
        sampling_rate: 200
        station_channel_number: (None, None, None, None, None, None, None, ...)
        station_comment: STATION COMMENT
        station_name: KW1
        station_name_extension:
        stream_name: EH
        time_quality: ?
        time_source: 1
        total_installed_channels: 3
        trigger_time: 2015-10-09T22:50:51.000000Z
        trigger_time_message: Trigger Time = 2015282225051000

        trigger_type: CON
    DT Packet
        packet_sequence: 1
        experiment_number: 0
        unit_id: AE4C
        byte_count: 1024
        time: 2015-10-09T22:50:51.000000Z
        event_number: 427
        data_stream_number: 0
        channel_number: 0
        number_of_samples: 549
        data_format: C0
        flags: 0
    DT Packet
        packet_sequence: 2
        experiment_number: 0
        unit_id: AE4C
        byte_count: 1024
        time: 2015-10-09T22:50:51.000000Z
        event_number: 427
        data_stream_number: 0
        channel_number: 1
        number_of_samples: 447
        data_format: C0
        flags: 0
    ...

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

## Modules

`core` | REFTEK130 read support, core routines.
`util` |
`packet` | Routines for handling of Reftek130 packets.

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