.. highlight:: rst .. _kappa: ##### kappa ##### **Event Classification GUI** Description =========== Kappa is a graphical user interface for interactive event classification. It provides a :ref:`Summary tab` for a final event classification based on different observations and preliminary type guesses which are presented in the :ref:`observation tabs `. .. _kappa-summary: Summary and classification ========================== The summary tab is the main tab for making interactive event classifications. The preliminary type guesses and certainties from the individual observations are presented for joint evaluation in the table :ref:`Feature results `. A type selection can be made below in the :ref:`Event type ranking `. .. _fig-kappa-summary-tab: .. figure:: media/kappa-summary.png :align: center :width: 16cm Summary tab with individual observations and the final ranking. .. _kappa-summary-features: Feature results table --------------------- The row show the preliminary type guesses from the individual observations. The color indicate the status of the applied methods: * green: the observations are available and could be evaluated, * blue: the observations are being processed, * red: the observations are not available or the processing was not successful. When the preliminary event type different from the default, it is highlighted in bold letters. The different observations and methods may results in different suggestions for the event type or even no decision at all. To every observation a certainty is automatically assigned which can be adjusted manually. Together with the weight, an overall certainty is computed from the event type suggestions. .. _kappa-summary-ranking: Event type ranking ------------------ In the lower part, the event type suggestions are summarized. The most likely type is shown at the top of the table. They pie chart visualizes the relative certainties of the different types. The colors correspond to the rows in the table to the right. For making a final classification, select the event type in different ways: * **Pie chart:** Click on the type in the pie chart. The selection is highlighted by the circle segment outside the pie chart. In the pie chart the type can also be selected by using the courser keys or the mouse wheel and then pressing the Enter key. * **Table:** Click on the row of the table. In the table the type can also be selected by using the courser keys then pressing the Enter key. * **Pull-down menu:** Select the type from the pull-down menu in the lower part of the Summary tab. Press **Commit** to send the decision to the SeisComP messaging system. .. note:: To revise a classification simply select the correct one an press **Commit** again. .. _kappa-tabs: Detailed observation tabs ========================= The observations can be reviewed in the different observation tab. They provide automatic preliminary guesses of the event type based on the presented observation. The type along with the certainty can be interactively adjusted. .. note:: The behavior of all observation tabs can be configured in the module configuration of kappa. The parameters contain the alternative event types, fallback event types, thresholds, etc. Region check ------------ The region check tab shows the event location and the relation to pre-defined polygons. If the polygons contain information about the event type and the hypocenter of the event lies within the polygone, the preliminary type is given to the selected event. .. _fig-kappa-rc-tab: .. figure:: media/kappa-regioncheck.png :align: center :width: 16cm Region check tab Magnitude / Amplitude Ratio --------------------------- The Magnitude / Amplitude Ratio tab shows the network magnitude ratio of Ms_20 vs. mb. Upper and lower thresholds along with event types and example data points are configurable. If the selected event is below the lower or above upper thresholds, the respective preliminary event type is given with a certainty of 100%. If the event type is in between, the type and the certainty are given based on the event type associated to the closest threshold line. .. _fig-kappa-mag-amps-tab: .. figure:: media/kappa-mag-amps.png :align: center :width: 16cm Magnitude-Amplitude tab. The colors representing the event types and the thresholds are configurable. .. note:: Hold the mouse over an example point to read more information about this event. Moment tensor ------------- The moment tensor tab provides the full information about the moment tensor, its components and the derived focal mechanism values such as focal mechanism and principle axes. The beach balls represent the full moment tensor (left) and the double-couple (DC) moment tensor (right). The color of the represent the centroid depth of the moment tensor if given or the hypocenter depth. The rectangles around the beach balls represent the stations at their azimuth from the event origin. The colors of the station rectangles indicate the average station fit from moment tensor inversion: * green: good fit, low residual * yellow: intermediate * red: low fit, high residual. .. _fig-kappa-mt-tab: .. figure:: media/kappa-mt.png :align: center :width: 16cm Moment tensor tab. The color of the moment tensors indicate depth: red - shallow, yellow to green - intermediate, blue - deep. MachineLearning --------------- In the machine learning tabs multiple methods can be added and configured. The machine learning algorithms provide probabilities of particular event types based on provided features. By default, the features are the magnitude ratios: * :term:`Ms_20`/:term:`mb` * :term:`ML`/:term:`Md`. The machine learning methods are provided by Python scripts. Additional procedures can be added as profiles. .. note:: Machine learning algorithms are executed from configurable Python scripts. To use other methods simply create a new script and define it in :confval:`machineLearning.$name.command`. Ms vs. mb ^^^^^^^^^ The MachineLearning: Ms/mb tab compares Ms-mb magntiude ratios of the selected event with provided event examples. The classification and the certainties are based on machine learning. To run the machine learning tool press the **Start** button. The gray field to the left shows the progress information and possible errors. .. _fig-kappa-ml-ms-mb-tab: .. figure:: media/kappa-ml-ms-mb.png :align: center :width: 16cm Machine learning: Ms vs. mb ML vs. Md ^^^^^^^^^ The MachineLearning: ML/Md tab compares ML-Md magnitude ratios of the selected event with provided event examples. The classification and the certainties are based on machine learning. To run the machine learning tool press the **Start** button. The gray field to the left shows the progress information and possible errors. .. _fig-kappa-ml-ml-md-tab: .. figure:: media/kappa-ml-ml-md.png :align: center :width: 16cm Machine learning: ML vs. Md Origin Meta Information ----------------------- Kappa is able to evaluate origin comments. E.g. the template-based event detector `ccloc `_ can transport the event type of a master event to the new origin by a comment written to the origin. When the comment is configured in Kappa and found in an origin of an event, then this is a strong indicator that the event which contains the new origin is of the same type as the master event. The considered comment is configured by :confval:`originMeta.idEventType`. .. _fig-kappa-origin-tab: .. figure:: media/kappa-orgin.png :align: center :width: 16cm Origin meta information. Configuration ============= | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/kappa.cfg` | :file:`etc/global.cfg` | :file:`etc/kappa.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/kappa.cfg` kappa inherits :ref:`global options`. .. confval:: preferredEventTypes Type: *list:string* List of preferred event types which should appear on top of event type selection boxes. Default is ``earthquake,explosion``. .. confval:: eventTypeColors Type: *list:string* List of eventType to color mappings, e.g., earthquake:#00ff00, explosion:#ff0000. Default is ``earthquake:#b3de69,explosion:#fb8072,"nuclear explosion:#bc80bd","quarry blast:#fdb462","sonic blast:#80b1d3"``. .. note:: **regionCheck.\*** *Tests if events lies within or outside a region.* *Events within a region are flagged as positive, outside as negative.* *The event type is set accordingly.* .. confval:: regionCheck.enabled Type: *boolean* Defines whether this plugin should be available. Default is ``true``. .. confval:: regionCheck.name Type: *string* Name of the profile used in tab and summary table. Default is ``Region Check``. .. confval:: regionCheck.weight Type: *double* Weight of the event type reported by this plugin. Default is ``1.0``. .. confval:: regionCheck.defaultEventType Type: *string* Event type used as fallback when no other type applies. Leaving it empty will not propose a type. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: regionCheck.defaultMinDepth Type: *double* Unit: *km* Minimum hypocenter depth required for the default event type. .. confval:: regionCheck.defaultMaxDepth Type: *double* Unit: *km* Maximum hypocenter depth allowed for the default event type. .. confval:: regionCheck.regions Type: *list:string* The list of closed BNA polygon names defining regions for flagging event as positive or negative. A polygon name defines a positive region but names with prefix \! \(exclamation mark\) define negative regions. Evaluation is done in the order of the polygons. The last matching criteria applies and the event type is set accordingly. Default: If events are not positive or are negative regions the event type is set to \"outside of network interest\". Default: \"\!reject\", use \"accecpt\" to overwrite the default. Examples: Events are flagged positive within the polygon \"germany\": germany All events are flagged positive but events within the polygon \"quarries\" are negative: accept,\!quarries Events within the polygon \"germany\" are flagged positive but all other events and events within the polygon \"quarries\" are negaitve: germany,\!quarries All events are flagged positive but events within the polygon \"germany\" are negative and all events within the polygon \"saxony\" are positive: accept,\!germany,saxony Default is ``!reject``. .. confval:: regionCheck.readEventTypeFromBNA Type: *boolean* Read the event type from the BNA polygon header. The header must contain the type, e.g. header of a polygon with name \"quarry\": \"quarry\",\"rank 1\",\"eventType: quarry blast\",13 When active, type superseeds eventTypePositive and eventTypeNegative. This feature requires a SeisComP version greater than 2018.327. Default is ``false``. .. confval:: regionCheck.eventTypePositive Type: *string* New type of an event which is flagged positive. Ignored if readEventTypeFromBNA is active. Empty: Do not set type .. confval:: regionCheck.eventTypeNegative Type: *string* New type of an event which is flagged negative. Ignored if readEventTypeFromBNA is active. Empty means default: \"outside of network interest\" Default is ``"outside of network interest"``. .. note:: **magRatio.\*** *Magnitude ratio.* .. confval:: magRatio.enabled Type: *boolean* Defines whether this plugin should be available. Default is ``true``. .. confval:: magRatio.name Type: *string* Name of the profile used in tab and summary table. Default is ``Magnitude Ratio``. .. confval:: magRatio.weight Type: *double* Weight of the event type reported by this plugin. Default is ``1.0``. .. confval:: magRatio.typeX Type: *string* Magnitude type to bind to variable X. Default is ``mb``. .. confval:: magRatio.typeY Type: *string* Magnitude type to bind to variable Y. Default is ``Ms_20``. .. note:: **magRatio.upperType.\*** *Formula representing an upper bound for an event* *type. If the magnitude ratio exceeds the graph* *describled by this formula the configured event type* *is set.* .. confval:: magRatio.upperType.eventType Type: *string* The event type. E.g., earthquake. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: magRatio.upperType.formula Type: *string* E.g. x \- 0.68 .. confval:: magRatio.upperType.description Type: *string* Formula description or reference. .. confval:: magRatio.upperType.referenceData Type: *string* Name of file containing reference data. Each line is expected to hold a coordinate of form x,y and an event description, e.g. 5.5,6,gfz2020abcd .. note:: **magRatio.upperType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: magRatio.upperType.pen.color Type: *color* The color of the pen. Default is ``ff0000``. .. confval:: magRatio.upperType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: magRatio.upperType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. note:: **magRatio.lowerType.\*** *Formula representing a lower bound for an event* *type. If the magnitude ratio falls below the graph* *describled by this formula the configured event type* *is set.* .. confval:: magRatio.lowerType.eventType Type: *string* The event type. E.g., explosion. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: magRatio.lowerType.formula Type: *string* E.g. 0.95 \* x \- 1.668 .. confval:: magRatio.lowerType.description Type: *string* Formula description or reference. .. confval:: magRatio.lowerType.referenceData Type: *string* Name of file containing reference data. Each line is expected to hold a coordinate of form x,y and an event description, e.g. 5.5,6,gfz2020abcd .. note:: **magRatio.lowerType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: magRatio.lowerType.pen.color Type: *color* The color of the pen. Default is ``ff0000``. .. confval:: magRatio.lowerType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: magRatio.lowerType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. note:: **ampRatio.\*** *Amplitude ratio.* .. confval:: ampRatio.enabled Type: *boolean* Defines whether this plugin should be available. Default is ``true``. .. confval:: ampRatio.name Type: *string* Name of the profile used in tab and summary table. Default is ``Amplitude Ratio``. .. confval:: ampRatio.weight Type: *double* Weight of the event type reported by this plugin. Default is ``1.0``. .. confval:: ampRatio.typeX Type: *string* Amplitude type to bind to variable X. Default is ``mb``. .. confval:: ampRatio.typeY Type: *string* Amplitude type to bind to variable Y. Default is ``Ms_20``. .. confval:: ampRatio.unitX Type: *string* Amplitude unit. Default is ``nm``. .. confval:: ampRatio.unitY Type: *string* Amplitude unit. Default is ``nm``. .. note:: **ampRatio.upperType.\*** *Formula representing an upper bound for an event* *type. If the amplitude ratio exceeds the graph* *describled by this formula the configured event type* *is set.* .. confval:: ampRatio.upperType.eventType Type: *string* The event type. E.g., earthquake. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: ampRatio.upperType.formula Type: *string* E.g. x \- 0.68 .. confval:: ampRatio.upperType.description Type: *string* Formula description or reference. .. note:: **ampRatio.upperType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: ampRatio.upperType.pen.color Type: *color* The color of the pen. Default is ``ff0000``. .. confval:: ampRatio.upperType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: ampRatio.upperType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. note:: **ampRatio.lowerType.\*** *Formula representing a lower bound for an event* *type. If the amplitude ratio falls below the graph* *describled by this formula the configured event type* *is set.* .. confval:: ampRatio.lowerType.eventType Type: *string* The event type. E.g., explosion. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: ampRatio.lowerType.formula Type: *string* E.g. 0.95 \* x \- 1.668 .. confval:: ampRatio.lowerType.description Type: *string* Formula description or reference. .. note:: **ampRatio.lowerType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: ampRatio.lowerType.pen.color Type: *color* The color of the pen. Default is ``ff0000``. .. confval:: ampRatio.lowerType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: ampRatio.lowerType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. note:: **momentTensor.\*** *Evaluates the isotrophic component of a moment tensor solution.* .. confval:: momentTensor.enabled Type: *boolean* Defines whether this plugin should be available. Default is ``true``. .. confval:: momentTensor.name Type: *string* Name of the profile used in tab and summary table. Default is ``Moment Tensor``. .. confval:: momentTensor.weight Type: *double* Weight of the event type reported by this plugin. Default is ``1.0``. .. confval:: momentTensor.defaultEventType Type: *string* Event type used as fallback when no other type applies. Leaving it empty will not propose a type. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: momentTensor.iso Type: *double* Unit: *%* Threshold of the isotropic moment tensor component. Default is ``30``. .. confval:: momentTensor.eventType Type: *string* Event type to set if the iso threshold is exceeded. Default is ``explosion``. .. note:: **machineLearning.\*** *Machine learning.* .. confval:: machineLearning.profiles Type: *string:list* List of machine learning profiles to activate. .. note:: **machineLearning.\$name.\*** \$name is a placeholder for the name to be used. .. confval:: machineLearning.\$name.name Type: *string* Name of the profile used in tab and summary table. Default is ``Machine Learning``. .. confval:: machineLearning.\$name.weight Type: *double* Weight of the event type reported by this plugin. Default is ``1.0``. .. confval:: machineLearning.\$name.defaultEventType Type: *string* Event type used as fallback when no other type applies. Leaving it empty will not propose a type. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. .. confval:: machineLearning.\$name.command Type: *string* Command to execute. .. confval:: machineLearning.\$name.minValue Type: *double* Minimum expected value. Default is ``0.0``. .. confval:: machineLearning.\$name.maxValue Type: *double* Maximum expected value. Default is ``1.0``. .. confval:: machineLearning.\$name.lowerType.eventType Type: *string* EventType to use if probability exceeds the lower threshold. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. Default is ``explosion``. .. confval:: machineLearning.\$name.lowerType.threshold Type: *double* Lower threshold Default is ``0.2``. .. confval:: machineLearning.\$name.lowerType.referenceData Type: *string* Name of file containing reference data. Each line is expected to hold a probability value, the event time in iso format and an event description, e.g., 0.05,2017\-06\-23T22:58:12.123456,gfz2020abcd .. note:: **machineLearning.\$name.lowerType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: machineLearning.\$name.lowerType.pen.color Type: *color* The color of the pen. Default is ``ff0000``. .. confval:: machineLearning.\$name.lowerType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: machineLearning.\$name.lowerType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. confval:: machineLearning.\$name.upperType.eventType Type: *string* EventType to use if probability exceeds the upper threshold. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. Default is ``earthquake``. .. confval:: machineLearning.\$name.upperType.threshold Type: *double* Upper threshold Default is ``0.8``. .. confval:: machineLearning.\$name.upperType.referenceData Type: *string* Name of file containing reference data. Each line is expected to hold a probability value, the event time in iso format and an event description, e.g., 0.95,2017\-06\-23T22:58:12.123456,gfz2020abcd .. note:: **machineLearning.\$name.upperType.pen.\*** *Defines the pen used for the graph and event data.* .. confval:: machineLearning.\$name.upperType.pen.color Type: *color* The color of the pen. Default is ``00ff00``. .. confval:: machineLearning.\$name.upperType.pen.style Type: *string* The style of the pen. Supported values are: NoPen, SolidLine, DashLine, DotLine, DashDotLine, DashDotDotLine. Default is ``SolidLine``. .. confval:: machineLearning.\$name.upperType.pen.width Type: *double* Unit: *px* The width of the pen. Default is ``2.0``. .. note:: **originMeta.\*** *Reads the event type from origin comments, e.g. set by ccloc.* .. confval:: originMeta.enabled Type: *boolean* Defines whether this plugin should be available. Default is ``true``. .. confval:: originMeta.idEventType Type: *string* ID of the comment containing the event type hint. Default is ``ccloc:eventTypeHint``. .. confval:: originMeta.idCertainty Type: *string* ID of the comment containing the certainty value. Default is ``configID``. .. confval:: originMeta.idDescription Type: *string* ID of the comment containing an additional result description. Default is ``configID``. .. confval:: originMeta.defaultEventType Type: *string* Event type used as fallback when no other type applies. Leaving it empty will not propose a type. See \@ROOTDIR\@\/include\/seiscomp\/datamodel\/types.h or scolv for a list of supported event types. Bindings ======== Configuration ------------- .. confval:: enable Type: *boolean* Enables\/disables the station for event classification. Default is ``true``. .. confval:: channels Type: *list:string* Defines a list of preferred channels that are activated by default for that station. If this option is undefined then the highest sample rate channels for acceleration and velocity are used by default. If the list is empty \(which is a different state than undefined\) then no channels are selected by default. Command-line ============ .. program:: kappa Generic ------- Verbosity --------- Database --------