Utility Library - Helpers and Utilities¶
This library contains utility functions for file operations, data management, and common helper tasks.
CalibrateScreen()¶
Description:
Main calibration function Returns custom object with calibration data
Usage:
define CalibrateScreen(win)
ConcatenateList()¶
Combines list
Description:
Combines a list together to form a single string. Like ListToString but defaults to a separator of “ “ (space).
Usage:
define ConcatenateList(...)
Example:
ConcatenateList([1,2,3,444]) # == "1 2 3 444"
ConcatenateList(["a","b","c","d","e"],",") # == "a,b,c,d,e"
See Also:
ConvertIPString()¶
Converts an ip-number-as-string to usable address
Description:
Converts an IP address specified as a string into an integer that can be used by ConnectToIP.
Usage:
define ConvertIPString(...)
Example:
See nim.pbl for example of two-way network connection.
ip <- ConvertIPString("192.168.0.1")
net <- ConnectToHost(ip,1234)
dat <- GetData(net,20)
Print(dat)
CloseNetworkConnection(net)
See Also:
CR()¶
Description:
Produces <number> linefeeds which can be added to a string and printed or saved to a file. CR is an abbreviation for Carriage Return.
Usage:
define CR(...)
Example:
Print("Number: " Tab(1) + number + CR(2))
Print("We needed space before this line.")
See Also:
DirlistToText()¶
Description:
appends a set of nested directories into a path.
Usage:
define DirlistToText(list)
DrawObject()¶
Calls the .draw property of an object
Description:
Calls the function named by the .draw property of a custom object. Useful for handling drawing of a bunch of different objects. This is essentially the same as CallFunction(obj.draw, [obj]), but falls back to a normal Draw() command so it handles built-in objects as well.
Usage:
define DrawObject(...)
Example:
##This overrides buttons placement at the center:
done <- MakeButton("QUIT",400,250,gWin,150)
WaitForClickOnTarget([done],[1])
Clickon(done,gClick)
DrawObject(done)
See Also:
Inside(), ClickOnCheckbox(), MoveObject(), Draw()
EasyLabel()¶
Description:
Creates and adds to the window location a label at specified location. Uses standard vera font with grey background. (May in the future get background color from window). Easy-to-use replacement for the MakeFont, ~``MakeLabel``, ~ AddObject, ~ Move, steps you typically have to go through. The optional argument fontsize defaults to 16-point. The optional argument fg specifies a color name (e.g., "red") to use, and style specifies the font style, where 0,1,2,3 = normal, italic, bold, bolditalic.
Usage:
define EasyLabel(...)
Example:
win <- MakeWindow()
lab <- EasyLabel("What?",200,100,win)
Draw()
lab <- EasyLabel("What?",200,100,win,12)
See Also:
EasyTextBox()¶
Description:
Creates and adds to the window location a textbox at specified location. Uses standard vera font with white background. Easy-to-use replacement for the MakeFont,MakeTextBox, AddObject, Move, steps. The optional arguments fgcolor and bgcolor should specify color names (like white and black). By default, the textbox is created with a foreground of "black" and a background of "white".
Usage:
define EasyTextBox(...)
Example:
win <- MakeWindow()
entry <- EasyTextBox("1 2 3 4 5",200,100,
win,12,200,50)
Draw()
entry <- EasyTextBox("1 2 3 4 5",200,100,
win,12,200,50,"red","blue")
Draw()
See Also:
EndsWith()¶
Description:
Parameter file handling - supports both legacy CSV and modern JSON formats¶
Helper function: Check if a string ends with a given suffix Used to detect .json file extensions for parameter files
Usage:
define EndsWith(string, suffix)
Enquote()¶
Returns string surrounded by quote marks.
Description:
Surrounds the argument with quotes.
Usage:
define Enquote(...)
Example:
##use to add quoted text to instructions.
instructions <- "Respond whenever you see an "+
Enquote("X")
##Use it for saving data that may have spaces:
resp <- GetInput(tb, "<enter>")
FilePrint(fileout, Enquote(resp))
See Also:
gQuote
FetchText()¶
Description:
Helper function: Fetch text from URL or local file Handles both http:// URLs and local file paths
Usage:
define FetchText(source)
FilePrintList()¶
Description:
Prints a list to a file, without the ‘,’s or [] characters. Puts a carriage return at the end. Returns a string that was printed. If a list contains other lists, the printing will wrap multiple lines and the internal lists will be printed as normal. To avoid this, try FilePrintList(file,Flatten(list)).
Usage:
define FilePrintList(...)
Example:
FilePrintList(fstream, [1,2,3,4,5,5,5])
##
## Produces:
##1 2 3 4 5 5 5
FilePrintList(fstream,[[1,2],[3,4],[5,6]])
#Produces:
# [1,2]
#,[3,4]
#,[5,6]
FilePrintList(fstream,Flatten([[1,2],[3,4],[5,6]]))
#Produces:
# 1 2 3 4 5 6
See Also:
Print(), Print_(), FilePrint(), FilePrint_(), PrintList(),
FormatText()¶
Description:
this works at replacing carriage returns (n) etc. from text
Usage:
define FormatText(text)
GetEasyChoice()¶
Simple multiple choice
Description:
Hides what is on the screen and presents a textbox with specified message, and a series of options to select from. Returns element from corresponding position of the <output> list.
Usage:
define GetEasyChoice(...)
Example:
The code snippet below produces the following screen: gWin <- MakeWindow("white")
inp <- GetEasyChoice("What Year are you in school",
["First-year","Sophomore",
"Junior","Senior","Other"],
[1,2,3,4,5], gWin)
See Also:
GetEasyInput()¶
Gets typed input based on a prompt.
Description:
Hides what is on the screen and presents a textbox with specified message, and a second text box to enter input. Continues when ‘enter’ it hit at the end of text entry.
Usage:
define GetEasyInput(...)
Example:
gWin <- MakeWindow()
inp <- GetEasyInput("Enter Participant ID Code",gWin)
See Also:
GetEasyMultiChoice()¶
Simple select-multiple choice
Description:
The minchoices and maxchoices gives the range of the number of choices permitted.
Usage:
define GetEasyMultiChoice(text,choices,output,win,minchoices:1, maxchoices:1)
GetNewDataFile()¶
Opens a data file in subnum directory
Description:
Creates a data file for output, asking for either append or renumbering the subject code if the specified file is already in use.
Usage:
define GetNewDataFile(...)
Example:
file1 <- GetNewDataFile("1",gWin,"memorytest","csv",
"sub,trial,word,answer,rt,corr")
##above creates a file data\1\memorytest-1.csv
file2 <- GetNewDataFile("1",gWin,"memorytest","csv",
"sub,trial,word,answer,rt,corr")
# above will prompt you for new subject code
file3 <- GetNewDataFile("1",gWin,"memorytest-report","txt",
"")
##No header is needed on a text-based report file.
See Also:
GetNIMHDemographics()¶
Asks NIMH-related questions
Description:
Gets demographic information that are normally required for NIMH-related research. Currently are gender (M/F/prefer not to say), ethnicity (Hispanic or not), and race (A.I./Alaskan, Asian/A.A., Hawaiian, black/A.A., white/Caucasian, other). It then prints their responses in a single line in the demographics file, along with any special code you supply and a time/date stamp. This code might include a subject number, experiment number, or something else, but many informed consent forms assure the subject that this information cannot be tied back to them or their data, so be careful about what you record. The file output will look something like:
---- 31,Thu May 12 17:00:35 2011,F,hisp,asian,3331 32,Thu May 12 22:49:10 2011,M,nothisp,amind,3332 ----
The first column is the user-specified code (in this case, indicating the experiment number). The middle columns indicate date/time, and the last three columns indicate gender (M, F, other), Hispanic (Y/N), and race.
Usage:
define GetNIMHDemographics(...)
Example:
GetNIMHDemographics("x0413", gwindow,
"x0413-demographics.txt")
GetSubNum()¶
Asks user to enter subject number
Description:
Creates dialog to ask user to input a subject code
Usage:
define GetSubNum(...)
Example:
## Put this at the beginning of an experiment,
## after a window gWin has been defined.
##
if(gSubNum == 0)
{
gSubNum <- GetSubNum(gWin)
}
Note: gSubNum can also be set from the command line.
GetTranslations()¶
Loads multilingual translations with automatic language fallback
Description:
Automatically loads translation strings for experiments from JSON translation files. Implements a three-tier fallback system: (1) uses explicitly specified language if file exists, (2) falls back to system locale language if available, (3) defaults to English if no other translations are found. Normalizes all language codes to lowercase 2-letter codes (e.g., “en”, “es”, “ar”). Returns a custom object with translated strings as properties that can be accessed throughout the experiment.
Usage:
GetTranslations(testname, lang)
Example:
##Load translations with explicit language
gLanguage <- "es" ##Spanish
gStrings <- GetTranslations("stroop", gLanguage)
MessageBox(gStrings.instructions, gWin)
##Let it auto-detect from system locale
gLanguage <- "" ##Empty means use system locale
gStrings <- GetTranslations("flanker", gLanguage)
##Will try system language, fall back to English
##Translation files are expected at:
##translations/stroop.pbl-es.json
##translations/stroop.pbl-en.json
##etc.
See Also:
ReadTranslationJSON(), ReadTranslation(), GetSystemLocale(), Lowercase()
InitializeUpload()¶
Description:
Token-based multi-test hosting support¶
Initialize token-based upload configuration for uploading on emscipten branch.
This is only needed on emscripten to set up the virtual file system to store data in an easy-to-retrieve way. On native platforms, the Upload
Call this at the start of battery tests that will be hosted online Reads upload.json (written by JavaScript launcher) and sets up: - gToken: Study identifier - gTestName: Test name (e.g., “stroop”, “flanker”) - gUploadURL: Server endpoint for data upload (not needed here) - gParticipant: Participant ID - gDataDirectory: Centralized data path: /data/{token}/{test}/{participant}/ - gUploadSettings: Full configuration object - gUseUpload: Flag indicating token mode is active
Usage:
define InitializeUpload(file:"")
Inside()¶
Determines whether a point is inside a graphical object
Description:
Determines whether an [x,y] point is inside another object. Will operate correctly for rectangles, squares, circles, textboxes, images, and labels. For custom objects having a function name bound to their .inside property, it will use that function to test for insideness. [xylist] can be a list containing [x,y], and if it is longer the other points will be ignored (such as the list returned by WaitForMouseButton(). Returns 1 if inside, 0 if not inside.
Usage:
define Inside(...)
Example:
button <- EasyLabel("Click me to continue", 100,100,gWin,12)
continue <- 1
while(continue)
{
xy <- WaitForMouseButton()
continue <- Inside(xy,button)
}
See Also:
IsURL()¶
Description:
Helper function: Check if a string is a URL Used to detect http:// or https:// URLs for remote parameter loading
Usage:
define IsURL(string)
JSONText()¶
Description:
this will print the JSON object in a format that can be saved. It requires an PCustomObject, which is created with ParseJSON() function.
Usage:
define JSONText(obj, indent:0)
LikertTrial()¶
Description:
These helper functions require gTextBox, gHeader, and gFooter to work.
Usage:
define LikertTrial(text)
ListToHumanText()¶
Description:
Converts a list of a text listing of options
Usage:
define ListToHumanText(...)
Example:
ListToHumanText([1,2,3,444])
"1, 2, 3, or 444"
ListToHumanText(["a","b","c","d","e"],"and")
"a, b, c, d, and e"
See Also:
Lookup()¶
Description:
Returns element in <database> corresponding to element of <keylist> that matches <key>. If no match exists, Match returns an empty list.
Usage:
define Lookup(...)
Example:
keys <- [1,2,3,4,5]
database <- ["market","home","roast beef",
"none","wee wee wee"]
Print(Lookup(3,keys,database)))
## Or, do something like this:
data <- [["punky","brewster"],
["arnold","jackson"],
["richie","cunningham"],
["alex","keaton"]]
d2 <- Transpose(data)
key <- First(data)
Print(Lookup("alex", key, data))
##Returns ["alex","keaton"]
See Also:
MakeParameterObject()¶
Description:
This creates an object called ‘parameters’ with property-value pairs specified by pairs, and will load duplicate properties into lists.
Usage:
define MakeParameterObject(pairs)
MessageBox()¶
Pops up a message, overtop the entire screen, and waits for a click to continue.
Description:
Hides what is on the screen and presents a textbox with specified message, with a button to click at the bottom to continue. All arguments after window are optional, but permit changing the size of the text box, (left and right separately), removing the background, and allowing keyboard responses to advance. By default, if acknowledgement is set to <OK>, the messagebox will continue when the mouse button clicks an on-screen button labeled OK. If set to a key (e.g., ‘x’), it will continue when that key is pressed.
Usage:
define MessageBox(...)
Example:
gWin <- MakeWindow()
MessageBox("Click below to begin.",gWin)
MessageBox("this makes a messagebox filling the left side, permitting
graphics you might have put on the right to be displayed.",
gWin,40,100,gVideoWidth/2,
300,0,"<OK>")
MessageBox("This messagebox allows you to continue by hitting the x or z keys",
gWin,20,100,100,300,1,["X","Z"])
See Also:
GetEasyInput(), EasyTextBox(), PopUpMessageBox()
MoveCenter()¶
Description:
Moves a TextBox to a specified location according to its center, instead of its upper left corner.
Usage:
define MoveCenter(...)
Example:
MoveCenter(TextBox, 33, 100)
See Also:
Move(), MoveCenter(), .X and .Y properties
MoveCorner()¶
Moves an image or label by its upper corner.
Description:
Moves a label or image to a specified location according to its upper left corner, instead of its center.
Usage:
define MoveCorner(...)
Example:
MoveCorner(label, 33, 100)
See Also:
Move(), MoveCenter(), .X and .Y properties
MoveObject()¶
Calls the .move property of an object
Description:
Calls the function named by the .move property of a custom object. Useful if a custom object has complex parts that need to be moved; you can bind .move to a custom move function and then call it (and anything else) using MoveObject. MoveObject will fall back on a normal move, so you can handle movement of many built-in objects with it
Usage:
define MoveObject(...)
Example:
##This overrides buttons placement at the center:
done <- MakeButton("QUIT",400,250,gWin,150)
done.move <- "MoveCorner"
MoveObject(done, 100,100)
See Also:
PrintList()¶
Description:
Prints a list, without the ‘,’s or [] characters. Puts a carriage return at the end. Returns a string that was printed. If a list contains other lists, the printing will wrap multiple lines and the internal lists will be printed as normal. To avoid this, try PrintList(Flatten(list)).
Usage:
define PrintList(...)
Example:
PrintList( [1,2,3,4,5,5,5])
##
## Produces:
##1 2 3 4 5 5 5
PrintList([[1,2],[3,4],[5,6]])
#Produces:
# [1,2]
#,[3,4]
#,[5,6]
PrintList(Flatten([[1,2],[3,4],[5,6]]))
#Produces:
# 1 2 3 4 5 6
See Also:
Print(), Print_(), FilePrint(), FilePrint_(), FilePrintList(),
ReadCSV()¶
Opens a csv file returning a table with its elements
Description:
Reads a comma-separated value file into a nested list. Need not be named with a .csv extension. It should properly strip quotes from cells, and not break entries on commas embedded within quoted text.
Usage:
define ReadCSV(...)
Example:
table <- ReadCSV("datafile.csv")
See Also:
ReadJSONParameters()¶
Description:
Read JSON parameter file and convert to parameter object JSON format: simple key-value pairs, e.g., {“dopractice”: 1, “isi”: 1000} Returns a custom object with parameters as properties Supports both local files and URLs (http:// or https://) Returns empty parameter object if fetch/parse fails (allows fallback to defaults)
Usage:
define ReadJSONParameters(filename)
RemoveObjects()¶
Removes a (possibly nested) list of objects from a parent window
Description:
This is a recursive removeobjects
Usage:
define RemoveObjects(list,win)
ReplaceChar()¶
Description:
Substitutes <char2> for <char> in <string>. Useful for saving subject entry data in a file; replacing spaces with some other character. The second argument can either be a character to match, or a list of characters to match, in which case they all get replaced with the third argument.
Usage:
define ReplaceChar(...)
Example:
x <- ["Sing a song of sixpence"]
rep <- ReplaceChar(x," ", "_")
Print(rep)
# Result: Sing_a_song_of_sixpence
x <- ["sing a song of sixpence"]
rep <- ReplaceChar(x,["s","x"], "p")
Print(rep)
# Result: ping a pong of pippence
See Also:
for list items: Replace() , SplitString(),
SplitStringSlow()¶
Description:
Splits a string into tokens. <split> must be a string. If <split> is not found in <string>, a list containing the entire string is returned; if split is equal to "", the each letter in the string is placed into a different item in the list. The entire text of <split> is used to tokenize, but as a consequence this function is relatively slow, and should be avoided if your string is longer than a few hundred characters.
Usage:
define SplitStringSlow(...)
Example:
SplitStringSlow("Everybody Loves a Clown", " ")
# Produces ["Everybody", "Loves", "a", "Clown"]
SplitStringSlow("she sells seashells", "ll")
#produces ["she se","s seashe", "s"]
See Also:
Splitstring() FindInString(), ReplaceChar()
StripQuotes()¶
Description:
Strips quotation marks from the outside of a string. Useful if you are reading in data that is quoted.
Usage:
define StripQuotes(...)
Example:
text <- gQuote + "abcd" + gQuote
Print(StripQuotes(text)) ## abcd
Print(StripQuotes("aaa")) ##aaa
See Also:
StripSpace()¶
Description:
Strips spaces from the start and end of a string. Useful for cleaning up input and such.
Usage:
define StripSpace(...)
Example:
text <- " abcd "
Print(StripSpace(text)) ## 'abcd'
Print(StripSpace("aaa")) ## 'aaa'
See Also:
Tab()¶
Description:
Produces a tab character which can be added to a string. If displayed in a text box, it will use a 4-item tab stop.
Usage:
define Tab(...)
Example:
Print("Number: " Tab(1) + number )
Print("Value: " Tab(1) + value )
Print("Size: " Tab(1) + size )
See Also:
WaitForClickOnTarget()¶
Waits until any of a set of target objects are clicked.
Description:
Allows you to specify a list of graphical objects in <objectlist> and awaits a click on any one of them, returning the corresponding key in <keylist>. Also, sets the global variable gClick which saves the location of the click, if you need it for something else.
Usage:
define WaitForClickOnTarget(...)
Example:
resp <- Sequence(1,5,1)
objs <- []
loop(i,resp)
{
tmp <- EasyLabel(i +". ",
100+50*i,100,gWin,25)
objs <- Append(objs, tmp)
}
Draw()
click <- WaitForClickOnTarget(objs,resp)
Print("You clicked on " + click)
Print("Click location: [" + First(gClick) +
", " + Second(gClick) + "]")
WaitForClickOnTargetWithTimeout()¶
Description:
Allows you to specify a list of graphical objects in <objectlist> and awaits a click on any one of them, returning the corresponding key in <keylist>. Also, sets the global variable gClick which saves the location of the click, if you need it for something else. The function will return after the specified time limit. If no response is made by timeout, the text <timeout> will be returned (instead of the corresponding keylist element), and gClick will be set to [-1, -1]. This function can also be useful to dynamically update some visual object while waiting for a response. Give timeout some small number (below 50 ms, as low as 1-5), and loop over this repeatedly until a ‘proper’ response is given, redrawing a timer or other dynamic visual element each time. By default, this will only activate when a normal (left-click) is made on button 1. However, the three optional arguments button1, button2, and button3 permit waiting for any or all left, right, or center buttons.
Usage:
define WaitForClickOnTargetWithTimeout(...)
Example:
resp <- Sequence(1,5,1)
objs <- []
loop(i,resp)
{
tmp <- EasyLabel(i +". ",
100+50*i,100,gWin,25)
objs <- Append(objs, tmp)
}
Draw()
click <- WaitForClickOnTargetWithTimeout(objs,resp,3000)
Print("You clicked on " + click)
Print("Click location: [" + First(gClick) +
", " + Second(gClick) + "]")
##wait for a center-click.
click <- WaitForClickOnTargetWithTimeout(objs,resp,3000,0,0,1)
See Also:
WaitForDownClick()¶
Waits for mouse button to be clicked
Description:
Will wait until the mouse button is clicked down. Returns the same 4-tuple as WaitForMouseButton:
[xpos, ypos, button id [1-3], "<pressed>" or "<released>"]
but the last element will always be ``<pressed>``. Useful as a 'click mouse to continue' probe.
Usage:
define WaitForDownClick(...)
Example:
x <- WaitForDownClick()
Print("Click location: [" + First(x) +
", " + Second(x) + "]")
See Also:
YesNoTrial()¶
Description:
These helper functions require gTextBox, gHeader, and gFooter to work.
Usage:
define YesNoTrial(text)
ZeroPad()¶
Pads the beginning of a number with 0s so the number is size long
Description:
Takes a number and pads it with zeroes left of the decimal point so that its length is equal to <size>. Argument must be a positive integer and less than ten digits. Returns a string.
Usage:
define ZeroPad(...)
Example:
Print(ZeroPad(33,5)) # "00033"
Print(ZeroPad(123456,6)) #"123456"
Print(ZeroPad(1,8)) #"00000001"
See Also:
Functions Pending Documentation¶
AppendDirList()¶
Manages a list of directories for path navigation
Description:
Appends a directory to a directory list, handling special directory names like “.” (current directory) and “..” (parent directory). When “..” is encountered, it removes the last directory from the list (going up one level). When “.” is encountered, the list remains unchanged. Regular directory names are simply appended. Useful for building and navigating directory paths dynamically.
Usage:
define AppendDirList(dirlist, dir)
Example:
# Build a directory path dynamically
dirs <- []
dirs <- AppendDirList(dirs, "data") # ["data"]
dirs <- AppendDirList(dirs, "exp1") # ["data", "exp1"]
dirs <- AppendDirList(dirs, "results") # ["data", "exp1", "results"]
dirs <- AppendDirList(dirs, "..") # ["data", "exp1"] (go up)
dirs <- AppendDirList(dirs, "analysis") # ["data", "exp1", "analysis"]
# Current directory is ignored
dirs <- AppendDirList(dirs, ".") # ["data", "exp1", "analysis"] (unchanged)
See Also:
CreateParameters()¶
Creates a parameter object from defaults and an optional parameter file
Description:
Creates a parameter object by combining default values with parameters from a file. Supports both legacy CSV format (.par) and modern JSON format (.par.json). Can load parameters from local files or remote URLs (http:// or https://). If the file doesn’t exist or a URL cannot be fetched, only the defaults are used. Parameters from the file override defaults.
The function auto-detects file format based on extension: .json files (and all URLs) use JSON format, while .par files use legacy CSV format.
Usage:
define CreateParameters(defaults, file)
Example:
# Create parameters with defaults and local file
defaults <- [["trials", 20], ["isi", 1000], ["practice", 1]]
pars <- CreateParameters(defaults, "config.par.json")
# Now pars.trials, pars.isi, pars.practice are available
Print("Running " + pars.trials + " trials")
# Load from URL (uses JSON format automatically)
pars <- CreateParameters(defaults, "https://example.com/params.json")
# If file doesn't exist, defaults are used
pars <- CreateParameters(defaults, "nonexistent.json")
# pars still has default values
See Also:
DirToText()¶
Converts directory and file lists into path strings
Description:
Combines a list of directories and a list of filenames into complete path strings. Prepends directory names with backslashes and merges them with the filelist. This is a helper function for path manipulation when working with directory structures.
Usage:
define DirToText(dirlist, filelist, path)
Example:
# Combine directory components with files
dirs <- ["data", "experiment1"]
files <- ["trial01.csv", "trial02.csv"]
paths <- DirToText(dirs, files, "")
# Results in paths with directory prefixes
loop(p, paths)
{
Print(p)
}
See Also:
GetDirectory()¶
Extracts the directory path from a file path
Description:
Extracts and returns the directory portion of a file path, including the trailing separator. The function automatically detects the appropriate separator based on the platform (backslash for Windows, forward slash for Unix/Linux/Mac). Returns all but the last component (the filename). Useful for getting the parent directory of a file or for constructing new file paths in the same directory.
Usage:
define GetDirectory(filepath)
Example:
# Extract directory from file path
dir <- GetDirectory("data/experiment/results.csv")
Print(dir)
# Result: "data/experiment/" (on Unix/Linux/Mac)
# Works automatically on Windows too
dir <- GetDirectory("C:\Users\Lab\data\subject01.txt")
Print(dir)
# Result: "C:\Users\Lab\data\" (on Windows)
# Use with other path operations
filepath <- "results/trial-data.csv"
directory <- GetDirectory(filepath)
newfile <- directory + "summary-data.csv"
# newfile is "results/summary-data.csv"
# Common use case: creating pooled data files
fileOut <- GetNewDataFile(gSubnum, gWin, "test", "csv", "header")
dir <- GetDirectory(fileOut.filename) + "../"
pooledFile <- FileOpenAppend(dir + "pooled-results.csv")
See Also:
GetNewSubNum()¶
Requests a new subject number from a remote server
Description:
Connects to a remote PEBL data server to request and receive a new unique subject number for data collection. The server maintains a counter and returns sequential subject codes. If the server connection fails, a random 6-digit number is returned as a fallback. Used in labs or online studies where centralized subject numbering is needed across multiple testing stations or sessions.
Usage:
define GetNewSubNum(server, page, port, username, pword)
Example:
# Get new subject number from server
server <- "data.mylab.edu"
page <- "get_subject_id.php"
port <- 80
username <- "labuser"
password <- "secure_password"
gSubNum <- GetNewSubNum(server, page, port, username, password)
Print("Assigned subject number: " + gSubNum)
# Use subject number for data files
datafile <- FileOpenWrite("data/" + gSubNum + "/results.csv")
See Also:
ReadTranslation()¶
Loads multilingual text from a CSV translation file
Description:
Reads a CSV-format translation file containing text strings in multiple languages. Creates a custom object with text strings as properties that can be accessed in experiments. Useful for creating experiments that can be presented in different languages. The CSV file should have text keys in the first column and translated text in subsequent columns. Line breaks (\n) in the file are converted to actual carriage returns.
Usage:
define ReadTranslation(filename, lang)
Example:
# Load English translations from CSV file
# translations.csv contains:
# welcome,Welcome to the experiment
# instructions,Please press any key to begin
# thanks,Thank you for participating
trans <- ReadTranslation("translations-en.csv", "en")
MessageBox(trans.welcome, gWin)
MessageBox(trans.instructions, gWin)
# Run experiment...
MessageBox(trans.thanks, gWin)
See Also:
ReadTranslationJSON()¶
Loads multilingual text from a JSON translation file
Description:
Reads a JSON-format translation file containing text strings in multiple languages. Creates a custom object with text strings as properties that can be accessed in experiments. This is the modern alternative to ReadTranslation() with better support for complex text and special characters. The JSON file should contain key-value pairs where keys are text identifiers and values are the translated strings. Line breaks (\n) in the JSON are converted to actual carriage returns.
Usage:
define ReadTranslationJSON(filename, lang)
Example:
# Load English translations from JSON file
# translations-en.json contains:
# {
# "welcome": "Welcome to the experiment",
# "instructions": "Please press any key to begin",
# "thanks": "Thank you for participating"
# }
trans <- ReadTranslationJSON("translations-en.json", "en")
MessageBox(trans.welcome, gWin)
MessageBox(trans.instructions, gWin)
# Run experiment...
MessageBox(trans.thanks, gWin)
See Also:
SubstituteStrings()¶
Makes multiple substitutions in text
Description:
Performs multiple character substitutions in a text string. Takes a list of replacement pairs and applies each one sequentially using ReplaceChar(). Useful for cleaning up text, converting special characters, or applying multiple text transformations at once.
Usage:
define SubstituteStrings(text, replist)
Example:
# Replace multiple characters for file-safe names
text <- "Subject: John Doe (Test #1)"
replacements <- [[" ", "_"], [":", "-"], ["(", "["], [")", "]"], ["#", "num"]]
cleaned <- SubstituteStrings(text, replacements)
Print(cleaned)
# Result: "Subject-_John_Doe_[Test_num1]"
# Convert special characters in user input
userInput <- "Hello\nWorld!"
subs <- [["\n", " "], ["!", "."]]
formatted <- SubstituteStrings(userInput, subs)
Print(formatted)
# Result: "Hello World."
See Also:
SyncDataFile()¶
Synchronizes a data file with a remote server using HTTP POST
Description:
Uploads a data file to a remote server using HTTP POST with multipart/form-data encoding. Sends authentication credentials, task name, subject code, and optional authorization token along with the file contents. Used for real-time data synchronization during experiments or for batch uploads to a PEBL data collection server. Returns the server’s HTTP response.
Usage:
define SyncDataFile(server, page, port, username, pword, taskname, subcode, datafilename, token: "")
Example:
# Sync data file to server after each trial block
server <- "data.mylab.edu"
page <- "sync_data.php"
port <- 80
username <- "labuser"
password <- "secure_password"
taskname <- "stroop_task"
subcode <- gSubNum
datafile <- "data/" + subcode + "/block1.csv"
response <- SyncDataFile(server, page, port, username,
password, taskname, subcode, datafile)
Print("Server response: " + First(response))
# With authorization token for secure studies
token <- "study_auth_token_12345"
response <- SyncDataFile(server, page, port, username, password,
taskname, subcode, datafile, token)
See Also:
UploadFile()¶
Uploads a data file to a remote server
Description:
Uploads experimental data files to a remote server for centralized data collection. Only operates when the --upload command-line flag is used with PEBL. Reads server configuration from a JSON settings file containing host, page, port, and authentication details. If no_upload flag is set in settings or the file doesn’t exist, upload is skipped. Useful for online experiments or multi-site studies requiring automatic data upload.
Usage:
define UploadFile(subcode, datafilename, settings: "")
Example:
# Upload data file after experiment completes
# Run PEBL with: pebl experiment.pbl --upload upload.json
#
# upload.json contains:
# {
# "host": "data.mylab.edu",
# "page": "upload.php",
# "port": 80,
# "username": "labuser",
# "password": "secure_password"
# }
gSubNum <- "101"
datafile <- "data/" + gSubNum + "/results.csv"
# Upload will only happen if --upload was specified
UploadFile(gSubNum, datafile)
# Or specify custom settings file
UploadFile(gSubNum, datafile, "custom_upload.json")
See Also:
ClickOn()¶
Description:
Calls the function named by the .clickon property of a custom object. Useful for handling click events of a bunch of different objects. This is essentially the same as CallFunction(obj.clickon, [obj,gClick]).
Usage:
Clickon(obj,[x,y])
Example:
##This overrides buttons placement at the center:
done <- MakeButton("QUIT",400,250,gWin,150)
WaitForClickOnTarget([done],[1])
Clickon(done,gClick)
See Also:
Countdown()¶
Description:
Displays a 3-2-1 countdown on the screen in with 500 ms ISI. CountDown temporarily hides whatever is on the screen. It is useful in orienting participants to the first trial of a task. The second argument (useBackground) is true (1) by default. In this case, the entire screen will be hidden with a black overlay. If set to 0, this overlay will not be made.
Usage:
CountDown(win)
CountDown(win,(optional)useBackground)
Example:
win <- MakeWindow()
MessageBox("Press any key to begin",win)
CountDown(win)
Trial()
CountDown(win,0)
Trial
See Also:
GetInput()¶
Description:
Allows user to type input into a textbox.
Usage:
GetInput(<textbox>,<escape-key>)
See Also:
SetEditable(), GetCursorPosition(), MakeTextBox(), SetText()