You’re reading documentation for ISDB, an open-source software toolkit for building databases of viral integration sites in host genomes. If this is your first time hearing about ISDB, start on the home page.
This installation guide assumes the reader is comfortable using the command line, installing software on their system, and troubleshooting errors that arise when installing and configuring software. If you need help, we suggest contacting a local expert familiar with your computing systems.
Perl 5.14 or later, standard Unix tools including make
, and libcurl are all required to run the ISDB tools.
ISDB is designed to use PostgreSQL as the database server. You must either have “superuser” access to a PostgreSQL server, or access to the owner role of a database set up for your use.
Install Apple’s command line developer tools (Xcode) with:
xcode-select --install
Download and install Postgres.app
Configure your shell to make the PostgreSQL command line tools available:
sudo mkdir -p /etc/paths.d
sudo tee /etc/paths.d/postgresapp <<</Applications/Postgres.app/Contents/Versions/latest/bin
export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"
MacOS versions starting with 10.9 (Mavericks), released in 2013, include a sufficiently new version of Perl to run all the ISDB tools. libcurl is included with macOS as well.
Install packaged dependencies:
apt-get install build-essential git pkg-config libcurl4-gnutls-dev
Set up the PostgreSQL APT repository appropriate for your system Debian, Ubuntu following their instructions
Install libpq and PostgreSQL 9.4 or later:
apt-get install libpq-dev postgresql-9.4
The oldest currently supported Ubuntu release, Ubuntu 12.04.5 LTS, is known to work with ISDB tools.
These instructions should also work on Fedora and other RHEL variants, although they’ve only been tested on CentOS 7.
Install packaged dependencies:
yum install @development libcurl-devel perl-core
Set up the PostgreSQL yum repository for at least Pg 9.4 or newer following their instructions
Install PostgreSQL 9.4 or later:
yum install postgresql9.4{,-docs,-devel}
ISDB is distributed as source code and data directly from our version control repository. We aim to keep the branch (“version”) named master
up-to-date and suitable for use at all times.
To download a copy of ISDB, use git (which was installed if necessary in the previous steps):
git clone https://github.com/MullinsLab/ISDB.git isdb
This will show its progress and should generally take less than a minute. When it’s done, you’ll have a new directory called isdb
. Move into it on the command line by running:
cd isdb
The tools for populating the ISDB have dependencies that do not need to be installed system-wide. Once all the prerequisites are met, run:
make deps
inside your local isdb
directory to download these dependencies. The following components will be downloaded and installed within the isdb
directory:
cpanm
tool for managing Perl librariesliftOver
toolliftOver
chain file for mapping hg19 to hg38 coordinatesThe ISDB maintenance utilities are set up to run from inside the directory containing the source code. Once dependencies are installed, all the tools under bin/
should be functional.
You can use the bin/create-database
tool to create a new database called isdb
on your local PostgreSQL server. It must be run as a database superuser since it creates users and a database. This tool connects to PostgreSQL based on environment variables; see the database connection documentation for details.
If you’re using macOS and Postgres.app, then your macOS user is already a superuser so you can run:
./bin/create-database
If you’re on Linux or a vanilla PostgreSQL install, you’ll need to run the tool as the postgres
system user:
sudo -u postgres ./bin/create-database
After that, add your own Linux user as an ISDB administrator so you’ll be able to run ISDB tools without using sudo -u postgres
again:
sudo -u postgres createuser --role=isdb_admin $USER
You should now be able to connect to the isdb
database and confirm that the basics have been loaded. For example:
$ psql isdb
isdb =# select count(*) from ncbi_gene;
count
-------
51141
(1 row)
isdb =# select count(*) from integration;
count
-------
0
(1 row)
ISDB tools are distributed with some of the source data used to populate HIRIS. Even if you don’t plan on using this data in your ISDB installation, we suggest loading these sources to make sure the ISDB tools and the database you just set up are working correctly. You can use the load-source
tool to load the example sources (found in the sources
directory of this distribution).
For step-by-step instructions, pick up the getting started guide at the “Load example data sources” section.