~~DISCUSSION~~

=== Module 1: Setting up ===

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:
  * [[http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1000424|Noble, A Quick Guide to Organizing Computational Biology Projects]] ([[http://www.ploscompbiol.org/article/fetchObject.action?uri=info%3Adoi%2F10.1371%2Fjournal.pcbi.1000424&representation=PDF|direct link to pdf]])
  * [[http://www.youtube.com/GitHubGuides|Introduction to version control with GitHub]] ([[http://git-scm.com/book/en/Getting-Started-Git-Basics|more detailed doc pages]], [[http://stackoverflow.com/questions/tagged/git|git tagged questions on StackOverflow]], [[https://github.s3.amazonaws.com/media/progit.en.pdf|Pro Git manual]], surprisingly readable)
  * MATLAB documentation on [[http://www.mathworks.com/help/matlab/matlab_env/understanding-file-locations-in-matlab.html|File Locations]] and [[http://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html#br8ch8o|Search Paths]]

=== Setting up GitHub ===

%%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 [[http://windows.github.com/|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 [[https://help.github.com/articles/set-up-git|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 [[https://github.com/mvdm/nsb2014|here]] (for the hippocampus ensemble decoding tutorial, van der Meer) and [[https://github.com/fieldtrip/fieldtrip|here]] (for the %%FieldTrip%% tutorial, Womelsdorf).

=== Cloning the codebase ===

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 [[https://github.com/mvdm/nsb2014|repository]].

Now, clone the ''nsb2014'' repository and ''cd'' to it:

<code>
git clone https://github.com/mvdm/nsb2014.git
cd nsb2014
</code>

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:

<code>
git pull
</code>

Next, you can do the same thing for the [[https://github.com/fieldtrip/fieldtrip|FieldTrip code]]. Before doing so make sure that you are in the root %%GitHub%% folder, rather than in the ''nsb2014'' folder!

<code>
git clone https://github.com/fieldtrip/fieldtrip.git
</code>
=== Configuring MATLAB to use the code from GitHub ===

Open MATLAB and [[http://www.mathworks.com/help/matlab/matlab_env/create-matlab-shortcuts-to-rerun-commands.html | create a shortcut]] titled something like "CoSMo - Hippocampus". The code for the shortcut should be

<code matlab>
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);
</code>

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 [[http://www.mathworks.com/help/matlab/matlab_prog/regular-expressions.html|regular expressions]] to remove these:

<code>
p = regexprep(p,'D.*?\.git.*?;','');
</code>

Next, create a separate MATLAB shortcut for %%FieldTrip%% by modifying the ''cd'' line in the above example to point to the %%FieldTrip%% folder.
=== Establish a sensible folder structure ===

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

=== Obtaining the data set ===

A ZIP archive of the data set is available [[http://www.vandermeerlab.org/R042-2013-08-18.zip|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!

=== Making sure that things are working ===

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 [[http://blogs.mathworks.com/videos/2011/07/26/starting-in-matlab-cell-mode-scripts/|Cell Mode]] to check that you can load a data file:

<code matlab>
%% 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);
</code>

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.