Skip to content

Home

Jump to bottom
aringler-usgs edited this page Feb 18, 2020 · 4 revisions

Logo

We are pleased to announce ObsPy 1.2.0 has finally arrived! It is a pretty big release accumulating changes across the code base by XX unique contributors over the course of over 13 months! Thanks a lot to everyone involved - it would not be possible without your help!

We recommend all users to upgrade as it, aside from new features, contains a lot of bug fixes and smaller improvements and this release terminates the maintenance of the 1.1.x line. Additionally there should be no breaking changes (aside the later mentioned now-actually-removed deprecated functions/imports).

This document details significant new features and changes in ObsPy 1.2.0. The Full Changelog at the end is more comprehensive.

Documentation and resources for this version can (as always) be found at: https://docs.obspy.org

Aside from the occasional change and new feature, there never was any formal funding for ObsPy and it has been developed by enthusiastic volunteers, mostly from academia. If you use ObsPy, please consider acknowledging us so we can justify investing time into it.

Index

Supported Systems

We officially support the following systems (meaning we test that they work with ObsPy; other versions - especially newer ones, might work, but we cannot guarantee that).

Python modules:

  • Python: 3.4, 3.5, 3.6 (dropped support for Python 2.7)
  • NumPy: 1.6.2 - 1.13
  • SciPy: 0.11.0 - 1.0 (minimum SciPy is now 0.11.0)
  • matplotlib: 1.1.1 - 2.1 (added support for matplotlib 2.x)
  • basemap: 1.0.2 - 1.1.0

Supported Operating Systems (mostly 32bit and 64bit):

  • Windows
  • OSX
  • Linux (tested with default packages on CentOS/RedHat 7, Debian 7 + 8 + 9, Fedora 25 + 26, openSUSE Leap 42.2 + 42.3, Ubuntu 14.04 + 16.04 + 17.04 + 17.10)
  • Raspberry Pi (Raspbian Wheezy + Jessie + Stretch)

Updating ObsPy

Updating should be straight-forward. So depending on your installation do

# Generic Python
#
# For the first time we also have binary wheels for Linux and OSX so
# this now also works without a compiler.
$ pip install -U obspy
# Anaconda Python Distribution
# `conda install -c obspy obspy` is no longer supported for most platforms!
$ conda update -c conda-forge obspy
# Debian/Ubuntu
# add debs.obspy.org to your /etc/apt/sources.list first
$ apt-get update
$ apt-get upgrade python-obspy  # and/or python3-obspy

or whatever your package manager of choice needs to be told to update a package.

New Deprecations

  • obspy.core.UTCDateTime: Deprecation warnings now occur when comparing attributes outside init or comparing different precisions.
  • obspy.core.convert_id_to_quakeml_uri: Is being deprecated and replaced by ResourceIdentifier (see [#2303] (https://github.com/obspy/obspy/pull2303))
  • obspy.core.get_quakemk_uri is being deprecated and replaced by obspy.core.get_quakemk_uri_str.

Notable Changes in obspy.core

Additional Support for Nordic Format

New client in obspy.clients.nrl to access the Nominal Response Library (NRL) to get ObsPy Response objects (see #1185). This means that full station metadata can now be assembled programmatically using ObsPy (see http://docs.obspy.org/tutorial/code_snippets/stationxml_file_from_scratch.html). Usage example:

>>> from obspy.clients.nrl import NRL
>>> nrl = NRL()
>>> response = nrl.get_response(
...		sensor_keys=['Streckeisen', 'STS-1', '360 seconds'],
...     datalogger_keys=['REF TEK', 'RT 130 & 130-SMA', '1', '200'])
>>> print(response)
Channel Response
    From M/S (Velocity in Meters per Second) to COUNTS (Digital Counts)
    Overall Sensitivity: 1.50991e+09 defined at 0.020 Hz
    10 stages:
        Stage 1: PolesZerosResponseStage from M/S to V, gain: 2400
        Stage 2: ResponseStage from V to V, gain: 1
        Stage 3: CoefficientsTypeResponseStage from V to COUNTS, gain: 629129
        Stage 4: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 5: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 6: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 7: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 8: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 9: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1
        Stage 10: CoefficientsTypeResponseStage from COUNTS to COUNTS, gain: 1

read_inventory() support for (X)SEED and RESP files

This finally unifies station information and response handling for all file formats ObsPy can work with. ObsPy can now read (X)SEED and RESP files with obpsy.read_inventory() (see #1185). A couple of things to note:

  • RESP files don't store coordinates. They will thus be set to zero in the ObsPy objects.
  • Malformed SEED/RESP responses will be interpreted in the way evalresp interprets them.
  • Blockette 60 responses will be converted to their non-dictionary counterparts.

This, amongst other things, makes it a useful tool to convert your legacy data to modern StationXML files.

New Things Regarding Data Downloading

FDSNWS Routing Clients

ObsPy now has support for two FDSNWS routing services:

They support a similiar interface to the normal FDSN clients, but will query one of the routing services to figure out which data center has what data, before actually downloading the data. Usage example:

>>> from obspy import UTCDateTime
>>> client = RoutingClient("iris-federator")  # Can also be "eida-routing".
>>> st = client.get_waveforms(
...     channel="LHZ", starttime=UTCDateTime(2017, 1, 1),
...     endtime=UTCDateTime(2017, 1, 1, 0, 5), latitude=10,
...     longitude=10, maxradius=25)
>>> print(st)
2 Trace(s) in Stream:
II.MBAR.00.LHZ | 2017-01-01T00:00:00Z - ... | 1.0 Hz, 300 samples
II.MBAR.10.LHZ | 2017-01-01T00:00:00Z - ... | 1.0 Hz, 300 samples

EIDA Token Authentication

(Experimental) support for token based authentication as implemented by many EIDA nodes (see #1928).

Mass Downloader

  • The mass downloader now has exclude_networks and exclude_stations arguments to not download certain pieces of data. (see #1305)
  • The mass downloader can now download stations that are part of a given inventory object.
  • The mass downloader now also works with restricted data. (See #1350)

Quality Control Module

There is a new obspy.signal.quality_control module to compute quality metrics from MiniSEED files (see #1141). The calculated metrics are in accordance with the EIDA WF Catalog Service.

>>> from obspy.signal.quality_control import MSEEDMetadata
>>> mseedqc = MSEEDMetadata(['path/to/file', 'path/to/file2'])
# Calculated metrics are available as
>>> mseedqc.meta
# Serialize to JSON with.
>>> mseedqc.get_json_meta()

Iterative reading of SEGY and Seismic Unix Files

Useful for reading arbitrarily large files without running into memory problems:

>>> from obspy.core.util import get_example_file
>>> filename = get_example_file("00001034.sgy_first_trace")
>>> from obspy.io.segy.segy import iread_segy

>>> for tr in iread_segy(filename):
...     # Each Trace's stats attribute will have references to the file
...     # headers and some more information.
...     tf = tr.stats.segy.textual_file_header
...     bf = tr.stats.segy.binary_file_header
...     tfe = tr.stats.segy.textual_file_header_encoding
...     de = tr.stats.segy.data_encoding
...     e = tr.stats.segy.endian
...     # Also do something meaningful with each Trace.
...     print(int(tr.data.sum() * 1E9))
-5

New Signal Processing Things

  • New correlate function for calculating the cross-correlation function (new implementation based on Scipy). To calculate the shift of the maximum of the cross correlation use xcorr_max. The old xcorr function is deprecated but currently still exists (see #1585).
  • New obspy.signal.regression module to compute linear regressions, with or without weights, with or without allowing for an intercept. (see #1716, #1747)
  • add new plotting capabilities to PPSD (temporal variations per frequency and spectrogram-like plot) and also make underlying processed PSDs available via PPSD.psd_values property (see #1327)

Changes in obspy.taup

  • Add obspy.taup.taup_geo.calc_dist_azi, a function to return the distance, azimuth and backazimuth for a source - receiver pair. (see #1538)
  • Fixing calculations through very small regional models. (see #1761)
  • Updated ray path plot method, added travel time plot method, and wrapper functions for both ray path and travel time plotting. (see #1501, #1877)

Miscellaneous Notable Bug Fixes and Improvements

Full Changelog

1.2.0: (doi: XXXYYY)
- obspy.core:
   * inventory objects have been adapted to StationXML 1.1 for details on
     changes see #2510 and
     https://github.com/FDSN/StationXML/blob/master/Changes.md
   * Fixed import of custom plugins (see #2423)
   * Fixed "==" comparison for Stream and Trace which was very slow in case of
     traces with >1e6 samples (see #2377)
   * Added almost_equal method for Stream and Trace classes (see #2286).
   * Casting FDSN identifiers to strings upon setting in the stats dictionary
     (see #1997).
   * UTCDateTime objects will now always evaluate equal if their string
     representations are equal (see #2049).
   * UTCDateTime objects now issue depreciation warnings when setting any
     attributes outside of init, or comparing UTCDateTime objects with
     different precisions (see #2077).
   * UTCDateTime objects can now accept hour, minute, second, and microsecond
     values greater than their normal limits by setting the strict keyword
     argument to False (see #2232).
   * fixed UTCDateTime(..., julday=366) for non-leap years. This was returning
     January 1st of the next year in case of non-leap years being used. Now it
     properly raises an out-of-bounds ValueError (see #2369)
   * When reading StationXML/SC3ML, make sure to properly read empty string
     fields as empty strings instead of "None" (see #2519 and #2527)
   * better ISO8601 detection for UTCDateTime objects and UTCDateTime(...,
     iso8601=False) now completely disables ISO8601 handling (see #2447)
   * Added replace method to UTCDateTime class (see #2077).
   * Added remove method to Inventory class (see #2088).
   * Added id property to WaveformStreamID (see #2131).
   * Added __str__ and _repr_pretty_ method for Comment class (see #2115)
   * Added __eq__ to QuantityError so empty instances equal None (see #2185).
   * Reworked the event scoped resource identifiers for the event classes
     hopefully fixing all edge-cases (see #2091).
   * Added a hook to allow users to customize finding objects for
     resource_ids which are not found via the normal means (see #2279).
   * Calling Stream.write(...) on an empty stream will now raise an
     ObsPyException consistently across all I/O plugins (see #2201)
   * Stream.get_gaps() will now properly report gaps within Traces that
     have masked arrays (i.e. Traces that have been merged without a fill
     value, see #2299 and #2300).
   * Added copy method to Inventory class (see #2322).
   * The Response.recalculate_overall_sensitivity() method now accepts integers
     (see #2338, #2343).
   * Added wildcard and url support to read_inventory (see #2326).
   * Modified stream.get_gaps() to deal with overlaps correctly (see #1403)
   * Added option "label_epoch_dates" to Inventory/Network.plot_response() to
     optionally add channel epoch start/end dates to legend labels (see #2309)
   * Deprecated the convert_id_to_quakeml_uri, regenerate_uuid, and
     get_quakeml_uri methods of the ResourceIdentifier class (see #2303).
   * Added get_quakeml_uri_str and get_quakeml_id methods to the
     ResourceIdentifier class (see #2303).
   * New method to create response objects directly from poles and zeros (see
     #1962).
   * Added Stream.stack method (see #2440).
   * Added a component field to the Stats object which allows to get and set
     the last character of the SEED channel (see #2484).
   * Fixed a bug in Stream.plot(type='section', reftime=..., ...) that caused
     wrong relative start times of traces relative to given reftime (see #2493)
   * Fixed a Windows-specific path case issue in a helper function that returns
     a list of untracked files in the git repository (see #2296)
   * Fix a bug that was causing an exception being raised in `Response.plot()`
     because a float was being passed down to numpy.linspace as length of array
     (see #2533)
   * Geographic select of inventory/network/station (see #2515)
 - obspy.clients.fdsn:
   * Add new `_discover_services` boolean flag to the Client, which allows the
     Client to skip the initial services query at instantiation.  This can
     reduce the load on service providers, but skips checks against unsupported
     query parameters.
   * Adding more location codes to the default priority list in the mass
     downloader (see #2155, #2159).
   * The mass downloader now raises a warning if all channels from a station
     have been deselected due to the default location priorities setting. This
     is a pure usability improvement as it has been confusing users
     (see #2159).
   * make sure that streams fetched via FDSN are properly trimmed to user
     requested times if data center serves additional data around the start/end
     (see #1887, #2298)
   * fix a problem that could spam subprocesses that were not closed in routed
     clients (see #2342 and #2344)
   * make it possible to use signed EIDA tokens and also skip token validation
     completely (see #2297)
   * adding a mapping for RASPISHAKE
 - obspy.clients.neic:
   * properly use specified timeout value (see #2450)
 - obspy.clients.seishub:
   * Properly handle fetching poles and zeros in presence of multiple metadata
     files for a given station (see #2411)
 - obspy.clients.seedlink:
   * add method "get_info()" to fetch information on what
     networks/stations/locations/channels are served by the seedlink server
     (see #2405)
   * "get_waveforms()" can now be used with '*' and '?' wildcards in any part
     of requested SEED ID, i.e. network, station, location and channel (see
     #2405)
 - obspy.clients.iris:
   * results of distaz method are now returned as native floats (see #2499)
 - obspy.geodetics:
   * new utility function `inside_geobounds()` to check whether an object is
     inside a geographic bound (see #2515)
 - obspy.imaging:
   * obspy-scan can now be used with wildcarded SEED IDs when specifying what
     to plot after scanning data (see #2227)
   * fix a problem in Scanner when loading npz on Python3 that was written on
     Python2 (see #2413)
   * fix an issue that could make small landmasses not get plotted in basemap
     plots (see #2471, #2477)
   * Fixed a bug in Stream.plot(type='section', reftime=..., ...) that caused
     wrong relative start times of traces relative to given reftime (see #2493)
 - obspy.io:
    * added read support for receiver gather format v. 1.6 (see #2070)
    * added read support for FOCMEC 'out' and 'lst' files (see #2156)
    * added read support for HypoDD 'pha' files (see #2378)
 - obspy.io.arclink:
   * Accommodate change in SeisComP3 publicID delimiter from '#' to '/' in
     ArclinkXML (see #2552)
 - obspy.io.dmx:
   * Add read support for INGV's DMX format (see #2452)
 - obspy.io.gcf:
   * Fixes Python 3.8 compatibility of GCF reader. (see #2505)
 - obspy.io.mseed:
   * Fix a bug resulting in an infinite loop when trying to read a FullSEED
     file without any data records (see #2534 and #2535)
   * Add ability to write int64 data to mseed if it can safely be downcast
     to int32 data, otherwise raises ObsPyMSEEDError. (see #2356)
   * The recordanalyzer can now detect calibration blockettes 300, 310,
     and 320 (see #2370).
   * Can now write zero sampling-rate traces. (see #2488, 2509)
 - obspy.io.nordic:
   * Add ability to read and write focal mechanisms and moment tensor
     information. (see #1924)
   * Add explicit warnings regarding unsupported sections of Nordic files.
   * Fix mapping of magnitude-types between MS to S and Ms to s.
   * Output preferred origin when writing to Nordic format instead of using
     the first origin (see #2195)
   * Include high-accuracy phase-pick reading and writing - high-accuracy is
     now the default phase-writing format, a boolean flag `high_accuracy`
     has been added to turn this off. (see #2351 and #2348)
   * Allow long-phase names (both reading and writing) - longer than 4 char.
     (see #2351)
   * Include AIN as takeoff-angle when reading and writing nordic files
     (see #2404).
   * Add error ellipses and read high-accuracy hypocenter lines (see #2451)
   * Fix the incorrect handling of events missing pick evaluation information
     (see #2520)
 - obspy.io.reftek:
   * Implement reading reftek encodings '16' and '32' (uncompressed data,
     16/32bit integers, see #2058 and #2059)
 - obspy.io.rg16:
   * implement module to read waveforms and headers from fcnt format (see #2265).
   * Fix reading when start+endtime are inside one data packet (see #2485).
 - obspy.io.seg2:
   * Handle data format code 3 trace data (#2022, #2385).
   * Improve parsing of free-form entries (#2385).
   * Fix non-native endian data loading (#2385).
 - obspy.io.segy:
   * show nice error message when trying to write a trace with too many samples
     in it (see #2358, #1393)
 - obspy.io.seiscomp:
   * Very large performance improvement reading large sc3ml inventory files by
     pre-indexing sensors, dataloggers and responses and reducing lxml calls
     (see #2296).
   * When reading StationXML/SC3ML, make sure to properly read empty string
     fields as empty strings instead of "None" (see #2519 and #2527)
 - obspy.io.stationxml:
   * When reading StationXML/SC3ML, make sure to properly read empty string
     fields as empty strings instead of "None" (see #2519 and #2527)
   * inventory objects have been adapted to StationXML 1.1 for details on
     changes see #2510 and
     https://github.com/FDSN/StationXML/blob/master/Changes.md
 - obspy.io.quakeml:
   * Allow writing invalid ids but raise a warning
     (see #2104, #2090, #2093, #1872).
   * Skip invalid enumeration values during reading but raise a warning.
     (see #2106, #2098, #2095)
   * Catalogs with empty event description objects can be round-tripped (see
     #2339, #2340).
   * Correctly handle QuakeML native namespaces (if they are not matching the
     document root's namespace) as custom namespaces and parse them into
     `.extra` (see #2466)
 - obspy.io.sac:
   * Fix bug writing inventory with SOH channels to SACPZ (see #2200).
 - obspy.io.segy:
   * Raise nicer error messages when header packing fails (see #2194, #2196).
 - obspy.io.seiscomp:
   * Adding support for SC3ML 0.10 (see #2024).
   * Update xsl to allow conversion of amplitude picks not associated with
     origins (see #2273).
 - obspy.io.sh:
   * Add read support for SeismicHandler EVT event files (see #2109)
 - obspy.io.shapefile:
   * Add possibility to add custom database columns when writing catalog or
     inventory objects to shapefile (see #2012 and #2305)
 - obspy.io.xseed:
   * Ability to parse SEED files with extra newlines between blockettes
     (see #2383)
 - obspy.signal.trigger:
    * fix a bug in AR picker (see #2157)
    * option to return Baer-Kradolfer characteristic function from pk_mbaer
      function added (see #2341)
 - obspy.signal.polarization:
   * Fix an issue in selecting Z/N/E traces from given stream (see #2365)
 - obspy.signal.PPSD:
   * Changed numpy-based serialization as to not require pickling (see #2424).
   * Fixed exact trace cutting for PSD segments (see #2040).
   * Timestamp representations internally and in npz I/O were changed to use
     integer nanosecond POSIX timestamps to avoid any potential floating point
     inaccuracies and since this is also what UTCDateTime is based on nowadays
     (see #2045).
   * Fixed the check for new PSD slices whether they should be added or whether
     they would add unwanted duplicated data (see #2229).
   * Fix `period_lim` option when `xaxis_frequency=True` (see #2246).
   * Added `allow_pickle` parameter to `PPSD.add_npz` and `PPSD.load_npz` and
     set its default to `False` (see #2457).
   * Added representation of earthquake models from Clinton & Heaton (2002) in
     'plot()' method using option 'show_earthquakes' (see #2455).
 - obspy.signal.cross_correlation:
   * Add new `correlate_template()` function with 'full' normalization option,
     required for correlations in template-matching
     (see #2035 and #2042).
   * 'domain' parameter in correlate function is deprecated in favour of new
     'method' parameter to be consistent with recent SciPy versions
     (see #2042).
   * Add `correlate_stream_template()` and `correlation_detector()`
     functions to detect events based on template matching (see #2315)
 - obspy.taup:
   * fix cycling through colors in ray path plots (see #2470, #2478)
   * fix a floating point issue on IBM machines (see #2559, #2560)

Clone this wiki locally