# obspy.core.inventory - Classes for handling station metadata

This module provides a class hierarchy to consistently handle station metadata. This class hierarchy is closely modelled after the upcoming de-facto standard format FDSN StationXML which was developed as a human readable XML replacement for Dataless SEED.

Note

IRIS is maintaining a Java tool for converting dataless SEED into StationXML and vice versa at https://seiscode.iris.washington.edu/projects/stationxml-converter

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

StationXML files can be read using the `read_inventory()` function that returns an `Inventory` object.

    >>> from obspy import read_inventory
    >>> inv = read_inventory("/path/to/BW_RJOB.xml")
    >>> inv
    <obspy.core.inventory.inventory.Inventory object at 0x...>
    >>> print(inv)
    Inventory created at 2013-12-07T18:00:42.878000Z
        Created by: fdsn-stationxml-converter/1.0.0
                http://www.iris.edu/fdsnstationconverter
        Sending institution: Erdbebendienst Bayern
        Contains:
            Networks (1):
                BW
            Stations (1):
                BW.RJOB (Jochberg, Bavaria, BW-Net)
            Channels (3):
                BW.RJOB..EHE, BW.RJOB..EHN, BW.RJOB..EHZ

The file format in principle is autodetected. However, the autodetection uses the official StationXML XSD schema and unfortunately many real world files currently show minor deviations from the official StationXML definition causing the autodetection to fail. Thus, manually specifying the format is a good idea:

    >>> inv = read_inventory("/path/to/BW_RJOB.xml", format="STATIONXML")

## Class hierarchy

The `Inventory` class has a hierarchical structure, starting with a list of `Networks`, each containing a list of `Stations` which again each contain a list of `Channels`. The `Responses` are attached to the channels as an attribute.

    >>> net = inv[0]
    >>> net
    <obspy.core.inventory.network.Network object at 0x...>
    >>> print(net)
    Network BW (BayernNetz)
        Station Count: None/None (Selected/Total)
        None -
        Access: None
        Contains:
            Stations (1):
                BW.RJOB (Jochberg, Bavaria, BW-Net)
            Channels (3):
                BW.RJOB..EHZ, BW.RJOB..EHN, BW.RJOB..EHE

    >>> sta = net[0]
    >>> print(sta)
    Station RJOB (Jochberg, Bavaria, BW-Net)
        Station Code: RJOB
        Channel Count: None/None (Selected/Total)
        2007-12-17T00:00:00.000000Z -
        Access: None
        Latitude: 47.74, Longitude: 12.80, Elevation: 860.0 m
        Available Channels:
            RJOB..EHZ, RJOB..EHN, RJOB..EHE

    >>> cha = sta[0]
    >>> print(cha)
    Channel 'EHZ', Location ''
       Timerange: 2007-12-17T00:00:00.000000Z - --
       Latitude: 47.74, Longitude: 12.80, Elevation: 860.0 m, Local Depth: 0.0 m
       Azimuth: 0.00 degrees from north, clockwise
       Dip: -90.00 degrees down from horizontal
       Channel types: TRIGGERED, GEOPHYSICAL
       Sampling Rate: 200.00 Hz
       Sensor: Streckeisen STS-2/N seismometer
       Response information available

    >>> print(cha.response)
    Channel Response
       From M/S (Velocity in Meters Per Second) to COUNTS (Digital Counts)
       Overall Sensitivity: 2.5168e+09 defined at 0.020 Hz
       4 stages:
          Stage 1: PolesZerosResponseStage from M/S to V, gain: 1500
          Stage 2: CoefficientsTypeResponseStage from V to COUNTS, gain: 1.67...
          Stage 3: FIRResponseStage from COUNTS to COUNTS, gain: 1
          Stage 4: FIRResponseStage from COUNTS to COUNTS, gain: 1

## Preview plots of station map and instrument response

For station metadata, preview plot routines for geographic location of stations as well as bode plots for channel instrument response information are available. The routines for station map plots are:

> - `Inventory.plot()`
> - `Network.plot()`

For example:

    >>> from obspy import read_inventory
    >>> inv = read_inventory()
    >>> inv.plot()

(Source code, png, hires.png)

The routines for bode plots of channel instrument response are:

> - `Inventory.plot_response()`
> - `Network.plot_response()`
> - `Station.plot()`
> - `Channel.plot()`
> - `Response.plot()`

For example:

    >>> from obspy import read_inventory
    >>> inv = read_inventory()
    >>> resp = inv[0][0][0].response
    >>> resp.plot(0.001, output="VEL")

(Source code, png, hires.png)

For more examples see the Obspy Gallery.

## Dealing with the Response information

The `get_evalresp_response()` method will call some functions within evalresp to generate the response.

    >>> response = cha.response
    >>> response, freqs = response.get_evalresp_response(0.1, 16384, output="VEL")
    >>> print(response)
     [  0.00000000e+00 +0.00000000e+00j  -1.36383361e+07 +1.42086194e+06j
       -5.36470300e+07 +1.13620679e+07j ...,   2.48907496e+09 -3.94151237e+08j
        2.48906963e+09 -3.94200472e+08j   2.48906430e+09 -3.94249707e+08j]

Some convenience methods to perform an instrument correction on `Stream` (and `Trace`) objects are available and most users will want to use those. The `attach_response()` method will attach matching responses to each trace if they are available within the inventory object. The `remove_response()` method deconvolves the instrument response in-place. As always see the corresponding docs pages for a full list of options and a more detailed explanation.

    >>> from obspy import read
    >>> st = read()
    >>> inv = read_inventory("/path/to/BW_RJOB.xml")
    >>> st.attach_response(inv)
     []
    >>> st.remove_response(output="VEL", water_level=20)
    <obspy.core.stream.Stream object at 0x...>

## Writing

`Inventory` objects can be exported to StationXML files, e.g. after making modifications.

    >>> inv.write('my_inventory.xml', format='STATIONXML')

## Classes & Functions

`inventory.read_inventory` | Function to read inventory files.

## Modules

`inventory` | Provides the Inventory class.
`network` | Provides the Network class.
`station` | Provides the Station class.
`channel` | Provides the Channel class.
`response` | Classes related to instrument responses.
`util` | Utility objects.

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