Documentation update #92

tmgreenfield1101 · 2020-07-27T15:44:37Z

An update to the tutorial section of the documentation. Included is a new "detect" tutorial.

First stages of generatign tutorials. Added the Archive one from a branh Conor hasd made and a new detect one

hemmelig

In addition to the comments:

There is already a PR submitted for the Archive tutorial. Delete the file from this PR.

There's a .swp file included - please remove this.

In order for this to be parsed into the documentation, you will need to add an entry to the tutorials.rst file (see existing example).

Other than that, this is a great addition! If you could ensure the read/display code works as expected for the Onset inspection, that would be great.

hemmelig · 2020-07-27T16:48:39Z

docs/tutorials/detect.rst

+
+You will need a semi-continuous waveform archive organised in a known way (see `Archive` tutorial), a travel time LUT (as generated in the previous tutorial) and a station file (as used to generate the LUT). You will also need to choose a location to store your results and a name for your run. QuakeMigrate will automatically generate an output structure to store all your results and place this in a folder in your chosen location named as the run name. You may well run QuakeMigrate many times before you reach the final set of parameter values which produce the best results. It is therefore important to choose a clear and documented run-naming-scheme.
+
+.. note:: Your run name and directory does not have to be the same for the three QuakeMigrate stages (`detect`, `trigger` and `locate`).


Not true - each stage will look for info from the previous stage with a consistent naming scheme. It is possible to run trigger with different subnames (and subsequently locate).

hemmelig · 2020-07-27T17:10:03Z

docs/tutorials/detect.rst

+Decimation of the LUT
+===========================
+
+To reduce computation time the decimation functionality of the LUT can be used. This reduces the number of nodes at which the coalescence is calculated resulting in a spatially low-pass filtered coalescence function. This is reasonable when we use the data for earthquake detection, but should be carefully considered if the locations output from a decimated grid are to be relied upon. 


I would perhaps like to add some discussion here about the issues of over decimation - can lead to mis-migration of onset functions. Decimation (and choice of node spacing more generally) should be chosen carefully against the expected sharpness of the onset functions (related to data quality/dominant period of signals). We have a simple idea of how to mitigate the impact this has, using a boxcar filter, but this is yet to be implemented.

hemmelig · 2020-07-27T17:18:19Z

docs/tutorials/detect.rst

+QuakeMigrate transforms your waveform data using two preprocessing operations before migration and stacking. These are a bandpass filter and transformation into an onset function. 
+
+
+The onset function should (if correctly specified) peak at the arrival time of a seismic phase. This function acts to simplify the seismic wavefield recorded by your instruments so the migration and stacking process work more reliably with noisy data or inaccurate velocity models. The correct choice of bandpass filters maximises the signal-to-noise ratio of your desired arrivals thereby maximising the coalescence value of any migrated earthquake.


Also, critically, extracts probabilistic 'information', which is one of the cornerstones of the method. When the Onset tutorial is written, can just refer the user there.

hemmelig · 2020-07-27T17:20:13Z

docs/tutorials/detect.rst

+    from quakemigrate.signal.onset import STALTAOnset
+    onset = STALTAOnset(position="classic")
+
+The STALTA function is the ratio between the average value in a short window to the average value in a longer window. In theory, if your window lengths are well-chosen, this function should peak at the arrival time of a seismic phase. The `STALTAOnset` function that ships with QuakeMigrate takes a single keyword argument which specifies the window position relative to the reference point (see image below).


Good to include here the exact words behind the initialism

hemmelig · 2020-07-27T17:25:01Z

docs/tutorials/detect.rst

+
+.. image:: img/waveform.png
+
+Using the `classic` argument will reproduce the `classic_sta_lta` from obspy (https://docs.obspy.org/packages/autogen/obspy.signal.trigger.classic_sta_lta.html) where both windows are behind the current timestamp. This is the more usual formulation as it is causal (i.e. doesn't rely on future data to generate the value at a particular time). In contrast, the `centred` argument will place the short window ahead of the current timestamp. This will maximise the signal-to-noise ratio. 


It currently uses the ObsPy function - I've rewritten both of the functions into C, pending a PR to merge them in.

More to it than just maximising the snr - the windows are also then more statistically independent, at the cost of being less stable. In fact, good to mention here that the classic positioning is more stable in the presence of non-seismic noise - signal offsets due to recording issues etc.

docs/tutorials/detect.rst

hemmelig · 2020-07-27T19:26:19Z

docs/tutorials/detect.rst

+
+    st[0].plot()
+
+By storing the data as miniSEED files, we not only make it easy to plot and manipulate the data using python libraries through obspy. We also can use miniSEEDs impressive compression routines to effciently store large volumes of data. To access this, we store values in the scanmseed object as integers. To return the values stored in the `scanmseed` object to the real values, divide the coalesence traces by 5 and the X, and Y traces by 6. The depth (Z trace) is stored to the nearest millimetre, the exact number to divide the output by will depend on your units.


On your choice of units for the lookup table.

tmgreenfield1101 · 2020-07-28T08:23:39Z

OK - had thought it would be more helpful to have them in one PR. I'll do that

hmm - thought I had not added that - will do

OK

docs/tutorials/detect.rst

Deleting swp file.

…t size

…d1101/QuakeMigrate into documentation_update

Development

A new example which includes grabbing data from IRIS and magnitudes Small changes to the creation of plots. Reduces the physical size of each generated figure to make printing and viewing easier

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

hemmelig · 2021-01-02T12:39:44Z

Some of this PR has been extracted and re-submitted as part of #119. The Ethiopia example remains - it is probably worth extracting this and submitting a standalone PR, but with the Iceland dyke intrusion example, which covers most aspects of the package (namely magnitudes), this is not critical.

tmgreenfield1101 added 4 commits July 23, 2020 19:57

Added new archive and detect tutorial

f5e9061

First stages of generatign tutorials. Added the Archive one from a branh Conor hasd made and a new detect one

update to the detect docs

de2755e

update to detect

3b554ae

detect update

88429e1

tmgreenfield1101 requested review from hemmelig and TomWinder July 27, 2020 15:45

hemmelig reviewed Jul 27, 2020

View reviewed changes

hemmelig reviewed Jul 28, 2020

View reviewed changes

tmgreenfield1101 and others added 21 commits July 28, 2020 16:04

Delete archive.rst

33ab6be

Delete .detect.py.swp

201d0f6

Deleting swp file.

New example inspired by Ethiopia and new plots which have smaller fon…

de01df3

…t size

Merge branch 'documentation_update' of https://github.com/tmgreenfiel…

003a6c6

…d1101/QuakeMigrate into documentation_update

Merge pull request #1 from QuakeMigrate/development

b3c37a7

Development

Merge branch 'documentation_update' into development

78ee8d2

Merge pull request #2 from tmgreenfield1101/development

ef29368

Development

A quick fix to the network problem which works through each stage.

1d304a2

A new example which includes grabbing data from IRIS and magnitudes Small changes to the creation of plots. Reduces the physical size of each generated figure to make printing and viewing easier

Update docs/tutorials/detect.rst

26bcff2

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

2e0a3a4

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

115039a

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

adfff16

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

1f34d48

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

c7d9fdd

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

6e2df0a

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

0fe9f4a

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

2ea130c

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

cca0398

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

76514a0

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

aa9a8d8

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

0110614

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

tmgreenfield1101 and others added 18 commits August 3, 2020 16:31

Update docs/tutorials/detect.rst

a832a2e

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

110d6a9

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

361d323

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

9d93d76

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

ec85d19

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

1fc6332

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

17175e4

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

9d7c275

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

bb1e5e9

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

798a6d9

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

a25a13b

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

6f9d443

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

ae72542

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

5bcb181

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update iceland_trigger.py

8c69fba

Update rutford_trigger.py

672af9c

Update docs/tutorials/detect.rst

97501a2

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Update docs/tutorials/detect.rst

6422e17

Co-authored-by: Conor Bacon <conor.bacon@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation update #92

Documentation update #92

tmgreenfield1101 commented Jul 27, 2020

hemmelig left a comment

hemmelig Jul 27, 2020

hemmelig Jul 27, 2020

hemmelig Jul 27, 2020

hemmelig Jul 27, 2020

hemmelig Jul 27, 2020

hemmelig Jul 27, 2020

tmgreenfield1101 commented Jul 28, 2020

hemmelig commented Jan 2, 2021


		You will need a semi-continuous waveform archive organised in a known way (see `Archive` tutorial), a travel time LUT (as generated in the previous tutorial) and a station file (as used to generate the LUT). You will also need to choose a location to store your results and a name for your run. QuakeMigrate will automatically generate an output structure to store all your results and place this in a folder in your chosen location named as the run name. You may well run QuakeMigrate many times before you reach the final set of parameter values which produce the best results. It is therefore important to choose a clear and documented run-naming-scheme.

		.. note:: Your run name and directory does not have to be the same for the three QuakeMigrate stages (`detect`, `trigger` and `locate`).

		QuakeMigrate transforms your waveform data using two preprocessing operations before migration and stacking. These are a bandpass filter and transformation into an onset function.


		The onset function should (if correctly specified) peak at the arrival time of a seismic phase. This function acts to simplify the seismic wavefield recorded by your instruments so the migration and stacking process work more reliably with noisy data or inaccurate velocity models. The correct choice of bandpass filters maximises the signal-to-noise ratio of your desired arrivals thereby maximising the coalescence value of any migrated earthquake.


		.. image:: img/waveform.png

		Using the `classic` argument will reproduce the `classic_sta_lta` from obspy (https://docs.obspy.org/packages/autogen/obspy.signal.trigger.classic_sta_lta.html) where both windows are behind the current timestamp. This is the more usual formulation as it is causal (i.e. doesn't rely on future data to generate the value at a particular time). In contrast, the `centred` argument will place the short window ahead of the current timestamp. This will maximise the signal-to-noise ratio.


		st[0].plot()

		By storing the data as miniSEED files, we not only make it easy to plot and manipulate the data using python libraries through obspy. We also can use miniSEEDs impressive compression routines to effciently store large volumes of data. To access this, we store values in the scanmseed object as integers. To return the values stored in the `scanmseed` object to the real values, divide the coalesence traces by 5 and the X, and Y traces by 6. The depth (Z trace) is stored to the nearest millimetre, the exact number to divide the output by will depend on your units.

Documentation update #92

Are you sure you want to change the base?

Documentation update #92

Conversation

tmgreenfield1101 commented Jul 27, 2020

hemmelig left a comment

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

hemmelig Jul 27, 2020

Choose a reason for hiding this comment

tmgreenfield1101 commented Jul 28, 2020

hemmelig commented Jan 2, 2021