Compiled c library with functions and data structures for handling task parameters.

Summary

The current TaskParameters file version if v8.1.0. The versioning is more "advanced" than other repos and that reflects the carry-over on previous iterations of the task which did use the same or similarly-organized parameters, with the goal of some (limited/user-forced) backwards compatibility.

Task Parameters

Parameter	Default Value	Description
Version	8.1.0	Current file version of parameters.
Subject	Default	Current file version of parameters.
Tag	MID-0	Identifier indicating something qualitative about the current dataset (i.e. which orientation and which run number).
Mode	STANDARD_PRACTICE	See enumerated options in the `DataStructures` repo for valid values.
Orientation	MID	Can be MID, PRO, or SUP (see also: `DataStructures`)
Trials	2500	Maximum trials to run for a single set.
Max Overshoots	1	Maximum allowable trials before failure when moving to T2.
Cursor Radius	8	Cursor radius (pixels).
Target Radius	40	Target radius (pixels).
Line Width	5	Width of lines rendered on screen (pixels). NOT included in "hit" calculations.
Travel Distance	275	Distance traveled from middle of center target to middle of outer target.
Min `T1_HOLD_1` Time	1.000	Minimum number of seconds in the `T1_HOLD_1` state (before T2 appears; see also: `StateServer` for State Machine).
Max `T1_HOLD_1` Time	1.000	Maximum number of seconds in the `T1_HOLD_1` state (before T2 appears; see also: `StateServer` for State Machine). If this is less than or equal to Min `T1_HOLD_1`, then the value of Min `T1_HOLD_1` is always used (non-random; see also: `MathUtilities` for implementation details).
Min `T1_HOLD_2` Time	1.300	Minimum number of seconds in the `T1_HOLD_2` state (before T1 disappears; see also: `StateServer` for State Machine).
Max `T1_HOLD_2` Time	1.500	Maximum number of seconds in the `T1_HOLD_2` state (before T1 disappears; see also: `StateServer` for State Machine). If this is less than or equal to Min `T1_HOLD_2`, then the value of Min `T1_HOLD_2` is always used (non-random; see also: `MathUtilities` for implementation details).
Fixed `REACT` Time	0.250	Number of seconds permitted before trial fails due to sitting in T1 for too long after T1 has disappeared (the "GO" cue). See also: `StateServer`.
Fixed `MOVE` Time	0.800	Number of seconds permitted before trial fails due to taking too long to reach T2 after the "GO" cue. See also: `StateServer`.
Fixed `OVERSHOOT` Time	0.500	Number of seconds permitted to return to T2 after entering then exiting it, before the trial fails. This is also used for a "soft" reset for T1, but overshoots of T1 prior to `T1_HOLD_2` do not count as a failure. See also: `StateServer`.
Fixed `T2_HOLD_1` Time	0.500	Number of seconds required to hold in T2 to successfully complete the trial. See also: `StateServer`.
Fixed `T2_HOLD_2` Time	0.300	Number of seconds delay after receiving the reward, to allow reward consumption. See also: `StateServer`.
N Trials Before Increase	50	Number of trials allowed before increasing the reward amount by the fixed increment defined in the `Volume Increase` parameter.
Volume Increase	0.010	Number of mL to increase the reward size by every `N Trials Before Increase` trials.
Reward Volume	0.210	Initial reward volume (mL) for each successful trial, prior to any increases.
Bribe Volume	0.150	Size of "bribe" rewards (mL) that can be dispensed on an ad hoc basis.
X Gain	1.00	The gain on scaling of pixels relative to the full range-of-motion x-axis calibration. Increasing this value causes the cursor to move more horizontal pixels for the same angular displacement of the x-axis potentiometer.
Y Gain	1.00	The gain on scaling of pixels relative to the full range-of-motion y-axis calibration. Increasing this value causes the cursor to move more vertical pixels for the same angular displacement of the y-axis potentiometer.
RNG Seed	1708628427	Unsigned integer that is the random number seed by default. This can be used to help reproduce the order of targets/trial durations, etc.

Compiling

Libraries

To re-compile the static link library (.lib), use the following command:

cd %NML_NHP_C_PROJECTS%/TaskParameters && gcc -c src/parameters.c -o lib/parameters.o -Iinclude && ar rcs lib/TaskParameters.lib lib/parameters.o && cp src/parameters.h ../StateServer/include/parameters.h && cp lib/TaskParameters.lib ../StateServer/lib/TaskParameters.lib && cp src/parameters.h include/parameters.h && cp src/parameters.h ../TaskController/include/parameters.h && cp lib/TaskParameters.lib ../TaskController/lib/TaskParameters.lib && doxyincrement.bat && doxygen > %NML_NHP_C_PROJECTS%/doxygen_output.log

Applications

To test that parameters are generated/parsed correctly, it is recommended to first compile and run the executables for generating and test-reading the parameters. First, use bin/gen_params.exe to produce an example parameters file; then, use bin/test_params.exe to read the example.tsv file produced by bin/gen_params.exe and return example_new.tsv to indicate the ability to successfully copy and output the same values into a second UTF-8 encoded file.

`gen_params.exe`

To re-compile the parameter generator application bin/gen_params.exe, use the following command:

gcc src/gen_params.c -Iinclude -o bin/gen_params.exe -Llib -lTaskParameters -lDataStructures

`test_params.exe`

To re-compile the test parameter application bin/test_params.exe, use the following comand:

gcc tests/test_parameters.c -Iinclude -Llib -lTaskParameters -lDataStructures -obin/test_params.exe

(Note that this requires having already compiled lib/TaskParameters.lib as shown above).

For External Use

Assume we have the following project folder structure:

my_project
|--src
|  |--my_code.c
|  |--my_code.h
|
|--include
|  |--data_structures.h
|  |--parameters.h
|
|--lib
|  |--DataStructures.lib
|  |--TaskParameters.lib

To compile, you would use the following command:

gcc -o bin/my_executable.exe src/my_code.c -Llib -Iinclude -lTaskParameters -lDataStructures

_(Note 1: you do not link the DataStructures library during the static compilation of lib/TaskParameters.lib; however, since TaskParameters includes DataStructures, it must be linked during compilation of any executable that uses TaskParameters as indicated above; -lTaskParameters should be linked before -lDataStructures in the options order as shown)._

_(Note 2: the #include data_structures.h directive must come before the #include parameters.h directive in my_code.h)_

Note about gcc

Note that to use gcc on a Windows 64-bit architecture, the simplest way is to download msys2, which will allow you to use pacman from an msys2 terminal. You can first check to see if you already have gcc installed:

pacman -Q | grep mingw-w64-x86_64-gcc

If you see anything in the terminal following this command, it means you already have gcc. Otherwise, you need to install it (and probably the rest of the toolchain, such as a linker etc.):

pacman -S mingw-w64-x86_64-toolchain

This will give several options for what you can install. If you are unsure what to do, just install all of them.
Finally, you may also want a toolchain for compiling 32-bit applications from your 64-bit Windows operating system. In that case, you can try:

(bash)

pacman -S mingw-w64-i686-toolchain

The last step is to make sure the folder with the correct binaries are on your PATH environment variable. Probably the best strategy here, on a Windows device, is as follows:

Open the Start menu and type Environment, this should bring up a Control Panel shortcut to "Edit the System Environment Variables." Click that.
Click "Environment Variables..." at the bottom right.
Under System Variables, click "New..." and define a new environment variable: MINGW_PATH. If you installed msys2 in the default location, then go to C:/mingw64. You will be looking for the sub-folder containing binaries. In my install, that is located at C:\msys64\mingw64\bin – so that is my MINGW_PATH environment variable.
Under User Variables, find Path. Click Edit... with Path selected.
In the new popup, click New to add a new Path value. Enter MINGW_PATH%. Now, you can add or remove MINGW_PATH% from the user Path variable depending on what compiler needs you have. Click on the newly added value, and click Move Up until it is at the top of the list. This ensures we don't accidentally find gcc somewhere else and use a different unintended version. Note that if you want to switch between i.e. C:\msys64\mingw32\bin and C:\msys64\mingw64\bin it might just be easiest to change the value of MINGW_PATH environment variable.