Installation

ngi_reports Python Package

To create reports you need to install the ngi_reports package. First, either download or clone the repository. Make sure that you include the --recursive flag:

git clone --recursive https://github.com/NationalGenomicsInfrastructure/ngi_reports.git

(remember to fork instead if you intend to make changes to the code)

Next, install the package by running:

cd ngi_reports
python setup.py install

You also need to install the pandocfilters submodule:

cd data/pandoc_templates/pandocfilters/
python setup.py install

These commands should install all dependencies so that the python code is ready to run. If you're intending to make changes to the code, use develop instead of install so that you don't need to run the setup script each time you make a change.

Next, you need a config file in your home directory called ~/.ngi_config/ngi_reports.conf. This file should be formatted for Python ConfigParser and look like this:

[ngi_reports]
support_email: genomics_support@scilifelab.se
ngi_node: stockholm

[organism_names]
hg19: Human
hg18: Human
mm10: Mouse
mm9: Mouse
canFam3: Dog
canFam2: Dog
sacCer2: Saccharomyces cerevisiae
TAIR9: Arabidopsis
rn5: Rat
rn4: Rat
WS210: C. elegans
xenTro2: Xenopus
dm3: Drosophila

Obviously, if you're working at the Uppsala NGI node, change the ngi_node to uppsala instead of stockholm. The organism_names section should have reference id key - text pairs. This is used to make the report more verbose.

Bash Commands

To use ngi_reports from the command line easily, there are some bash commands that you need. These are written into a bash script to make life easy - you need to add this to your ~/.bashrc file (~/.bash_profile on a mac):

source ~/opt/ngi_reports/scripts/start_ngi_reports.sh

note that you need to change the path to point to your ngi_reports directory..

If you are running ngi_reports on Uppmax, use the following script instead:

source ~/opt/ngi_reports/scripts/uppmax_ngi_reports.sh

ngi_visualizations

The ngi_reports scripts use a separete Python module called ngi_visualizations. You can find this repository along with installation instructions on github: ngi_visualizations

At the time of writing, the package could be installed as follows:

git clone https://github.com/NationalGenomicsInfrastructure/ngi_visualizations.git
cd ngi_visualizations
python setup.py install

Status DB

If you're running ngi_reports from the Stockholm NGI node, you'll need access to Status DB. This is done using the statusdb python package. See that readme for installation instructions (it's very similar to the above, but I don't want to duplicate it here in case it gets out of date).

Pandoc Conversion

Only read this if you're NOT running on UPPMAX

NGI reports use Pandoc to convert the autogenerated Markdown files into HTML and PDF reports. Head to the pandoc installation page and download the appropriate version for your system. Make sure that you also download and install LaTeX and all of the LaTeX packages that you can get your hands on.

Note: nestor and milou UPPMAX clusters have pandoc installed, but a very old version. This software has been build and tested with Pandoc v1.13.1 and won't work with version 1.9.4.1 which is on UPPMAX. There is a stand alone binary of pandoc which is bundled with the repository (ngi_reports/data/pandoc_templates/pandoc) which does work, however. If you use the UPPMAX bash script (see above) then the commands should use this binary and everything should work.

XeLaTeX

Only read this if you're NOT running on UPPMAX

The PDF conversion step uses XeLaTeX to render TeX to PDF. If you're using a Mac, download and install BasicTeX If you're using a PC, install MiKTeX

Again, the UPPMAX installation of LaTeX and XeLaTeX isn't good enough for what we need, and again, we use a portable installation. This is too big to put on GitHub (> 4gb) and so is stored the group directory. The following lines in uppmax_ngi_reports.sh make it available for us on Nestor:

# Add XeLaTeX to the path
export PATH=/apus/v1/a2012043_nobackup/software/TeXLive/bin/x86_64-linux:$PATH

As with above - if you're using the UPPMAX bash script then everything should work..

If for whatever reason that doesn't work (wrong group permissions or something) then you can generate this software yourself by downloading and installing a portable version of TeXLive. You'll need to add this directory to your path by editing the ngi_reports bash script.

Fonts

The LaTeX to PDF conversion uses two fonts - Helvetica Neue for headings and body text, and Consolas for code. These come bundled in the repository in ngi_reports/data/pandoc_templates/assets/fonts/. If you don't have them installed the PDF should still look correct (as it references this path directly when generating the output), but the HTML may not render properly. If so, you can install these fonts on your local machine from that directory.