Author: Lisa A. Ouellette
Date: 2018-01-21

# LinkageMapView Examples

#### Lisa A. Ouellette

#### 2018-01-21

## Introduction

The LinkageMapView package produces linkage group maps and QTL maps from a variety of inputs. The output is a portable document format (PDF) and publication ready.

There are many options for customizing the maps which will be reviewed in this vignette.

## Input

### Linkage group positions and loci names

The first argument, mapthis, can be one of the following:

- a file name. The file can be a text file or a comma delimited file. The first three columns should be in this order:
  - linkage group name - character
  - position - numeric
  - locus name at this position - character
- a data frame with columns as described above.
- a cross object from the qtl package.

A data frame example:

    library(LinkageMapView)
    data(carrot)
    head(carrot)
    #>     group position    locus
    #> 1 2170LG3    0.000 BSSR-094
    #> 2 2170LG3    7.039   ESSR86
    #> 3 2170LG3   11.123      F3H
    #> 4 2170LG3   11.123     FLS1
    #> 5 2170LG3   13.079   ESNP32
    #> 6 2170LG3   13.079   ESNP31

A cross object from the qtl package example:

    library(qtl)
    #> Warning: package 'qtl' was built under R version 3.4.1
    data(hyper)
    class(hyper)
    #> [1] "bc"    "cross"
    summary(hyper)
    #>     Backcross
    #>
    #>     No. individuals:    250
    #>
    #>     No. phenotypes:     2
    #>     Percent phenotyped: 100 100
    #>
    #>     No. chromosomes:    20
    #>         Autosomes:      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
    #>         X chr:          X
    #>
    #>     Total markers:      174
    #>     No. markers:        22 8 6 20 14 11 7 6 5 5 14 5 5 5 11 6 12 4 4 4
    #>     Percent genotyped:  47.7
    #>     Genotypes (%):
    #>           Autosomes:    BB:50.1  BA:49.9
    #>        X chromosome:    BY:53.0  AY:47.0

The mapthese parameter is a vector of linkage groups from the input that you wish to print. The default prints all linkage groups in the input. You can print linkage groups in any order and you can print linkage groups more than once.

## PDF options

The following PDF options can be specified and will be passed through to the PDF device.

- pdf.family - the font family for all text. Default is “Helvetica”.
- pdf.fg - the foreground color (lines and text). Default is “black”.
- pdf.bg - the background color. Default is “transparent”.
- pdf.pointsize - default is 12.
- pdf.title - the title for a PDF ONLY appears in the metadata and does not appear in the output itself. See main.
- pdf.width - width of the output file in inches.
- pdf.height - height of the output file in inches.

Note that pdf.width and pdf.height will be calculated automatically if they are not specified.

Continuing with the hyper cross object loaded above from the qtl package:

    outfile = file.path(tempdir(), "hyper.pdf")
    lmv.linkage.plot(hyper,outfile,mapthese=c(1,4,6,15))
    #> Required pdf.width = 13.686
    #> Required pdf.height = 4.23313333333333
    #> Using pdf.width = 14
    #> Using pdf.height = 5

## Position and Locus Format Options

If more than one locus name appears at the same position, the label is indented slightly to catch your eye. The parameter maxcolsfordups determines how many loci names will print on one line before going to subsequent lines. The default is 3. When multiple lines are required for all the labels at the same position, the labels are joined by a vertical line.

The roundpos parameter, which defaults to 1, specifies how many positions after the decimal point should be printed for the locus position.

Another parameter for handling multiple loci at the same position, is dupnbr. If TRUE, only the first locus name at a position will print with, “## more” afterwards, indicating the number of duplicate locus names at that position:

    outfile = file.path(tempdir(), "hyper_dupnbr.pdf")
    lmv.linkage.plot(hyper,outfile,mapthese=c(1,4,6,15),dupnbr = TRUE)
    #> Required pdf.width = 12.8381666666667
    #> Required pdf.height = 4.0656
    #> Using pdf.width = 13
    #> Using pdf.height = 5

There is another parameter, showonly, which can be used to specify the locus names to be printed. All other locus names and positions will not be printed. The next example will demonstrate the use of the showonly parameter along with loci and position formatting options. By default the positions print to the left of the linkage group and so the position format options begin with an ‘l’. And by default the loci print to the right of the linkage group and so the loci format options begin with an ‘r’:

- lcex - Default is par(“cex”)
- lcol - Default is par(“col”)
- lfont - Default is par(“font”)
- rcex - Default is par(“cex”)
- rcol - Default is par(“col”)
- rfont - Default is par(“font”)

See help for par, `?par`, for a full description of these defaults.

In this example we will show only one locus per linkage group. The positions and locus will be printed at twice the normal magnification (lcex=2 and rcex=2), the positions will be green, the loci red, and the position font will be bold (2) and the loci font will be italic (3).

    outfile = file.path(tempdir(), "hyper_showonly.pdf")
    lmv.linkage.plot(hyper,outfile,mapthese=c(1,4,6,15),lcol="green",lcex=2,lfont=2,
        rcol="red",rcex=2,rfont=3,
        showonly=c("D1Mit123","D4Mit80","D6Mit135","D15Mit156"))
    #> Required pdf.width = 16.0066666666667
    #> Required pdf.height = 2.0552
    #> Using pdf.width = 17
    #> Using pdf.height = 3

Lines are still drawn across the linkage group to indicate all locus positions even though the labels are not shown. Note that the color of the line across the linkage group and to the loci name defaults to the color of the loci name. This default can be changed with rsegcol=FALSE which indicates the line across the linkage group and to the loci name should be the pdf.fg color instead.

## Main Title and Linkage Group Titles

The main parameter is used for a title for the entire drawing and defaults to NULL. By default, each linkage group name is printed above the linkage group. To turn off linkage group names printing use prtlgtitles=FALSE. You can override the linkage group names to be printed by using the lgtitles parameter. The magnification, font and color of the linkage group titles and the main title can be adjusted with the following parameters:

- cex.lgtitle - Default is par(“cex.main”)
- cex.main - Default is par(“cex.main”)
- col.lgitle - Default is par(“col.main”)
- col.main - Default is par(“col.main”)
- font.lgtitle - Default is par(“font.main”)
- font.main - Default is par(“font.main”)

    outfile = file.path(tempdir(), "hyper_titles.pdf")
    lmv.linkage.plot(hyper,outfile,mapthese=c(1,4,6,15),col.lgtitle = "blue",cex.lgtitle=2,
        col.main = "red",main="Overall Title for the Output Map")
    #> Required pdf.width = 13.686
    #> Required pdf.height = 4.23313333333333
    #> Using pdf.width = 14
    #> Using pdf.height = 5

## Quantitative Trait Loci (QTL) input

There are two different ways to input QTL.

1. qtldf = a data frame containing these columns:

- chr - Linkage group name for QTL.
- qtl - Name (label) for QTL.
- so - Start of outer interval. Numeric.
- si - Start of inner interval. Numeric.
- ei - End of inner interval. Numeric.
- eo - End of outer interval. Numeric.
- col - Color for QTL.

2. qtlscanone = scanone object from package r/qtl. If provided, all QTLs in the data frame will be drawn by calculating their start and end with the r/qtl function bayesint with defaults.

The next example demonstrates several features in addition to qtldf. If you wish to use different colors or formats for different loci labels you can do so with the markerformatlist parameter, providing a list of loci and their desired format options. If you specify ruler=TRUE the positions will not be printed. Instead a vertical axis, or ruler, will be drawn on the left side of the page. You may also reverse the positions on a linkage group. Specify a vector of linkage group names using the revthese parameter. The ‘chromosome’ has various format options as well:

- lg.col - color for the inside of the chromosome. The default is pdf.bg.
- lgw - width of chromosome in inches. Default is 0.25 inches.
- lg.lwd - linkage group line width. The width of the line around the chromosome. Defaults to par(“lwd”).

    ## plot a carrot comparative linkage map
    ## kindly provided by Massimo Iorizzo:
    ## Cavagnaro et al. BMC Genomics 2014, 15:1118
    data(carrot)
    # make a df to pass qtl info
    qtldf <- data.frame(
      chr = character(),
      qtl = character(),
      so = numeric(),
      si = numeric(),
      ei = numeric(),
      eo = numeric(),
      col = character(),
      stringsAsFactors = FALSE
    )
    qtldf <- rbind(qtldf,
                   data.frame(
                     chr = "70349LG3",
                     qtl = "RTPE-Q1",
                     so = 36.6,
                     si = 37,
                     ei = 37,
                     eo = 38,
                     col="red"
                   ))
    # make a list to pass label options
    flist <- list()
    locus <- c("BSSR-094", "K0149", "K0627", "K2161", "ESSR-087", "ESSR-057")
    font  <- c(2)   #bold
    flist[[1]] <- list(locus = locus, font = font)
    locus <- c("F3H", "FLS1")
    font  <- c(4)   #bold italic
    flist[[2]] <- list(locus = locus, font = font)
    locus <- c("P3", "P1", "Raa1")
    font  <- c(3)   #italic
    col <- c("red")
    flist[[3]] <- list(locus = locus, font = font, col = col)

    outfile = file.path(tempdir(), "carrot.pdf")
    lmv.linkage.plot(
      carrot,
      outfile = outfile,
      ruler = TRUE,
      lgtitle = c("2170", "70349", "10117"),
      maxnbrcolsfordups = 2,
      markerformatlist = flist,
      lg.col = "lightblue1",
      pdf.height = 16,
      pdf.width = 10,
      revthese = c("70349LG3"),
      qtldf=qtldf
    )
    #> Required pdf.width = 8.4455
    #> Required pdf.height = 14.7877333333333
    #> Using pdf.width = 10
    #> Using pdf.height = 16

## Density Maps and Ruler Customization

The last example will illustrate producing a density map. There is a helper function, `?lmvdencolor` which you may use to provide your own color palette, window size and color bias. In this example the defaults are accepted and the denmap=TRUE parameter is specified. In addition, this example customizes the ruler (y axis).

    ## do a density map with default colors and customize the axis
    data(oat)

    ## draw tickmarks at each cM from 0 to largest position of linkage groups to be drawn
    maxpos <- floor(max(oat$Position[oat$Group == "Mrg01" | oat$Group == "Mrg02"]))
    at.axis <- seq(0, maxpos)

    ## put labels on ruler at every 10 cM
    axlab <- vector()
          for (lab in 0:maxpos) {
            if (!lab %% 10) {
              axlab <- c(axlab, lab)
            }
            else {
              axlab <- c(axlab, NA)
            }
          }

    outfile = file.path(tempdir(), "oat_denmap.pdf")
    lmv.linkage.plot(oat,outfile,mapthese=c("Mrg01","Mrg02"),denmap=TRUE, cex.axis = 1, at.axis = at.axis, labels.axis = axlab)
    #> Required pdf.width = 2.5668
    #> Required pdf.height = 10.5916666666671
    #> Using pdf.width = 3
    #> Using pdf.height = 11