GTEx IGV integration

[duyentnguyen]

We were looking to start updating the IGV browser used in the GTEx Portal in preparation for our v8 release coming some time mid/end of April. In the process, we were hoping to update to a newer version of IGV (v2.2.5). Currently, a lot of the testing is being done with our v7 data, though we do have v8 eQTL track now, too.

A few questions came up that I thought would be best to reach out to you about:

• We include our own gene reference track with a bed file. The annotations that appear on clicking an element of the track have a lot more information, but for some reason, doesn't display the name of the genes. Is the format of our bed file wrong/outdated? Why does this happen?
• File type "gwasSNPS" seems to have allowed support for our GWAS catalog track in the past, but doesn't seem to exist in the newer version. Is there a different file type I should be using for this? The track still appears, but the annotations seem to be a bit odd.
• There doesn't seem to be any highlighting anymore when I search for the gene name or snpId. Has this feature been removed from newer versions of IGV?
• Our v8 eQTL data will refer to chromosomes using hg38's standard of "chr1", "chrM", etc. Is there already native support for this in igv.js, or should I provide this mapping through the aliasUrl attribute that's part of the reference object?
• IGV seems to have specified the query specifically for datasetId "gtex_v7". Maybe it would be best to leave this out, so that it can default to whatever our latest release is?

[jrobinso]

@dnguyen1193 Could you attach a sample bed file (first item) and a sample "gwasSNPS" file (second item). RE the last item, nothing is hardcoded, its all in the track config. What leads you to think otherwise? gtex_v7 is the default value.

[jrobinso]

RE highlighting, this has never been a standard igv.js feature, it is enabled if a gtex eqtl track is loaded. I just tested and its working fine for me. In what context are you seeing a problem?

RE chr names, yes those mappings are automatic. You don't have to do anything.

[duyentnguyen]

fasta file: http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/hg19.fasta.fai cytoband file: http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/cytoBand.txt sample bed file: https://s3.amazonaws.com/igv.broadinstitute.org/annotations/hg19/genes/gencode.v19.genes.v7_model.patched_contigs.sorted.bed gwasSNPs file: http://dn7ywbm9isq8j.cloudfront.net/annotations/hg19/gwas/v2_newest_converted_GWAS_catalog_SNPs_Pval5E08_hg19_040115.bed featureUrl: https://gtexportal.org/rest/v1/reference/features/

@francois-a Do we have v8 files/hg38 that IGV can be tested with?

RE highlighting, creating an IGV browser with the configurations above, typically, if I have an eQTL track open and search for a gene (e.g. Muscle - Skeletal track open, search for 'ACTN3' or vice versa), the eQTLs relevant to that gene will be highlighted, and the gene is highlighted in the the gene track. I'm not seeing either of those happen with v2.2.5.

RE default values, using IGV 1.0, the queries for the eqtl tracks to the SingleTissueEqtlByLocation endpoint use the default value for datasetId and is not included in, but when I swap to IGV 2.2.5, it seems to append "datasetId=gtex_v7" to the end of the query (i.e. http://local.gtex.org/rest/v1/association/singleTissueEqtlByLocation?chromosome=11&start=66304459&end=66805264&tissueName=Muscle_Skeletal&datasetId=gtex_v7)

[jrobinso]

@dnguyen1193 Thanks for the files. I will setup a test case you can maintain via pull requests going forward.

RE the datasetId, again it is whatever you set in the track configuration. If you don't set anything it defaults to gtex_v7. Could you attach a track configuration you are using for the eqtl tracks?

Are you saying no datasetID should be include in the query if one is not explicitly set in the config? This would be a change from earlier direction but I'm happy to drop the query parameter if that's what you want.

[jrobinso]

@dnguyen1193 If I recall correctly GTEx uses a custom gene search service (gene -> location lookup). Could you attach the javascript config object for that service so I can setup a more complete test? Thanks.

[jrobinso]

@dnguyen1193 I can't reproduce your highlighting issue, works from igv.js stand alone. Are you passing the gene or snp name to the igv.js "search" function, or have you just passing the genome location directly? If that latter its not going to work.

[jrobinso]

@dnguyen1193 Only issue remains is the gwas snp file issue. That's not a bed file, despite the extension. Where did the file come from? Can you point me to a spec for the format? I can recover the code that parses it, but I'd like to know this is a stable format, looks rather ad-hoc.

[duyentnguyen]

The featureUrl is used for the IGV "search" functionality next to the specified chromosome. For the ACTN3 example specified above, typing in "ACTN3" will result in this URL: https://gtexportal.org/rest/v1/reference/features/ACTN3

When we add an eQTL track to IGV, this is the object we were using:

igvBrowser.loadTrack({
    type: 'eqtl',
    sourceType: 'gtex-ws',
    url: directory.getSingleTissueEqtlByLocationUrl().url, // https://gtexportal.org/rest/v1/association/singleTissueEqtlByLocation
    tissueName: params.tissueName,
    name: tissueDisplayName
})

I actually didn't realize that we could include "datasetId" in the track configuration - adding that fixes the datasetId issue - thanks for that clarification!

I still am not able to get the highlighting to work, though.. I am passing "ACTN3" to the searchbox, which then converts it to a genomic location. Are there other steps in between that we control on the GTEx portal? Maybe it has to do with the gene track not appearing correctly with gene names on my end?  

[duyentnguyen]

We're working on getting an answer about the the GWAS catalog file/track.

[jrobinso]

@dnguyen1193 Re highlighting, what do you mean you are "passing ACTN3" to the searchbox? There is no API to pass anything to the searchbox, exactly what are you calling? Do you mean the user types ACTN3 to the IGV searcbox? If not could you try that (type ACTN3 into the IGV searchbox, not the gtex portal gene search box).

[duyentnguyen]

Sorry - yes, I do mean typing ACTN3 into the IGV searchbox (in the top left corner next to the logo, reference, and chromosome). It gets replaced with the genomic location after the IGV browser jumps to the correct location.

[jrobinso]

It could be caused by using a custom search service. Could you give me the "config" you pass to IGV to configure the search service. I need the whole config object, not just the URL.

On Fri, Mar 15, 2019 at 1:03 PM dnguyen1193 notifications@github.com wrote:

Sorry - yes, I do mean typing ACTN3 into the IGV searchbox (in the top left corner next to the logo, reference, and chromosome). It gets replaced with the genomic location after the IGV browser jumps to the correct location.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/igvteam/igv.js/issues/874#issuecomment-473423524, or mute the thread https://github.com/notifications/unsubscribe-auth/AA49HEKrEis42WMChfdoSG2HIZ9PPDDlks5vW_yrgaJpZM4bwfpB .

[duyentnguyen]

let options = {
    type: "GTEX",
    reference: {
        id: 'hg19',
        name: 'Genes',
        fastaURL: directory.getFastaUrl().url, // http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/hg19.fasta.fai
        cytobandURL: directory.getCytobandUrl().url, // http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/cytoBand.txt
        tracks: [
            {
                name: 'Genes',
                type: 'annotation',
                url: directory.getGencodeBedFileUrl().url, https://s3.amazonaws.com/igv.broadinstitute.org/annotations/hg19/genes/gencode.v19.genes.v7_model.patched_contigs.sorted.bed
                displayMode: 'EXPANDED',
                height: 100,
                autoHeight: true,
                removable: false,
                order: Number.MAX_VALUE // pinning track to bottom
            }
        ]
    },
    locus: params.location, // something like: chr1:1-500,000
    flanking: 75000,
    search: {
        url: featureUrl, // https://gtexportal.org/rest/v1/reference/features/$FEATURE$
        resultsField: 'features'
    },
    tracks: [
        {
            name: 'GWAS Catalog',
            // type: 'gwasSNPS', -- errors with this track type
            url: directory.getGwasCatalogUrl().url,
            indexed: false,
            color: 'rgb(100,200,200)',
            displayMode: 'EXPANDED',
            order: Number.MAX_SAFE_INTEGER // 2nd to last track
        }
    ]
};

[jrobinso]

perfect.

On Fri, Mar 15, 2019 at 1:13 PM dnguyen1193 notifications@github.com wrote:

let options = { type: "GTEX", reference: { id: 'hg19', name: 'Genes', fastaURL: directory.getFastaUrl().url, // http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/hg19.fasta.fai cytobandURL: directory.getCytobandUrl().url, // http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/cytoBand.txt tracks: [ { name: 'Genes', type: 'annotation', url: directory.getGencodeBedFileUrl().url, https://s3.amazonaws.com/igv.broadinstitute.org/annotations/hg19/genes/gencode.v19.genes.v7_model.patched_contigs.sorted.bed displayMode: 'EXPANDED', height: 100, autoHeight: true, removable: false, order: Number.MAX_VALUE // pinning track to bottom } ] }, locus: params.location, // something like: chr1:1-500,000 flanking: 75000, search: { url: featureUrl, // https://gtexportal.org/rest/v1/reference/features/$FEATURE$ resultsField: 'features' }, tracks: [ { name: 'GWAS Catalog', // type: 'gwasSNPS', -- errors with this track type url: directory.getGwasCatalogUrl().url, indexed: false, color: 'rgb(100,200,200)', displayMode: 'EXPANDED', order: Number.MAX_SAFE_INTEGER // 2nd to last track } ] };

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/igvteam/igv.js/issues/874#issuecomment-473426120, or mute the thread https://github.com/notifications/unsubscribe-auth/AA49HICWWIE9iTVV7eaEEsbqLooczHRdks5vW_7agaJpZM4bwfpB .

[jrobinso]

OK, I can reproduce the problem. It is, as I suspected, related to the custom search service. If you comment out the "search" object it works as before. I'll have to dig into this to see what the solution is.

[jrobinso]

The problem is the configuration of the search service. You need to specify what fields contain the gene and snp names, if they are not "gene" and "snp". Did you change this configuration from the previous release? Its also possible igv's default values for these fields changed. At any rate you need to use this with your current service

            search: {
                url: 'https://gtexportal.org/rest/v1/reference/features/$FEATURE$',
                resultsField: 'features',
                geneField: 'geneSymbol',
                snpField: 'snpId'
            }

[jrobinso]

Moving on to the first bullet, you say gene symbols are not displayed. I don't understand what you mean by that, here's what I see with your igv configuration object

[jrobinso]

@dnguyen1193 OK I added a parser for format "gtexgwas" using the example file you sent. This parser will work for a bed-like file with exactly these columns:

chrom   chromStart  chromEnd    Strongest SNP-risk allele   Disease/Phenotype   P-value Odds ratio or beta  PUBMEDID

You specify format differently with igv.js 2.5, in this case the type is "annotation" and format is "gtexgwas" . Track config for the example is

                {
                    name: 'GWAS Catalog',
                    type: 'annotation',
                    format: 'gtexgwas',
                    url: 'http://dn7ywbm9isq8j.cloudfront.net/annotations/hg19/gwas/v2_newest_converted_GWAS_catalog_SNPs_Pval5E08_hg19_040115.bed',
                    indexed: false,
                    color: 'rgb(100,200,200)',
                    displayMode: 'EXPANDED',
                    order: Number.MAX_SAFE_INTEGER // 2nd to last track
                }

[jrobinso]

I think we've covered all the issues here and this thread is getting long. I'm going to close it, if you have other issues open a new git issue for each one. I'll paste the current example track config below. To test it pull from master and build, or you can use the nightly snapshot https://igv.org/web/snapshot/dist/igv.min.js. Note, as covered in the readme, this is the only file required for igv.js, dependencies from earlier versions (fontawesome, igv.css, other css) are not required and should not be included.

Example config (everything working as far as I can tell):

        let options = {
            type: "GTEX",
            reference: {
                id: 'hg19',
                fastaURL: "http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/hg19.fasta",
                indexURL: "http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/hg19.fasta.fai",
                cytobandURL: "http://dn7ywbm9isq8j.cloudfront.net/genomes/seq/hg19/cytoBand.txt",
                tracks: [
                    {
                        name: 'Genes',
                        type: 'annotation',
                        url: 'https://s3.amazonaws.com/igv.broadinstitute.org/annotations/hg19/genes/gencode.v19.genes.v7_model.patched_contigs.sorted.bed',
                        displayMode: 'EXPANDED',
                        height: 100,
                        autoHeight: true,
                        removable: false,
                        order: Number.MAX_VALUE // pinning track to bottom
                    }
                ]
            },
            //locus: params.location, // something like: chr1:1-500,000
            flanking: 75000,
            search: {
                url: 'https://gtexportal.org/rest/v1/reference/features/$FEATURE$',
                resultsField: 'features',
                geneField: 'geneSymbol',
                snpField: 'snpId'
            },
            tracks: [
                {
                    name: 'GWAS Catalog',
                    type: 'annotation',
                    format: 'gtexgwas',
                    url: 'http://dn7ywbm9isq8j.cloudfront.net/annotations/hg19/gwas/v2_newest_converted_GWAS_catalog_SNPs_Pval5E08_hg19_040115.bed',
                    indexed: false,
                    color: 'rgb(100,200,200)',
                    displayMode: 'EXPANDED',
                    order: Number.MAX_SAFE_INTEGER // 2nd to last track
                },
                {
                    type: "eqtl",
                    sourceType: "gtex-ws",
                    url: "https://gtexportal.org/rest/v1/association/singleTissueEqtlByLocation",
                    tissueName: "Muscle_Skeletal",
                    name: "Muscle Skeletal",
                    visibilityWindow: 1000000
                }
            ]
        }

[jrobinso]

@dnguyen1193 If you use ES6 imports or require.js use the appropriate igv.js include, see the readme.