Installing C-PAC
----------------

Requirements
^^^^^^^^^^^^

System Requirements
""""""""""""""""""
C-PAC is **designed to run in a \*nix-like environment** and thus does not support Windows.  The C-PAC team actively tests C-PAC in Ubuntu Linux, although older versions of that distribution and other \*nixes (such as Mac OS X) should work as well.   As a general rule, C-PAC can operate on any machine capable of reliably running AFNI . 

Hardware Requirements
""""""""""""""""""""
* A multiprocessor/multicore system (highly recommended)
* 8 GB of RAM (for computationally-intensive processes such as anatomical registration using ANTS)
* 5.7 GB of free hard disk space (8.3 GB with ANTs)

A Note About the \*nix Command Line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**This user guide assumes a basic level of experience using the command line.** If you are new to the command line (also known as the terminal), the resources below will help you get started:

* Getting to Know the Command Line 
* Terminals for Absolute Beginners (Part 1 )
* Learning the Shell 
* Unix Tutorial for Beginners 
* Unix for the Beginning Mage 

Installation Overview
^^^^^^^^^^^^^^^^^^^^^
If you are using Ubuntu (version 12/14) you can download  and run cpac_install.sh  with the following terminal commands as root:

.. code-block:: bash

    wget https://github.com/FCP-INDI/C-PAC/blob/master/scripts/cpac_install.sh?raw=true -O cpac_install.sh
    chmod +x cpac_install.sh
    sudo ./cpac_install.sh -r
   
This will install all of the prerequisites and resources listed below. If you have previously installed versions of these, they will not be reinstalled, and the script will not check the release version to match the requirements of C-PAC. 
 
**Note**: This script is intended for Ubuntu Linux 12/14,  but it may work for older releases of Ubuntu.

**For other operating systems**, this page will guide you through the following C-PAC installation steps:

* Installing the required system-level dependencies
* Installing the required Python dependencies 
* Installing AFNI and FSL
* Installing C3D and ANTS (optional, but recommended)
* Installing the required C-PAC image resources
* Installing C-PAC itself

It will also provide information on how to:

* Test your installation.
* Upgrade C-PAC to a new version.
* Run C-PAC without installing.

Instructions for Installing Particular Dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Installing System-Level Dependencies
""""""""""""""""""""""""""""""""""""

A complete installation of C-PAC requires that the following dependencies be installed on your OS (and possibly other packages depending on your configuration):

* cmake
* make
* build
* git
* unzip
* libxp
* netpbm
* gcc (with Fortran and C++ compilers and libgfortran)
* The Python developer libraries
* lapack and its developer libraries
* libcanberra (under Linux)
* The Mesa OpenGL utility library
* gsl
* zlib and its developer libraries
* Graphviz  (optional; required for workflow graphs)
* Xvfb
* libxml
* libxslt
* Python developer libraries

The command to install all of these on Ubuntu 12/14 is:

.. code-block:: bash
    
    sudo apt-get install -y cmake git make unzip libcanberra-gtk-module libxp6 netpbm libglu1-mesa gsl-bin zlib1g-dev graphviz graphviz-dev pkg-config build-essential libxml2-dev libxslt-dev python-dev xvfb

OS-Specific Instructions 
''''''''''''''''''''''''

**Mac OS X:** 

* Installing system-level and Python dependencies will be made much easier if you download the Xcode Command Line Tools from Apple  (requires a free Apple account), which includes (among other things) Git and gcc.
* You may want to consider using a package manager such as Homebrew .

**Ubuntu 16.04:**

* The apt-get command used for Ubuntu 12/14 works with *libxp6* omitted. Unfortunately, libxp is no longer included in the Ubuntu repositories and will need to be compiled from source.  The commands to accomplish this are as follows (note that these commands must be executed as the root user).

.. code-block:: bash

    apt-get install autoconf autogen xutils-dev x11proto-print-dev
    cd /tmp
    git clone https://anongit.freedesktop.org/git/xorg/lib/libXp.git
    cd libXp
    ./autogen.sh
    configure
    make
    make install

Installing Python Dependencies
""""""""""""""""""""""""""""""
Please ensure that you are using Python 2.7 and above, but not Python 3 (since it is not backwards-compatible). Though many computers come with Python pre-installed, C-PAC relies on a number of special-purpose packages, which are listed below. Packages with an asterisk can be installed through `easy_install <https://pythonhosted.org/setuptools/easy_install.html>`_ or pip.  Installing `Anaconda <https://store.continuum.io/cshop/anaconda/>`_ (**64-bit version only**), `Miniconda <http://conda.pydata.org/miniconda.html>`_ or  `Enthought Canopy <https://www.enthought.com/products/canopy/>`_ and using a package manager can simplify installation greatly.  Instructions for Miniconda are given below.

* SciPy and NumPy  
* Nipype (version 0.11 is compatible with C-PAC 0.3.9; version 0.10 is compatible with versions of C-PAC after 0.3.7, version 0.9.2  for C-PAC versions 0.3.4b, 0.3.5, and 0.3.6; version 0.12 of nipype is not compatible with the currently release versions of C-PAC)
* Nibabel
* NetworkX  * 
* Traits  * 
* Matplotlib  *
* wxPython 
* PyYAML  * 
* PyLockfile  *
* Cython  (version 12.1 or greater)  *
* iPython  (optional)
* PyGraphviz  (optional; required for workflow graphs)
* Patsy 
* Boto 3 
* psutil 
* INDI-tools 
* future 
* prov 
* simplejson 
* pandas 

Miniconda
''''''''

The following commands will install all the Python dependencies within a Miniconda environment:

.. code-block:: bash

   wget http://repo.continuum.io/miniconda/Miniconda-3.8.3-Linux-x86_64.sh
   chmod +x Miniconda-3.8.3-Linux-x86_64.sh
   ./Miniconda-3.8.3-Linux-x86_64.sh -b
   export PATH=~/miniconda/bin:${PATH}
   echo 'export PATH=~/miniconda/bin:${PATH}' >> ~/.bashrc
   conda create -y -n cpac python
   source activate cpac
   conda install -y cython numpy scipy matplotlib networkx traits pyyaml nose ipython pip wxpython pandas
   pip install lockfile pygraphviz nibabel nipype patsy psutil boto3 INDI-tools future prov simplejson
   source deactivate
 
OS-Specific Instructions 
''''''''''''''''''''''''

**Mac OS X:** 

* It is highly recommended that you use either Canopy or Anaconda/Miniconda to install Python packages such as wxPython, SciPy and NumPy.  Manually installing these packages on OS X can be difficult and error-prone.  If you use Anaconda/Conda, the commands above should install all packages seamlessly (assuming you download the Mac OS X Miniconda install script instead of the Linux script when using `wget`).  


Installing AFNI and FSL
"""""""""""""""""""""""
C-PAC harnesses the power of two leading neuroimaging software packages (AFNI ) to perform key analyses. These packages must be installed before running C-PAC. 

To install AFNI on a non-Fedora 21 64-bit Linux machine you may run the follow commands as the super user:

.. code-block:: bash
    cd /tmp
    wget http://afni.nimh.nih.gov/pub/dist/tgz/linux_openmp_64.tgz
    tar xfz linux_openmp_64.tgz
    mv linux_openmp_64 /opt/afni

For AFNI to be available globally on your machine, you should then add the following lines to the file located at `/etc/bash.bashrc`:

.. code-block:: bash
    export PATH=/opt/afni:$PATH
    export DYLD_FALLBACK_LIBRARY_PATH=/opt/afni

If you open a new shell and type `afni` the AFNI console should now appear.  If not, double-check the lines added to `/etc/bash.bashrc` for typos and make sure that `/opt/afni` contains the AFNI commands.

For more details about installing AFNI (including instructions for other architectures) please refer to the AFNI manual here .

To install FSL on a Debian or Ubuntu-based Linux machine you may run the follow commands as the super user to install the Neurodebian  repository, which contains a pre-packaged version of FSL that integrates seamlessly with the Debian ecosystem:

.. code-block:: bash
    wget -O- http://neuro.debian.net/lists/$(lsb_release -cs).us-nh.full | tee /etc/apt/sources.list.d/neurodebian.sources.list
    apt-key adv --recv-keys --keyserver pgp.mit.edu 2649A5A9
    apt-get update

A note regarding the Neurodebian repository: We have encountered compatibility issues in the past with the Neurodebian binary for AFNI.  For this reason, it is suggested that you follow the installation instructions above or the instructions from the AFNI homepage.

Now install FSL using:

.. code-block:: bash
    apt-get install -y fsl-5.0-complete

For FSL to be available globally on your machine, you should then add the following lines to the file located at `/etc/bash.bashrc`:

.. code-block:: bash
    FSLDIR=/usr/share/fsl/5.0
    . ${FSLDIR}/etc/fslconf/fsl.sh
    PATH=${FSLDIR}/bin:${PATH}
    export FSLDIR PATH

For more details about installing FSL (including instructions for other architectures) please refer to the FSL documentation here .

OS-Specific Instructions 
''''''''''''''''''''''''

**Mac OS X:**

* In Mac OS X, you can make it so that a local user account can find AFNI by adding the lines in the instructions above to the :file:`.bashrc` file in your home directory and then adding the following code to the :file:`.bash_profile` file in your home directory.

    .. code-block:: bash

        if [ -f ~/.bashrc ]; then
            source ~/.bashrc
        fi

Installing C3D and ANTS (optional, but recommended) 
""""""""""""""""""""""""""""""""""""""""""""""""""
ANTS is an optional, but recommended package for performing image registration / normalization.  ANTS depends upon C3D, which can be installed by following the steps below.  If you do not want to install ANTS, you may skip this step.  You can always install ANTS later.

Installing C3D
'''''''''''''

#. Download C3D from here  (for Mac users). 
#. Unzip the downloaded archive, and place the extracted folder in the location of your choosing. 

#. Add the following text to your :file:`.bashrc` file: 

.. code-block:: bash

    export PATH=/path_to/C3D/bin:$PATH

Where :file:`/path_to/C3D` is the location of the extracted folder.

#. Open a new terminal window. Test your installation by running :file:`c3d_affine_tool`. If this fails, see the `Troubleshooting` section below.

**Troubleshooting:**

* If you are given a permissions error, run :file:`chmod -R /path_to/X`, where X is the folder of the package giving you the error.

* If you have added the paths to your :file:`.bashrc` (and :file:`.bash_profile` if necessary) but you are still unable to run the commands above, try adding or removing a trailing / from the paths (e.g. :file:`../bin` vs. :file:`../bin/`). We are working to compile a list of which platforms require the slash and which do not.


Installing ANTS
''''''''''''''

To install ANTS, follow the instructions below. 

For Debian-based platforms, install the Neurodebian keys (see the FSL installation instructions above) and run the following command as the super user:

.. code-block:: bash

    apt-get install ants

For other platforms, download ANTS from Github and compile from source:

.. code-block:: bash

    cd /tmp
    git clone https://github.com/stnava/ANTs.git 

This will create a folder named "ANTS" in the directory where you ran the command from.

Next, create a new directory in a location of your choosing and navigate to it:

.. code-block:: bash

    mkdir /opt/ants
    cd /opt/ants

Next, run these commands from this directory to build your ANTS install:

.. code-block:: bash

    cmake -c -g /tmp/ANTS
    make -j <number>

Where <number> is how many cores you wish to dedicate to building your install - the more you use, the sooner it will complete. For example, if you want to use four cores, you would run 'make -j 4'.

Once this is complete, you will need to modify your environment. Add the following text to your :file:`.bashrc` file: 

.. code-block:: bash

    export ANTSPATH=/opt/ants/bin
    export PATH=/opt/ants/bin:$PATH

You can test the installation by opening a new terminal window and running this command:

.. code-block:: bash

    antsApplyTransforms

If this returns a help page with a list of parameters, your ANTS installation was a success.

OS-Specific Instructions 
''''''''''''''''''''''''

**Mac OS X:**

* Similar to the AFNI and FSL path setup, you must also add the C3D and ANTS paths to your :file:`.bash_profile` file. 

Installing C-PAC Image Resources
"""""""""""""""""""""""""""""""
During preprocessing and analysis, C-PAC utilizes many of the standard brain atlases and tissue maps provided by FSL. Additionally, C-PAC requires the following non-standard files in order to run properly:

* Binarized tissue prior probability maps (used during :doc:`tissue segmentation </anat>`)
* Symmetric versions of the MNI152 brain template and masks (used when calculating :doc:`VMHC </vmhc>`)

These files are included in the C-PAC Image Resources package, available here . You may install these files using the following commands or use the included script (install_resources.sh):

.. code-block:: bash

    cd /tmp
    wget http://fcon_1000.projects.nitrc.org/indi/cpac_resources.tar.gz
    tar xfz cpac_resources.tar.gz
    cd cpac_image_resources
    cp -n MNI_3mm/* $FSLDIR/data/standard
    cp -n MNI_4mm/* $FSLDIR/data/standard
    cp -n symmetric/* $FSLDIR/data/standard
    cp -nr tissuepriors/2mm $FSLDIR/data/standard/tissuepriors
    cp -nr tissuepriors/3mm $FSLDIR/data/standard/tissuepriors
    cp -nr tissuepriors/4mm $FSLDIR/data/standard/tissuepriors
    cp -n HarvardOxford-lateral-ventricles-thr25-2mm.nii.gz $FSLDIR/data/atlases/HarvardOxford
 
These commands perform the following steps:

* The image resources are downloaded.

* 3mm and 4mm MNI tempaltes are copied to the :file:`/data/standard` directory of your FSL installation.

* Files located in the :file:`/symmetric` folder of the C-PAC Image Resources directory are copied to the :file:`/data/standard` directory of your FSL installation.

* The :file:`/2mm` and :file:`/3mm` folders located in C-PAC Image Resources directory are copied to :file:`/data/standard/tissuepriors` directory of your FSL installation.

Installing C-PAC
"""""""""""""""
Congratulations, you are now ready to install C-PAC itself!

C-PAC is available for download from the C-PAC Homepage . Click the button labeled "Download as tar.gz". Unpack the downloaded archive and navigate to the new directory. To install C-PAC, run the command ``sudo python setup.py install``. C-PAC will be installed alongside your other python packages. If this fails, check to make sure that you have all the dependencies installed.  You may also install C-PAC using the commands below:

 .. code-block:: bash
   
   cd /tmp
   git clone https://github.com/FCP-INDI/C-PAC.git
   cd C-PAC
   python setup.py install

Testing Your C-PAC Installation
''''''''''''''''''''''''''''''
In a new terminal window, open iPython (or Python) and enter the command ``import CPAC``. If installation was successful, this will execute without an error and present you with a blank new line. If you encounter an error (e.g. ``no module named C-PAC``), try re-running the C-PAC install command above. If this does not work, see the :doc:`Troubleshooting and Help Page </help>`.  Note that if you do not open a new terminal window and are still within the C-PAC installation directory ('C-PAC'), you may encounter errors that can be alleviated by leaving the 'C-PAC' directory.

Once you are able to successfully ``import CPAC`` it is safe to delete any setup files downloaded during the install process (e.g. Nipype and C-PAC downloads, FSL install scripts, etc.), as they are no longer needed.

**Note:** The test process described here only acts to confirm that the C-PAC python package has been correctly installed. To fully test C-PAC on your system, please see the :doc:`Benchmark Page </benchmark>`.

Updating C-PAC 
""""""""""""""
C-PAC is being actively developed, and new versions (containing bug fixes and new features) are often released. To update to the latest version, simply download it from the C-PAC Homepage  and repeat the instructions in the `Installing C-PAC` section above. A list of previous versions and the changes they contain is available on the :doc:`Release Notes Page </rnotes>`.

**Note: If you are using Anaconda/Miniconda you may also use the following command (replacing 'cpac' with your environment name) to remove an old environment before creating a new environment to replace it.**

 .. code-block:: bash

    conda remove --all -n cpac

Running C-PAC Without Installing
""""""""""""""""""""""""""""""""

Users wishing to run C-PAC without installing it can do so by copying the downloaded C-PAC directory to the location of their choice. C-PAC can then be run by opening iPython (or Python) from within this directory. This is useful in cases where a user does not have sufficient privileges to install Python packages, but is running on a machine that already contains all C-PAC dependencies.

Some network centrality features will not be available without compiling the C-based elements. In order to do this without installing the rest of C-PAC, simply use the following command

.. code-block:: bash

    python setup.py build_ext --inplace

**Note:** Unfortunately, it is not possible at this time to use the C-PAC GUI without installing C-PAC.
