Event Report Tool Instructions 2024-1¶
Overview¶
This document aims to instruct how to use the Event Report tool (ERT) to merge GIFT event output files and create event reports. Events that occur during a domain session are stored in various places and formats (e.g., bookmark files, domain session log files), therefore the ERT was created to facilitate the selection and merging of important events from those sources. Once a report is configured, an output file can be created (e.g., csv) that can be imported into a third party tool (e.g., Excel, SPSS, RapidMiner, etc.) for further analysis.
Where to Start¶
Follow the instructions within the “Run Instructions” document to bring up the ERT Webpage.
Selecting Event Sources¶
Before you can begin to configure an ERT report, you must select the event source file(s). Figure 1 shows the select event source(s) page which is the first page that appears when the ERT is launched.
Figure 1. Screenshot of the ERT event source selection web page.
You can select more than one source file by holding the “Ctrl” button on your keyboard and then left mouse clicking on your selections.
When finished selecting one or more event sources, click the “Continue” button.
Configure and Create Report¶
After the event source(s) have been selected, a web page resembling the one shown in Figure 2 will be created. The top left list box is populated with all of the events found in the event source(s). Those event types listed for the ERT property value “defaultEventTypes” (in ert.properties) will be checked by default to facilitate quicker report generation (more information can be found here under Tool Properties – Event Report Tool section). From here you are free to customize the report that will be created as described in the following sections.
Figure 2. A screenshot of the ERT web page showing the events and event type columns for a selected domain session log.
Customize Event Type Columns¶
In order to specify which columns of a particular event type will be included in the report, select the “Customize” link and then check/uncheck each corresponding column that is listed in the list box to the right of the list of events. The event type columns list will contain the columns for every event of that type found in the event source(s). Keep in mind that if the event type is not selected, i.e., checked, the event type columns will not appear in the report even if they are checked themselves.
Customize Default Columns¶
The default columns are a list of columns that every row will have in the report (e.g. Time). These include metadata about the event such as various time stamps and the event type name. You can change the ordering of these columns by using the up/down arrow buttons. In addition, the columns can be removed or added from the report by selecting the checkbox next to each column name.
Some of the default columns such as “Time” have additional customization that can be selected. This includes filtering events out of a generated report based on a window of time. An example of this dialog is shown in Figure 2.
Exclude Empty Columns¶
Checking this property will remove any columns where all of its cells are empty. This can happen based on default column filter settings. For example, when a report would normally have a column with values in it but those values are then filtered out based on the filter parameters.
Sort By Column¶
The sort by column will order the rows in the generated report file by the value in each row for the column chosen (ascending order). Currently only the default columns (e.g. user id) are available as choices for sorting.
Merge By Column¶
The merge by column will combine rows where the values for the ‘merge-by-column’ match. Currently only the default columns (e.g. domain session id) are available as choices for merging.
There are several things to consider when merging rows (consider RowA being merged with RowB).
- If RowA and RowB have different, non-empty, values in any column (other than the merge-by-column), a new column will be added to the report with a suffix (e.g. (2) ) added to the column name. The new column name will have the value of RowB in it for the resulting row of merging RowA and RowB.
- If the merge-by-column is a time based column (e.g. time, domain session time), than all other time columns will be removed from the report.
- If the merge-by-column is not a time based column, than all of the time based columns will be removed from the report.
Empty Cell Value¶
Usually there will be empty cells in the report being generated due to the fact that events are time stamped down to the millisecond and every row in the report contains the columns for all events as configured by the user. For this reason, the ERT allows you to provide the value that will be written to the report file in place of no data (i.e. nothing). This is useful for third party tools such as SPSS which requires a period (“.”) in empty cells.
Create Report Output File¶
After the report has been configured, select “Create File” and a file will be written to the GIFT output directory where the Admin Server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation).
Save Settings¶
Use this feature to save the current report settings to a file that can be loaded in the future. The settings file will be written to the GIFT output directory where the Admin server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation).
Load Settings¶
Use this feature to load the settings saved in a file. Currently, only the list of settings files located in the GIFT output directory where the Admin server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation) will be shown for selection.
If a column is in the loaded settings file but is not in any of the event sources selected, than that column will be ignored. For example, if the settings file has a reference to a survey question column, however the selected event source(s) don’t have any survey events in them. In this example the survey question column will not be shown on the ERT customize report page.
Decoding survey responses¶
The ERT logic will output columns for survey question responses. The cell values will contains different information depending on the type of question. (Developers can look at mil.arl.gift.common.ert.event.SurveyResultEvent.java)
From https://gifttutoring.org/boards/6/topics/1467
What do the dots in the cell mean?
'.' indicate that there is no content to place in that cell. Instead of leaving the cell empty, GIFT places a period in the cell. This makes the cell SPSS compliant, for those that want to use that analysis tool.
Another thing you might notice is that spaces are replaced with underscores. This is also for SPSS compliance.
How do I correlate the headings with each survey question?
Ideally you would use the 'Tag' feature on each survey question in the survey composer prior to collecting user study data. This is documented in the Researchers Guide to GIFT by Anne Sinatra. A tag is a way authors can provide identifiers to important survey questions. These tags will replace some of the syntax you are seeing right now (which I will explain next) so that you can easily interpret which question the column represents. But in case you didn't read that series of papers and didn't use the tag feature, GIFT uses the survey database ids to identify the source question.
S_11827_SQ_131654_Q70461_R_Vesicular_cell_smear_on_a_glass_slide_C_Polymerase_chain_reaction_(PCR)
Survey id 11827
Survey Question id 131654
Question id 70461
[This is a matrix of choices question]
Row choice text: Vesicular_cell_smear_on_a_glass_slide
Column choice text: Polymerase_chain_reaction_(PCR)
A value of 1 in this column would indicate that the choice was mode by the user.
S_11817_SQ_131515_Q70322_choice_index
Survey id 11817
Survey question 131515
Question id 70322
The row value for this column contains the index of the choice made for this question.
S_11822_Score(2)
This row value for this column contains the survey score for Survey with id 11822, and the '(2)' means this is the 2nd time the survey was taken in the course.
S_11881_SQ_132029_Q70378
This row value for this column contains the question text.