1.1 Supported file formats

Tracks:

• BigWig (.bw) - http://genome.ucsc.edu/FAQ/FAQformat.html#format6.1
• Wiggle (.wig) - http://genome.ucsc.edu/goldenPath/help/wiggle.html
• BedGraph (with .wig extension) - http://genome.ucsc.edu/goldenPath/help/bedgraph.html

Features:

• BED - http://genome.ucsc.edu/FAQ/FAQformat.html#format1
• GFF - http://genome.ucsc.edu/FAQ/FAQformat.html#format3
• GTF (with .gff extension) - http://genome.ucsc.edu/FAQ/FAQformat.html#format4

Files must be formatted according to UCSC guidelines. All widely used chromosome names conventions are accepted, e.g. for human files either ‘chr1’ or ‘1’ can be used, however these conventions should not be mixed within single files.

1.2 Adding files

Press the Add files button to bring up the file upload panel.

File upload panel

You can drag and drop files here or press the Add files... button to open a file selection menu. Before starting the upload the following mandatory information must be provided about each file:

• User ID
• Reference genome - drop-down menu containing reference genome package currently installed in R

Comments are optional.

The contents of the text field can be copied to all files by clicking the icon at the left of the field. The default values can be set using Set defaults... button. Default values are stored using the browser cookies, and the settings will be remembered across different sessions as long as the same web browser is used. File extensions that are not supported will raise an error.

File upload panel with 4 files selected

Individual files can be uploaded by pressing ‘start’ next to the file name or all files can be uploaded at once by pressing the Start upload button at the top of file upload panel.

During the upload process a progress bar is displayed. After upload SeqPlots gives a message that upload was successful or or gives an error message. Common errors are misformatted file formats or chromosome names do not matched the reference genome. For more information please refer to Error explained chapter.

A feedback on successfully upload files

To dismiss the upload window, click on X or outside the window.

1.3 Downloading and removing files

Clicking the New plot set button brings up the file collection window. The primary function of this window is to choose signal tracks and feature files to use for calculating the plots. However, it also provides basic file management capabilities. Information on files can be reviewed and files can be downloaded or deleted. Fields can be searched, filtered and sorted by any column. The red x button on the right site of file table removes a single file from the collection, while Remove selected files button will erase all selected files.

The file collection window

2.1 Selecting files

The Tracks and Features tabs displays information about the files and allows you to filter and sort by any column. The “Search:” dialog allows you to find any keyword in any field, while dropdowns below the file grid allow for more advanced filtering on specific columns.

Select files by clicking on the file name or any other part of the row beside Show comment and Download or Remove buttons. Chosen files are highlighted in light blue. Clicking the file name again will cancel the selection. At least one signal track or motif and one feature file must be selected before starting the calculation.

2.2 Setting up plot options

Options controlling the plot settings is found below the file selection window:

1. Bin track @ [bp]: - this numeric input determines the resolution of data acquisition; the default value 10 means that 10bp intervals within the plotting range will be summarized by calculating the mean. Higher values increases the speed of calculation, but decreases resolution. See the explanations.
2. Choose the plot type - there are three options:
   • Point Features - anchor plot on the start of a feature. By default, plot will be directional if strand information is present (i.e, use start position and plot on positive strand for + strand features and use end position and plot on negative strand for minus strand features). If strand information is not present in the feature file (or if the “ignore strand” option is chosen), plot will use start position of feature and be plotted on the positive strand (see explanations). User chooses length of upstream and downstream sequence to plot.
   • Midpoint Features - similar to point feature, but plot is centered on the midpoint of the feature.
   • Endpoint Features - similar to point feature, but plot is centered on the end of the feature. Strand information is used by default to determine the end side.
   • Anchored Features - features are anchored at start and stop positions and given pseudo-length chosen by the user. Additionally, the user chooses the length of sequence upstream of the start and downstream of the end to plot.
3. Ignore strand - the directionality (strand) will be ignored all features plotted on the positive strand.
4. Ignore zeros - signal values of 0 in the track will be be excluded from calculations
5. Calculate heatmap - selecting this generates and saves a heat map matrix. Select if you wish to generate heatmap; uncheck if you only wish to generate average plots, as this will speed calculations.
6. Plotting distances in [bp] - the distances in to be plotted:
   • Upstream - the plotting distance in base pairs upstream to the feature
   • Anchored - the pseudo-length, to which the features will be extended or shrunk using linear approximation (only for anchored plots)
   • Downstream - the plotting distance in base pairs downstream to the feature

2.3 Plotting sequence motif density

The Sequence features tab allows you to calculate and plot the density of any user-defined motif around the chosen genomic feature using the reference sequence package. Motif plots can be mixed with track files’ signal plots. The following options can be set:

1. DNA motif - the DNA motif
2. Sliding window size in base pairs [bp] - the size of the sliding window for motif calculation. The value (number of matching motifs within the window) is reported in the middle of the window, e.g. if window is set to 200bp, DNA motif is “GC” and there are 8 CpGs in first 200 bp of the chromosome the value 8 will be reported at 100th bp.
3. Display name - The name of the motif that will be shown in key and heatmap labels. Leave blank to use DNA motif value.
4. Plot heatmap or error estimates - this checkbox determines if heatmap matrix and error estimates should be calculated. If unchecked much faster algorithm will be used for motif density calculation, but only the average plot without the error estimates will be available.
5. Match reverse complement as well - select if reverse complement motif should be reported as well. For example the TATA motif will report both TATA and ATAT with this option selected.

Sequence motifs selection tab

Clicking Add button adds the motif to plot set, while Reset All clears the motif selection. On the right side of the motif setting panel gives a list summary of included motifs.

2.4 Starting the plot set calculation

The options are executed by pressing the Run calculation button. This dismisses the file collection window and brings up the calculation dialog, which shows the progress. On Linux and Mac OS X (systems supporting fork based parallelization) the calculation can be stopped using the Cancel button - this will bring back all settings in file collection window.

The calculation progress dialog

After successful execution the plot array and plot preview panel will appear. In case of error an informative error pop-up will explain the problem. Please refer to the error section for further information.

The plot array

3.1 Previewing plot

After calculating or loading a plot set, a plot array of checkboxes is displayed to select the desired pairs of features and tracks/motifs. Clicking on the column name (tracks/motifs) or row name (features) selects/deselects the whole column or row. Clicking on top-left most cell of plot array toggles the selection of whole array.

Plot preview plus Line plot, Heatmap and refresh buttons

If at least one pair on plot array is selected pressing the Line plot button produces an average plot preview and the Heatmap button produces a heatmap preview. Alternatively, pressing the [RETURN] key will also produce the new selection and options. These operations are done automatically in reactive mode (see Advanced options chapter). Plots can be downloaded as PDF files using the Line plot and Heatmap buttons next to Download (at the top of the panel).

Below the plotting buttons are options for labeling plots and setting axes. On application start the first panel responsible for bringing file upload, management and plot set calculation modals is active. The further three panels hold common plot settings.

3.2 Titles and axis panel

The view on titles and axis panel

This panel groups settings influencing the plot main title, axis labels, various font sizes plus vertical and horizontal plot limits.

• Title - The main title of the plot, shown in top-center part of the figure; default empty
• X-axis label - Label shown below horizontal axis; default empty
• Y-axis label - Label shown below vertical axis; default empty
• Title font size - Font size of the title in points (point = ~1/72 an inch for standard A4 output); default 20 points
• Labels font size - Font size of axis labels in points; default 16 points
• Axis font size - Controls axis ticks font size, that is size of the numbers indicating position in base pairs on X-axis and means signal value on X-axis; default 14 points
• Set X-axis limits - Set hard plotting limits for X-axis; default values are whole range chosen during plot set calculation
• Set Y-axis limits - Set hard plotting limits for Y-axis; default values are a range between lowest and highest mean signal extended by error estimate

3.3 Guide lines and data scaling

The view on guide lines and data scaling

Controls in this panel controls the display of guide lines and error estimates, and allows to log scale the signal prior to plotting.

• Transform signal - if set to Log2 transform performs log2 transformation of the signal prior to plotting; default setting is Do not transform
• Show vertical guide line - show the vertical line at point 0 - beginning of the feature or midpoint and end of the pseudo-length scaled features (only for anchored plots); turn on by default
• Show horizontal guide line - show the horizontal line at user determined height; turn off by default
• Show error estimates - show error standard error and 95% confidence interval as fields, if turned off only the line representing the mean signal is shown; turn on by default

3.4 Keys, labels and colors panel

The view on keys, labels and colors panel (left). Color picker, label text input and Priority/Order checkboxes reviled on plot set grid (right).

This panel groups two types of controls. Colors, Label and Priority/Order are a checkboxes revealing further controls on plot set grid, specific for a feature-track pair or sub-heatmap. Show plot key, Show error estimate key and Legend font size re global controls specific for average plots. Inputs on plot set grid do not have specific labels, but the tooltip explaining their meaning is shown on mouse cursor hover.

• Colors - checkboxes revealing a color picker on plot set grid. This input allows to control the colors of specific feature-track pair average plots or sub-heatmaps. In browser supporting the color picker ‘e.g Chrome’ the system dialog will show up. In other browsers (e.g. Firefox) the javaScript color picker will be initialized.
• Label - checkboxes revealing a label text input plot set grid. This controls the names shown on the key with average plots or the heatmap top labels.
• Priority/Order - checkboxes revealing numeric input on plot set grid. These number determine the order of average plots and hetamaps. Feature-track pair with the highest priority will be listed on the top of key for average plots and left-most for heatmaps.
• Show plot key - shows the key giving the color to feature-track pair label mapping. If turned on the additional drop-down allows to choose the position on the plot, top-right by default
• Show error estimate key - shows the key gexplaining the meaning of error fields. If turnedon the additional drop-down allows to choose the position on the plot, top-left by default
• Legend font size - set the size of font used to plot the keys; 12 default Heatmaps ========

Heatmaps are often more informative than average plots. If there is variability in signal along individual instances of a given genomic feature (e.g., because there are different biological classes), an average plot might not represent the behavior of any individual feature and could even give a misleading picture. SeqPlots plots track-feature pairs as sub-heatmaps horizontally aligned on single figure. All sub-heatmaps must have the same number of data rows, hence in single plot mode simultaneous plotting is possible only on single features or feature files containing exact same number of rows. The heatmaps can be sorted and clustered by k-means, hierarchical clustering or super self organising maps (SupreSOM).

3.5 Heatmap setup tab

This tab has heatmap specific options for data processing and display.

The view on Heatmap setup tab (left). Color picker, Label text input, Priority/Order checkboxes, Choose individual heatmaps for sorting/clustering control and Set individual color key limits numric inputs reviled on plot set grid (right).

• Sort heatmap rows by mean signal - sorts the heatmap rows based on the mean value of each row across included sub-heatmps. Can be set to increasing or decreasing order. Turned off by default.

• Clustering algorithm - choose clustering algorithm (k-means, hierarchical or SupreSOM). If clustering is not desired, choose do not cluster, which uses the feature file in the uploaded order . K-means by default.

• Make cluster calculation repeatable - enforces, that clustering with non-deterministic algorithms, like k-means or SupreSOM will generate the same results as most recently plotted heatmap. This is achieved by re-using R random number generator seed.

• Plot selected cluster - this option is available only if Make cluster calculation repeatable is turned on. Allows to select one of the clusters and zoom it to whole plot height. Plot all clusters by default.

• Choose individual heatmaps for sorting/clustering - this checkbox brings up a new control panel on the plot set grid to determine if a given sub-heatmap should be included in plotting and/or clustering. The excluded sub-plots will be plotted in the order of the other sub-heatmaps, but their values will not influence the clustering/sorting. By default all sub-heatmaps are included.

• Heatmaps have individual color keys - by default all sub-heatmap have their own color keys. This option determines if each sub-heatmap should have a separate color key (plotted below the heatmap) or a single, common key should be calculated for all sub-plots (plotted rightmost). The example below show the difference between separate (left) and common (right) color keys:

  

  Heatmaps have individual color keys usage example: separate (left) and common (right) color keys

• Set default color key limits - this option determines the limits in mapping the numerical values to the colors. The range of colors generated is dependent on these options. Values lower or higher than the given limits will be plotted in the limit value color. If this checkbox is not selected, limits are auto-generated using Color key scaling parameter. If this option it turned off two numerical fields, min and max, are shown to manually set the limits.

  • Color key scaling - this slider influences how color key limits are generated. For example, 0.01 (default value) calculates limits using data ranging from 1-99 percentile of available data points. 0.1 uses data ranging from 10-90 percentile. The general formula for limit is: [quantile(data, Color key scaling); quantile(data, 1-Color key scaling)]
  • min and max numeric inputs - enter values to manually specify color key limits as numeric values.

• Set individual color key limits - this option is similar to manual set up of color key limits, but this allows one to specify different values for individual sub-heatmaps. When this checkbox is selected min and max numeric input menu is shown on the plot set grid

• Set colorspace - This input allows to use color palettes from RColorBrewer package, which would replace default color palette for heatmaps. By selecting Reverse checkbox the reversed color palette will be used. Here are available color pallets (click here to see example heatmap plotted with different color palettes):

  

  Color palettes from RColorBrewer

  When the Custom option is selected three-color pickers are shown to setup custom color mappings for heatmaps. The following example below shows standard jet colors (left), default blue color mapping after selecting the checkbox (middle) and custom color selection (right):

  

  Set default colorspace usage example: standard jet colors (left), default blue color mapping after selecting the checkbox (middle) and custom color selection (right)

3.6 Other options controlling heatmap appearance

The heatmap output shares many display options from other tabs. Here we provide a list of these inputs, please refer to “Viewing and manipulating plots” for further reference.

• Titles and axis panel
  • X-axis label - Label shown below horizontal axis, drawn separately for each sub-heatmap; default empty
  • Y-axis label - Label shown next to vertical axis, drawn separately for each sub-heatmap; default empty
  • Labels font size - Font size for axis labels and main labels of sub-heatmaps; default 16 points
  • Axis font size - Controls axis ticks font size; default 14 points
  • Set X-axis limits - Set hard plotting limits for X-axis; default values are whole range chosen during plot set calculation
• Guide lines and data scaling panel
  • Transform signal - if set to Log2 transform performs log2 transformation of the signal prior to plotting; default setting is Do not transform
  • Show vertical guide line - show the vertical line at point 0 - beginning of the feature or midpoint and end of the pseudo-length scaled features (only for anchored plots); turn on by default
• Keys, labels and colors panel
  • Colors - for hetmaps this input allows to control the color mapping of specific sub-heatmaps. The map starts with white (for low color key limit) and finishes with selected color (for high color key limit).
  • Label - allows to set up custom sub-heatmap top labels
  • Priority/Order - Use this to place heatmaps in your desired order. The feature-track pairs with the highest priority will be plotted as left-most sub-heatmaps.
  • Legend font size - control the font size of common color key, inactive if heatmaps have individual color keys; 12 default

4.1 PDF output size

The last tab (Batch operation and setup) on the tool panel includes batch operations and various other settings including PDF output size. By default the output PDF will be A4 landscape. This can be changed using the drop-down list to following settings:

• user defined - this option reveals two numeric inputs that allows to set output PDF width and height. The values must be given in inches.
• Legal rotated - US Legal landscape: 14" by 8.5"
• A4 - A4 portrait: - 8.27" × 11.69"
• Letter - US Letter portrait: 8.5" × 11"
• Legal - US Legal portrait: 8.5" × 14"
• Executive - a.k.a Monarch paper: 7.25 × 10.5"

The view on top part of batch operation and setup panel

5.1 Load or save plotset

Controls available on the “Load or save plotset” panel:

• Load saved plot set - drop-down list to select a plotset. Once the Rdata binary file is selected the plot grid will be displayed. Selecting the file reveals two additional buttons:
  • Remove dataset - this button deletes the selected saved plot set from user data.
  • Download plotset - this button saves a copy of the plotset in selected location.
• Save current plot set - Enter desired name and press the Save button (appears after input of name). It is also possible to save a copy of loaded plot sets. The plot set binary files can be renamed simply by loading them, saving a copy and deleting original source file.

All saved dataset can be found in data location/publicFiles. Any SeqPlots Rdata binaries put in the folder will become available for loading in Load saved plot set control.

The view on the “Load or save plotset” panel

5.2 Plot set files structure

The plot sets files can be also directly loaded in R. This allows further processing and customization of the plots. Data structure is a nested list, which elements be accessed by [[ R operator. The nesting goes as follow:

• feature - R list
  • track - R list
    • means - numeric vector giving mean signal value for each (binned) genomic position
    • stderror - numeric vector giving standard error for each (binned) genomic position
    • conint - numeric vector giving 95% confidence interval for each (binned) genomic position
    • all_ind - numeric vector giving the genomic position in base pairs
    • e - character string giveing numeric vector giving the indicates of anchored distance, NULL for point features plots
    • desc - auto generated title of the plot
    • heatmap - numeric matrix, (binned) signal values for each genomic position (columns) and each feature (rows)

The example structure:

List of 2
 $ HTZ1_Differential_genes_TOP100_v2.gff:List of 2
  ..$ HTZ1_JA00001_IL1andIL2_F_N2_L3_NORM_linear_1bp_IL010andIL009_averaged.bw    :List of 7
  .. ..$ means   : num [1:501] 2.52 2.52 2.52 2.53 2.54 ...
  .. ..$ stderror: num [1:501] 0.114 0.112 0.111 0.11 0.109 ...
  .. ..$ conint  : num [1:501] 0.226 0.223 0.221 0.218 0.217 ...
  .. ..$ all_ind : num [1:501] -1000 -995 -990 -985 -980 -975 -970 -965 -960 -955 ...
  .. ..$ e       : NULL
  .. ..$ desc    : chr "HTZ1_JA00001_IL1andIL2...\n@HTZ1_Differential_genes_TOP100_v2"
  .. ..$ heatmap : num [1:100, 1:501] 2.36 5.25 2.2 3.48 4.32 ...
  ..$ HTZ1_JA00001_IL3andIIL5_F_lin35_L3_NORM_linear_1bp_IL008andIL011_averaged.bw:List of 7
  .. ..$ means   : num [1:501] 2.36 2.35 2.35 2.36 2.38 ...
  .. ..$ stderror: num [1:501] 0.126 0.125 0.125 0.126 0.125 ...
  .. ..$ conint  : num [1:501] 0.249 0.249 0.247 0.251 0.249 ...
  .. ..$ all_ind : num [1:501] -1000 -995 -990 -985 -980 -975 -970 -965 -960 -955 ...
  .. ..$ e       : NULL
  .. ..$ desc    : chr "HTZ1_JA00001_IL3andIIL5...\n@HTZ1_Differential_genes_TOP100_v2"
  .. ..$ heatmap : num [1:100, 1:501] 2.61 3.17 1.42 2.46 4.26 ...
 $ HTZ1_Differential_genes_BOTTOM100.gff:List of 2
  ..$ HTZ1_JA00001_IL1andIL2_F_N2_L3_NORM_linear_1bp_IL010andIL009_averaged.bw    :List of 7
  .. ..$ means   : num [1:501] 1.57 1.57 1.58 1.6 1.62 ...
  .. ..$ stderror: num [1:501] 0.0996 0.0985 0.1003 0.1022 0.1018 ...
  .. ..$ conint  : num [1:501] 0.198 0.195 0.199 0.203 0.202 ...
  .. ..$ all_ind : num [1:501] -1000 -995 -990 -985 -980 -975 -970 -965 -960 -955 ...
  .. ..$ e       : NULL
  .. ..$ desc    : chr "HTZ1_JA00001_IL1andIL2...n@HTZ1_Differential_genes_BOTTOM100"
  .. ..$ heatmap : num [1:100, 1:501] 1.64 1.37 1.61 1.77 1.86 ...
  ..$ HTZ1_JA00001_IL3andIIL5_F_lin35_L3_NORM_linear_1bp_IL008andIL011_averaged.bw:List of 7
  .. ..$ means   : num [1:501] 1.94 1.94 1.95 1.96 1.97 ...
  .. ..$ stderror: num [1:501] 0.123 0.123 0.124 0.126 0.128 ...
  .. ..$ conint  : num [1:501] 0.244 0.245 0.246 0.251 0.253 ...
  .. ..$ all_ind : num [1:501] -1000 -995 -990 -985 -980 -975 -970 -965 -960 -955 ...
  .. ..$ e       : NULL
  .. ..$ desc    : chr "HTZ1_JA00001_IL3andIIL5...\n@HTZ1_Differential_genes_BOTTOM100"
  .. ..$ heatmap : num [1:100, 1:501] 1.61 1.37 1.29 3.04 3.77 ...

7.1 Stickers