Feature Request: Better Way to Create/Access Experiment Design Variables and Runner Variable in the Scripts

[A-Ivan]

See Feature #49 for full details.

"Currently the way to access the variables in the trial script is to something like:

variable_type variableName = (variable_type) Data["variable_name"];

For example: string colorString = (string)Data["Color"];

Having to manually cast (writing the variable type) and to type in the variable's name in quotes can lead to syntax problems and typos. Because the variable names and their type has already been set using the Design File, it would be great of this information could simply be pulled from the Design file.

This could be done automatically, for instance by having a button at the end of the Design File which would edit the Trial, Block, Runner, and Experiment scripts adding the variables setup in the Design file as private class variables (the user could then cut and paste these variables to specific functions in these files). A warning could appear stating that this would overwrite these files so any edits to them would be lost, asking the user if they would like to continue or cancel.

If this step is part of the setup process, first using the script Helper Tool to setup the Experiment files/scripts, then creating the variables in the Design file, then pressing this button to automatically add the files to the previously generated script files (trial, block, etc.), overwriting these files would not be an issue."

[A-Ivan]

Hi @AdamBebko

I was able to get this working but I wasn't able to push to the dev branch or create a new branch and create a pull request, it says that permission is denied.

Summary of the changes:

1. Variables.cs, 2 independent variable list variables have been created to hold all the independent variables and all the independent block variables, respectively. This helps to go through the list of the list of variables when writing them to their respective scripts.
2. ExperimentDesignFile2.cs, some supporting variables and functions have been created to help the changes in the ExperimentDesignFile2Editor.cs script.
3. ExperimentDesignFile2Editor.cs , this is where most of the changes have occurred.

• A ScriptReference class was serialized so that the user can drag the experiment's Trial, Block, and Experiment scripts in the DesignFile Editor. These will be the scripts that will be overwritten to contain the variable declarations. There is also a button that searches for the Trial, Block, and Editor scripts in the experiment folder created if the user uses the Script Helper Tool to create the experiment files. The option for the user to drag the files was used so that if the user manually created the Trial, Block, or Experiment script, they can drag them in.
• ShowAutomaticVariableSetupOptions function: a Show/Hide section with Buttons, Labels, and Helper Text have been added to the DesignFile to explain help the user choose the files to be overwritten and to overwrite the files with the runner, independent, and dependent variables the user has created (in the same DesignFile). The Trial, Block, and Experiment scripts can all be overwritten at the same time or each one can be overwritten independently, as is done in the Script Helper Tool.
• AutomaticTrialVariableScriptSetup function: this takes care of getting the relevant data ready to overwrite the experiment's trial script. The main idea is that specific text in the trial script, for instance "// float thisTrialsDistanceValue = (float)Data["MyDistanceFloatVariableName"]; // Read values of independent variables" will be overwritten with experiment's independent variables. This is similar to what is done in the Script Helper Tool to create the trial script from the template trial script. This file overwrite occurs for the independent variables, dependent variables, and runner instantiation.
• AutomaticBlockVariableScriptSetup and AutomaticExperimentVariableScriptSetup functions do the same as the trial's variable setup function, but the block has a different independent variable text to find/change, will only add block independent variables, and will not add dependent variables. The experiment variable setup function only adds the runner information.

This is what the original Design File (at the end of the variables section) used to look like:

This is what the new Design File (at the end of the variables section) used to look like:

Section Hidden

Section Shown

Experiment Script References Expanded

This can still be worked on to make it look better, but at least it works.

Here is an example of the output files this generates:

Design File Variables

Trial Script Original

Trial Script Output

Block Script Original

Block Script Output

Experiment Script Original

Experiment Script Output

What still needs to be added are:

• Inform the user of trial/block/experiment script was dragged into the correct place in the DesignFile. Using the Get Type/GetScriptFromInspector function in the ScriptReference class would cause Errors and not allow the DesignFile to be shown. But something similar would work.
• Check and inform the user if string to replace (specific text in the template scripts) exists. For instance if the user is not using a template script or if they have modified the text in the document.
• The Trial, Block, and Experiment files can be automatically set in the DesignFile when they are created using the Script Helper Tool.

[AdamBebko]

This looks great. Thanks for your work. I'll look into the permissions issue for pull requests.

I have a couple questions:

• How does this system handle variable deletions?
• How does it handle variable renames?
• I can forsee situations where a user edits the script manually, and then it becomes out of sync with the design file? How can this be handled?

[A-Ivan]

You're welcome.

Answering your questions:

• How does this system handle variable deletions?
  If a variable is deleted, it is automatically updated on the independent and block list variables, found in the Variables.cs script. The user would have to either create another experiment trial script using the Script Helper Tool and then press the button to set up the variables in that script, or they would have to manually delete that old variable's line from the trial script.

• How does it handle variable renames?
  Same as the previous answer, but instead of deleting the variable's line from the script, they would rename the variable if they do not want to regenerate/set up the script again.

• I can forsee situations where a user edits the script manually, and then it becomes out of sync with the design file? How can this be handled?
  This is something I also thought of, but I don't know how to get around it. This is the same problem with other aspects when the user uses a custom script and they have to manually drag it into gameobjects and set other things up. One possible solution could be to discuss this issue in the documentation.

Another solution could be to provide, in the documentation, the lines that are searched for/replaced in each script, for instance in the trial script "// float thisTrialsDistanceValue = (float)Data["MyDistanceFloatVariableName"]; // Read values of independent variables", and explain that this line needs to appear in their custom trial script if they want the script to have its variable automatically set up.

This could be explained and exemplified, but because it is a custom script it then relies on the user to put in some extra effort.

What do you think?

[AdamBebko]

Hmmm. These might cause some issues for people who aren't great at coding. since it would cause issues where their scripts can get out of sync with their design file changes, and the sources of the problems would be not overtly obvious. At least in the current system it gives an error to the correct part of your script, which you can easily change yourself.

A super early version of bmlTUX had something like this, and I decided to take it out. I wanted to minimize bmlTUX caused errors, in favour of the users being the ones making errors. Then it's less of a "Black box", and debugging becomes a bit easier. The cost is a slight annoyance of updating your trial scripts when you rename a variable. But smart programmers could put something like this somewhere:

//List of all variable names, one source of truth means changes in one spot only
const string ColorVariable = "Color";
const string SizeVariable = "Size";

// To actually access variables.
string ColorString => (string) Data[ColorVariable];
float Size => (float) Data[SizeVariable];

Again, I decided against putting this stuff directly in tutorials to make it less complicated to beginners. They probably don't know the value of One Source of Truth, and might not even know the => operator!

A more robust solution I considered is code generation, where every time someone modifies a variable, an autogenerated script is updated with similar code to what you wrote. Then it would stay in sync with the design file, if it was overwritten on each change with a correct new file. I decided this would be too much work to make the slight annoyance worthwhile.

Happy to hear your thoughts on this.

[AdamBebko]

I'm going to close this for now, pending future discussions. Feel free to open it if you have further ideas. I appreciate the input a lot! It's definitely a weak point of bmlTUX, but its a lesser-of-two-evils situation, that I considered heavily during development. Balancing good coding practices with noob-friendliness.