QuakeMigrate 1.0.0 Release Notes
QuakeMigrate 1.0.0 is the culmination of almost 18 months of hard work, and is
the first major, stable release of the package. The codebase has been largely
re-written, delivering dramatic improvements in run-time and memory usage, many
new features and far greater flexibility to the user. There have also been a
large number of bug fixes relating to the stability and performance of the
package. All users are encouraged to update to this release.
We anticipate releasing v1.1.0 soon, with a significant expansion of
tutorials and related documentation, and some further improvements to
user-flexbility. (And maybe a couple more bug-fixes!) So please give us your
feedback!!
Thank you to everyone who has been part of the journey so far! With your help,
we have tested the code thoroughly, but it is inevitable that we won’t
have covered every possible use-case and combination of parameters – so please
continue to provide feedback. And please let us know when it works well, too!
It is our favourite source of motivation.
Highlights
-
Cross-platform support: QuakeMigrate has now been successfully built and
run on Linux, Mac and Windows! The core development of the code continues to
be carried out largely on Linux, so additional feedback & testing from
Windows and Mac users will continue to be appreciated.
-
Documentation: We now have comprehensive documentation automatically
built from the source code, plus installation instructions (for Linux, Mac
and Windows) and a limited set of tutorials. More coming soon!
-
Local magnitude calculation: support for built-in local magnitude
calculation (and output of cut raw, real and Wood-Anderson simulated
waveforms for each event).
-
Single-phase support: QuakeMigrate now supports flexible multiple-phase
stacking. For example, users processing Z-only nodal data may wish to only
stack P-wave onset functions. The flexible implementation allows users to
design onset functions for any phase of their choosing (with P and S the
default for the time being). But if you want to design an onset function to
identify and migrate/stack Vsh, Vsv etc. it is now easy to do!
-
Publication-ready plots: significant improvements to the information
content, clarity and aesthetics of automatic plots (including from the
trigger, locate, local-magnitude calculation and auto-picking modules &
sub-modules).
-
Examples: Two new examples; another demonstration of using QuakeMigrate
to detect and locate high-frequency basal icequakes (amongst crevassing
noise!), plus detecting dike-induced earthquakes during the 2014
Bárðarbunga-Holuhraun dike intrusion - featuring an event rate of more than
150 earthquakes per hour (~ 4000 per day!).
-
Tests: we have made our first steps on the journey to including a
comprehensive suite of tests, to verify correct operation after installation.
These are based on the included
icequake_iceland and dike_intrusion
example use-cases. More to come soon.
-
Logging: flexible log output – currently split mainly between “info”,
“warning” and “debug” levels. We recommend sticking with the default –
“debug" returns a lot of additional info!!
-
Modularity: the picker and onset sub-modules are now built on an abstract
base class, making it straightforward to build and share new alternatives
that integrate with the core migration machinery of the package.
-
License: QuakeMigrate 1.0.0 is released under the GPL v3 license.
Users who have been using the development branch
v1.0.0 serves as a citable release of the version of the code that has been
available on the development branch since January 2020 – however note there
have been a significant number of further enhancements and bug fixes over this
period, particularly since May 2020. We intend to maintain a far more granular
series of releases in future – thank you for your patience!
Users upgrading from the 0.x.x series
Users upgrading from the 0.x.x series will notice differences in the absolute
value of the coalescence functions calculated, due to bug-fixes affecting the
core migration and stacking functions. However, the relative values of the
coalescence functions through time should remain largely unchanged, meaning
trigger results and relative uncertainty estimates are still valid. Absolute
uncertainty estimates, however, were previously being over-estimated, and
trigger thresholds will need to be updated. To re-emphasise: there have been
major bug-fixes and improvements reaching throughout the entire package. To
benefit from these improvements we highly recommend re-processing the data
through all stages (detect, trigger & locate), though we have tried to
incorporate backwards-compatibility for all old output file formats wherever
possible, for example to allow you to solely re-run locate().
Changelog
This provides a limited summary of the major changes to the code since the
previous release. For full details please see the linked pull requests, and
commit messages therein.
- Change to top-level package name -
QMigrate → quakemigrate See #85
-
quakemigrate.core
- C libraries now build automatically when installing the package.
- C functions have been cleaned up and documented properly. See #21.
-
quakemigrate.export – new!
- Add some export utilities to a new module (
export).
- Currently includes functions to take the outputs of QuakeMigrate to: ObsPy
catalogue; ObsPy catalogue to NLLoc OBS file; ObsPy catalogue to MFAST SAC
input; QuakeMigrate to pyrocko Snuffler input.
-
quakemigrate.io
- Refactor the I/O system entirely. This was in response to Issue #66. See
68c13f7 for full details.
- The re-write of the
quakemigrate.io.data sub-module includes fixing bugs
and making breaking changes related to the detrending and
upsampling/decimation of waveform data. See c1ff447 and #103.
- Add support for reading response information (via a light wrapper of the
obspy function) and functions for response removal & Wood-Anderson
seismogram simulation, for use with the new
quakemigrate.signal.local_mag module.
- Add a new, more comprehensive, transparent & flexible
check_availability() function, to check what data is available given a
set of provided quality criteria.
- Added functions for removing response and simulating WA response
here, allowing for this functionality to be accessed from anywhere across
the package. This includes the ability to output real and/or WA cut
waveforms (as velocity or displacement seismograms), for example for
spectral analysis. Response removal parameters are specified (along
with the instrument response inventory) when creating the
Archive
object.
- The format of triggered event files, event files, pick files and
station-availabiity files have been heavily overhauled. See #76.
- Fix to allow for numerical station names.
-
quakemigate.lut – significant rewrite (see #54, #65)
- Significant changes to API – see examples.
- Users from the 0.x series will need to update their look-up table files
(using an included utility function) or re-compute them.
- Fully-documented, including a tutorial in the documentation.
- Handling of a possible bug/ambiguity in the scipy RegularGridInterpolator
API. The default for the fill_value parameter does not appear to be
consistent with documentation.
- The traveltime lookup tables are now stored in a dictionary structure
maps[station][phase] to enable migration of a flexible combination of
seismic phases, and to make it possible to migrate onsets for a subset of
the phases and stations contained in the LUT. See #75, #103.
- The 3-D grid on which the lookup tables are defined is now more intuitive
to build. The user simply chooses the positions of a pair of opposite
corners (the lower-left and upper-right) in geographic coordinates, the
geographic and cartesian projections (using pyproj), and a node spacing
along each axis.
The number of grid nodes will be calculated automatically to span the
volume of interest.
- User-specified units: the user must specify when making an LUT whether to
use units of metres or kilometres; this will then be used consistently
throughout the package. See #79.
-
quakemigrate.plot – new! See #83.
- Extracted all base plotting methods to individual modules within the
quakemigrate.plot module. No longer using a class to pass the information
around.
- Revamp all of the figures produced by QuakeMigrate to include more useful
information and to make better use of the available space. See 72b1c47 for
details.
-
quakemigrate.signal
- Refactor to be more flexible with the input data.
- QuakeMigrate now allows for single-component data to be used, or
stacking to be performed on just one phase (e.g. just P or just S). The
required changes reached quite deep into the package and have changed how
Onset objects are created, but is ultimately very straightforward to use.
See #103.
- Channel names can now be specified by the user, by default they are “Z”
for vertical component, and “[N,1]” and [“E,2”] for horizontal
components.
- Internally use
obspy.Trace objects to store data up to the point of
passing it to the C functions; this adds greater flexibility and more
built-in methods for quality checking, filtering, re-sampling etc. than the
previous framework using arrays.
-
quakemigate.signal.onsets – significant re-write
- Extracted the embedded onset function generation from the core QuakeScan
class to a new submodule,
quakemigrate.signal.onsets.
- Various changes to parameter names – see examples.
- Created an Abstract Base Class – Onset. This class can be used as a base
class for a class implementing an alternative onset function algorithm,
while ensuring compliance with the embedded code in QuakeScan.
- Created a new class OnsetData to store the pre-processed waveforms used
for onset calculation, the onset functions themselves, and all associated
parameters and attributes.
- Significant expansion to the options available for data quality-checking;
now exposed to the user, giving the flexibility to select which to use.
- The STA/LTA onset function remains the default.
-
quakemigate.signal.pickers – significant re-write
- Extracted the embedded picking functions from the core QuakeScan class to
a new module,
quakemigrate.signal.pickers.
- General improvements to picking through a mix of fixes and features.
Major improvement to clarity/style.
- Created an Abstract Base Class – PhasePicker. This class can be used as a
base class for a class implementing an alternative phase picking
algorithm, while ensuring compliance with the embedded code in
QuakeMigrate.
- The user can provide a different onset function for phase picking using
GaussianPicker than they used for migration in locate().
- Bug fixes related to calculating the pick threshold; new option to use
the median absolute deviation of the noise, rather than a percentile.
See #116.
- Fitting a 1-D Gaussian to the phase onset function remains the default
method of phase picking.
-
quakemigate.signal.trigger
- Add dynamic trigger threshold method based on the median absolute
deviation, a robust statistical estimator that is insensitive to extreme
outliers. See #59.
- Added the ability to trigger events restricted to a specific region of
the grid (specified as geographic coordinates, and illustrated on the
trigger summary plot).
- Numerous bug-fixes related to the handling of overlapping triggers.
- Fix an indexing bug in trigger that caused the last event to be missed if
it was a single sample in length.
-
quakemigrate.signal.local_mag – new! See #71
- A comprehensive suite of codes for local earthquake magnitude calculation
by measuring displacement amplitudes from Wood-Anderson simulated
seismograms.
- This can optionally be used as part of a locate run to automatically
output ML estimates for each located event.
- General changes
- Update to various class attributes. Deprecation warnings + internal
attribute re-mappings have been included to ease the transition.
- Add additional examples (Rutford icequakes + Iceland dike intrusion). This
includes a script that performs data download from IRIS through an FDSN
client. See #105.
- Option to locate events from a user-provided triggered event file, as well
as the existing functionality to automatically read triggers between two
timestamps from the default output directory structure. See #53.
- Re-write
setup.py to automatically build the C extension library and link
it to the rest of the package. Should be more robust on different
platforms. Functions to read .dll or .so files (depending on operating
system) have been added to automatically load the correct linked library.
See #84.
- Add a system of module imports through
__init__.py files to reduce the
verbosity of input statements.
- New, intuitive directory structure for outputs, allowing straightforward
batch processing of data archives. See #68.
- Option to run trigger() multiple times from the same detect() output by
using different run sub-names. Also incorporated into the functions used by
locate() to read triggered event files.
- Add readthedocs documentation with sphinx. Here we can host the
documentation for the source code, instructions on installation, and
tutorials on how to use the package.
- The internal reference frame has Z being positive down (the depth frame).
Station elevations in the station input file are in the positive up
(elevation/natural frame) and converted internally.
- More information on intermediate results is retained in the final output
files. For example, the coalescence and normalised coalescence values for a
triggered event, along with which value it was triggered against.
- Added tests based on the "Iceland Icequake" and "Volcanotectonic_Iceland"
example use-cases to veryify correct operation ofter installation.
- Added Continuous Integration (Travis CI) allow us to catch breaking
issues before new features/fixes are merged and, in particular, should
help us keep on top of changes related to upstream changes to
dependencies.
- License: QuakeMigrate v1.0.0 is released under the GPLv3 license.
- Optimisations
- Optimise compute by changing the flags passed to the the compiler. Bumped
more of the compute() method to the C library to maximise efficiency.
See a9ffdb6
- Moved to logging with the native Python logging module, which allows for
writing logs to file as well as stdout in a more concise manner. See #81
Thanks!
Thank you to all those who have contributed to this release, whether by writing
code, reporting bugs, or suggesting new features and improvements! This
includes, but is not limited to (listed alphabetically):
- Pascal Audet
- Vivek Babu
- Conor Bacon
- Paul Derand
- GitHub user @fontiela
- Miriam Gauntlett
- Amy Gilligan
- Tim Greenfield
- Thomas Hudson
- Junior Kimata
- Ian Lee
- Andrew Owen
- Miriam Reiss
- Daniel Roberts
- Charlie Schoonman
- Nate Stevens
- Jonathan Smith
- GitHub user @bvicic
- GitHub user @SeisVincent
- Tom Winder