make printable

new: v1.0: - released

see also: databases database of events tqs tools webDocuSys output used by eventlog interface upload/download upload/download scheme for yaml config files

webEventSys

Description

Find the presentation about the tool functionalities here.

The tool webEventSys helps to create the instrument-specific content of pull-down menues for the interface to the event log database. The database interface is located under https://ssoint.hq.eso.org/eventlog/home. It is intended to log events related to data quality. For this, it has the option to select all or specific raw_types which might be affected, and all or specific QC1 parameters (KPI or non-KPI). For the authorized user, it is possible to enter new quality events. For these it is important to have pull-down menues which list all raw_types and all QC1 parameters relevant for quality events. To maintain the entries for these pull-down menues is the goal of the tool webEventSys.

Both the raw_types and the QC1 parameters need to be entered in configuration files which comes in a special format, the yaml format. The raw_types are extracted from the local OCA rules. The QC1 parameters are extracted from the local trendPlotter configuration files.

The quality events that can be entered in the event log database usually relate to external events (like earthquakes), interventions (like mirror coatings), component replacements (new grating). But they might also relate to pipeline changes or changes of score thresholds. As a principle, all possible entries of "events" should be visible on the HC monitor.

In general, the OCA rules will contain some raw_types which are not relevant for any HC plot. Also, not all QC1 parameters used on the HC monitor are related to instrument quality. If e.g. a temperature parameter is monitored, this QC1 parameter is not directly related to quality. Such irrelevant raw_types or parameters can therefore be hidden by entering them in an "embargo" file. They will then be removed from the output yaml file.

Check out the URL http://sciops.pl.eso.org/wiki/index.php/Database_of_events_affecting_data_quality_or_their_measurements_:_guidelines for the guidelines for filling in the events.

Tool calls: option -C

The normal tool call is

webEventSys -C (for Create).

You can also just call

webEventSys

for a dialogue where you can enter -C. You call this option not only for creation, but also for any modification.

Then, there is a dialogue in which the tool reads all raw_types from the OCA rules, and then removes the ones which are already entered in $DFO_CONFIG_DIR/webEventSys/embargo.webEventSys. Example:

There are some obvious examples for raw_types that cannot be relevant for any HC plot: ACQ for acquisition, SCIENCE raw_types, or STD raw_types not monitored on the HC monitor. But they are part of the OCA rules, and therefore the tool finds them. If you want them to be removed from the list, enter them in the embargo file:

and call the tool again. Now the dialogue looks different:

Second, the tool scans all config.tp* files for QC1 parameter names. It finds KPI parameters and non-KPI parameters and lists them in alphabetical order.

Some of those may be useless for an event log, they can be embargoed in the same way as the raw_types. Open the embargo file, and enter items with a leading QC_PARAMS:

Then call the tool again, and these parameters will have disappeared from the final list.

Before uploading the result file, the tool gives you a chance to inspect it:

You will notice that the result yaml file has an additional section with modes, in addition to the expected ones (kpi_parameters, non-kpi_parameters, raw_types). This is modes:

The list of instrument modes is automatically added by the tool. Its content is read from a master file all_modes.txt under http://qcweb.hq.eso.org/DB_QCEVENTS. This file is downloaded into your account and analyzed for the content for instrument $DFO_INSTRUMENT which is then added to the $DFO_INSTRUMENT.yaml file. The content should not be modified, it is based on high-level and cross-instrument principles by SciOps.

If you hit return, the result yaml file is uploaded to the URL http://qcweb.hq.eso.org/DB_QCEVENTS. This is the place where the eventlog interface reads it and fills its pull-down menues "Ins. Modes", "KPI params.", and "Non-KPI Params".

If you have created a new $DFO_INSTRUMENT.yaml file (because you have run the tool for the first time on your account), the instrument configuration file is automatically updated to contain this new instrument.

---

Other options: -S

With option -S, you can upload a structured yaml file that you have prepared and edited. The ral power of the yaml markup language is the possibility to easily structure information. This can be used here to create context-aware menues which, e.g. offer only the QC1 parameters relevant in the context of the previously chosen mode. While this is great for anyone using the pull-down menues, it might become very cumbersome to create this structure in the yaml file since it requires in-depth knowledge of these relations. For the moment, this option is NOT supported automatically. If you want to use it, you can start from the unstructured yaml file (see previous section), copy it to a file called <instr>_context.yaml, edit the file and then upload it using this option -S. Be aware of the fact that any syntax error in the file will result in an empty interface, with no further debugging information.

Other options: -Q

With option -Q, you can explore the broader context around a given QC1 parameter and its scores. One of the main drivers for the event log is the need for documenting a change of a score threshold, or a KPI reference value. If there is the need to enter such an event in the eventlog, the interface has a button "Create Event". It might also occur that one wants to edit an existing event.

Since we usually start with a score that shows some behaviour (like being red although it was green before, or vice versa), the tool option -Q helps to explore all configuration files (trendPlotter, scoreQC) that define a score for a selected QC1 parameter. With the output, one can identify all cases where this QC1 parameter is scored, and enter a specific comment why its thresholds are modified, and also select the corresponding raw_type.

Enter option -Q and start a dialogue. Either you know the name of the QC1 parameter already, then enter it. Or you ask for an overview of all configured parameters and then make your choice.

The tool will return the name(s) of all HC repors that make use of this parameter. Note that in general, names of QC parameters are not unique per raw_type, and their score rules become unique only in combination with certain setup rules. It might occur that a specific QC parameter name is used in 6 HC reports, and that the selected HC report has 6 plots for 6 different setups, each with thresholds. Therefore, only the combination of QC parameter name, HC report and specific HC plot is uniquely describing a score rule and its modification. The tool option -Q tries to help with finding this score rule, or the set of all of them.

If the tool finds a scoring rule attached to a selected QC parameter, it gives the information about the score threshold and the affected raw_type, which is useful for entering the proper information for the quality event. If it does not find a score rule, then there is no quality event associated to the selected QC parameter. It might even be true that this QC parameter is not scored anywhere, in which case it could be entered in the embargo file.

How to use

Type

webEventSys -h for on-line help,

webEventSys -v for the version number.

The standard mode is:

webEventSys -Q

with a dialogue for selecting a QC parameter,

webEventSys -C

for creating the yaml file for the local instrument, or

webEventSys -S

for attempts to upload a structured yaml file instead of the standard unstructured yaml file.

Output

The output in options -C or -S is the <instrument>.yaml file uploaded to http://qcweb.hq.eso.org/DB_QCEVENTS.

Its impact is seen under https://ssoint.hq.eso.org/eventlog/home where it defines the content of the pull-down menues under raw_types, kpi_parameters and non-kpi_parameters.

Configuration

The tool has no configuration file. Under $DFO_CONFIG_DIR/webEventSys there might be an optional "embargo" file with two parts, starting with RAW_TYPES and QC_PARAMS. The entries in these sections are suppressed in the final choice of raw_types and QC parameters.

The URL of the Event Log interface is configured in $DFO_CONFIG_DIR/trendPlotter/config.trendPlotter (because of the link being visible on the HC monitor). It is configured as QUALITY_EVENTLOG_URL.

Note that the name of the instrument used in this context is encoded as $QC1_INSTRUMENT in .dfosrc and that it needs to come in upper-case letters.

Operations

Keep in mind that you should re-run the tool when:

• you have done a significant change of a HC plot or a KPI plot (like adding or removing a QC parameter), because then the pull-down menues on the eventlog interface need to be updated;
• you have done a significant change of your OCA rules (like adding or removing a raw_type), for the same reason.

The need for updating the pull-down menues also means that you might need to modify your embargo file, for the RAW_TYPEs and/or for the QC_PARAMETERs.

Instrument modes

If the file all_modes.txt has been modified by an authorized user (see here), the tool has to be called again with option -C in order to re-create the <instr>.yaml file and bring the modified list of modes to effect.

Rules for entering a comment on the eventlog interface

For QCG, the main driver for a new quality comment is the change of a scoring threshold, or a KPI reference value. This could be induced by an instrument event, like an intervention or an earthquake. But you don't need to enter every earthquake or every intervention, only if these have an impact on scoring thresholds. Likewise, a new pipeline vesion should be entered but only if it affects the scoring thresholds. The main principle is already in the name: quality events.