---
title: "Using the circlizePlus Package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the circlizePlus Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Addition rules

ccPlot(contain n ccPars)+ccPar=ccPlot(contain n+1 ccPars),n>=0

ccPlot(contain n ccTracks)+ccTrack=ccPlot(contain n+1 ccTracks),n>=0

ccPlot(contain n ccLinks)+ccLink=ccPlot(contain n+1 ccLinks),n>=0

ccTrak(contain n ccTrakGeoms)+ccTrackGeom=ccTrack(contain n+1 ccTrackGeoms),n>=0

ccTrack(contain n ccCells)+ccCell=ccTrack(contain n+1 ccCells),n>=0

ccCell(contain n ccCellGeoms)+ccCellGeom=ccCell(contain n+1 ccCellGeoms),n>=0

## S4 class ccCell and ccCells

-   ccCell: Generate a cell container that belongs to a particular sector.
-   ccCells: A list of multiple `ccCell`. Any `ccCellGeom` and `ccCells` are added together as if they were added to each `ccCell` contained in the `ccCells`.

## API outline

### Initializer

-   Class: [ccPlot-class](https://tianzelab.github.io/circlizePlus/reference/ccPlot-class.html)
-   Function: [ccPlot()](https://tianzelab.github.io/circlizePlus/reference/ccPlot.html)

### Parameter

-   Class: [ccPar-class](https://tianzelab.github.io/circlizePlus/reference/ccPar-class.html)
-   Function: [ccPar()](https://tianzelab.github.io/circlizePlus/reference/ccPar.html)

### Cell container

-   Class: [ccCell-class](https://tianzelab.github.io/circlizePlus/reference/ccCell-class.html), [ccCells-class](https://tianzelab.github.io/circlizePlus/reference/ccCells-class.html)
-   Function: [ccCell()](https://tianzelab.github.io/circlizePlus/reference/ccCell.html), [ccCells()](https://tianzelab.github.io/circlizePlus/reference/ccCells.html)

### Cell geometry

-   Class: [ccCellGeom-class](https://tianzelab.github.io/circlizePlus/reference/ccCellGeom-class.html), [ccGenomicCellGeom-class](https://tianzelab.github.io/circlizePlus/reference/ccGenomicCellGeom-class.html)
-   Function: [ccText()](https://tianzelab.github.io/circlizePlus/reference/ccText.html), [ccPoints()](https://tianzelab.github.io/circlizePlus/reference/ccPoints.html), [ccLines()](https://tianzelab.github.io/circlizePlus/reference/ccLines.html), [ccSegments()](https://tianzelab.github.io/circlizePlus/reference/ccSegments.html), [ccRect()](https://tianzelab.github.io/circlizePlus/reference/ccRect.html), [ccPolygon()](https://tianzelab.github.io/circlizePlus/reference/ccPolygon.html), [ccXaxis()](https://tianzelab.github.io/circlizePlus/reference/ccXaxis.html), [ccYaxis()](https://tianzelab.github.io/circlizePlus/reference/ccYaxis.html), [ccBarplot()](https://tianzelab.github.io/circlizePlus/reference/ccBarplot.html), [ccBoxplot()](https://tianzelab.github.io/circlizePlus/reference/ccBoxplot.html), [ccViolin()](https://tianzelab.github.io/circlizePlus/reference/ccViolin.html), [ccArrow()](https://tianzelab.github.io/circlizePlus/reference/ccArrow.html), [ccRaster()](https://tianzelab.github.io/circlizePlus/reference/ccRaster.html), [ccDendrogram()](https://tianzelab.github.io/circlizePlus/reference/ccDendrogram.html), [ccGenomicPoints()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicPoints.html), [ccGenomicLines()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicLines.html), [ccGenomicRect()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicRect.html), [ccGenomicText()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicText.html), [ccGenomicAxis()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicAxis.html)

### Track container

-   Class: [ccTrack-class](https://tianzelab.github.io/circlizePlus/reference/ccTrack-class.html), [ccGenomicTrack-class](https://tianzelab.github.io/circlizePlus/reference/ccGenomicTrack-class.html)
-   Function: [ccTrack()](https://tianzelab.github.io/circlizePlus/reference/ccTrack.html), [ccTrackHist()](https://tianzelab.github.io/circlizePlus/reference/ccTrackHist.html), [ccGenomicTrack()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicTrack.html), [ccGenomicIdeogram()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicIdeogram.html), [ccGenomicHeatmap()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicHeatmap.html), [ccGenomicLabels()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicLabels.html), [ccGenomicRainfall()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicRainfall.html), [ccGenomicDensity()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicDensity.html)

### Track geometry

-   Class: [ccTrackGeom-class](https://tianzelab.github.io/circlizePlus/reference/ccTrackGeom-class.html)
-   Function: [ccTrackLines()](https://tianzelab.github.io/circlizePlus/reference/ccTrackLines.html), [ccTrackPoints()](https://tianzelab.github.io/circlizePlus/reference/ccTrackPoints.html), [ccTrackText()](https://tianzelab.github.io/circlizePlus/reference/ccTrackText.html)

### Link

-   Class: [ccLink-class](https://tianzelab.github.io/circlizePlus/reference/ccLink-class.html), [ccHeatmapLink-class](https://tianzelab.github.io/circlizePlus/reference/ccHeatmapLink-class.html), [ccGenomicLink-class](https://tianzelab.github.io/circlizePlus/reference/ccGenomicLink-class.html)
-   Function: [ccLink()](https://tianzelab.github.io/circlizePlus/reference/ccLink.html), [ccHeatmapLink()](https://tianzelab.github.io/circlizePlus/reference/ccHeatmapLink.html), [ccGenomicLink()](https://tianzelab.github.io/circlizePlus/reference/ccGenomicLink.html)

### Heatmap

-   Class: [ccHeatmap-class](https://tianzelab.github.io/circlizePlus/reference/ccHeatmap-class.html)
-   Function: [ccHeatmap()](https://tianzelab.github.io/circlizePlus/reference/ccHeatmap.html)

## Data mapping from track to cell geometry

|                                      |                   |                  |                  |                  |           |            |             |           |                              |                |
|-------|-------|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| ccTrack Constructor                  | ccGenomicTrack()  | ccGenomicTrack() | ccGenomicTrack() | ccGenomicTrack() | ccTrack() | ccTrack()  | ccTrack()   | ccTrack() | ccTrack()                    | ccTrack()      |
| Parameters in ccTrack Constructor    | data              | data             | data             | data             | x, y      | x, y       | x, y        | x, y      | x, y                         | x, y           |
| ccCellGeom Constructor               | ccGenomicPoints() | ccGenomicLines() | ccGenomicRect()  | ccGenomicText()  | ccLines() | ccPoints() | ccPolygon() | ccText()  | ccRect()                     | ccSegments()   |
| Parameters in ccCellGeom Constructor | region, value     | region, value    | region, value    | region, value    | x, y      | x, y       | x, y        | x, y      | xleft, ybottom, xright, ytop | x0, y0, x1, y1 |

A combination of each column in the table above:

### Get track from ccGenomicTrack()

`region` and `value` in ccGenomicCellGeom constructor can be `NULL` or function like `function(region,value){...}`. The above data can be obtained from the `data` parameter of `ccGenomicTrack`.

In the following example code, the `region` and `value` in the `ccGenomicLines` constructor are `NULL`. Their real data comes from the `data` value of the corresponding sector in `ccGenomicTrack`. The `region` and `value` in the `ccGenomicPoints` constructor are `function`. Their real data is calculated based on the definition of the function.

``` r
data = generateRandomBed(nr =30, nc = 2)
all_chr = c("chr1","chr2","chr3","chr4","chr5","chr6","chr7","chr8","chr9","chr10","chr11","chr12","chr13","chr14","chr15","chr16","chr17","chr18","chr19","chr20","chr21","chr22","chrX","chrY")
cc = ccPlot(initMode = "initializeWithIdeogram", plotType=NULL)
t1 = ccGenomicTrack(data=data, numeric.column = 4,
                    panel.fun=function(region,value,...){
                      circos.genomicPoints(region,value,...)
                    })
cells1 = ccCells(sector.indexes = all_chr) + ccGenomicLines(numeric.column=2) + ccGenomicPoints(region=\(region,value){region}, value=\(region,value){value}, numeric.column=2)
t1 = t1 + cells1
show(cc+t1)
```

### Get track from ccTrack()

`x`, `x0`, `x1`, `xleft`, `xright`, `y`, `y0`, `y1`, `ytop`, `ybottom` in ccCellGeom constructor can be `NULL` or function like `function(x,y){...}`. The above data can be obtained from the `x` and `y` parameter of `ccTrack`.

In the following example code, the `x` and `y` in the first `ccPoints` constructor are `NULL`. Their real data comes from the `x` and `y` of the corresponding sector in `ccTrack`. The `y` in the second `ccPoints` constructor are `function`. Their real data is calculated based on the definition of the function.

``` r
sectors = c('a','a','a','a','b','b','b','b','c','c','c','c','d','d','d','d')
x1 = c(1,2,3,4,1,2,3,4,1,2,3,4,1,2,3,4)
y1 = c(1,2,3,4,4,3,2,1,1,1,1,1,1,2,1,2)
cc = ccPlot(initMode = "initialize", sectors = sectors, x = x1)
cells = ccCells(sector.indexes = letters[1:4])
cc_point = ccPoints()
cells = cells + cc_point + ccLines()
track1 = ccTrack(sectors = sectors, x=x1, y = y1,panel.fun = function(x,y){
  circos.points(y,x)
})
cell_single = ccCell(sector.index = letters[3]) + ccPoints(y=\(x,y){x-y})
track1 = track1 + cells + cell_single
show(cc  + track1)
```