Goals:

• Use GitHub to acquire the analysis code we will use
• Set up suitable MATLAB paths
• Obtain the tutorial data set and test your path setup

Resources for reference:

• Noble, A Quick Guide to Organizing Computational Biology Projects (direct link to pdf)
• Introduction to version control with GitHub (more detailed doc pages, git tagged questions on StackOverflow, Pro Git manual, surprisingly readable)
• MATLAB documentation on File Locations and Search Paths

GitHub is a system for “distributed version control”: it keeps track of changes to a set of collaboratively edited files, such as pieces of MATLAB code. This system makes it easy to share improvements between collaborators. Most relevant to the CoSMo tutorials here, GitHub makes it possible to easily disseminate code hotfixes to everyone when needed. More generally, however, it is a very valuable tool that you might like to use in your own projects.

Download and install the Git client of your choice if you don't already have one installed. For Windows, I recommend GitHub Windows as a user-friendly way to get started. For more details on installing Git and setting up GitHub on various operating systems, see GitHub: Set Up Git; note that you may need to select “Run as administrator” (Windows) when running the installer.

Next, configure your client. For GitHub Windows, after starting up the GUI, click Tools > Options. Set the “Default Storage Directory” to something reasonable: on vandermeerlab computers, this should be something on the D: drive (for example, D:\My_Documents\GitHub\).

A GitHub account is not necessary for now; not having one means you will only be able to download (“pull”) code, and not be allowed to upload (“push”) changes you make. Feel free to sign up/sign in if you like.

If for some reason you are having trouble with GitHub you can simply download ZIP archives of the code here (for the hippocampus ensemble decoding tutorial, van der Meer) and here (for the FieldTrip tutorial, Womelsdorf).

Once your client is configured, we can create a local copy of the codebase. To do this, first open a shell. In Windows, you can do this from within the GitHub client by selecting “Tools and Options” in the top right and then “Open in Git shell”, or by clicking the “Git shell” icon. Make sure that you are in the GitHub directory. Alternatively, you can click the “Clone in Desktop” link on the repository.

Now, clone the nsb2014 repository and cd to it:

git clone https://github.com/mvdm/nsb2014.git
cd nsb2014

Verify that this has created a nsb2014 folder with various subfolders and files in it, indicating that you have a local copy of the codebase. If at any time during the course the code changes, you can simply “pull” the latest version from GitHub by doing:

git pull

Next, you can do the same thing for the FieldTrip code. Before doing so make sure that you are in the root GitHub folder, rather than in the nsb2014 folder!

git clone https://github.com/fieldtrip/fieldtrip.git

Open MATLAB and create a shortcut titled something like “CoSMo - Hippocampus”. The code for the shortcut should be

restoredefaultpath; % start with a clean slate
 
cd('D:\My_Documents\GitHub\nsb2014\code-matlab'); % replace with your actual path
p = genpath(pwd); % create list of all folders from here
addpath(p);

This ensures that whenever you click this button, you have a “clean” path of only the MATLAB default plus your local version of the GitHub repository.

Note: if you don't like the .git folders in your path that result from the above, you can get clever with regular expressions to remove these:

p = regexprep(p,'D.*?\.git.*?;','');

Next, create a separate MATLAB shortcut for FieldTrip by modifying the cd line in the above example to point to the FieldTrip folder.

So far, you have a local GitHub repository clone added to MATLAB's path. But as you work through the tutorial, you will write your own analysis code. You will also have data files to work with. It is important to consider where all of these files will go, and how you will manage them. I recommend using three separate locations:

• GitHub folders. Files in here you only change (or add) when you can improve what is already there. This content is backed up and version-controlled (i.e. you can see the complete history of changes and revert to any version you want) through the GitHub system. These files can be shared by multiple different projects, including working through these modules, and perhaps a PhD project! For me, this folder is in D:\My_Documents\GitHub\.
• Project folders. Each project has a home folder which holds the code for that project. As explained in the Noble paper linked to above, if you don't want to place this under version control you can simply create a new folder, with the date as the name, for each day you work on the project. If you find you are copying certain functions or snippets of code from day to day, those should be moved to the shared folder. It is critical that the contents of this folder are backed up in case of computer failure. I use Dropbox for this, so an example project folder I have is D:\My_Documents\Dropbox\projects\CoSMo2014\.
• Data folders. Data, both raw and preprocessed, should live in a different place: D:\data\ in my case. This is because different projects may access the same data, and because backup strategies for data are typically different than for code.

With this trifold division, when you want to work on a project, you would click the appropriate MATLAB shortcut for it first. Following the example above, this should add the appropriate GitHub folders to the path. Next, the shared folder of the project is also added to the path. Data is generally not added to the path, because some data files in different folders may have the same name. Then, you create a new folder with today's date, and you are ready to go!

There are several situations when it is appropriate to move code from your project folder to a GitHub folder:

• you improve a piece of code that was already on GitHub
• you have a new piece of code in the shared project folder that is proving useful
• you reach a milestone, such as an analysis that tests a certain hypothesis

A ZIP archive of the data set is available here. Unzip and place this in a sensible location, such as C:\data\HCdecoding\. Do not place it in the same folder as your analysis code!

Xreate a folder with today's date in your project folder (an approach motivated in the Noble paper linked to above). Create a sandbox.m file in it, and use Cell Mode to check that you can load a data file:

%% load data
cd('C:\Data\HCdecoding\R042-2013-08-18'); % replace this with where you saved the data
 
cfg = [];
cfg.fc = {'R042-2013-08-18-CSC03a.ncs'}; % cell array with filenames to load
csc = LoadCSC(cfg);

Of course, this will only work if you first click the “Hippocampus” shortcut you created above. To test your FieldTrip setup, proceed to the tutorial webpage.