Author: Lakshay Anand

chromoMap provides interactive, configurable and elegant graphics visualization of chromosomes or chromosomal regions allowing users to map chromosome features (like genes,SNPs etc.) onto the chromosome and visualize the feature-associated data (like multi-omics data). Each chromosome is composed of loci(representing a specific range determined based on chromosome length) that, on hover, shows details about the annotations in that locus range. The plots can be saved as HTML documents that can be shared easily. In addition, you can include them in R Markdown or in R Shiny applications.

Some of the prominent features of the package are:

  • visualizing polyploidy simultaneously on the same plot.
  • annotating groups of elements as distinct colors using chromoMap-DiscreteColorMaps.
  • visualizing multi-omics data associated with features using a variety of plots like chromoMap-HeatMaps (for chromsome heat-maps), chromoMap-Bar (bar plots on chromosomes), chromoMap-Scatter (scatter plot on chromosomes), and epi-tags (condition-based tagging of chromosome loci).
  • Visualize correlations between genomic features using the chromLinks plots
  • adjusting chromosome range or visualizing chromosome regions such as genes
  • adding labels to the plot
  • adding hyperlinks to each element

Getting Started

This vignette provide you with a description of how you can use the various features of chromoMap to create fantastic annotation plots and visualizing the feature-associated data. If you, however, want to know more about the applications of the plot, please check the publication or contact me. I recommend using the RStudio application since the interactive plots can be viewed beautifully in the application’s viewer pane and it allows you to export the plot either as static image or a stand-alone HTML web page.

Install chromoMap

You can install the package by just typing the following commands:

install.packages("chromoMap")

Prepare Input Data Files

The chromoMap can be used to visualize and annotate chromosomes of any living organism. It is because it renders the chromosome based on the co-ordinate information that you will provide as input. So, if you have the genomic co-ordinates of the organism, you can create chromoMaps for it.

The input data are tab-delimited text files (almost similar to the BED file format). It takes separate files for the chromosomes and the annotations. The input files should not have column headers (however, I have explained each column type below)

Chromosome Files

This file contains the co-ordinates of the chromosomes. The columns of this file(in order) are described below (all columns are mandatory unless specified optional):

  • chromosome name: a character representing the chromosome/contig/region name like ‘chr1’ or ‘1’ or ‘ch1’
  • chromosome start: a numeric value to specify chromosome (or chromosome region) start position. If you are considering entire chromosome this value is typically 1.
  • chromsome end: a numeric value specifying chromosome/contig/region end position. Again, if you are considering entire chromosome, then this value is the length of chromosome.
  • centromere start (optional): centromeres will be added automatically if you provide the its start cordinates.

I have developed algorithm that will include both start and end coordinates of chromosomes so that users can also be able to visualize a region of chromosome (not necessarily starting at 1). You can use your imagination to visualize anything that has coordinates( like RNA as well).

Your chromosome file should look like:

Annotation Files

Once you have chromosome co-ordinates in file, the next thing is to have data for annotation. annotation elements/features could be anything that has co-ordinates like genes,SNPS, etc., and associated data, like gene-expression, methylation etc. The annotation-data is also provided in the same format.

  • Element Name: a character specifying (uniquely) the elements. This can be identifiers,symbols etc.
  • Chromosome Name: a character specifying the chromosome name. [NOTE: the chromosome names should be consistent in chromosome and data files.]
  • Element Start: A numeric specifying element start position.
  • Element End: A numeric specifying element end position.
  • Data(optional): A numeric or character specifying the data value.
  • Secondary Data(optional): A vector specifying the data value.useful for multi-factor scatter plots.
  • Hyperlinks(optional): a character specifying the URL of the element.

your annotation file should look like:



To prevent you from making some possible errors, here are a few points to care about while preparing files:

  • Do not include column headers in files.
  • Chromosomes names should be consistent in both files.
  • Elements and chromosome names (first column of both files) should be unique.

TIP: You can use MS excel to create your files and then use save as tab-delimited option.

chromoMap files for this vignette

For the plots in this vignette, I will be using synthetic chromosome and annotation files.

# chromosome files
chr_file_1 = "chr_file_without_centromere.txt"
chr_file_2 = "chr_file_with_centromere.txt"

# annotation files

anno_file_1 = "annotation_pos.txt"
anno_file_2 = "annotation_pos_and_neg.txt"

NOTE: I have used variables to assign file names. You can directly use the file names strings in the chromoMap( ) function.

Let’s have a look at the data in these files:

chromosome file:


head(read.table(chr_file_1,sep = "\t"))
#>     V1 V2   V3
#> 1 chr1  1 1000
#> 2 chr2  1  700

Chromosome file with centromere:


head(read.table(chr_file_2,sep = "\t"))
#>     V1 V2   V3  V4
#> 1 chr1  1 1000 500
#> 2 chr2  1  700 450

Annotation file with positive data.


head(read.table(anno_file_1,sep = "\t"))
#>    V1   V2  V3  V4  V5
#> 1 An1 chr1 558 560  10
#> 2 An2 chr2 396 398  34
#> 3 An3 chr2 281 283  89
#> 4 An4 chr1 125 127  56
#> 5 An5 chr2 406 408 100
#> 6 An6 chr2 340 342  91

Annotation file with both positive and negative data.


head(read.table(anno_file_2,sep = "\t"))
#>    V1   V2  V3  V4   V5
#> 1 An1 chr1 558 560  -64
#> 2 An2 chr2 396 398   29
#> 3 An3 chr2 281 283 -137
#> 4 An4 chr1 125 127 -129
#> 5 An5 chr2 406 408  -18
#> 6 An6 chr2 340 342  149

R objects as chromoMap Inputs

chromoMap now supports passing R objects directly as input instead of filenames. The chromosome cordinate input (first argument) and annotations(second argument) can either be passed as a character vector specifying the filenames or as a list of data.frames with one data.frame per ploidy.

# passing data.frames directly instead of files
chromoMap(list(chr.data),list(anno.data))
# for polyploidy
chromoMap(list(chr.data1,chr.data2),
          list(anno.data1,anno.data2),ploidy = 2)

Note: The format of the data is the same. column names or row names is irrelevant and can be anything but the order should be same as described above (for files).

My first chromoMap

Once you have your input files ready, begin creating chromosomes plots like a pro. The simple annotation plot can be created using the following command:

library(chromoMap)
chromoMap(chr_file_1,anno_file_1)

#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

This will create a plot with default properties.

that’s it! you have created a simple annotation plot. now hover over the annotated loci to see the magic. you should see a tooltip describing:

  • the range of the selected locus in bp
  • the count showing total elements mapped at this locus
  • the element(s) names mapped at this locus which is clickable

If you have added hyperlinks to the elements, you can click the element labels in tooltip to access the web page.

Tool-tip Toggle: On hover, the tooltip appear on the screen as long as your pointer is over the locus. It will disappear if you move the pointer away. You can click the locus to have a stable tooltip on screen. click again on same or other locus to hide it again.

If you are not satisfied with the default look of the plot(which I’m sure you wouldn’t), you can play around with some of the properties to style your plot described under the section ‘configuring chromoMap’ in this vignette.

Now, let’s create one with centromeres.

library(chromoMap)
chromoMap(chr_file_2,anno_file_1)

#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

Polyploidy

Biologically speaking, chromosomes occur in sets. So, just visualizing a set of chromosome(called as haploid) wouldn’t be sufficient in some scenarios. Hence, I added the feature of adding sets of chromosomes as seperate set of files. Don’t forget to set the ploidy argument to the number of sets you are passing.

library(chromoMap)
chromoMap(c(chr_file_1,chr_file_1),c(anno_file_1,anno_file_2),
          ploidy = 2)

#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 2 
#> Number of Chromosomes in set  1 : 2 
#> Number of Chromosomes in set  2 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200 
#> Number of annotations in data set  2 : 200

polyploidy turned out to be a powerful feature that can actually be used in multiple ways. The sets of chromsomes are rendered independent of each other and, hence, can differ in number and size. Using this feature you can visualize polyploid sets, haploid sets of different species on same plot, or even different samples of same species for comparison. Be creative to use this feature to your own requirement. Some interesting examples I have included in my paper.

Point and Segment-annotation plots

I have provided two types of annotation algorithms that will visualize the annotations differently. Point annotation will annotate an element on a single locus, ignoring its size. While, the segment-annotation algorithm consider the size and visualize the annotation as a segment.

The default is point-annotation. To use segment annotation set the argument segment_annotation to TRUE. Segment annotations will be advantageous in cases like displaying gene structure.

chromoMap("chromosome_file.txt","annotation_file.txt",segment_annotation = T)

here’s a hypothetical example(exon regions of the genes g1,g2 and g3).

Data-based annotation plots

Huge volume of biological data is being produced in today’s world. I thought it would be nice to visualize the data associated with the chromosome regions or elements/features. You can do this by creating data-based color annotation plots in chromoMap. Before going forward let’s know about the data types chromoMap can handle. You can use either numeric data or character/categorical data for annotations. For the type of data type you are using, you need to set the argument data_type to either numeric or categorical. Also, to use this category of plot, you need to set data_based_color_map to TRUE.Now let’s explore the various types of plots you can create using chromoMap.

chromoMap-DiscreteColorMaps

This type of plot can be used if your annotations are categorized into groups. This plot will assign distinct colors to each group. Your annotations file’s data column should have groups assigned to each element as character value.

IMPORTANT: the data_colors argument will specify the color for each group and must be passed as a list() of vectors. If the ploidy is 2, two vectors will be passed in list. Hence, you must pass a vector for each ploidy in a list.

chromoMap("chromosome_file.txt","annotation_file.txt",
          data_based_color_map = T,
          data_type = "categorical",
          data_colors = list(c("orange","yellow")))

#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 20

The best thing is, it can also create a legend for each group with labels used by you as group names. [see more under ‘legends’ section]

chromoMap-HeatMaps

chromoMap-HeatMaps are chromosome heatmaps that allow you to visualize feature associated numeric data as heat colors. In your annotations file, add numeric data in data column.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric")
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

data_colors can be used to set the heat colors also. It should be passed as a list of vector(s) with a vector for each ploidy.

Data Aggregation

Well, remember that chromosomal locus in the plot is a range, and more than one elements can be annotated in that range. So, for the data assignment of the loci where multiple elements are mapped, there is an aggregation method that allows you to control how data is aggregated/summarized for a given locus. The data for each locus will be determined by aggregate_func argument which can take avg for average (default) ,sum for summation of data values of all elements mapped on that locus, min , max, and count.

So, if you want to use the sum function:

chromoMap("chromosome_file.txt","annotation_file.txt",
          data_based_color_map = T,
          data_type = "numeric",
          aggregate_func = "sum")

You can use the different agregate functions for each ploidy by passing the argument as vector. Hence, for polyploidy, if only one value is passed, this value will be used for all sets.Otherwise, you can specify for each set as:

chromoMap(c("chromosome_file_set_1.txt","chromosome_file_set_2.txt")
          ,c("annotation_file_set_1.txt","annotation_file_set_2.txt"), 
          ploidy = 2, data_based_color_map = T,data_type = "numeric"
          ,aggregate_func = c("avg","sum"))

Note: If only one element is annotated per loci, than the loci will take the element’s data value.

chromoMap-Bar Plots

In addition to visualizing numeric data as heat colors on the chromosomes, chromoMap allows creating data charts over the annotated loci. chromoMap-Bar plot can be used to visualize annotated data as barplots. You will need to use the plots argument to specify the type of data charts you wish to visualize.

chromoMap(chr_file_1,anno_file_1,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "bar")
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

The bars represents the aggregate_function values for the loci. You can customize the chromoMap-Bar plots using various properties described under customizing Data-Plots section.

You can also turn off the heatmap feature to selectively visualize the chromoMap-Bar plots ( applicable for all of the plots discussed in the subsequent section). For that, set the heat_map argument to FALSE.

chromoMap(chr_file_1,anno_file_1,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "bar",
          heat_map = F)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

chromoMap-Scatter Plots

chromoMap-Scatter plots allows to visualize each value for a given annotated locus as scatter plot.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter")
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

chromoMap-Scatter plots are also interactive as the tooltips for a scatter shows the annotated element name and value.

epi-tags

epi-tags are special plots that allow to add tags over annotated loci.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "tags")
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

These epi-tags can be filtered based on mathematical conditions on the data (discussed in the next section.)

chromoMap-Filters

This feature allows to filter numeric data based on the various mathematical conditions.

tag-filters

Tag-filters allows you to selectively tag a locus based on mathemetical condition on the data. If the condition is satisfied, the locus will be tagged. tag-filters are passed using the tag_filter argument. The argument is a list of vectors where you can pass a vector for each ploidy. the vector specifies two values necessary to pass for a filter. The first value specifies the operation-type and the second value specifies the operands. Following table describes all possible operation-types along with usage example.

In general, filters are specified as list(c("operation-type-label","operand1","operand2"))

#> Warning: package 'knitr' was built under R version 4.0.4
operation type label description usage example
eq equal list(c(“eq”,5))
lt less than list(c(“lt”,-5))
gt greater than list(c(“gt”,6))
lte less than equal list(c(“lte”,6))
gte greater than equal list(c(“gte”,6))
gtalt greater than AND less than list(c(“gtalt”,5,-5))
gtolt greater than OR less than list(c(“gtolt”,5,-5))
gtealte greater than equal AND less than equal list(c(“gtealte”,5,-5))
gteolte greater than equal OR less than equal list(c(“gteolte”,5,-5))

For instance, to tag the loci with negative number values:

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "tags",
          tag_filter = list(c("lt",0)))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

plot-filters

plot-filters are similar to tag-filters as they allow filtering of numeric data based on mathematical conditions, but they are visualized as condition-based coloring of chromoMap-Bar and chromoMap-scatter plots. The plot_filter argument allows you to pass filter conditions. It is also a list of vector(s) similar to tag_filter above, except that you have to pass an additional necessary option of color to it. If the condition is satisfied, this color value is assigned.

So, plot-filters are specified as list(c("operation-type-label","operand1","operand2","color-value"))

Here is an example of using plot-filter on chromoMap-Bar plots. bars with value greater than and equal to are colored ‘green’.

chromoMap(chr_file_1,anno_file_1,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "bar",
          plot_filter = list(c("gte",50,"green")))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

Similarly, it can be applied for chromoMap-Scatter plots. The following example visualizes negative values as red on the scatter plot.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          plot_filter = list(c("lt",0,"red")))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

multi-factor scatter plots

In order to visualize a second factor onto the scatter plot, you can now use a special plot_filter option. The input data specifying the categories should be passed a secondary data column in addition to the primary data.

the input data file now looks like:

head(anno_file_3)
#>    V1   V2  V3  V4  V5 V6
#> 1 An1 chr1 558 560  10  C
#> 2 An2 chr2 396 398  34  B
#> 3 An3 chr2 281 283  89  B
#> 4 An4 chr1 125 127  56  A
#> 5 An5 chr2 406 408 100  B
#> 6 An6 chr2 340 342  91  D

You can specify the colors of each category by using the scatter.colors argument. The legend is automatically displayed and can be adjusted with scatter.lg_x and scatter.lg_y arguments.

chromoMap(chr_file_1,anno_file_3,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          plot_filter = list(c("col","byCategory")),
          scatter.colors = c("pink3","orange3","purple","blue2"))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

NOTE: As of now, only categorical data is supported as secondary data for this feature.



Customizing chromoMaps

chromoMap allows various options to customize and fine-tune your plots as desirable. This section covers all the customization options available.

width and height

You can configure the dimensions(width and height) of the plot by using the parameter canvas_width and canvas_height.

chromoMap("chromosome_file.txt","annotation_file.txt",
          canvas_width = 600,
          canvas_height = 700)

When you use multiple ploidy, the plot might go off the margins. You can adjust the width and height to fit the plot to your need.

Title

You can add a title to your plot by using title argument.

chromoMap("chromosome_file.txt","annotation_file.txt",
          title = "my first chromoMap plot")

You can also adjust the font-size of the title using the title_font_size argument:

chromoMap("chromosome_file.txt","annotation_file.txt",
          title = "my first chromoMap plot",
          title_font_size = 12)

Margins

You can adjust the left and top margins through top_margin and left_margin.

chromoMap("chromosome_file.txt","annotation_file.txt",
          top_margin = 25,
          left_margin = 15)

Chromosome colors

You can change the color of each set of chromosome by using chr_color property.

chromoMap("chromosome_file.txt","annotation_file.txt",
          chr_color = c("orange"))

For polyploidy, if only one color is passed it will be taken for all sets of chromsomes. Otherwise, you can assign color to each set:

chromoMap(c("chromosome_file_set_1.txt","chromosome_file_set_2.txt")
          ,c("annotation_file_set_1.txt","annotation_file_set_2.txt"), 
          ploidy = 2,
          chr_color = c("pink","blue"))

USEFUL TIPS :

  • Use hexadecimal color codes to assign beautiful color shades to embellish your plot.
  • setting the chromosome color to white will make them appear invisible hence only colored annotations will be visible(might be helpful in some case).

Annotation colors

For simple annotation plot, you can change the annotation color by using anno_col argument.

chromoMap("chromosome_file.txt","annotation_file.txt",
          anno_col = c("orange"))

For polyploidy, if you have passed one color value it will be taken for all the sets. Otherwise, you can pass distinct color values for each set:

chromoMap(c("chromosome_file_set_1.txt","chromosome_file_set_2.txt")
          ,c("annotation_file_set_1.txt","annotation_file_set_2.txt"), 
          ploidy = 2,
          anno_col = c("pink","blue"))

NOTE: For data-based annotation plots(chromoMap-DiscreteColorMaps or chromoMap-HeatMaps), colors are controlled by data_colors argument which is passed as a list of vector(s).

Chromosome width, length, and spacing

Do you think chromosomes appear too thin or too short for your annotations? well, you can adjust these parameters by using chr_width and chr_length arguments.

chromoMap("chromosome_file.txt","annotation_file.txt",
          chr_width = 4,
          chr_length = 5)

the spacing between chromosomes can be adjusted with ch_gap argument.

chromoMap("chromosome_file.txt","annotation_file.txt",
          ch_gap = 6)

Chromosome curves

The curves appearing at the telo-meres (chromosome end loci) and in centromere locus can also be adjusted using the chr_curve argument.

chromoMap("chromosome_file.txt","annotation_file.txt",
          chr_curve = 5)

TIP: setting this property to 0 will remove the curves that render the chromosomes as rectangles.

Chromsome scale y-position

You can adjust the y or vertical position of the chromosome scale using the y_chr_scale argument.

Chromosome text

Well, the chromosome text will be taken from file you have provided. The only thing I thought might be useful is to enable or disable text individually for each ploidy. This is done by using chr_text parameter.

chromoMap("chromosome_file.txt","annotation_file.txt",
          chr_text = F)

For multiple ploidy pass a vector:

chromoMap(c("chromosome_file_set_1.txt","chromosome_file_set_2.txt")
          ,c("annotation_file_set_1.txt","annotation_file_set_2.txt"), 
          ploidy = 2,
          chr_text = c(T,F))

you can adjust the text font size using text_font_size parameter.

plot ID

The id argument allows to uniquely identify the plot. This feature is important when including multiple chromoMap plots in a single HTML document (like RMarkdown) as it prevent from any conflicts.

chromoMap("chromosome_file.txt","annotation_file.txt",
          id="my_plot_1")

Automatic color assignments

As a test feature, chromoMap now automatically assigns random color values if the colors are not passed manually. the color values are randomly selected and change every time you plot. I would still recommend using the manual color assignments.

Also, now you can use R color names such as ‘red3’ as color inputs.

Customizing Data Plots

chromoMap-Bar, chromoMap-Scatter , and epi-tag plots can be customized as desired.

Reference Lines

You can add a horizontal reference line to the data-plots. Set the ref_line argument to TRUE. The reference line is attached to the axis-scale. By default, the line is attached at the beginning of the axis(position:0). You can adjust the refl_pos argument to bring the line to desirable position.

TIP:For the line to be at the middle of axis, set refl_pos argument to exactly half of plot_height.

chromoMap(chr_file_1,anno_file_1,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "bar",
          ref_line = T,
          refl_pos = 15)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

Reference line in scatter plot:

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          ref_line = T,
          refl_pos = 20)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

You can change the color and stroke-size of the reference line using refl_color and refl_stroke_w arguments respectively.

Plot height

Change the plot height using plot_height parameter.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          plot_height = 50)

Plot Colors

Change the plot colors (bar and scatter colors) using the plot_color parameter.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          plot_color = "orange")

For the epi-tag plots, you need to use tagColor argument that will change the tag-head colors.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "tags",
          tagColor = "orange")

Plot y-axis range and ticks

You can change the range of y-axis of the plots using plot_y_domain argument. It is passed as list of vector(s), a vector for each ploidy. You can also change the number of ticks of the scale using the plot_ticks argument.

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          plot_ticks = 3,
          plot_y_domain = list(c(-5,5)))

Highlighting with grid lines

vertical grid lines can be used to highlight specific regions of the chromosomes. You can add any number of grid-lines to the plot. Set the vertical_grid argument to TRUE. You can add multiple grid lines by specifying a vector of positions(in bp) within the max range of the plot(depicted by the horizontal chromosome scale). The following example demonstrate the use of grid lines where 5 grid lines are added at random genomic positions 1,54,100,420, and 621(the entire scale is 1k bp wide). The plot also demonstrate the use of other customization options.

chromoMap(c(chr_file_1,chr_file_1),c(anno_file_1,anno_file_2),
          ploidy = 2
          data_based_color_map = T,
          data_type = "numeric",
          plots = c("bar","scatter"),
          plot_height = 40,
          plot_color = c("green","red"),
          ref_line = T,
          refl_pos = 20,
          #gridline arguments
          vertical_grid = T,
          grid_array = c(1,54,100,420,621))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 2 
#> Number of Chromosomes in set  1 : 2 
#> Number of Chromosomes in set  2 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200 
#> Number of annotations in data set  2 : 200

adding labels to grid lines

You can also add text/labels for individual grid line. the text will added at the top end of the grid-line and needs to be passed as an array(vector) of texts for each corresponding position passed in grid_array. Use the grid_text argument to pass the text, grid_text_size to specify the text font-size, grid_text_y to adjust the vertical position of the texts, and grid_color to change color of grid-lines.

chromoMap(c(chr_file_1,chr_file_1),c(anno_file_1,anno_file_2),
          ploidy = 2
          data_based_color_map = T,
          data_type = "numeric",
          plots = c("bar","scatter"),
          plot_height = 40,
          plot_color = c("green","red"),
          ref_line = T,
          refl_pos = 20,
          #gridline arguments
          vertical_grid = T,
          grid_array = c(1,54,100,420,621),
          grid_text = c("","","mark 1","region 1",""))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 2 
#> Number of Chromosomes in set  1 : 2 
#> Number of Chromosomes in set  2 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200 
#> Number of annotations in data set  2 : 200

Note: for the grid-lines for which no text was displayed an empty string "" is added corresponding to the grid-line position. The length of grid_array and grid_text should match.

Quick Zoom-in

chromoMap now supports a quick zoom-in feature that allow the users to zoom in on a specific region of interest on any chromosome. The region information is passed with the region argument which is a character vector containing region(s) in the following format:

c("<chromsome name>:<ploidy>:<region start>:<region stop>")

eg. c(“chr1:1:5142689:6478512”)

highlighting a region

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          #highlighting a region on chr1
          vertical_grid = T,
          grid_array = c(550,754))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 200

zooming in on that region

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          #zoom in
          region = c("chr1:1:550:754"))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> WARNING:  80  out-of-bound annotations are removed in chromosome set  1 .
#> Number of annotations in data set  1 : 120

Note: the scale of the chromosomes will be updated based on their new length. The region zoom could have been done by modifying the chromosome range in the input chromosome files but this argument provides a quick option to view a region of interest without changing the master chromosome data.

multiple regions can also be passed as:

chromoMap(chr_file_1,anno_file_2,
          data_based_color_map = T,
          data_type = "numeric",
          plots = "scatter",
          #zoom in
          region = c("chr1:1:550:754","chr2:1:221:450"))
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> WARNING:  138  out-of-bound annotations are removed in chromosome set  1 .
#> Number of annotations in data set  1 : 62

Legends

legends are provided for data-based annotation plots (chromoMap-DiscreteColorMaps and chromoMap-HeatMaps). It is hidden by default. Use legend option to enable it.

chromoMap("chromosome_file.txt","annotation_file.txt",
          data_based_color_map = T,
          data_type = "categorical",
          legend = T)

For polyploidy, you can enable or disable the legend independently for each set.

chromoMap(c("chromosome_file_set_1.txt","chromosome_file_set_2.txt")
          ,c("annotation_file_set_1.txt","annotation_file_set_2.txt"), 
          ploidy = 2,
          data_based_color_map = T,
          data_type = "numeric",
          legend = c(F,T))

positioning legends

I know, the legends in your plot are present weirdly?. I have made the postion of legends independent of the plot and hence you can position it anywhere in the plot you want using the y and x direction length. Consider the orgin to be the bottom right corner of the plot now tweak the lg_x and/or lg_y arguments to adjust the positioning of the legend.

chromoMap("chromosome_file.txt","annotation_file.txt",
          data_based_color_map = T,
          data_type = "categorical",
          legend = T, lg_x = 100,
          lg_y = 250)

Labellings

This feature I added at the end thought might be useful in some scenarios. This will show the labels (element names) on top of locus. It is disabled by default, to enable it use label argument.

chromoMap("chromosome_file.txt","annotation_file.txt",
          labels=T)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 20

You can change the labels angle and font-size using label_angle and label_font arguments respectively.

chromoMap("chromosome_file.txt","annotation_file.txt",
          labels=T,
          label_font = 12,
          label_angle = -65)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 20

TIP: To make the labels non-overlapping, tweak the chromosome length and width properties like shown in the following example.

chromoMap("chromosome_file.txt","annotation_file.txt",
          labels=T,
          label_angle = -65,
          chr_length = 6,
          chr_width = 25,
          canvas_width = 800)
#> ********************************** __ __ ************
#> ** __**|__ * __* __ * __ __ * __ *|  |  |* __ * __ **
#> **|__**|  |*|  *|__|*|  |  |*|__|*|  |  |*|_ |*|__|**
#> ***********************************************|   **
#> *****************************************************
#> OUTPUT: 
#> Number of Chromosome sets: 1 
#> Number of Chromosomes in set  1 : 2 
#> Processing data.. 
#> Number of annotations in data set  1 : 20

Exporting chromoMaps

The RStudio allows the option to export the graphics, shown in its viewer’s pane ,as either a static image or a web page. Use this feature to either save chromoMaps as static images and include them into your documents or papers, or export interactive plots as standalone-html to include them as supplementary materials in publications.

Including chromoMaps in Shiny Applications

You can include chromoMaps in Shiny application by using the function chromoMapOutput() in the UI part of the code and renderChromoMap() in the server part of the code.

Shiny Application example

library(shiny)
library(chromoMap)

# Define UI for application that draws chromoMap
ui <- fluidPage(
   
   # Application title
   titlePanel("An example of chromoMap in Shiny"),
   
   # you can use GUI controls for your chromoMap
   sidebarLayout(
      sidebarPanel(
         #some code
      ),
      
      # Show a plot of the generated distribution
      mainPanel(
         chromoMapOutput("myChromoMap")
      )
   )
)

# Define server logic required to draw chromoMap
server <- function(input, output) {
   
   output$myChromoMap <- renderChromoMap({
     chromoMap("chromosome_file.txt","annotation_file.txt")
   })
}

# Run the application 
shinyApp(ui = ui, server = server)

license

The chromoMap package is distributed under GPL-3 (GNU GENERAL PUBLIC LICENSE version 3).

Contact

You are welcome to send feedback or bug reports through e-mail

Session Info

 sessionInfo()
#> R version 4.0.3 (2020-10-10)
#> Platform: x86_64-w64-mingw32/x64 (64-bit)
#> Running under: Windows 10 x64 (build 19042)
#> 
#> Matrix products: default
#> 
#> locale:
#> [1] LC_COLLATE=C                          
#> [2] LC_CTYPE=English_United States.1252   
#> [3] LC_MONETARY=English_United States.1252
#> [4] LC_NUMERIC=C                          
#> [5] LC_TIME=English_United States.1252    
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] knitr_1.31      chromoMap_0.3.1
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.27     R6_2.5.0          jsonlite_1.7.2    magrittr_2.0.1   
#>  [5] evaluate_0.14     highr_0.8         rlang_0.4.10      stringi_1.5.3    
#>  [9] jquerylib_0.1.3   bslib_0.2.4       rmarkdown_2.7     tools_4.0.3      
#> [13] stringr_1.4.0     htmlwidgets_1.5.3 xfun_0.20         yaml_2.2.1       
#> [17] compiler_4.0.3    htmltools_0.5.1.1 sass_0.3.1