seiscomp-training/etc/descriptions/scevent.xml

<?xml version="1.0" encoding="UTF-8"?>
<seiscomp>
	<module name="scevent" category="Processing">
		<description>
		Associates an Origin to an Event or forms a new Event if no match is found.
		Selects the preferred origin, magnitude and focal mechanism.</description>
		<configuration>
			<parameter name="eventIDPrefix" type="string">
				<description>Prefix for all Event IDs</description>
			</parameter>
			<parameter name="eventIDPattern" type="string" default="%p%Y%04c">
				<description>
					Defines the pattern to generate an event ID.

					%p : prefix

					%Y : year

					%[w]c: alpha character

					%[w]C: upper case alpha character

					%[w]d: decimal

					%[w]x: hexadecimal

					%[w]X: upper case hexadecimal

					[w] is an optional width parameter.
				</description>
			</parameter>
			<parameter name="eventIDLookupMargin" type="integer" default="-1">
				<description>
					Configures the number of event ID slots to look back and
					forth when an event ID is already taken. The default in
					previous versions was 5. Now -1 means that the margin is
					determined automatically based on "eventAssociation.eventTimeBefore"
					and "eventAssociation.eventTimeAfter". According to the
					configured "eventIDPattern" a fixed time range per slot
					can be computed and with that width the number of look
					ahead slots and look back slots can be computed based on
					the given time ranges for event association.
				</description>
			</parameter>
			<parameter name="populateFERegion" type="boolean" default="false">
				<description>
					If enabled then the EventDescription with type
					'Flinn-Engdahl region' will be populated with the
					Flinn-Engdahl region name.
				</description>
			</parameter>
			<group name="processing">
				<group name="blacklist">
					<parameter name="eventIDs" type="list:string">
						<description>
						Defines a blacklist of event ids. The items of this list
						are only matches against %c, %C, %d, %x and %X of the
						eventIDPattern description. Year (%Y) and prefix (%p) are
						not matched. The match is case-sensitive, so blacklisting
						e.g. abcd would only match in combination with %c. If %C
						is used ABCD has to be blacklisted.
						</description>
					</parameter>
				</group>
			</group>
			<group name="eventAssociation">
				<description>
					Criteria defining if Origins are associated to an event
					and which Origins and magnitudes become preferred.
				</description>

				<parameter name="minimumDefiningPhases" type="int" default="10">
					<description>
						Minimum number of Picks for an Origin that is automatic and cannot be
						associated with an Event to be allowed to form an new Event.
					</description>
				</parameter>

				<parameter name="minimumScore" type="double">
					<description>
						Minimum score of an automatic Origin to be allowed to
						form an new Event. This requires an activated score
						plugin and a score processor. Configure &quot;score&quot;
						for defining the score processor and the score processor
						parameters. If minimumScore is defined, &quot;minimumDefiningPhases&quot;
						has no effect on association as this phase check will be
						superseded by the score check. It is the task of the score
						processor to evaluate a proper score for all input Origins.
					</description>
				</parameter>

				<parameter name="ignoreFMDerivedOrigins" type="boolean" default="true">
					<description>
						Ignore and do not associate Origins derived
						from CMT/MT inversions.
					</description>
				</parameter>

				<parameter name="eventTimeBefore" type="double" unit="s" default="1800">
					<description>
						Time range before the Origin time of an incoming Origin to search for
						matching events.
					</description>
				</parameter>

				<parameter name="eventTimeAfter" type="double" unit="s" default="1800">
					<description>
						Time range after the Origin time of an incoming Origin to search for
						matching events.
					</description>
				</parameter>

				<parameter name="minimumMatchingArrivals" type="int" default="3">
					<description>
						Minimum number of matching picks between two Origins to be associated
						to the same event.
					</description>
				</parameter>

				<parameter name="maximumMatchingArrivalTimeDiff" type="double" unit="s" default="-1">
					<description>
						Negative time window: compare only pickIDs to find
						matching arrivals. A non negative
						value (including 0) compares pick times regardless
						of the pickID. Pass: |pick1.time - pick2.time| &lt;= threshold
					</description>
				</parameter>

				<parameter name="compareAllArrivalTimes" type="boolean" default="true">
					<description>
						This parameter is only used in conjunction with
						eventAssociation.maximumMatchingArrivalTimeDiff.
						If a station has multiple associated arrivals for a
						particular event, this flag defines if the time distance
						of a new pick to all arrivals must be within
						eventAssociation.maximumMatchingArrivalTimeDiff
						or if one matching arrival is enough.
					</description>
				</parameter>

				<parameter name="allowLooseAssociatedArrivals" type="boolean" default="false">
					<description>
						Allows to match picks that are associated with weight 0.
					</description>
				</parameter>

				<parameter name="maximumTimeSpan" type="double" unit="s" default="60">
					<description>
					Associates an Origin with an existing event  if the Origin
					time differs not more than 60 seconds unless the
					minimumMatchingArrivals criteria matches.
					</description>
				</parameter>

				<parameter name="maximumDistance" type="double" unit="degrees" default="5">
					<description>
						Allowed location difference between an incoming Origin compared with
						preferred Origins to get associated.
					</description>
				</parameter>

				<parameter name="magTypes" type="list:string" default="M">
					<description>
						Magnitude type priority list for becoming a preferred magnitude for an
						event.

						Example:

						M, mBc, Mw(mB), Mwp, ML, MLh, MLv, mb
					</description>
				</parameter>

				<parameter name="enableFallbackMagnitude" type="boolean" default="false">
					<description>
						If true, one magnitude will be preferred even if magnitude criteria are
						not fullfilled.
					</description>
				</parameter>

				<parameter name="minimumMagnitudes" type="int" default="4">
					<description>
						Minimum number of station magnitudes referenced to a network magnitude
						to become a preferred magnitude.
					</description>
				</parameter>

				<parameter name="minMwCount" type="int" default="8">
					<description>
					Minimum number of station magnitudes required for Mw(mB) to be considered as
					preferred magnitude.
					</description>
				</parameter>

				<parameter name="mbOverMwCount" type="int" default="30">
					<description>
						Minimum number of station magnitudes which ensures that Mw(mB) will be
						preferred and not mb.
					</description>
				</parameter>

				<parameter name="mbOverMwValue" type="double" default="6">
					<description>
						Average between mb and Mw(mB) which must be exceeded to become Mw(mB)
						preferred.
					</description>
				</parameter>

				<parameter name="magPriorityOverStationCount" type="boolean" default="false">
					<description>
						If false then the station count rules out the magnitude priority
						which is only taken into account if two magnitudes have the
						same station count.

						If true then the priority rules out the station count
						which is only taken into account if two magnitudes have the
						same priority.
					</description>
				</parameter>

				<parameter name="priorities" type="list:string" default="AGENCY, STATUS, PHASES_AUTOMATIC, TIME_AUTOMATIC">
					<description>
						The general priority list to decide if an Origin becomes preferred.
						The priority decreases in the order of the parameters.
						This list is not used unless this parameter is activated.

						Empty priority list: scevent replicates the default hard wired behaviour:
							AGENCY, STATUS, PHASES_AUTOMATIC, TIME_AUTOMATIC

						Each item in the list corresponds to a check that is performed.
						Each check computes a score of the incoming Origin (s1) and the
						current preferred Origin (s2). If the s1 is lower than s2,
						the incoming Origin is rejected and does not become preferred.
						All subsequent checks are ignored.
						If s1 is equal to s2, the next check in the list is performed.
						If s1 is larger than s2, the Origin becomes preferred and
						all subsequent checks are ignored.

						Available tokens:

						AGENCY: check based on agency priorities

						AUTHOR: check based on author priorities

						MODE: evaluation mode priority: 0 = unset, 1 = automatic, 2 = manual, manual over-rules automatic

						STATUS: priority combined from evaluation status and evaluation mode:
						-100 = status is rejected, -1 = status is reported,
						0 = status is preliminary or status is unset and mode is automatic,
						1 = status is confirmed or status is unset and mode is manual,
						2 = status is reviewed, 3 = status is final,

						METHOD: check based on the method priorities

						PHASES: higher phase count = higher priority

						PHASES_AUTOMATIC: only checks phase priorities for incoming automatic Origins

						RMS: lower rms = higher priority

						RMS_AUTOMATIC: only check RMS on incoming automatic Origins

						TIME: more recent Origins (creationTime) have higher priorities

						TIME_AUTOMATIC: only check creationTime priority on incoming automatic Origins

						SCORE: evaluates the score according to a configured ScoreProcessor and
							   prefers the Origin/Focalmechanism with the highest score.
					</description>
				</parameter>

				<parameter name="agencies" type="list:string">
					<description>
						The agencyID priority list. When the eventtool comes to the point to
						select a preferred Origin based on AGENCY it orders all Origins by its agency priority and
						selects then the best one among the highest priority agency. It also defines the
						agency priority for custom priority checks
						(eventAssociation.priorities).

						The parameter is only considered when defined in &quot;priorities&quot;.
					</description>
				</parameter>

				<parameter name="authors" type="list:string">
					<description>
						The author priority list. When the eventtool comes to the point to
						select a preferred Origin based on AUTHOR it orders all Origins by its author priority and
						selects then the best one among the highest priority author. It also defines the
						author priority for custom priority checks (eventAssociation.priorities).

						The parameter is only considered when defined in &quot;priorities&quot;.
					</description>
				</parameter>

				<parameter name="methods" type="list:string">
					<description>
						The method priority list. When the eventtool comes to the point to
						select a preferred Origin based on METHOD it orders all Origins by its methodID priority and
						selects then the best one among the highest priority method. It also defines the
						method priority for custom priority checks (eventAssociation.priorities).
						A defined method string must match exactly the string in Origin.methodID.

						The parameter is only considered when defined in &quot;priorities&quot;.
					</description>
				</parameter>

				<parameter name="score" type="string">
					<description>
						Defines the ScoreProcessor interface to be used along
						with priority &quot;SCORE&quot;.

						The parameter is only considered when defined in &quot;priorities&quot;.
					</description>
				</parameter>

				<parameter name="declareFakeEventForRejectedOrigin" type="boolean" default="false">
					<description>
						If the preferred Origin has evaluation status 'rejected', the
						Event type will be set to 'not existing' unless the Event
						type has been fixed by an operator or the preferred Origin
						has been fixed.
					</description>
				</parameter>

				<parameter name="delayTimeSpan" type="int" unit="s">
					<description>
						Configures a timespan to delay Event creation. If a new Origin arrives
						which cannot be associated to an existing Event, delay the Event creation for a certain
						timespan.
					</description>
				</parameter>

				<group name="region">
					<description>
					Region filter for creating events. Use with care! Origins
					outside may be ignored even if they would
					become preferred otherwise.
					</description>
					<parameter name="rect" type = "string" >
						<description>
						Region by geographic coordinates.

						Format: "South, East, North, West"
						</description>
					</parameter>

					<parameter name="minDepth" type="double"  unit="km">
						<description>
						Minimum depth.
						</description>
					</parameter>

					<parameter name="maxDepth" type="double" unit="km">
						<description>
						Maximum depth.
						</description>
					</parameter>
				</group>

				<group name="delayFilter">
					<description>
						The delayFilter group configures an Origin filter to activate the delay feature for
						this Origin. If more than one filter is given they are combined with AND.
					</description>
					<parameter name="agencyID" type="string">
						<description>The agencyID of the Origin to be delayed.</description>
					</parameter>
					<parameter name="author" type="string">
						<description>The author of the Origin to be delayed.</description>
					</parameter>
					<parameter name="evaluationMode" type="string">
						<description>
							The evaluation mode of the Origin to be delayed. Can be either &quot;manual&quot;
							or &quot;automatic&quot;.
						</description>
					</parameter>
				</group>
			</group>
		</configuration>
		<command-line>
			<group name="Generic">
				<optionReference>generic#help</optionReference>
				<optionReference>generic#version</optionReference>
				<optionReference>generic#config-file</optionReference>
				<optionReference>generic#plugins</optionReference>
				<optionReference>generic#daemon</optionReference>
				<optionReference>generic#auto-shutdown</optionReference>
				<optionReference>generic#shutdown-master-module</optionReference>
				<optionReference>generic#shutdown-master-username</optionReference>
				<option flag="x" long-flag="expiry" argument="time">
					<description>Time span in hours after which objects expire.</description>
				</option>
				<option flag="O" long-flag="origin-id" argument="publicID">
					<description>
						OriginID to be associated. When given no messages are sent.
						Only the status of the association is written to stdout.
					</description>
				</option>
			</group>

			<group name="Verbosity">
				<optionReference>verbosity#verbosity</optionReference>
				<optionReference>verbosity#v</optionReference>
				<optionReference>verbosity#quiet</optionReference>
				<optionReference>verbosity#component</optionReference>
				<optionReference>verbosity#syslog</optionReference>
				<optionReference>verbosity#lockfile</optionReference>
				<optionReference>verbosity#console</optionReference>
				<optionReference>verbosity#debug</optionReference>
				<optionReference>verbosity#log-file</optionReference>
			</group>

			<group name="Messaging">
				<optionReference>messaging#user</optionReference>
				<optionReference>messaging#host</optionReference>
				<optionReference>messaging#timeout</optionReference>
				<optionReference>messaging#primary-group</optionReference>
				<optionReference>messaging#subscribe-group</optionReference>
				<optionReference>messaging#encoding</optionReference>
				<optionReference>messaging#start-stop-msg</optionReference>
			</group>

			<group name="Database">
				<optionReference>database#db-driver-list</optionReference>
				<optionReference>database#database</optionReference>
				<optionReference>database#config-module</optionReference>
				<optionReference>database#inventory-db</optionReference>
				<optionReference>database#db-disable</optionReference>
			</group>
		</command-line>
	</module>
</seiscomp>