Embedding

Embed ProteinPaint in your website in 3 seconds

Quick start

Create an HTML file with following content and display it in the web browser to see embedding in action:

<script>
runproteinpaint({
    host:'https://proteinpaint.stjude.org',
    holder:document.getElementById('a'),
    parseurl:true,
block:true,
nobox:1,
noheader:1,
genome:'hg19',
position:'chr12:25334648-25426944',
nativetracks:'RefGene',
tracks:[   
    {
    type:"bigwig",
  url:"http://hgdownload.soe.ucsc.edu/goldenPath/hg19/phyloP100way/hg19.100way.phyloP100way.bw",
	name:"UCSC phyloP 100ways",
	height:100
      },
	    ]
})
</script>

</body>
</html>

View this example live at https://proteinpaint.stjude.org/?appcard=bigwig

The JavaScript function runproteinpaint() accepts an object as input, which contains key-value pairs to do many things such as launching components and customizing looks.

Parameter names are case-sensitive.

Required parameters

holder:<dom>

A DOM object.

Via jQuery, use as:
- holder:yourvariable[0],
Via D3.js, use as:
- holder:yourvariable.node(),

parseurl:true

Value is boolean, if true, will attempt to parse parameter from URL from the parent web page.

noheader:true

Value is boolean, if true, will hide the default page header.

genome:'genome_name'

Name of the reference genome

Genome browser view

runproteinpaint({
host:'https://proteinpaint.stjude.org',
holder:document.getElementById('a'),
parseurl:true,
block:true,
nobox:1,
noheader:1,
genome:'hg19',
position:'chr12:25334648-25426944',
nativetracks:'RefGene',
tracks:[   
	{
		"type":"bigwig",
		"file":"hg19/hg19.100way.phastCons.bw",
		"name":"UCSC phastCons 100ways",
		"height":100
	},
]
})

View this example live at https://proteinpaint.stjude.org/?appcard=bigwig. Click on Examples and click on the Code button.

block:true

Value is “true”. By setting this attribute it will require the “genome” to be set.

width:INT

Optional width of the genome browser in number of pixels.

nativetracks:'RefGene'

Show one or more native tracks. The tracks must be available from this genome on this ProteinPaint server. Value can be following:

Track names joined by comma, e.g. “refgene”, or “refgene,repeatmasker”. Track names are case insensitive.
Array of track names, [“refgene”, “repeatmasker”]
Array of track objects, with custom settings, each track must have the “name” attribute
- [ {“name”:”refgene”, “stackheight”:15} ]
All track names are case-insensitive, e.g. “refgene” and “RefGene” refers to the same track

tracks:[]

Provide one or more custom tracks.

Tracks must be declared as JSON objects, as defined in this tutorial.

tkjsonfile:'path/to/file.json'

Load a set of tracks and facet tables from a JSON file hosted at the directory. The JSON data structure is the same as the URL parameter of the same name.

legendimg:{}

Define a legend image for a genome browser instance. The image is not associated with any of the tracks included in this genome browser.

.name:STR

An optional name for this legend.

.file: “path/to/image.png”

Required. Provide the path of a PNG image file from the “tp/” directory.

legendimg:{}

Define a legend image for a genome browser instance. The image is not associated with any of the tracks included in this genome browser.

.name:STR

An optional name for this legend.

.file: “path/to/image.png”

Required. Provide the path of a PNG image file from the “tp/” directory.

Defining view range

position:'chr1:22222-33333'

Specify the genomic region to display by default. If not provided, will show the default region of this genome (pre-configured in ProteinPaint). Note that the genome browser will force a minimum 400 bp range centered on the input position. If this is undesired (e.g. to zoom in to finest level), use “chr/start” keys as below.

positionbygene:'crebbp'

A gene name or RefSeq accession may be given instead of “position” (genomic coordinate). Gene name is case insensitive.

chr:'chr?',start:12345,

Provide both “chr” and “start” keys to zoom into a nucleotide, at the finest possible resolution. Optionally, define “stop”.

URL parameters

Example:

http://host/yourpage.html?position=chr1:111-222&hlregion=..

In which “yourpage.html” the HTML file calls the embedding API from this section to launch a genome browser.

The URL parameters will customize the ways the genome browser is shown, without having to update anything inside the HTML file. The URL parameters are listed below.

position=chr:start-stop

Will change the default position.

hlregion=region1,region2,...

To highlight the given regions. Requirements defined here.

For more information about URL parameters, please refer to the wiki page.

Genome browser API

By executing “runproteinpaint()” in your embedding code, it will return a promise and resolve to an object with the attribute “block”. The block attribute is the genome browser object which provides the following methods so you can manipulate the genome browser through your code.

Changing view range

runproteinpaint({ block:true, …  })
.then(_=>{
  _.block.jump_1basedcoordinate('chr1:222-333')
  // above will enforce a minimum 400bp range
  // alternatively, use {chr,start} to zoom in to finest level
  _.block.jump_1basedcoordinate({chr:'chr1',start:222})
})

Highlight a region

runproteinpaint({ block:true, …  })
.then(_=>{
  _.block.highlight_1basedcoordinate('chr1:222-333')
})

Only show specific tracks for a track type

All the other tracks of the same type will be turned hidden.

runproteinpaint({ block:true, …  })
.then(_=>{
  _.block.showTrackByFile([
     {type:’bam’,file:’path/to/file1.bam’},
     {... another file}
  ]}
})

Show given tracks

runproteinpaint({ block:true, …  })
.then(_=>{
  _.block.turnOnTrack([
     {type:’bam’,file:’path/to/file1.bam’},
     {... another file}
  ]}
})

Hide given tracks

runproteinpaint({ block:true, …  })
.then(_=>{
  _.block.turnOffTrack([
     {type:’bam’,file:’path/to/file1.bam’},
     {... another file}
  ]}
})

Gene view

Defining a gene

Following methods allow defining the gene to be used in the gene view.

gene:'ikzf1'

To launch a gene-view with the given gene. Value can be gene symbol (TP53) or isoform name (NM_000546), case-insensitive.

gene2canonicalisoform:'ENSGxxx'

Supply an ENSEMBL/GENCODE gene ID to be converted to the canonical isoform of this gene. E.g. for ENSG00000133703 (KRAS), it will be converted to the default isoform ENST00000256078 and used for gene view.

The feature must be enabled in the genome configuration on the server side.

mds3_ssm2canonicalisoform:{}
runproteinpaint({
  genome:'hg38',
  mds3_ssm2canonicalisoform:{
    dslabel:'GDC',
    ssm_id:'4fb37566-16d1-5697-9732-27c359828bc7'
  },
  tracks:[
    { type:'mds3', dslabel:'GDC' }
  ]
})

Only for the NCI GDC API support on hg38. Requires the hg38 genome and the GDC dataset. Supply a SSM ID to look for the gene annotated to this mutation, the canonical isoform of the gene will be used for the gene view. In above example, the SSM is KRAS G12V mutation and will yield the canonical isoform of ENST00000256078 for gene view.

When the corresponding GDC track is provided in the “tracks[]” array, the SSM will be highlighted among all GDC variants on this isoform.

dataset:'clinvar'

Show built-in datasets, join multiple by comma, case-insensitive

hlaachange:'V617F'

Highlight given mutations (mostly AA change names but could be label of any other type), for the first dataset specified by the “dataset” parameter. Groups of mutations with any label matching this input will be shown as expanded, while the rest folded. Mutation label must be exact match, case-sensitive. This will only be effective for the first dataset to be rendered.

Provide the variants as string, join multiple mutation names by comma. Unmatched ones won’t be displayed:

hlaachange: “V617F,V392M”,

Alternatively, provide an array of mutations. Each mutation is described using a few attributes, of which “name” is used for matching. In case no match can be found, the unmatched ones will be shown as a new track, thus the purpose of “codon” and “class”.

hlaachange: [
    { name:'V617F',codon:617,class:'missense'},
    { name:'new datapoint',codon:500,class:'nonsense'}
]

Value of “class” can be either class code or label. See below for supported classes.

mset:[]

⚠ This feature is deprecated. To see a replacement method, click here and then click the tab named “Custom Data(Differential Phosphorylation)”.

For adding one or multiple sets of predefined variants. See example.

mclassOverride:{}

To change the label and color of class codes (defined above), use mclassOverride:

mclassOverride: {
    className: 'My Classes',
    classes: {
        M: {
            label: 'Custom Label',
            color: 'red' 
        },
        … more customized class codes
    }
}

If a value is provided for ‘className’, the value will appear on the left-hand side of the class labels in the legend instead of ‘CLASS’. If not provided, the default ‘CLASS’ label will appear.

The class code keys under ‘classes’ (e.g. 'M':{} in the example above’) must match a class value for mset.mlst[i].class. The class code key 'M':{} in this example matches the class: 'M' defined in the previous example.

hidedatasetexpression:true

Only apply when “dataset” is provided. If set to true, will not display the gene expression panel accompanying the dataset, and will only show mutation data over the gene/protein.

hidegenecontrol:true

If set to true, will hide the control buttons atop the coordinate ruler when showing a gene.

hidegenelegend:true

If set to true, will hide all legends when showing a gene (mutation class, mutation origin, protein domains)

hide_dsHandles:true

If set to true, will hide the dataset buttons next to the “Zoom IN” button on the top row.

GenomePaint

GenomePaint is a type of track that can function in both genome browser and gene view. Learn more.

datasetqueries:[ {dataset, querykey, … } ]

This launches one or multiple official GenomePaint tracks, available for this genome. See this tutorial for launching custom track.

Requires “block:true” to be set.

The track is a combination of mutation, CNV, LOH, SV/fusion, FPKM etc. Works with gene view and genome browser view.

Each JSON object defines a track backed by a GenomePaint dataset, along with customization options.

dataset: STR

querykey: STR

Points to the official dataset available from this genome.

Following parameters will change the default behavior of the track.

singlesample: {}

singlesample:{
   name: STR,
   waterfall:{
      inuse: true
   }
}

isfull: BOOL

isdense: BOOL

Defines if to show in “dense” or “expanded” mode, works for multi-sample. This overrides the default setting on the dataset.

sampleAttribute:{}

sampleAttribute:{
   "cancer_type": {
       hiddenvalues: [ "NBL", "RB" ]
   }
}

Optional. If provided, will filter out samples if they match with the given sample attribute key and values.

vcf:{}

hiddenclass: [ 'M', 'N', … ]
- See hlaachange for list of SNV/indel classes

.hide_cnvgain:true

.hide_cnvloss:true

Setting to true to hide either gain or loss

cnv:{}

hidden:1
upperlengthlimit: 0

loh:{}

hidden:1
upperlengthlimit: 0
- Set to 0 to show all LOH segments

sv:{}

hidden:1

fusion:{}

hidden:1

itd:{}

hidden:1

sampleset:[]

sampleset:[
   { name:'Group1', samples:['sample1','sample2', … ] },
   { name:'Group2', samples:['sampleA','sampleB', … ] }
}

Optional. Provides one or more groups of samples to limit the view only to these samples.

fixedgeneexpression:[]

Add one or multiple ""fixed genes" to the gene expression panel. Example value: [{gene:'STIL'},{gene:'CMPK1'}]

getallsamples: true

To show all samples by default. Effect is samples without genomic variations in the current view range will still show with their available gene expression data.
This feature works for all custom tracks. For official track, if its backend configuration does not allow it, the flag will be ignored.

mdssamplescatterplot:{ dataset:'xxx' }

Launches the sample scatterplot view from a GenomePaint datasets as well as for custom data. For official datasets See example. For specifications for official as well as custom dataset see this documentation.

mdssurvivalplot:{}

Launches a set of Kaplan-Meier plots from a GenomePaint dataset, with customizations for each plot. Only available for official datasets. View instructions.

display_termdb:{}

Launch termdb. Refer to termdb document.

samplematrix:{}

Using an official dataset (example):

samplematrix:{
  genome:'hg19',
  dslabel:'Pediatric2',
  ismutation_allsymbolic:true,
  limitsamplebyeitherannotation:[ { key:'diagnosis_short', value:'NBL' } ],
  features:[
    {
       label:'MYCN',
       ismutation:1,
       querykeylst:['svcnv','snvindel'],
       width:50,
       position:'chr2:16079110-16087476',
       snvindel:{
         excludeclasses:{snv:1,Intron:1,E:1,mnv:1,Utr3:1,Utr5:1}
       }
    },
    { … another feature … }
  ]
}

Using a custom dataset (to add example):

samplematrix:{
  genome:'hg38',
  iscustom:true,
  querykey2tracks:{
    svcnv:{
      type:'mdssvcnv',
     url:'https://pecan.stjude.cloud/static/hg38/tcga-gdc/DLBC/TCGA_DLBC.CNV.gz',
    },
    vcf:{
      type:'mdsvcf',
     url:'https://pecan.stjude.cloud/static/hg38/tcga-gdc/DLBC/TCGA_DLBC.vcf.gz'
    }
  },
  features:[
    {
      label:'CDKN2A/B',
      ismutation:1,
      querykeylst:['svcnv','vcf'],
      width:50,
      position:'chr9:21843776-22119276',
      snvindel:{excludeclasses:{Intron:1}}
    },
    { … another feature … }
  ]
}

Prediction of motif change caused by mutation

Refer to the fimo API.

Differential gene expression viewer

mavolcanoplot:{}

Will launch the differential gene expression viewer that renders the data in MA-plot and Volcano-plot. Keys:

input:”... … ”
- A long string of differential gene expression data.
url:”...”
- The URL of a single text file of the differential gene expression data, based on format specification.
dataname:"whatever"
- Name of the dataset
tracks:[ ]
- Optional. Provides a set of tracks to be displayed over the selected gene when clicking a gene in the MA/Volcano plot.
- Supported tracks:
  - bigWig
  - Stranded bigWig
  - Refer to this tutorial for declaring tracks
- This requires the values in the “gene” column of the differential expression file to be valid gene names, so that the genomic position can be derived based on the gene name for launching the genome browser.

Note for browsing stranded bigWig tracks on DNANexus:

The bigWig format file must be named as following to be recognized:

*.posStrand.bw
*.negStrand.bw

Fusion editor

fusioneditor:{} Will launch the Fusion Editor, value is an object, keys:

input:”... … ”
- A long string of fusion gene data (from CICERO output). \n as line break, tab separates columns, first line is header, refer to Format specification
urls:[ URL1, URL2, ... ]
- List of URLs of text files as input, format of each file should match specification: Format specification
- “urls” will be ignored if “input” is set.
dataname
- Name of this dataset
uionly:true
- ...

Example: https://proteinpaint.stjude.org/examples/fusioneditor.html

Study view

studyview:{} (this part is being updated) Loads a study view by accepting various types of data. For mutation data including SNV/indel, ITD, sv/fusion, truncation, intragenic deletion, CNV, data should be submitted as a string variable that contain the entire content of a text file.

studyview: {

    snvindel:”a string, \n as line breaks, first line is header”,

    svjson:”sv/fusion/itd/trunctation/deletion data in json format … “,

    cnv:”cnv data in tabular format, \n as line breaks, first line is header “,

    name:”name of this dataset”,

    genome:”hg19”,

}

The “studyview” object is very similar to the JSON definition of study, with most attributes applicable here, except these:

mutationset : []
dbexpression : {}

study:”path/to/studyconfigfile” Loads a study view from a server-side JSON file. Value is the JSON file path starting from path. Visit here for JSON file format

Disco

Loads the disco plot from either custom data or target a sample from a dataset.

Custom data:

mlst An array of objects. Objects may either detail the genomic position or protein characteristics.

Genomic example:

{
    dt: 4,
    chr: "chr1",
    start: 1,
    stop: 100000000,
    value: 0.5
},

Please see the chart on dt values below to decide which value to use.

Protein example:

{
    alt: "T",
    chr: "chr1",
    class: "M",
    dt: 1,
    gene: "H3F3A",
    isoform: "NM_002107",
    mname: "K28M",
    position: 226252135,
    ref: "A"
},

Datasets:

In the disco object, define the dataset, genome, and sample id to launch the plot. Here's an example:

disco: {
    dslabel: "GDC",
    genome: "hg38",
    sample_id: "TCGA-85-7710-01A"
}

Please see the runproteinpaint() calls from the Disco plot examples.

Other parameters

base_zindex:100

Set z-index value to floating panels and menus/tooltip.

variantPageCall_snv:(arg)=>{...}

A logo generator: by calling this function with appropriate arguments it generate a status logo for a given SNV/indel variant (e.g. telling the pathogenecity of the variant)

Applicable to both SQLite-based dataset tracks and VCF tracks.

Function argument is an object with following keys:

chr:””
- chromosome name
position:INT
- 1-based position on the chromosome
refallele:””
- the reference allele
altallele:””
- the alternative allele *The notation for ref/alt alleles will vary based on source of data in the track, could potentially cause error. Standard notation is required http://varnomen.hgvs.org/
container: *A D3 element as the container of the logo

onloadalltk_always:(block)=>{...}

Provide a callback that will run when the genome browser instance is updated and rendered every time. Argument is the “block” instance.

dt

A common parameter is dt. Please refer to this chart on which dt value to use

Item Value

snv indel 1

fusion rna 2

gene expression 3

cnv 4

sv 5

itd 6

del 7

nloss 8

closs 9

loh 10

metabolite intensity 11

suppressErrors: []

An array of strings, each referring to the type of error message to suppress. The valid values are:

“bulk-bad-lines”
(may add to this list)

App Instance Tracking

A runproteinpaint() call will return the main Proteinpaint app instance that was created for rendering tracks in that function call. Besides the main app instance, separate renderer app instances may be created for each track or view, and these renderer instances are tracked in instanceTracker.

// example of capturing the main Proteinpaint app instance as a “pp” variable
// and attaching callbacks to renderer app instance events
const pp = runproteinpaint({
  ...,
  instanceTracker: {} // optional, an empty object may be created automatically
  “callbacks”: {
    “sjcharts”: {
       “hm”: {
          “postInstance”: (hmInstance) => { … save hmInstance reference, do something },
          “postRender”: (hmInstance) => { … do something },
       }
  },
  ...
}

console.log(pp)

instanceTracker: {}

Optional object for tracking renderer app instances, the default is to automatically create a unique, empty tracker object for each runproteinpaint() call. Supplying the same instanceTracker object as an argument will allow separate runproteinpaint() calls to share or reuse existing renderer instances.

Note that a subnested “sjcharts”:{} object will be created under instanceTracker to avoid namespace conflicts between PP and sjcharts instances that may have the same rendererType abbreviation.

callbacks{}

Optional nested object for attaching callbacks to a renderer instance. The root object is keyed by the renderer-instance-type (see the supported app.instanceTracker keys above). The value is an object with keys named after an instance event, and with function values as callback when the event gets triggered.

NOTE: Use a subnested “sjcharts”:{} object under callbacks to avoid namespace conflicts between PP and sjcharts instances that may have the same rendererType abbreviation. The possible renderer type keys in callbacks.sjcharts are {hm, pb, sk, disco}.

Renderer instance events for sjcharts renderers are:

postInstace: right after a renderer instance is created (supported by hm, sjchartspb, sk, disco, and sv rendererTypes)
postInit: right after an instance is fully initialized, for example after an instance is hydrated by server data or fully configured (supported by hm rendererType)
firstRender: right after an instance renders a view for the first time (supported by hm rendererType)
postRender: right after an instance renders a view, every time (supported by hm rendererType)

Returned App Instance Properties

The returned app instance will be an object with the following properties:

app.callbacks

The value for the optional callbacks argument to runproteinpaint()

app.debugmode

The value for the optional debugmode argument to runproteinpaint()

app.genomes

The filled-in genomes data as returned by the Proteinpaint server when the app launches

app.holder

The value for the required holder argument to runproteinpaint()

app.holder0

The main container for rendered visualizations, as opposed to permanent containers that hold elements, such as headers, that persist even when a visualization gets deleted or rerendered

app.hostURL

May be the value of the optional host argument to runproteinpaint(), or by default, may be computed from the window.location.hostname

app.instanceTracker

An object with keys by rendererType and values of the corresponding renderer instance. Currently, only a limited number of renderer instances may be available in this object, including:

hm: a heatmap renderer instance
- .getSchema(): obtain the heatmap configuration to recover the heatmap as currently rendered, given the same input files
pb: (TODO) a pie-bar aka pie charts renderer instance
sk: (TODO) a Sankey aka ribbon graph renderer instance
sv: (TODO) a survival plot renderer instance

Home
Installation
Usage
- Embedding
- URL parameters
Development
- Automated Change Log
- Pull Request Checklist
Plots
Tracks
- Interaction Tracks: Hi‐C and Arc
- Track list and Facet Table
Apps
- Data Browser
Publications
- St. Jude Survivorship Portal Data Releases

Provide feedback

Saved searches

Use saved searches to filter your results more quickly