Installation.Rmd

---
title: "Installation details"
author: "Gregory Jefferis"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation Details}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
## Preface
This document provides additional details about installation that may help you
solve certain difficulties, especially on Windows or Mac platforms.

The source code for this vignette is available at 
https://github.com/natverse/nat/blob/master/vignettes/Installation.Rmd. 
If you find something unclear or notice a typo, I would be very happy if you 
would click on the Pencil Icon on that page or follow 
[this link to edit](https://github.com/natverse/nat/edit/master/vignettes/Installation.Rmd)
and suggest an alternative wording. Don't be shy about doing this; I have to 
review any change and even if your suggestion is not perfect it will still
be a prompt for me to improve this document. Thank you!

# Prerequisites
**nat** is an R package and therefore runs on Mac/Linux/Windows. The only 
pre-requisite for most functionality is a recent version of R (>=3.1.0 recommended).

* https://www.r-project.org

3D visualisation is provided by the rgl package based on OpenGL. On Mac OS X if 
you use RStudio or R from the terminal, you must have a copy of XQuartz, the X11
window manager, installed. This is no longer a default install since Mac OS X 
10.8. You need to install XQuartz, before installing the nat package. Logout and login for the installation to take effect. You can get it from 
https://xquartz.macosforge.org/landing/. This page is also linked from the 
[Download R for (Mac) OS X](https://cran.r-project.org/bin/macosx/) page.

If you want to apply non-rigid registrations calculated by the 
Computational Morphometry Toolkit (CMTK) you will need to install that separately – see section *External Dependencies* below. 

# Basic Installation
As of v1.0 there is a released version on CRAN. This is normally updated only
every few months.

```r
install.packages("nat")
```

If you wish to run the package tests, it is necessary to install with all dependencies:

```r
install.packages("nat", dependencies=TRUE)
```

# Development version
**nat** remains under quite active development, so we generally suggest using the
development version directly from github. The recommended way to do this is to
install Hadley Wickham's invaluable [devtools](https://CRAN.R-project.org/package=devtools)
package (if you have not already done so) and then use that to install nat.

```r
# install devtools if required
if (!require("devtools")) install.packages("devtools")
# then install nat
devtools::install_github("natverse/nat")
```

The **nat** package includes extensive unit tests which are run along with R's
(extremely fastidious) package check routines by the [Travis](http://travis-ci.org/natverse/nat)
continuous integration server. The master branch is therefore considered very stable
and may well contain fixes or enhancements over released versions. 
However, you can install any [release version](https://github.com/natverse/nat/tags)
including the [latest release](https://github.com/natverse/nat/releases/latest) 
as follows:

```r
devtools::install_github("natverse/nat@v1.8.6")
```

The same syntax can be used to install any arbitrary version that you want 
from github. See `?install_github` for details.

Note: Windows users need [Rtools](https://cran.r-project.org/bin/windows/Rtools/) to
install in this way, but devtools should offer to install this for you if you
do not already have it.

# External Dependencies
**nat** is self sufficient for core functionality, but the transformation of 3D
data using Computational Morphometry Toolkit (CMTK) registrations depends on an
external installation of that toolkit. CMTK binaries can be downloaded for
Windows, Linux and Mac at <http://www.nitrc.org/projects/cmtk/>. Source code is 
available from the same site or an unofficial mirror repository at 
<https://github.com/jefferis/cmtk>. We have extensive experience of using CMTK
under Linux (where we compile from source) and Mac (where we compile or use the
MacOSX-10.6-x86_64.dmg binary installers). We have also used 
[neurodebian](http://neuro.debian.net/pkgs/cmtk.html) to install as part of the
Travis continuous integration setup (see the project's [.travis.yml](https://github.com/natverse/nat/blob/master/.travis.yml) file).

## CMTK+nat on Windows

We have much less experience using CMTK on Windows than on Mac/Linux platforms.
Experiments in May 2016 suggest that the best option is to use the cygwin
CMTK distribution (cygwin provides a linux like environment). Here are the steps we
took:

* You must ensure that you have at least version [nat v1.8.5](https://github.com/natverse/nat/releases/tag/v1.8.5). 
  It is recommended that follow the steps for installing the development version of
  nat straight from github as described in section **Development version**
* Install [Cygwin](https://www.cygwin.com/) accepting the default path `C:\cygwin64`
* When you run Cygwin's setup.exe, you should also install all *fftw3* packages. 
  (fftw3 is a CMTK dependency which provides fast Fourier transform functions)
* Download `CMTK-3.3.1-CYGWIN-x86_64.tar.gz` to the cygwin folder (`C:\cygwin64`)
* Start a Cygwin terminal and go to the root directory with the command `cd /`
  (this is the same place as `C:\cygwin64` in the Windows file system).
* On the Terminal, issue the following command 
  `tar -xvf CMTK-3.3.1-CYGWIN-x86_64.tar.gz` to extract CMTK to the cygwin folder.
* Optionally add `C:\cygwin64\bin` to your windows path (since v1.8.10 nat should 
  look after this - see ?cmtk.bindir).
* The nat function `cmtk.bindir()` should now correctly identify the CMTK binary
  directory. You can test that the executables are working by trying the following in R `library(nat);cmtk.dof2mat(version = TRUE)`
  which should then respond with "3.3.1" if you 
  have installed the CMTK version we have just mentioned.