1.4 User Manual Updated for release 1.4.4 (Feb. 2016) Alamut Batch 1.4 User Manual This document and its contents are proprietary to Interactive Biosoftware. They are intended solely for the contractual use of its customer in connection with the use of the product(s) described herein and for no other purpose. This document and its contents shall not be used or distributed for any other purpose and/or otherwise communicated, disclosed, or reproduced in anyway whatsoever without the prior written consent of Interactive Biosoftware. Interactive Biosoftware does not convey any license under its patent, trademark, copyright, or common-law rights nor similar rights of any third parties by this document. The instructions in this document must be strictly and explicitly followed by qualified and properly trained personnel in order to ensure the proper and safe use of the product(s) described herein. All of the contents of this document must be fully read and understood prior to using such product(s). © 2016 Interactive Biosoftware. All rights reserved. © Interactive Biosoftware ii February 2016 Alamut Batch 1.4 User Manual Contents À propos ..................................................................................................................................... 5 Product description .................................................................................................................... 5 Standalone version ................................................................................................................. 5 Client/Server version .............................................................................................................. 6 System requirements ................................................................................................................. 6 Standalone version ................................................................................................................. 6 Client/Server version .............................................................................................................. 6 What is new in release 1.4.4? .................................................................................................... 7 What is new in release 1.4.3? .................................................................................................... 7 What is new in release 1.4.2? .................................................................................................... 7 What is new in release 1.4.1? .................................................................................................... 7 What is new in version 1.4? ....................................................................................................... 7 What was new in version 1.3? ................................................................................................... 8 What was new in version 1.2? ................................................................................................... 8 What was new in version 1.1? ................................................................................................... 8 Installation ................................................................................................................................ 10 Client/Server GUI frontend (Windows only) ........................................................................ 10 Client/Server command-line program (Windows and Linux) .............................................. 10 Standalone command-line program (Linux only) ................................................................. 11 Variant Input file....................................................................................................................... 12 Using Alamut Batch .................................................................................................................. 13 GUI frontend (Windows only) .............................................................................................. 13 Command-line program (Windows and Linux) .................................................................... 14 Software parameters................................................................................................................ 15 Transcript file format ........................................................................................................... 18 External annotation files ...................................................................................................... 18 Using a local HGMD® Professional database installation .................................................... 18 Output ...................................................................................................................................... 19 Viewing annotated variants in Alamut® Visual ........................................................................ 26 Local splicing effect predictions ............................................................................................... 27 Installing Alamut Batch Standalone ......................................................................................... 28 © Interactive Biosoftware iii February 2016 Alamut Batch 1.4 User Manual Alamut Batch Standalone components................................................................................ 28 The Alamut Database ....................................................................................................... 28 Software Programs ........................................................................................................... 28 System Requirements .......................................................................................................... 28 Installing ............................................................................................................................... 28 Installing the alamut_db database ................................................................................... 28 Installing Alamut Batch .................................................................................................... 28 Installing ancillary programs ............................................................................................ 29 Other prediction tools ...................................................................................................... 29 Python proxy programs .................................................................................................... 29 Updating the alamut_db database .................................................................................... 29 © Interactive Biosoftware iv February 2016 Alamut Batch 1.4 User Manual À propos À propos This user manual describes how to install and use Alamut Batch version 1.4.4 (Feb. 2016). NOTE Alamut Batch was previously named Alamut-HT Product description Alamut Batch is a high-throughput annotation engine for NGS analysis. Designed for intensive variant analysis workflows, this software enriches raw NGS variants with dozens of annotations including effects on human genes, detailed SNP information, and missense and splicing predictions. Annotations provided by Alamut Batch are similar to those available in the Alamut® Visual mutation interpretation software. Alamut Batch is able to annotate tens of thousands variants per hour. This schematic drawing shows where Alamut Batch, Alamut Focus, and Alamut Visual take place in a typical NGS analysis pipeline: Alamut Focus is an optional variant filtration companion application to Alamut Batch. Alamut Batch can be used independently from Alamut Visual. However, results from Alamut Batch can be easily injected into Alamut Visual so as to benefit from its rich feature set, including graphical visualization. Alamut Batch annotates variants by querying a database storing information about human genes (the Alamut database). Technically, Alamut Batch comes in two versions depending on where the gene database is located: • The Standalone version uses a locally installed database • The Client/Server version connects over the internet to our hosted database Standalone version The Standalone version of Alamut Batch provides best performance by including in a local installation all software components and the Alamut database required by the annotation process. It is most appropriate for intensive variant annotation needs such those of whole exome analyses. Alamut Batch Standalone is a Linux command-line program. © Interactive Biosoftware 5/29 February 2016 Alamut Batch 1.4 User Manual System requirements Client/Server version The Client/Server version of Alamut Batch connects remotely to the central Alamut database. Due to internet latency the Client/Server version is slower than the Standalone version but is very easy to install. It is however an efficient solution for moderate variant annotation needs such those of gene panels sequencing analyses. Alamut Batch Client/Server is available as a command-line program on Windows and Linux operating systems. The software is also available with a GUI frontend on Windows. System requirements Standalone version Alamut Batch Standalone requires the following system specifications: • 64-bit CentOS 6.4 distribution (or other compatible Linux distribution) • Python 2.6 or 2.7 • Python MySQLdb package (if access to a local HGMD® Professional database installation is intended) • OpenSSL client libraries (e.g. RPM package openssl.x86_64) • 4 GB RAM minimum • 5 GB hard drive space • Internet connection required for license control Client/Server version Alamut Batch Client/Server requires the following system specifications: • 64-bit CentOS 6.4 distribution (or other compatible Linux distribution) • 4 GB RAM minimum • 100 MB hard drive space • Internet connection required Or: • Windows XP, 7, or 8 (32-bit or 64-bit) • 2 GB RAM minimum • 50 MB hard drive space • Internet connection required © Interactive Biosoftware 6/29 February 2016 Alamut Batch 1.4 User Manual What is new in release 1.4.4? What is new in release 1.4.4? Release 1.4.4 adds the following new annotations: • Full HGNC gene name (e.g. ‘Cystic fibrosis transmembrane conductance regulator’ for CFTR) • Gene Ontology (GO) biological processes, cellular components and molecular functions Also, starting with this release, coding genes with non-AUG translation initiation codons are now handled (eg. WT1). What is new in release 1.4.3? Release 1.4.3 is a bug-fix release. 1000Genomes population frequencies were in a muddle: • 1000G_AFR_AF field contained EAS population frequency • 1000G_AMR_AF field contained SAS population frequency • 1000G_EAS_AF field contained AFR population frequency • 1000G_EUR_AF field contained AMR population frequency • 1000G_SAS_AF field contained EUR population frequency Frequency values are now placed where they belong. What is new in release 1.4.2? Release 1.4.2 is a bug-fix release. In lists of genes of interest, entries with official symbols containing lower-case letters (eg. C2orf16) were discarded. They are now handled properly. What is new in release 1.4.1? Release 1.4.1 is a minor release fixing the following bugs: • Output field pos was intended to report the original genomic variant position as supplied in the input file. In previous versions the value of this field could be different from the original input value (due to adjustments, mainly in case of indels). This has now been fixed, and the field has been renamed to inputPos for clarity. Whatever the computed variant position, reflected by fields gDNAstart and gDNAend, inputPos always holds the value supplied in the input file. • The program crashed if the multi-process (--processes) option was used on a single-variant input file. This has now been fixed and multi-processing is automatically disabled if the input file contains only a few variants. What is new in version 1.4? Version 1.4 adds annotations from ClinVar, COSMIC and ExAC. © Interactive Biosoftware 7/29 February 2016 Alamut Batch 1.4 User Manual What was new in version 1.3? Note that, since a given genomic variant can match multiple ClinVar or COSMIC records, annotations from these datasets are output as lists where each item is separated by a '|' character. Lists in each field are ordered by dataset entries. For example variant MLH1 NM_000249.2:c.793C>T has 3 entries in ClinVar, yielding the following ClinVar annotation fields: clinVarIds RCV000022502.22|RCV000075872.1|RCV000034802.1 clinVarOrigins germline|germline|germline clinVarMethods literature only|research|research clinVarClinSignifs Pathogenic|Pathogenic|VUS clinVarReviewStatus 1|3|1 clinVarPhenotypes Lynch syndrome ii|Lynch syndrome|Not provided What was new in version 1.3? Version 1.3 adds support for the GRCh38 (hg38) human genome assembly, and includes 1000 genomes Phase 3 version 5 variant frequencies for five sub-populations (African, East Asian, South Asian, European, American). What was new in version 1.2? Version 1.2 introduces the following new features: • Support for non-protein coding genes now available in the Alamut gene database • Output annotation lines now include the original variant position provided in the input variant file. (This helps in reconciling variants between the output annotation file and other variant files, which could previously show problematic in case of variant position changes due to application of HGVS rules.) • VCF quality, filter, information, and genotype fields are now reported in the output even for not-annotated variants • Annotation can now be restricted to a list of preferred transcripts specified in a gene/transcripts file (--translist option) • Annotation can also be restricted to a range of variants of the input file [--from and –-to options] (not available in the Windows GUI) Two other new features are specific to the Standalone version: • Multi-process support: Annotation jobs can now be split among multiple processes on the same computer (--processes option) • Access to local HGMD® Professional database installations has been changed since BIOBASE no longer provides a query API (see Using a local HGMD® Professional database installation) What was new in version 1.1? Here are the new features introduced in version 1.1: © Interactive Biosoftware 8/29 February 2016 Alamut Batch 1.4 User Manual What was new in version 1.1? • Integration of HGMD (the Human Gene Mutation Database) data, available to HGMD® Professional subscribers • Integration of NHLBI GO Exome Sequencing Project (ESP) data • Unannotated variants are now reported in the annotation output file (and in the failed variants output file as well) unless the --outputannonly option is specified • If the new option --ssIntronicRange <n> is used, intronic variants located within the specified range <n> from the nearest splice site are annotated as 'splice site' in the varLocation annotation field • Variants can now be filtered by regions of interest defined in a BED format file (--roilist <ROI list BED file name>) • External annotations supplied in variant annotation files can now be integrated in the output (--extAnnFile <external annotation file name>) • Version 1.1.3 adds three output fields reporting validation details of dbSNP entries • Version 1.1.3 also adds three output fields reporting frequencies of ESP alternate alleles (alternate alleles not always being minor alleles) • Version 1.1.4 adds an option to allow processing even if the input file has invalid entries • Version 1.1.5 fixes a bug where variants affecting multiple genes where not processed on all genes • Version 1.1.6 adds the HGMD variant sub-category output field and fixes a network proxy bug for HTTPS • Version 1.1.7 brings improvements to the GUI version: all command-line options are now also available in the graphical interface • With version 1.1.7 it is now possible to input variant alleles that are the same as the transcript allele (e.g. when the genome reference sequence has the minor allele of a SNP and the transcript has the major allele) • Version 1.1.7 can query a local HGMD database installation • Version 1.1.8 fixes a bug occurring when a gene cannot be loaded • Version 1.1.9 features performance improvements and support for mitochondrial variants • Version 1.1.10 fixes a bug causing software crashes on transcripts where the STOP codon is isolated in a 3’UTR exon • Version 1.1.11 supports a wider range of VCF variant descriptions (i.e. descriptions that don’t strictly comply with the format specification) and can now output VCF genotype fields of all input samples © Interactive Biosoftware 9/29 February 2016 Alamut Batch 1.4 User Manual Installation Installation Download the software from http://downloads.interactive-biosoftware.com The downloaded file is a self-extractable archive on Windows and a tarball on Linux. Extract the contents. Client/Server GUI frontend (Windows only) Launch the program Alamut-Batch-UI.exe Open the Option panel and supply: • Your Institution ID in the 'Institution' field • Your license key in the 'Licence Key' field • User initials as appropriate in the 'User initials' field If your internet access is behind a proxy, you will also need to supply appropriate proxy settings. NOTE The Alamut Server name is 'a-ht.interactive-biosoftware.com' by default. If you are based in North America, please change the server name to 'a-ht-na.interactive-biosoftware.com'. Client/Server command-line program (Windows and Linux) Edit the alamut-batch.ini file and supply: • Your Institution ID in the 'Institution' field • Your license key in the 'Licence Key' field • User initials as appropriate in the 'User' field NOTE The Alamut Server name (in field [Network] IBS\Server) is 'a-ht.interactive- © Interactive Biosoftware 10/29 February 2016