Analytics File System

A high-level overview of MAGES analytics file system is depicted in the image below.

Inside Users container (i.e., the root node) the following structure exists:

1. User Folders

   One folder per user. Each of these folders contain all necessary files of their respective user progress.

2. Module Folders

   Each user folder contains one or more modules folder. Module folders are named after respective module names. Module folders are generated when user runs a module for the first time.

3. SessionDates Folders

   These folders are contained inside their respective module folder. Each of the session folders represents a single user session of the module. A session folder is created when the user finishes a complete playthrough of the specific module.

   Generally, we store the following data for each user:

   3.1. Number of critical errors in each module session and the name of the action, where they occured.

   3.2. Number of non-critical (or normal) errors in each module session and the name of the action, where they occured.

   3.3. The score of each action in each module session.

   3.4. The time that the user needed for each action in each module session, measured in seconds.

   3.5. The total data (all errors, critical errors, warnings, final score) for each module session.

Stored data

The content that is saved in the files mentioned above, concerns the progress of users in each step of our module.

A basic example is provided below.

Errors & Warnings Data

Files under this category concern errors and warnings occurred during users playthrough.

Errors and warnings are structured in a similar manner as shown in the image above.

The structure is intuitive and self-explanatory. Each action the user obtains a warning/error is kept in track alongside the amount of errors.

Action	Errors
Question Action Example	1
Assemble Knossos Or Sponza Action	0
Remove Jar Example	0
Remove Jar With Tool Example	2
Apply Glue Action	0
Insert Plug Action	0

Scoring Data

We keep track of users’ score for each action in the module.

Specifically, the name of the action is saved, along with the score. Score variables are integers within the range of \(score \in [0, 100]\).

An example file content of users’ score is exhibited in the table below.

Action	Score
Question Action Example	100
Assemble Knossos Or Sponza Action	100
Remove Jar Example	100
Remove Jar With Tool Example	50
Apply Glue Action	80
Insert Plug Action	90

Timing Data

The time users spent on each action; is another important variable we monitor. More specifically, action names are accompanied by a double-precision number, which represents the time user has spent on that action.

Timings are measured in seconds. An example is shown in the table below.

Action	Time
Question Action Example	10.25
Assemble Knossos Or Sponza Action	83.70
Remove Jar Example	20.48
Remove Jar With Tool Example	115.80
Apply Glue Action	30.67
Insert Plug Action	17.61

Accumulated User Data

For convenience, we keep the concrete form of the data presented above, augmented with relative, yet necessary, information per session.

Namely, we keep track of the following information; the session date (DD/MM/YY), time session ended (HH:MM:SS), module difficulty, handedness, total score, total time, total errors (normal, critical) and warnings, number of current session (identifier), and total time of session.

Username	IP	Session Date	Session Time	Difficulty	Total Score	Total Time In Seconds	Total Errors	Total Critical Errors	Total Warnings	Total Time
Username	IP	06/12/2020	16:00:44	Easy	36	484	0	1	0	00:08:04

Scoring Factors

In order to calculate and store scoring information more precisely and for better and more detailed presentation of the data to the users, we also keep another type of information called Scoring Factors.

There are different kinds of scoring factors, some of them are the same across all of our modules (that would be the ones that concern errors, critical errors and warnings) and some others that are a bit more specific to module actions (for instance, for a module that contains question actions, there will be different scoring factor for those actions).

Error	100
0	-1
Object has been contaminated!
Error	30
2	-1
Goggles can be recycled!
Critical Error	0
1	-1
You are entering without PPE

The data shown above are the scoring factors for a specific action of a module.

The first line states the word “Error”, which means that this scoring factor concerns an error of this action. The integer “100” is the score credited to this factor. The “0”, which is located below the word “Error” in this example, is the number of times the users made that error. “-1” means that this error can be made infinite times (or that there is not any limit to the number of times that this error can be made).

In case there is a limit, that number may be any positive integer. Finally, the name of the specific error that this scoring factor represents is given (in this example “Object has been contaminated”.

An action can have one or more scoring factors. In the case of our example, this specific action had three different scoring factors. The first one is the one we just finished presenting. The rest follow exactly the same logic.