# obspy.io.nlloc - NonLinLoc file format support for ObsPy

This module provides read/write support for some NonLinLoc file formats.

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

## Example

If NonLinLoc location run was performed using one of the standard projections available in the NonLinLoc package, it is straightforward to read a NonLinLoc Hypocenter-Phase file into an ObsPy `Catalog` object:

    >>> from obspy import read_events
    >>> cat = read_events("/path/to/nlloc.hyp")
    >>> print(cat)
    1 Event(s) in Catalog:
    2006-07-15T17:21:20.195670Z | +51.658,   +7.737

    >>> event = cat[0]
    >>> print(event)
    Event:  2006-07-15T17:21:20.195670Z | +51.658,   +7.737

             resource_id: ResourceIdentifier(id="smi:local/...")
           creation_info: CreationInfo(author='Claudio Satriano',
                                       creation_time=UTCDateTime(2013, 6, 21, ...),
                                       version='NLLoc:v6.02.07')
     preferred_origin_id: ResourceIdentifier(id="smi:local/...")
                    ---------
                comments: 1 Elements
                   picks: 5 Elements
                 origins: 1 Elements

    >>> origin = event.origins[0]
    >>> print(origin)
    Origin
             resource_id: ResourceIdentifier(id="smi:local/...")
                    time: UTCDateTime(2006, 7, 15, 17, 21, 20, 1956...)
               longitude: 7.736781...
                latitude: 51.657659...
                   depth: 1433.5... [confidence_level=68, uncertainty=...]
              depth_type: 'from location'
                 quality: OriginQuality(...)
      origin_uncertainty: OriginUncertainty(...)
           creation_info: CreationInfo(author='Claudio Satriano',
                                       creation_time=UTCDateTime(2013, 6, 21, ...),
                                       version='NLLoc:v6.02.07')
                    ---------
                comments: 1 Elements
                arrivals: 5 Elements

If, instead, NonLinLoc location run was performed in some custom coordinate system (as opposed to WGS84 with depth in meters down), we need to set up a coordinate conversion function to convert from the NonLinLoc location coordinates x, y, z to longitude, latitude and depth in kilometers. In the example, the location run was done in Gauß-Krüger zone 4 (EPSG:31468, but in kilometers for coordinates) and depth in kilometers. So we have to convert x and y (of NonLinLoc location run) to meters (as defined in EPSG:31468) and then we convert to WGS84 (EPSG:4326). The z coordinate is already in kilometers downwards and can be left as is. For the conversion we use pyproj.

    >>> import pyproj
    >>> proj_wgs84 = pyproj.Proj(init="epsg:4326")
    >>> proj_gk4 = pyproj.Proj(init="epsg:31468")
    >>> def my_conversion(x, y, z):
    ...     x *= 1e3
    ...     y *= 1e3
    ...     x, y = pyproj.transform(proj_gk4, proj_wgs84, x, y)
    ...     return x, y, z

Then, we can load the NonLinLoc Hypocenter-Phase file into an ObsPy `Catalog` object using `read_events()`, supplying our coordinate mapping function as coordinate_converter kwarg, which will be passed down to the low-level routine `read_nlloc_hyp()`.

    >>> from obspy import read_events
    >>> cat = read_events("/path/to/nlloc_custom.hyp",
    ...                  coordinate_converter=my_conversion)
    >>> print(cat)
    1 Event(s) in Catalog:
    2010-05-27T16:56:24.612600Z | +48.047,  +11.646

    >>> event = cat[0]
    >>> print(event)
    Event:  2010-05-27T16:56:24.612600Z | +48.047,  +11.646

           resource_id: ResourceIdentifier(id="smi:local/...")
         creation_info: CreationInfo(creation_time=..., version='NLLoc:v6.00.0')
        ---------
                 picks: 8 Elements
               origins: 1 Elements

    >>> origin = event.origins[0]
    >>> print(origin)
    Origin
           resource_id: ResourceIdentifier(id="smi:local/...")
                  time: UTCDateTime(2010, 5, 27, 16, 56, 24, 612600)
             longitude: 11.64553754...
              latitude: 48.04707051...
                 depth: 4579.4... [confidence_level=68, uncertainty=191.6063...]
                    ...
         creation_info: CreationInfo(creation_time=UTCDateTime(2014, 10, 17,
    16, 30, 8), version='NLLoc:v6.00.0')
        ---------
              comments: 1 Elements
              arrivals: 8 Elements

## Modules

`core` | NonLinLoc file format support for ObsPy
`util` | NonLinLoc file format support for ObsPy

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