Installation

Before you start

You will need a relatively powerful desktop machine. The pipeline is mainly IO-bound and won't need ridiculous quantities of RAM or unusual numbers of cores. The following will work just fine:

• CPU: i7-3930K, i7-5960X, or i7-4820 or similar.

• RAM: 32 GB is sufficient for 1 micron per pixel data sets and 64 GB will be adequate for 0.5 micron per pixel sets. These numbers are generous and assume 200 tiles per plane. Use more RAM if multiple people are likely to be using the machine at once.

• We use X99 motherboards which will take 128 GB of RAM.

• Storage: We run with at least four platter drives using btrfs (software) RAID. 8 TB total local storage is generally adequate for us. You might want more.

  SSDs are expensive and not necessary since stitching will be an order of magnitude faster than acquisition with the above setup.

We have had good results running with Ubuntu 16.04 and 18.04. Some aspects of the pipeline do not currently run on Windows. You will need MATLAB R2018a or later, with the the statistics, parallel computing, and image processing toolboxes.

Cloning the repository

The first thing you need to do is get StitchIt's code onto you machine. On the project's main page is a green button near the top right of the screen that says "Clone or download". From here you can download a zip file containing StitchIt or, much better, clone StitchIt using Git. If you plan on seriously using StitchIt you should definitely clone it with Git. StitchIt receives regular updates and Git makes it easy to keep track of these and stay up to date. To clone and stay up to date with Git do the following:

• Download and install free Git client such as http://www.syntevo.com/smartgit/ or GitHub Desktop.

• Clone the repository using the URL you see when you press the green "Clone or download" button. SmartGit instructions GitHub Desktop.

• Once cloned, both of these tools have a "pull" button that checks for updates on GitHub and downloads them if available.

• If all you're doing is cloning the repository and staying up to date with pull then that's all you need to do. If you would like to learn more about Git, possibly to contribute to StitchIt, then the Atlassian Git tutorial is a great starting point.

Installing in MATLAB

You should now have a directory somewhere on your computer that contains StitchIt. The easiest way of installing StitchIt in MATLAB is to add it to the MATLAB path using the pathtool command:

• Start MATLAB.

• Run pathtool and a GUI will open.

• Click "Add with subfolders".

• Navigate to the StitchIt directory. Enter it and select the code directory then press "Open".

• The code directory and all it's subdirectories are now added to the "MATLAB search path" list.

• Hit "Save". This will update a file called pathdef.m that contains the list of directories you see in the GUI.

A common problem is that MATLAB complains you don't have write access to save the pathdef.m file. This happens because by default you are attempting to save the pathdef.m file in the MATLAB install directory. A solution to this problem is outlined here. Basically, the answer is to to tell the GUI to save the file in your startup folder. Typing userpath will report which the startup folder is. You save the pathdef.m file in there.

A better approach than the above is to create a file called startup.m in your startup folder. This file will be run every time MATLAB starts. In the startup.m file you can use the genpath and addpath commands to add directories to the path. Doing this has the advantage that if a future release of StitchIt has a different path (i.e. a directory is added or removed) then this will be automatically dealt with when startup.m runs. For example your startup.m file could look like this:

function startup
 stitchit=genpath('~/work/Anatomy/StitchIt/code');
 araTools=genpath('~/work/Anatomy/code/ARA_tools/code');

 addpath(...
    stitchit,...
    araTools,...
    '~/work/Anatomy/code/AllenBrainAPI/',...
    '~/work/Matlab_Scripts/yamlmatlab',...
    '~/work/Matlab_Scripts/MelastiX/code',...
    '~/work/Matlab_Scripts/SlackMatlab');

Installing dependencies

In the same manner as for StitchIt, clone and add to your path Slack MATLAB if you wish to send Slack progress messages during data acquisition. In the pathtool GUI just add the single project directory and don't add subfolders (as shown above). If you add subfolders MATLAB will add the hidden .git directory and all its many subfolders. Once everything is installed, move on to setting up the INI file.

Problems?

StitchIt should have no other dependencies. If you get an error that indicates a function is missing, please file a bug report.