Theoretical principle
As indicated in the presentation of the Excel exporter, the main idea is to limit as much as possible the human work and the potential errors.
As a reminder, the Excel exporter allows the compilation of data from structurally identical protocols. The result files are compiled by groups. The Excel exporter is not designed to analyze a single result file.
Excel document structure
An Excel document can have a customized structure, however, the pages related to the extractions of run results are invariable: The Excel exporter will produce one sheet per experiment, and each sheet will contain 1 or more value tables.
Each value table contains the values for all trials in the experiment for all participants in the study. The double entry table is formatted as follows: each row of the table corresponds to a participant and each column corresponds to a trial in the experiment.
An Excel table for a type of value.
We start with a simple principle: we want to compile values extracted from the results in Excel tables. By convention and logic, an Excel table should normally contain values extracted in the same way. Indeed, in order to be analyzed, an Excel table of values must contain values extracted in a similar way.
First observation
This is our first point: an Excel table for a value type.
Value type?
In a result file, we have datasets named DataRecords containing a large number of values. It is possible to extract a specific value from a dataset by producing a specific extraction structure.
Refined first observation
Let's refine our first finding: an Excel table for a value from a result extraction structure.
Automation
We know that the Excel table must contain comparable data and it will only be comparable if the result extraction structure is the same for all cells in the table.
When an extraction structure is finalized, it can be copied to all the trials of the linked experiment, this procedure can be automated.
Copy of the extraction structure
If an extraction structure is produced once on a trial, VRmaze is able to copy it automatically to all trials.
Copy extraction structure on multiple result files
VRmaze is able to copy an extraction structure from one protocol to another, so it is able to process a large number of result files with identical logical structure.
Reference protocol
We have just understood that VRmaze is capable of copying an extraction structure over all trials from all result files, without human intervention. In terms of an Excel table, this means that if we provide the way to calculate one of the values in the table, VRmaze is able to fill the table completely.
Here comes the concept of a reference protocol. The reference protocol is a specific result protocol that contains different extraction structures. This reference protocol is used by the generator, which will search for all extraction structures and copy them to all trials in all result files.
The main human work is here: you have to produce an extraction structure for each desired Excel table. The main idea is that each extraction structure must be created once and only once to allow the generation of the Excel file.
The creation of an extraction structure must be produced on one try. By convention, the VRmaze Excel generator expects the reference protocol to contain extraction structures on each of the first trials of each experiment.
Extraction structure and reference protocol
One or more extraction structures must be present only on the first trial of each experimentation. This is called the "reference protocol".
Different extraction on different trials ?
An advanced use of the reference protocol is to produce the extraction not on the first trial only, but on all trials. The control becomes total, but the work much heavier. This allows for fully customizable data generation.
Which file to use ?
The easiest way, when creating a reference protocol, is to copy one of the result files and modify it to obtain this reference protocol.
Excel entry point
A logical result structure is not enough to produce an Excel table. Indeed, by convention, we have to declare that an extraction structure will be exported in Excel. This declaration allows for example to have other analysis structures without exporting them all.
The extraction structure will be used in Excel only if it is declared exportable. The declaration is made by an additional node called "Excel entry point". Adding an Excel entry point to an extraction structure allows, in addition to configuring the generated table in terms of formulas to be added.
Supporting an extraction
An extraction structure will generate an Excel table in the presence of an Excel entry point.
Entry point identifier
When creating multiple Excel entry points, it is imperative to specify a different entry point identifier each time. Each different entry point ID will produce a different table in Excel.
Experimental score
If the experiments in the reference protocol have scoring algorithms, these algorithms will be copied to the files to be processed so that they can be included in a score page in the Excel file.
Scorings
There are only a few scoring algorithms in the current versions of VRmaze. More scoring algorithms will be added as time goes on.
Example of creating a reference protocol
| Procedure | Screenshot |
|---|---|
Open a result file and look for the first trial of the first experiment. Every trial in VRmaze contains camera data. Select the DataRecord of the subject camera. |
 |
| Add a filter to calculate the total time of the trial via the "Total Timer" filter. This first extraction allows you to obtain a numerical value. |  |
| Now let's indicate that we want to export this structure to Excel by adding an Excel entry point. Add an Excel entry point via the context menu of the total time calculation filter. |  |
| The Excel entry point parameters allow you to configure the formulas to be applied, for example, and the title of the Excel table to be displayed. Change the entry point identifier to "EntryPoint01" and if you wish, add formulas to be applied. |  |
| Save the file as "ReferenceProtocol.xml". |
The reference protocol is finished. It contains only one Excel entry point in the structure of the first trial of the first experiment which will result in only one table in the Excel document. This table will contain all the times for each trial for all participants.
Add more Excel entry points
You can add as many Excel entry points as needed via other extractions. Repeat the procedure for adding entry points on the first trial of the second experiment if you wish, making sure to specify a different entry point ID.
The Excel entry point is not displayed ?
The Excel entry point is only displayed on filters whose output is a single value. Filters that produce a dataset from a parent dataset are not compatible with the Excel entry point.
Entry point identifier
Please be sure to specify a different entry point identifier each time.