igvR 1.20.0
With a properly configured web server, and a few annotation files, you can use igvR with any genome of interest. We demonstrate that here with covid-19, the SARS-CoV-2 genome, obtained from the NCBI, and hosted on an nginx webserver running at the Institute for Systems Biology.
We begin, however, by showing the explicit configuration required to loading the hg38 annotated genome hosted by igv.org, to familiarize you with the full range of parameters you can use if you have the data.
library(igvR)
igv <- igvR()
setBrowserWindowTitle(igv, "hg38 explicit")
setCustomGenome(igv,
id="hg38",
genomeName="Human (GRCh38/hg38)",
fastaURL="https://s3.amazonaws.com/igv.broadinstitute.org/genomes/seq/hg38/hg38.fa",
fastaIndexURL="https://s3.amazonaws.com/igv.broadinstitute.org/genomes/seq/hg38/hg38.fa.fai",
cytobandURL="https://s3.amazonaws.com/igv.broadinstitute.org/annotations/hg38/cytoBandIdeo.txt",
chromosomeAliasURL=NA,
geneAnnotationName="Refseq Genes",
geneAnnotationURL="https://s3.amazonaws.com/igv.org.genomes/hg38/refGene.txt.gz",
geneAnnotationTrackHeight=500,
geneAnnotationTrackColor="darkBlue",
initialLocus="chr5:88,621,308-89,001,037",
visibilityWindow=5000000)
base.url <- "https://igv-data.systemsbiology.net/testFiles/sarsGenome"
fasta.file <- sprintf("%s/%s", base.url,"Sars_cov_2.ASM985889v3.dna.toplevel.fa")
fastaIndex.file <- sprintf("%s/%s", base.url, "Sars_cov_2.ASM985889v3.dna.toplevel.fa.fai")
annotation.file <- sprintf("%s/%s", base.url, "Sars_cov_2.ASM985889v3.101.gff3")
Sys.sleep(2)
setCustomGenome(igv,
id="Sars_cov_2",
genomeName="Sars_cov_2.ASM985889v3",
fastaURL=fasta.file,
fastaIndexURL=fastaIndex.file,
geneAnnotationURL=annotation.file,
geneAnnotationName="ASM985889v3",
geneAnnotationTrackHeight=500,
geneAnnotationTrackColor="darkBlue",
visibilityWindow=30000)
If you work with a novel organism, or use a non-standard assembly, then the open source free nginx web server is a good choice. I have had some success with a simple Python Flask server, but recently ran into errors which I could not fix, and so switched to (and now recommend) nginx.
Javascript interpreters running in compliant web browsers will (with some exceptions) not load code or data, within a running script, if that code or data comes from a web host other than the host from which the script came.
The CORS protocol eases this restriction - counter-intuitively, to my mind. If the cross-origin data has a header which announces CORS saftey, then Javascript will proceed. Thus nginx (or some alternative server you use) must be CORS enabled
Genome files are often very large and therefore only read into igv.js and manageable chunks. Your webserver must respond to those “chunk” requests, called “byte-range” support.
This is what we use at the Institute for Systems Biology to serve the SARS-CoV-2 genome and annotation. This file is called default.conf and is supplied in the Docker command shown below.
server {
listen 80;
server_name localhost;
#access_log /var/log/nginx/host.access.log main;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
# max requests per keepalive connection
keepalive_requests 55000;
# awesome OPTIONS header
if ($request_method = 'OPTIONS') {
add_header "Access-Control-Allow-Origin" $http_origin;
add_header "Vary" "Origin";
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'DNT,Range,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Acopenept-Ranges,Content-Encoding,Content-R$
# Tell client that this pre-flight info is valid for 20 days
add_header 'Access-Control-Max-Age' 1728000;
add_header 'Content-Type' 'text/plain charset=UTF-8';
add_header 'Content-Length' 0;
return 204;
}
if ($request_method = 'POST') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'DNT,Range,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Acopenept-Ranges,Content-Encoding,Content-R$
add_header 'Access-Control-Expose-Headers' 'Accept-Ranges,Content-Encoding,Content-Length,Content-Range,Cache-Control,Content-Language,Content-Type,Expires,Last-Modified,Pragma,Date';
}
if ($request_method = 'GET') {
add_header "Access-Control-Allow-Origin" $http_origin;
add_header "Vary" "Origin";
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'DNT,Range,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Acopenept-Ranges,Content-Encoding, Content-$
add_header 'Access-Control-Expose-Headers' 'Accept-Ranges,Content-Encoding,Content-Length,Content-Range,Cache-Control,Content-Language,Content-Type,Expires,Last-Modified,Pragma,Date';
}
}
# redirect server error pages to the static page /50x.html
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}The Docker container provided for free use by nginx.com is all you need. The -v options mount two host directories so that they are visible within the running container.
We run the nginx contaier on host port 60050 (container port 80) - and other routers and proxies map
60050 to a DNS-specified virtual host, visible outside our ISB firewall, as
https://igv-data.systemsbiology.net
That virtual host setup, the DNS entry, and the proxying are not covered here.
docker run -p 60050:80 \
-v /yourConfigurationDirectory/fullPath/goesHere/default.conf:/etc/nginx/conf.d/default.conf:ro \
-v /yourDataDirectory/fullPath/goesHere/:/usr/share/nginx/html:ro \
--restart always \
-d nginxsessionInfo()
#> R version 4.3.0 RC (2023-04-13 r84269)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 22.04.2 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.17-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C LC_TIME=en_GB LC_COLLATE=C
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] BiocStyle_2.28.0
#>
#> loaded via a namespace (and not attached):
#> [1] digest_0.6.31 R6_2.5.1 bookdown_0.33 fastmap_1.1.1 xfun_0.39
#> [6] cachem_1.0.7 knitr_1.42 htmltools_0.5.5 rmarkdown_2.21 cli_3.6.1
#> [11] sass_0.4.5 jquerylib_0.1.4 compiler_4.3.0 highr_0.10 tools_4.3.0
#> [16] evaluate_0.20 bslib_0.4.2 yaml_2.3.7 BiocManager_1.30.20 jsonlite_1.8.4
#> [21] rlang_1.1.0