marcel/pylot
3
0
Fork 0
Code Issues 7 Pull Requests 1 Releases Wiki Activity

Fix errors, add picking window description

Browse Source
This commit is contained in:
Darius Arnold 2018-10-23 11:47:02 +02:00
parent 86035d3cd6
commit b01c15d755
7 changed files with 79 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/gui.md
View File

@ -31,6 +31,7 @@
- [2. Wadati check](#2-wadati-check) - [2. Wadati check](#2-wadati-check)
- [Comparison between automatic and manual picks](#comparison-between-automatic-and-manual-picks) - [Comparison between automatic and manual picks](#comparison-between-automatic-and-manual-picks)
- [Export and Import of automatic picks](#export-and-import-of-automatic-picks) - [Export and Import of automatic picks](#export-and-import-of-automatic-picks)
- [Location determination](#location-determination)
- [FAQ](#faq) - [FAQ](#faq)
# PyLoT GUI # PyLoT GUI
@ -43,10 +44,10 @@ After opening PyLoT for the first time, the setup routine asks for the following
Questions: Questions:
1. Full Name 1. Full Name
2. Authority: Enter authority/instituiton name 2. Authority: Enter authority/institution name
3. Format: Enter output format (*.xml, *.cnv, *.obs) 3. Format: Enter output format (*.xml, *.cnv, *.obs)
TODO: explain what these things mean, where they are used [//]: <> (TODO: explain what these things mean, where they are used)
## Main Screen ## Main Screen
@ -63,6 +64,7 @@ Click on any trace to open the stations [picking window](#picking-window), where
<img src=images/gui/pylot-waveform-plot.png alt="A Waveform Plot showing traces of one event"> <img src=images/gui/pylot-waveform-plot.png alt="A Waveform Plot showing traces of one event">
Above the traces the currently displayed event can be selected.
In the bottom bar information about the trace under the mouse cursor is shown. This information includes the station name (station), the absolute UTC time (T) of the point under the mouse cursor and the relative time since the first trace start in seconds (t) as well as a trace count. In the bottom bar information about the trace under the mouse cursor is shown. This information includes the station name (station), the absolute UTC time (T) of the point under the mouse cursor and the relative time since the first trace start in seconds (t) as well as a trace count.
#### Mouse view controls #### Mouse view controls
@ -81,6 +83,8 @@ Press right mouse button and click "View All" from the context menu to reset the
#### Buttons #### Buttons
[//]: <> (Hack: We need these invisible spaces to add space to the first column, otherwise )
Icon &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Description Icon &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Description
--- | --- --- | ---
<img src="../icons/newfile.png" alt="Create new project" width="64" height="64"> | Create a new project, for more information about projects see [Projects and Events](#projects-and-events). <img src="../icons/newfile.png" alt="Create new project" width="64" height="64"> | Create a new project, for more information about projects see [Projects and Events](#projects-and-events).
@ -91,7 +95,7 @@ Icon &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp
<img src="../icons/openpick.png" alt="Load event information" width="64" height="64"> | Load picks/origins from disk into the currently displayed event. If a pick already exists for a station, the one from file will overwrite the existing one. <img src="../icons/openpick.png" alt="Load event information" width="64" height="64"> | Load picks/origins from disk into the currently displayed event. If a pick already exists for a station, the one from file will overwrite the existing one.
<img src="../icons/openpicks.png" alt="Load information for all events" width="64" height="64"> | Load picks/origins for all events of the current project. PyLoT searches for files within the directory of the event and tries to load them for that event. For this function to work, the files containing picks/origins have to be named as described in [Event folder structure](#event-folder-structure). If a pick already exists for a station, the one from file will overwrite the existing one. <img src="../icons/openpicks.png" alt="Load information for all events" width="64" height="64"> | Load picks/origins for all events of the current project. PyLoT searches for files within the directory of the event and tries to load them for that event. For this function to work, the files containing picks/origins have to be named as described in [Event folder structure](#event-folder-structure). If a pick already exists for a station, the one from file will overwrite the existing one.
<img src="../icons/savepicks.png" alt="Save picks" width="64" height="64"> | Save event information such as picks and origin to file. You will be asked to select a directory in which this information should be saved. <img src="../icons/savepicks.png" alt="Save picks" width="64" height="64"> | Save event information such as picks and origin to file. You will be asked to select a directory in which this information should be saved.
<img src="../icons/openloc.png" alt="Load location information" width="64" height="64"> | <img src="../icons/openloc.png" alt="Load location information" width="64" height="64"> | Load location information from disk,
<img src="../icons/Matlab_PILOT_icon.png" alt="Load legacy information" width="64" height="64"> | Load event information from a previous, MatLab based PILOT version. <img src="../icons/Matlab_PILOT_icon.png" alt="Load legacy information" width="64" height="64"> | Load event information from a previous, MatLab based PILOT version.
<img src="../icons/key_Z.png" alt="Display Z" width="64" height="64"> | Display Z component of streams in waveform plot. <img src="../icons/key_Z.png" alt="Display Z" width="64" height="64"> | Display Z component of streams in waveform plot.
<img src="../icons/key_N.png" alt="Display N" width="64" height="64"> | Display N component of streams in waveform plot. <img src="../icons/key_N.png" alt="Display N" width="64" height="64"> | Display N component of streams in waveform plot.
@ -99,40 +103,56 @@ Icon &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp
<img src="../icons/tune.png" alt="Tune Autopicker" width="64" height="64"> | Open the [Tune Autopicker window](#tuning). <img src="../icons/tune.png" alt="Tune Autopicker" width="64" height="64"> | Open the [Tune Autopicker window](#tuning).
<img src="../icons/autopylot_button.png" alt="" width="64" height="64"> | Opens a window that allows starting the autopicker for all events ([Production run of the AutoPicker](#production-run-of-the-autopicker)). <img src="../icons/autopylot_button.png" alt="" width="64" height="64"> | Opens a window that allows starting the autopicker for all events ([Production run of the AutoPicker](#production-run-of-the-autopicker)).
<img src="../icons/compare_button.png" alt="Comparison" width="64" height="64"> | Compare automatic and manual picks, only available if automatic and manual picks for an event exist. See [Comparison between automatic and manual picks](#comparison-between-automatic-and-manual-picks). <img src="../icons/compare_button.png" alt="Comparison" width="64" height="64"> | Compare automatic and manual picks, only available if automatic and manual picks for an event exist. See [Comparison between automatic and manual picks](#comparison-between-automatic-and-manual-picks).
<img src="../icons/locate_button.png" alt="Locate event" width="64" height="64"> | Run a location routine (NonLinLoc) as configured in the settings on the picks. <img src="../icons/locate_button.png" alt="Locate event" width="64" height="64"> | Run a location routine (NonLinLoc) as configured in the settings on the picks. See [Location determination](#location-determination).
### Array Map ### Array Map
The array map will display a color diagram to allow a visual check of the consistency of picks across multiple stations. This works by calculating the time difference of every onset to the earliest onset. Then isolines are drawn between stations with the same time difference and the areas between isolines are colored. The array map will display a color diagram to allow a visual check of the consistency of picks across multiple stations. This works by calculating the time difference of every onset to the earliest onset. Then isolines are drawn between stations with the same time difference and the areas between isolines are colored.
The result should resemble a color gradient as the wavefront rolls over the network area. Stations where picks are earlier/later than their neighbours can be reviewed by clicking on them, which opens the picking window. The result should resemble a color gradient as the wavefront rolls over the network area. Stations where picks are earlier/later than their neighbours can be reviewed by clicking on them, which opens the [picking window](#picking-window).
Above the Array Map the picks that are used to create the map can be customized. Above the Array Map the picks that are used to create the map can be customized.
The phase of picks that should be used can be selected, which allows checking the consistency of the P- and S-phase seperately. The phase of picks that should be used can be selected, which allows checking the consistency of the P- and S-phase separately.
Additionally the pick type can be set to manual, automatic or hybrid, meaning display only manual picks, automatic picks or only display automatic picks for stations where there are no manual ones. Additionally the pick type can be set to manual, automatic or hybrid, meaning display only manual picks, automatic picks or only display automatic picks for stations where there are no manual ones.
![Array Map](images/gui/arraymap-example.png "Array Map") ![Array Map](images/gui/arraymap-example.png "Array Map")
*Array Map for an event at the Northern Mid Atlantic Ridge, between North Africa and Mexico (Lat. 22.58, Lon. -45.11). The wavefront moved from west to east over the network area (Alps and Balcan region), with the earliest onsets in blue in the west.* *Array Map for an event at the Northern Mid Atlantic Ridge, between North Africa and Mexico (Lat. 22.58, Lon. -45.11). The wavefront moved from west to east over the network area (Alps and Balcan region), with the earliest onsets in blue in the west.*
To be able to display an array map PyLoT needs to load an inventory file, where the metadata of seismic stations is kept. For more information see [Metadata](#adding-metadata). Additionally automatic or manual picks need to be loaded for the current event. To be able to display an array map PyLoT needs to load an inventory file, where the metadata of seismic stations is kept. For more information see [Metadata](#adding-metadata). Additionally automatic or manual picks need to exist for the current event.
### Eventlist ### Eventlist
The eventlist displays event parameters. The displayed parameters are saved in the .xml file in the event folder. Events can be deleted from the project by pressing the red X in the leftmost column of the corresponding event. The eventlist displays event parameters. The displayed parameters are saved in the .xml file in the event folder. Events can be deleted from the project by pressing the red X in the leftmost column of the corresponding event.
<img src="images/gui/eventlist.png" alt="Eventlist">
Column | Description
--- | ---
Event | Full path to the events folder.
Time | Time of event.
Lat | Latitude in degrees of event location.
Lon | Longitude in degrees of event location.
Depth | Depth in km of event.
Mag | Magnitude of event.
[N] MP | Number of manual picks.
[N] AP | Number of automatic picks.
Tuning Set | Select whether this event is a Tuning event. See [Automatic Picking](#automatic-picking).
Test Set | Select whether this event is a Test event. See [Automatic Picking](#automatic-picking).
Notes | Free form text field for notes regarding this event. Text will be saved in the notes.txt file in the event folder.
## Usage ## Usage
### Projects and Events ### Projects and Events
PyLoT uses projects to categorize different seismic data. A project consists of one or multiple events. Events contain seismic traces from one or multiple stations. An event also contains further information, e.g. origin time, source parameters and automatic and manual picks. PyLoT uses projects to categorize different seismic data. A project consists of one or multiple events. Events contain seismic traces from one or multiple stations. An event also contains further information, e.g. origin time, source parameters and automatic as well as manual picks.
Projects are used to group events which should be analyzed together. A project could contain all events from a specific region within a timeframe of interest or all recorded events of a seismological experiment. Projects are used to group events which should be analysed together. A project could contain all events from a specific region within a timeframe of interest or all recorded events of a seismological experiment.
### Event folder structure ### Event folder structure
PyLoT expects the following folder structure for seismic data: PyLoT expects the following folder structure for seismic data:
* Every event should be in it's own folder with the following naming scheme for the folders: * Every event should be in it's own folder with the following naming scheme for the folders:
``e[id].[doy].[yy]``, where ``[id]`` is a four-digit numerical id increasing from 0001, ``[doy]`` the three digit day of year and ``[yy]`` the last two digits of the year of the event. This structure has to be created by the user of PyLoT manually. ``e[id].[doy].[yy]``, where ``[id]`` is a four-digit numerical id increasing from 0001, ``[doy]`` the three digit day of year and ``[yy]`` the last two digits of the year of the event. This structure has to be created by the user of PyLoT manually.
* These folders should contain the seismic data for their event as ``.mseed`` or other supported filetype TODO: LINK HERE * These folders should contain the seismic data for their event as ``.mseed`` or other supported filetype
* All automatic and manual picks should be in an ``.xml`` file in their event folder. PyLoT saves picks in this file. This file does not have to be added manually unless there are picks to be imported. The format used to save picks is QUAKEML. * All automatic and manual picks should be in an ``.xml`` file in their event folder. PyLoT saves picks in this file. This file does not have to be added manually unless there are picks to be imported. The format used to save picks is QUAKEML.
Picks are saved in a file with the same filename as the event folder with ``PyLoT_`` prepended. Picks are saved in a file with the same filename as the event folder with ``PyLoT_`` prepended.
* The file ``notes.txt`` is used for saving analysts comments. Everything saved here will be displayed in the 'Notes' column of the eventlist. * The file ``notes.txt`` is used for saving analysts comments. Everything saved here will be displayed in the 'Notes' column of the eventlist.
@ -141,19 +161,19 @@ Picks are saved in a file with the same filename as the event folder with ``PyLo
PyLoT GUI starts with an empty project. To add events, use the add event data button. Select one or multiple folders containing events. PyLoT GUI starts with an empty project. To add events, use the add event data button. Select one or multiple folders containing events.
TODO: explain _Directories: Root path, Data path, Database path_ [//]: <> (TODO: explain _Directories: Root path, Data path, Database path_)
### Saving projects ### Saving projects
Save the current project from the menu with File->Save project or File->Save project as. Save the current project from the menu with File->Save project or File->Save project as.
PyLoT uses ``.plp`` files to save project information. This file format is not interchangable between different versions of Python interpreters. PyLoT uses ``.plp`` files to save project information. This file format is not interchangeable between different versions of Python interpreters.
Saved projects contain the automatic and manual picks. Seismic trace data is not included into the ``.plp`` file, but read from its location used when saving the file. Saved projects contain the automatic and manual picks. Seismic trace data is not included into the ``.plp`` file, but read from its location used when saving the file.
### Adding metadata ### Adding metadata
TODO: Add picture of metadata "manager" when it is done [//]: <> (TODO: Add picture of metadata "manager" when it is done)
PyLoT can handle ``.dless``, ``.xml``, ``.resp`` and ``.dseed`` file formats for Metada. Metadata files stored on disk can be added to a project by clicking *Edit*->*Manage Inventories*. This opens up a window where the folders that contain metadata files can be selected. PyLoT will then search these files for the station names when it needs the information. PyLoT can handle ``.dless``, ``.xml``, ``.resp`` and ``.dseed`` file formats for Metadata. Metadata files stored on disk can be added to a project by clicking *Edit*->*Manage Inventories*. This opens up a window where the folders which contain metadata files can be selected. PyLoT will then search these files for the station names when it needs the information.
# Picking # Picking
@ -170,28 +190,30 @@ To create manual picks, you will need to open or create a project that contains
Open the picking window of a station by leftclicking on any trace in the waveform plot. Here you can create manual picks for the selected station. Open the picking window of a station by leftclicking on any trace in the waveform plot. Here you can create manual picks for the selected station.
<img src="images/gui/picking/pickwindow.png" alt="Picking window">
*Picking window of a station.*
#### Picking Window Settings #### Picking Window Settings
Icon | Shortcut | Menu Alternative | Description Icon | Shortcut | Menu Alternative | Description
---|---|---|--- ---|---|---|---
<img src="../icons/filter_p.png" alt="Filter P" width="64" height="64"> | 1 or p | Filter->Apply P Filter | Filter all channels according to the options specified in Filter parameter, P Filter section. <img src="../icons/filter_p.png" alt="Filter P" width="64" height="64"> | p | Filter->Apply P Filter | Filter all channels according to the options specified in Filter parameter, P Filter section.
<img src="../icons/filter_s.png" alt="Filter S" width="64" height="64"> | 5 or s | Filter->Apply S Filter | Filter all channels according to the options specified in Filter parameter, S Filter section. <img src="../icons/filter_s.png" alt="Filter S" width="64" height="64"> | s | Filter->Apply S Filter | Filter all channels according to the options specified in Filter parameter, S Filter section.
<img src="../icons/key_A.png" alt="Filter Automatically" width="64" height="64"> | Ctrl + a | Filter->Automatic Filtering | Select the correct filter option (P, S) depending on the selected phase to be picked. <img src="../icons/key_A.png" alt="Filter Automatically" width="64" height="64"> | Ctrl + a | Filter->Automatic Filtering | If enabled, automatically select the correct filter option (P, S) depending on the selected phase to be picked.
![desc](images/gui/picking/phase_selection.png "Phase selection") | 1 or 5 | Picks->P or S | Select phase to pick. ![desc](images/gui/picking/phase_selection.png "Phase selection") | 1 (P) or 5 (S) | Picks->P or S | Select phase to pick. If Automatic Filtering is enabled, this will apply the appropriate filter depending on the phase.
![Zoom into](../icons/zoom_in.png "Zoom into waveform") | - | - | Zoom into waveform. ![Zoom into](../icons/zoom_in.png "Zoom into waveform") | - | - | Zoom into waveform.
![Reset zoom](../icons/zoom_0.png "Reset zoom") | - | - | Reset zoom to default view. ![Reset zoom](../icons/zoom_0.png "Reset zoom") | - | - | Reset zoom to default view.
![Delete picks](../icons/delete.png "Delete picks") | - | - | Delete all manual picks on this station. ![Delete picks](../icons/delete.png "Delete picks") | - | - | Delete all manual picks on this station.
![Rename a phase](../icons/sync.png "Rename a phase") | - | - | Click this button and then the picked phase to rename it. ![Rename a phase](../icons/sync.png "Rename a phase") | - | - | Click this button and then the picked phase to rename it.
![Continue](images/gui/picking/continue.png "Continue") | - | - | If checked, after accepting the manual picks for this station with 'OK', the picking window for the next station will be opened. This option is useful for fast manual picking of a complete event. ![Continue](images/gui/picking/continue.png "Continue with next station") | - | - | If checked, after accepting the manual picks for this station with 'OK', the picking window for the next station will be opened. This option is useful for fast manual picking of a complete event.
Estimated onsets | - | - | Show the theoretical onsets for this station. Needs metadata and origin information. Estimated onsets | - | - | Show the theoretical onsets for this station. Needs metadata and origin information.
Compare to channel | - | - | Select a data channel to compare against. The selected channel will be displayed in the picking window behind every channel to compare signal correlation. Compare to channel | - | - | Select a data channel to compare against. The selected channel will be displayed in the picking window behind every channel allowing the analyst to visually compare signal correlation between different channels.
Scale by | - | - | Normalized means every channel is scaled to it maximum seperately. If a channel is selected here, all channels will be scaled with regards to this channel. Scaling | - | - | Individual means every channel is scaled to its own maximum. If a channel is selected here, all channels will be scaled relatively to this channel.
Menu Command | Shortcut | Description Menu Command | Shortcut | Description
---|---|--- ---|---|---
P Channels and S Channels | - | Select which channels should be treated as P or S channels during picking. When picking a phase, only the corresponding channels will be shown during the precise pick P Channels and S Channels | - | Select which channels should be treated as P or S channels during picking. When picking a phase, only the corresponding channels will be shown during the precise pick. Normally, the Z channel should be selected for the P phase and the N and E channel for the S phase.
TODO: is the above table done?
### Filtering ### Filtering
@ -199,31 +221,30 @@ Access the Filter options by pressing Ctrl+f on the Waveform plot or by the menu
<img src=images/gui/pylot-filter-options.png> <img src=images/gui/pylot-filter-options.png>
Here you are able to select filter type, order and frequencies for the P and S pick seperately. These settings are used in the GUI for filtering for displaying the waveform data and during manual picking. The values used by PyLoT for automatic picking are displayed next to the manual values. They can be changed in the [Tune Autopicker dialog](#tuning). Here you are able to select filter type, order and frequencies for the P and S pick separately. These settings are used in the GUI for displaying the filtered waveform data and during manual picking. The values used by PyLoT for automatic picking are displayed next to the manual values. They can be changed in the [Tune Autopicker dialog](#tuning).
A green value automatic value means the automatic and manual filter parameter is configured the same, read means they are configured differently. A green value automatic value means the automatic and manual filter parameter is configured the same, red means they are configured differently.
By toggling the "Overwrite filteroptions" checkmark you can set whether the manual precise/second pick uses the filter settings for the automatic picker (unchecked) or whether it uses the filter options in this dialog (checked). By toggling the "Overwrite filteroptions" checkmark you can set whether the manual precise/second pick uses the filter settings for the automatic picker (unchecked) or whether it uses the filter options in this dialog (checked).
To guarantee consistent picking results between automatic and manual picking it is recommended to use the same fiter settings for the determination of automatic and manual picks. To guarantee consistent picking results between automatic and manual picking it is recommended to use the same filter settings for the determination of automatic and manual picks.
### Export and Import of manual picks ### Export and Import of manual picks
#### Export #### Export
After the creation of manual picks they can either be save in the project file (see [Saving projects](#saving-projects)). Alternatively the picks can be exported by pressing the <img src="../icons/savepicks.png" alt="Save event information button" title="Save picks button" height=24 width=24> button above the waveform plot or in the menu File->Save event information (shortcut Ctrl+p). Select the event directory in which to save the file. The filename will be ``PyLoT_[event_folder_name].[filetype selected during first startup]``. TODO: Is the filetype during first startup selected for saving files? After the creation of manual picks they can either be saved in the project file (see [Saving projects](#saving-projects)). Alternatively the picks can be exported by pressing the <img src="../icons/savepicks.png" alt="Save event information button" title="Save picks button" height=24 width=24> button above the waveform plot or in the menu File->Save event information (shortcut Ctrl+p). Select the event directory in which to save the file. The filename will be ``PyLoT_[event_folder_name].[filetype selected during first startup]``.
You can rename and copy this file, but PyLoT will then no longer be able to automatically recognize the correct picks for an event and the file will have to be manually selected when loading. You can rename and copy this file, but PyLoT will then no longer be able to automatically recognize the correct picks for an event and the file will have to be manually selected when loading.
#### Import #### Import
To import previously saved picks press the <img src="../icons/openpick.png" alt="Load event information button" width="24" height="24"> button and select the file to load. You are asked to save the current state of your current project if you have not done so before. You can continue without saving by pressing "Discard". To import previously saved picks press the <img src="../icons/openpick.png" alt="Load event information button" width="24" height="24"> button and select the file to load. You will be asked to save the current state of your project if you have not done so before. You can continue without saving by pressing "Discard". This does not delete any information from your project, it just means that no project file is saved before the changes of importing picks are applied.
PyLoT will automaticall load files named after the scheme it uses when saving picks, described in the paragraph above. If it cant file any aptly named files, a file dialog will open and you can select the file you wish to load. PyLoT will automatically load files named after the scheme it uses when saving picks, described in the paragraph above. If it can't find any matching files, a file dialogue will open and you can select the file you wish to load.
If you see a warning "Mismatch in event identifiers" and are asked whether to continue loading the picks, this means that PyLoT doesn't recognize the picks in the file as belonging to this specific event. They could have either been saved under a different installation of PyLoT but with the same waveform data, which means they are still compatible and you can continue loading them. Or they could be picks from a different event, in which case loading them is not reccommended. If you see a warning "Mismatch in event identifiers" and are asked whether to continue loading the picks, this means that PyLoT doesn't recognize the picks in the file as belonging to this specific event. They could have either been saved under a different installation of PyLoT but with the same waveform data, which means they are still compatible and you can continue loading them. Or they could be picks from a different event, in which case loading them is not recommended.
## Automatic Picking ## Automatic Picking
The general workflow for automatic picking is as following: The general workflow for automatic picking is as following:
- After setting up the project by loading waveforms and metadata, the right parameters for the autopicker have to be determined - After setting up the project by loading waveforms and optionally metadata, the right parameters for the autopicker have to be determined
- This [tuning](#tuning) is done for single stations with immediate graphical feedback of all picking results - This [tuning](#tuning) is done for single stations with immediate graphical feedback of all picking results
- Afterwards the autopicker can be run for all or a subset of events from the project - Afterwards the autopicker can be run for all or a subset of events from the project
@ -243,22 +264,17 @@ View of a station in the Tune Autopicker window.
4. These tabs are used to select the current view. __Traces Plot__ contains a plot of the stations traces, where manual picks can be created/edited. __Overview__ contains graphical results of the automatic picking process. The __P and S tabs__ contain the automatic picking results of the P and S phase, while __log__ contains a useful text output of automatic picking. 4. These tabs are used to select the current view. __Traces Plot__ contains a plot of the stations traces, where manual picks can be created/edited. __Overview__ contains graphical results of the automatic picking process. The __P and S tabs__ contain the automatic picking results of the P and S phase, while __log__ contains a useful text output of automatic picking.
5. These buttons are used to load/save/reset settings for automatic picking. The parameters can be saved in PyLoT input files, which have the file ending *.in*. They are human readable text files, which can also be edited by hand. Saving the parameters allows you to load them again later, even on different machines. 5. These buttons are used to load/save/reset settings for automatic picking. The parameters can be saved in PyLoT input files, which have the file ending *.in*. They are human readable text files, which can also be edited by hand. Saving the parameters allows you to load them again later, even on different machines.
6. These menus control the behaviour of the creation of manual picks from the Tune Autopicker window. Picks allows to select the phase for which a manual pick should be created, Filter allows to filter waveforms and edit the filter parameters. P-Channels and S-Channels allow to select the channels that should be displayed when creating a manual P or S pick. 6. These menus control the behaviour of the creation of manual picks from the Tune Autopicker window. Picks allows to select the phase for which a manual pick should be created, Filter allows to filter waveforms and edit the filter parameters. P-Channels and S-Channels allow to select the channels that should be displayed when creating a manual P or S pick.
7. The first two buttons toggle wether the waveforms should be displayed filtered with the settings for manual P and S picks respectively. The next button toggles whether selecting a phase to pick also filters the waveform with the parameters for that phase. 7. This menu is the same as in the [Picking Window](#picking-window-settings), with the exception of the __Manual Onsets__ options. The __Manual Onsets__ buttons accepts or reject the manual picks created in the Tune Autopicker window, pressing accept adds them to the manual picks for the event, while reject removes them.
The next two buttons, __P__ and __S__ select the phase for manual picking. Then two buttons that control the zoom level follow. After that, the __red X__ button deletes all picks from this station. The green button to the right allows to rename a pick phase. 8. The traces plot in the centre allows creating manual picks and viewing the waveforms.
The __Manual Onsets__ accepts or reject the manual picks created in the Tune Autopicker window, pressing accept adds them to the manual picks for the event, while reject removes them.
When metadata is available for a station/event, the __Estimated Onsets__ plots theoretical arrival times.
The __Compare to channel__ allows to select a channel, whose traces are then displayed in the same plot as the other channels. TODO: What is that good for?
___Scaling__ allows select a trace to which all other values are scaled. By default every trace is scaled to its own maximum, but with this selection every trace will be scaled relatively to the selected trace.
8. The traces plot in the center allows creating manual picks and viewing the waveforms.
9. The parameters which influence the autopicking result are in the Main settings and Advanced settings tabs on the left side. For a description of all the parameters see the [tuning documentation](tuning.md). 9. The parameters which influence the autopicking result are in the Main settings and Advanced settings tabs on the left side. For a description of all the parameters see the [tuning documentation](tuning.md).
### Production run of the autopicker ### Production run of the autopicker
After the settings used during tuning give the desired results, the autopicker can be used on the complete dataset. To invoke the autopicker on the whole set of events, click the <img src=../icons/autopylot_button.png alt="Autopick button" title="Autopick button" height=32> button. After the settings used during tuning give the desired results, the autopicker can be used on the complete dataset. To invoke the autopicker on the whole set of events, click the <img src=../icons/autopylot_button.png alt="Autopick" title="Autopick" height=32> button.
### Evaluation of automatic picks ### Evaluation of automatic picks
PyLoT has to internal consistency checks for automatic picks that were determined for an event: PyLoT has two internal consistency checks for automatic picks that were determined for an event:
1. Jackknife check 1. Jackknife check
2. Wadati check 2. Wadati check
@ -268,13 +284,13 @@ The jackknife test in PyLoT checks the consistency of automatically determined P
The idea is, that picks that are close together in time should not influence the estimation of the variance much, while picks whose positions deviates from the norm influence the variance to a greater extent. If the estimated variance of a subset with a pick removed differs to much from the estimated variance of all picks, the pick that was removed from the subset will be marked as invalid. The idea is, that picks that are close together in time should not influence the estimation of the variance much, while picks whose positions deviates from the norm influence the variance to a greater extent. If the estimated variance of a subset with a pick removed differs to much from the estimated variance of all picks, the pick that was removed from the subset will be marked as invalid.
The factor by which picks are allowed to skew from the estimation of variance can be configured, it is called *jackfactor*, see [here](tuning.md#Pick-quality-control). The factor by which picks are allowed to skew from the estimation of variance can be configured, it is called *jackfactor*, see [here](tuning.md#Pick-quality-control).
Additionally, the deviation of picks from the median is checked. The median of all P-picks that passed the Jackknife test is calculated. Picks whose onset times deviate from the mean onset time by more than the *mdttolerance* are marked as invalid. Additionally, the deviation of picks from the median is checked. For that, the median of all P-picks that passed the Jackknife test is calculated. Picks whose onset times deviate from the mean onset time by more than the *mdttolerance* are marked as invalid.
<img src=images/gui/jackknife_plot.png title="Jackknife/Median test diagram"> <img src=images/gui/jackknife_plot.png title="Jackknife/Median test diagram">
*The result of both tests (Jackknife and Median) is shown in a diagram afterwards. The onset time is plotted against a running number of stations. Picks that failed either the Jackknife or the median test are colored red. The median is plotted as a green line.* *The result of both tests (Jackknife and Median) is shown in a diagram afterwards. The onset time is plotted against a running number of stations. Picks that failed either the Jackknife or the median test are colored red. The median is plotted as a green line.*
The Jackknife and median check are suitable to check for picks that are outside of the expected time window, where maybe another phase was picked. The Jackknife and median check are suitable to check for picks that are outside of the expected time window, for example, when a wrong phase was picked. It won't recognize picks that are in close proximity to the right onset which are just slightly to late/early.
#### 2. Wadati check #### 2. Wadati check
@ -286,7 +302,7 @@ The Wadati check checks the consistency of S picks. For this the SP-time, the ti
### Comparison between automatic and manual picks ### Comparison between automatic and manual picks
Every pick in PyLoT consists of an earliest possible, latest possible and most possible onset time. Every pick in PyLoT consists of an earliest possible, latest possible and most likely onset time.
The earliest and latest possible onset time characterize the uncertainty of a pick. The earliest and latest possible onset time characterize the uncertainty of a pick.
This approach is described in Diel, Kissling and Bormann (2012) - Tutorial for consistent phase picking at local to regional distances. This approach is described in Diel, Kissling and Bormann (2012) - Tutorial for consistent phase picking at local to regional distances.
These times are represented as a Probability Density Function (PDF) for every pick. These times are represented as a Probability Density Function (PDF) for every pick.
@ -313,18 +329,23 @@ To compare the automatic and manual picks between multiple stations of an event,
*The top right plot shows the standard deviation of the comparison PDFs for S picks.* *The top right plot shows the standard deviation of the comparison PDFs for S picks.*
*The bottom right plot shows the expected values of the comparison PDFs for S picks.* *The bottom right plot shows the expected values of the comparison PDFs for S picks.*
*The standard deviation plots show that most P picks have an uncertainty between 1 and 2 seconds, while S pick uncertainties have a much larger spread between 1 to 15 seconds.* *The standard deviation plots show that most P picks have an uncertainty between 1 and 2 seconds, while S pick uncertainties have a much larger spread between 1 to 15 seconds.*
*This means P picks have higher quality classes on average than S picks.*
*The expected values are largely negative, meaning that the algorithm tends to pick earlier than the analyst with the applied settings (Manual - Automatic).* *The expected values are largely negative, meaning that the algorithm tends to pick earlier than the analyst with the applied settings (Manual - Automatic).*
*The number of samples mentioned in the plots legends is the amount of station that have an automatic and a manual P pick.* *The number of samples mentioned in the plots legends is the amount of stations that have an automatic and a manual P pick.*
### Export and Import of automatic picks ### Export and Import of automatic picks
Picks can be saved in *.xml* format. Picks can be saved in *.xml* format.
# Location determination
To be added.
# FAQ # FAQ
Q: During manual picking the error "No channel to plot for phase ..." is displayed, and I am unable to create a pick. Q: During manual picking the error "No channel to plot for phase ..." is displayed, and I am unable to create a pick.
A: Select a channel that should be used for the corresponding phase in the Pickwindow. For further information read [Picking Window settings](#picking-window-settings). A: Select a channel that should be used for the corresponding phase in the Pickwindow. For further information read [Picking Window settings](#picking-window-settings).
Q: I see a warning "Mismatch in event identifiers" when loading picks from a file. Q: I see a warning "Mismatch in event identifiers" when loading picks from a file.
A: This means that PyLoT doesn't recognize the picks in the file as belonging to this specific event. They could have been saved under a different installation of PyLoT but with the same waveform data, which means they are still compatible and you can continue loading them or they could be the picks of a different event, in which case loading them is not reccommended A: This means that PyLoT doesn't recognize the picks in the file as belonging to this specific event. They could have been saved under a different installation of PyLoT but with the same waveform data, which means they are still compatible and you can continue loading them or they could be the picks of a different event, in which case loading them is not recommended.

BIN
docs/gui.pdf Normal file
View File

Binary file not shown.

BIN
docs/images/gui/eventlist.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 191 KiB

BIN
docs/images/gui/picking/pickwindow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

BIN
docs/images/picking.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 281 KiB

18
docs/tuning.md
View File

@ -1,6 +1,6 @@
# AutoPyLoT Tuning # AutoPyLoT Tuning
A description of the parameters used for determing automatic picks. A description of the parameters used for determining automatic picks.
## Filter parameters and cut times ## Filter parameters and cut times
@ -8,8 +8,8 @@ Parameters applied to the traces before picking algorithm starts.
Name | Description Name | Description
--- | --- --- | ---
*P Start*, *P Stop* | Define time interval relative to trace start time for CF calculation on vertical trace. Value is relative to theoretical onset time if 'Use TayPy' option is enabled in main settings of 'Tune Autopicker' dialog. *P Start*, *P Stop* | Define time interval relative to trace start time for CF calculation on vertical trace. Value is relative to theoretical onset time if 'Use TauPy' option is enabled in main settings of 'Tune Autopicker' dialogue.
*S Start*, *S Stop* | Define time interval relative to trace start time for CF calculation on horizontal traces. Value is relative to theoretical onset time if 'Use TayPy' option is enabled in main settings of 'Tune Autopicker' dialog. *S Start*, *S Stop* | Define time interval relative to trace start time for CF calculation on horizontal traces. Value is relative to theoretical onset time if 'Use TauPy' option is enabled in main settings of 'Tune Autopicker' dialogue.
*Bandpass Z1* | Filter settings for Butterworth bandpass applied to vertical trace for calculation of initial P pick. *Bandpass Z1* | Filter settings for Butterworth bandpass applied to vertical trace for calculation of initial P pick.
*Bandpass Z2* | Filter settings for Butterworth bandpass applied to vertical trace for calculation of precise P pick. *Bandpass Z2* | Filter settings for Butterworth bandpass applied to vertical trace for calculation of precise P pick.
*Bandpass H1* | Filter settings for Butterworth bandpass applied to horizontal traces for calculation of initial S pick. *Bandpass H1* | Filter settings for Butterworth bandpass applied to horizontal traces for calculation of initial S pick.
@ -38,9 +38,9 @@ Parameters used for determination of initial S pick
Name | Description Name | Description
--- | --- --- | ---
*tdet1h* | Length of time window in seconds in which AR params of the waveform are determined. *tdet1h* | Length of time window in seconds in which AR params of the waveform are determined.
*tpred1h* | Length of time window in seconds in which the waveform is predicted using the AR modell. *tpred1h* | Length of time window in seconds in which the waveform is predicted using the AR model.
*AICtsmoothS* | Average of samples in this time window is used for smoothing the AIC-CF. *AICtsmoothS* | Average of samples in this time window is used for smoothing the AIC-CF.
*pickwinS* | Time window in which the minimum in the AIC-CF in front of the maximum in the ARH cf is determined. *pickwinS* | Time window in which the minimum in the AIC-CF in front of the maximum in the ARH-CF is determined.
*checkwinS* | Time in front of the global maximum of the ARH-CF in which to search for a second local extrema. *checkwinS* | Time in front of the global maximum of the ARH-CF in which to search for a second local extrema.
*minfactorP* | Used with *checkwinS*. If a second local maximum is found, it has to be at least as big as the first maximum * *minfactorS*. *minfactorP* | Used with *checkwinS*. If a second local maximum is found, it has to be at least as big as the first maximum * *minfactorS*.
*tsignal* | Time window in seconds after the initial P pick used for determining signal amplitude. *tsignal* | Time window in seconds after the initial P pick used for determining signal amplitude.
@ -54,8 +54,8 @@ Parameters used for determination of precise P pick.
Name | Description Name | Description
--- | --- --- | ---
*Precalcwin* | Time window in seconds for recalculation of the HOS-CF. The new CF will be two times the size of *Precalcwin*, since it will be calculated from the intialpick to +/- *Precalcwin*. *Precalcwin* | Time window in seconds for recalculation of the HOS-CF. The new CF will be two times the size of *Precalcwin*, since it will be calculated from the initial pick to +/- *Precalcwin*.
*tsmoothP* | Average of samples in this time window will be used for smoothing the secod HOS-CF. *tsmoothP* | Average of samples in this time window will be used for smoothing the second HOS-CF.
*ausP* | Controls artificial uplift of samples during precise picking. A common local minimum of the smoothed and unsmoothed HOS-CF is found when the previous sample is larger or equal to the current sample times (1+*ausP*). *ausP* | Controls artificial uplift of samples during precise picking. A common local minimum of the smoothed and unsmoothed HOS-CF is found when the previous sample is larger or equal to the current sample times (1+*ausP*).
## Precise S pick ## Precise S pick
@ -69,7 +69,7 @@ Name | Description
*Srecalcwin* | Time window for recalculation of ARH-CF. New CF will be calculated from initial pick +/- *Srecalcwin*. *Srecalcwin* | Time window for recalculation of ARH-CF. New CF will be calculated from initial pick +/- *Srecalcwin*.
*tsmoothS* | Average of samples in this time window will be used for smoothing the second ARH-CF. *tsmoothS* | Average of samples in this time window will be used for smoothing the second ARH-CF.
*ausS* | Controls artificial uplift of samples during precise picking. A common local minimum of the smoothed and unsmoothed ARH-CF is found when the previous sample is larger or equal to the current sample times (1+*ausS*). *ausS* | Controls artificial uplift of samples during precise picking. A common local minimum of the smoothed and unsmoothed ARH-CF is found when the previous sample is larger or equal to the current sample times (1+*ausS*).
*pickwinS* | Time window around intial pick in which to look for a precise pick. *pickwinS* | Time window around initial pick in which to look for a precise pick.
## Pick quality control ## Pick quality control
@ -84,7 +84,7 @@ Name | Description
*minAICSSNR* | Initial S picks with a SNR below this value will be discarded. *minAICSSNR* | Initial S picks with a SNR below this value will be discarded.
*minsiglength*, *noisefacor*. *minpercent* | Parameters for checking signal length. In the time window of size *minsiglength* after the initial P pick *minpercent* of samples have to be larger than the RMS value. *minsiglength*, *noisefacor*. *minpercent* | Parameters for checking signal length. In the time window of size *minsiglength* after the initial P pick *minpercent* of samples have to be larger than the RMS value.
*zfac* | To recognize misattributed S picks, the RMS amplitude of vertical and horizontal traces are compared. The RMS amplitude of the vertical traces has to be at least *zfac* higher than the RMS amplitude on the horizontal traces for the pick to be accepted as a valid P pick. *zfac* | To recognize misattributed S picks, the RMS amplitude of vertical and horizontal traces are compared. The RMS amplitude of the vertical traces has to be at least *zfac* higher than the RMS amplitude on the horizontal traces for the pick to be accepted as a valid P pick.
*jackfactor* | A P pick is removed if the jackknife pseudo value of the variance of his subgroup ist larger than the variance of all picks multiplied with the *jackfactor*. *jackfactor* | A P pick is removed if the jackknife pseudo value of the variance of his subgroup is larger than the variance of all picks multiplied with the *jackfactor*.
*mdttolerance* | Maximum allowed deviation of P onset times from the median. Value in seconds. *mdttolerance* | Maximum allowed deviation of P onset times from the median. Value in seconds.
*wdttolerance* | Maximum allowed deviation of S onset times from the line during the Wadati test. Value in seconds. *wdttolerance* | Maximum allowed deviation of S onset times from the line during the Wadati test. Value in seconds.

BIN
docs/tuning.pdf Normal file
View File

Binary file not shown.