BrainStreamPathsFolders

Paths and Folders

All files (e.g. functions or figures) and folders that are used in your experiment must be on the [Matlab search path].

Adding folders to the search path

At startup, BrainStream adds the BrainStream core folder and nearly all its subfolders to the search path. If you need additional files or folders, you must make sure they are added to the search path. It is possible to specify these folders in the block file under the keys [.DocsSectionsBlockFile#TopicExperiment MatlabPathFnc] or [.DocsSectionsBlockFile#TopicExperiment MatlabPathAdd]. Alternatively, you can use Matlab's [addpath] function to add individual folders. If you want to add a folder with all its subfolders, use addpath in combination with [genpath]:

addpath(pwd);          %adds the current working directory to the search path
addpath(genpath(pwd)); %adds the current working directory and all its subfolders to the search path 

It is often useful to write a user defined function that adds all necessary paths and execute this function at the start of the experiment (e.g. at the BS_INIT marker). For example, if the experiment needs access to functions that are located in the folder /Volumes/BCI/my_functions, you could make a function:

function event = add_folder(event)
addpath(fullfile('Volumes','BCI','my_functions')); % add my_functions folder to the Matlab search path

Then execute this function at the BS_INIT marker:

Actions Table
marker	time	function
BS_INIT	EVENT	add_folder

Tip: Use the fullfile function

It is recommended to use Matlab's [fullfile] function when you specify a file or folder. This ensures that the proper folders will be added on computers with different operating systems, as different systems may use either '/' or '\' as a file separator.

Tip: Use relative path names

It is recommended to use relative path names when you specify a folder, whether it is in the blocksettings or in functions like addpath. This means that you specify the path name of the folder you want to add relative to a folder of which the location is already known. The advantage of using relative path names is that the proper folders will be added also if you work on a different computer.

In BrainStream, you can make use of the [.DocsSectionsProgrmmersGuide#bs_folder bs_folder] function. For example, with input argument 'BLOCK', the output of this function is the path to the folder containing the block file of the experiment. If the block file is located in '/Volumes/BCI/my_bci/blockfile', and you want to add a folder which contains your functions and is located in '/Volumes/BCI/my_bci/functions', you can specify this folder like this:

functionfolder = fullfile(bs_folder('BLOCK'),..,'functions') % N.B. the '..' expression means going up one level

Output folders

BrainStream saves output in the folder specified in the [.DocsSectionsBuildingExperiments#SecBlock block file] under topic Files and key [.DocsSectionsBlockFile#KeyOutFolder OutFolder].

The output folder contains:

subject folders: a separate folder is created for each new subject. The folder has the subject's name.

session folders: a separate folder is created for each session with the same subject. The folder's name is the date of the session (YYYYMMDD).

This folder contains the most recently saved version of user defined variables. This is the folder where BrainStream looks for variables when a 'load' statement is specified in the Actions table.

run folders: a separate runfolder is created for each block within the experiment. The name of the folder is the name of the block followed by _ and a number indicating how many times this block has been repeated. Each runfolder contains:

module folders: Each module stores its results in a separate folder named accordingly. Brain Stream always stores its result in the 'main' module.

[.DocsSectionsLogFile log file]: gives an overview of everything that happened during your experiment.

brainstream folder: contains copies of the user defined variables that have been saved with a 'save' statement in the Actions table.

expdefs folder: contains copies of the experiment definition tables and blocksettings.

raw_bdf folder: contains the raw EEG data.