布局

通过前面一节的介绍，我们已经对 circlize 的构图方式有了一个大致的了解，下面我们将详细介绍一下 circlize 的布局结构

1. 坐标转换

我们最后看到的圆形布局结构图，其实是经过了三次的坐标转换。第一次是将数据映射到数据坐标系统中，即我们常用的笛卡尔坐标系；第二次进行极坐标变换，变成圆形布局；最后进行画布坐标变换，将图形输出到图形设备中。

图形总是绘制在半径为 1 的单位元内部，而且是从外向内依次进行绘制

2. 绘制规则

绘制圆形布局图的顺序依次是：初始化布局 -> 创建图形轨迹 -> 添加图形 -> 创建图形轨迹 -> 添加图形 ... -> clear。

1. 初始化布局

布局的初始化使用的是 circos.initialize() 函数，至少需要传递一个分类变量，而每个类别的 x 值范围可以设置为一个向量或范围值

circos.initialize(sectors, xlim)

2. 创建并添加图形

新创建的图形会放置在前面一个图形的内侧，只有创建了图形轨迹之后，才能往里面添加图形。添加图形的方式有三种

• 使用简单图形函数如 circos.points()、circos.lines() 等，逐单元格添加，需要使用 for 循环并指定 sector.index 和 track.index 来定位单元格，例如

circos.track(ylim)
for(sector.index in all.sector.index) {
    circos.points(x1, y1, sector.index)
    circos.lines(x2, y2, sector.index)
}

• 批次添加模式，使用 circos.trackPoints() 和 circos.trackLines() 等函数，同时要指定分类变量以及 x、y 的值，会自动为相应的单元格绘制图形，例如

circos.track(ylim)
circos.trackPoints(sectors, x, y)
circos.trackLines(sectors, x, y)

• 使用 panel.fun 参数添加自定义图形，推荐使用这种方式。这种方式会逐次添加单元格，每添加一个单元格会立即执行 panel.fun 函数，所以该函数总是指向当前创建的单元格，这样我们使用简单图形函数时就不需要指定单元格位置了

circos.track(sectors, all_x, all_y, ylim,
    panel.fun = function(x, y) {
        circos.points(x, y)
        circos.lines(x, y)
})

3. 扇形和轨迹

圆形布局的组成结构可以看下图

引自 circlize 文档

图中，蓝色部分的扇形是一个 sector 且索引为 a，红色圆圈是一个轨迹 track，轨迹的索引为 2

通过这两个索引值，就可以定位圆形布局中每一个单元格，如 a:1 可以用 sector.index = "a" 和 track.index = 1 来获取

sector 是在调用 circos.initialize() 函数时创建的，必须使用分类变量。每个扇形的大小是根据数据的范围来自动设置的

可以设置参数 x 或 xlim 的值来控制每个扇形的数据范围，x 接受一个长度与类别相同的数字向量，xlim 接受一个两列的矩阵为每个扇形设置不同的数据范围，或一个长度为 2 的向量，为所有的扇形设置相同的数据范围

circos.initialize(sectors, x = x)
circos.initialize(sectors, xlim = xlim)

如果没有设置 sectors 参数，将会把 xlim 的行名作为 sectors

circos.initialize(xlim = xlim)

如果想要设置 sectors 的排列顺序，需要使用 factor 并设置对应的 levels

circos.initialize(
  factor(sectors, levels = sectors), 
  xlim = c(0, 1)
)

同一扇形区域内的单元格拥有相同的 x 轴范围，而同一条轨迹中的图形共享相同的 y 范围。

circos.track() 可以接受 y 和 ylim 参数，ylim 为长度为 2 的向量。当然也可以指定 x 的值，但是该值只会传递到 panel.fun 的函数中。

circos.track(sectors, y = y)
circos.track(sectors, ylim = c(0, 1))
circos.track(sectors, x = x, y = y)

由于在初始化布局时就已经确定了每个扇形区域，所以，如果不指定 sectors 参数，默认会应用到所有的扇形中。而 sectors 参数可以是所有扇形的子集，意味着只对指定的这些扇形做相应的调整

circos.track(sub_sectors, y = y)

circos.track(ylim = c(0, 1))
circos.track(ylim = ranges(y))

每个单元格之间是相互独立的，拥有自己的坐标范围

4. 图形参数

圆形布局的一些基础参数，可以使用 circos.par() 来设置。

其中，对扇形进行定位的参数只能在初始化之前(circos.initialize)进行设置：

start.degree
gap.degree/gap.after
canvas.xlim
canvas.ylim
circle.margin
clock.wise
xaxis.clock.wise

可以使用函数参数的方式设置，如

circos.par("start.degree" = 30)

或者使用 $ 的形式

circos.par$start.degree = 30

重置参数的默认值

circos.par(RESET = TRUE)
# circos.clear()

5. panel.fun

panel.fun 参数是 circos.track() 函数中非常有用的参数，可以在创建完单元格之后立即绘制图形。

该参数接受的自定义函数需要两个参数 x、y 来定义单元格的数据点，会自动从 circos.track() 函数中的 x、y 中提取相应扇形区域的数据。

例如

sectors = c("a", "a", "a", "b", "b")
x = 1:5
y = 5:1
circos.track(sectors, x = x, y = y,
    panel.fun = function(x, y) {
        circos.points(x, y)
})

如果 circos.track() 函数中的 x、y 为空，则相应的 panel.fun 函数中的 x、y 也会为空，但是可以获取当前单元格索引的方式来获取全局数据变量的子集

sectors = c("a", "a", "a", "b", "b")
x2 = 1:5
y2 = 5:1
circos.track(ylim = range(y),
    panel.fun = function(x, y) {
        l = sectors == CELL_META$sector.index
        circos.points(x2[l], y2[l])
})

通过获取当前单元格的索引，可以获取对应扇形区域的数据子集，从而到达不使用 x、y 参数的目的。

当前单元格的信息，可以使用 get.cell.meta.data() 函数来获取

可以使用 get.cell.meta.data() 获取的信息有：

• sector.index: 扇形的名称
• sector.numeric.index: 扇形的数值索引
• track.index: 轨迹的数值索引
• xlim: x 轴的最大、最小值
• ylim: y 轴的最大、最小值
• xcenter: xlim 的均值
• ycenter: ylim 的均值
• xrange: x 数据范围 (xlim[2] - xlim[1])
• yrange: y 数据范围 (ylim[2] - ylim[1])
• cell.xlim: 单元格 x 轴范围（包括空白填充）
• cell.ylim: 单元格 y 轴范围
• xplot: 绘图区域的右边框与左边框的角度差，不受圆形布局的方向影响，xplot[1] 总是大于 xplot[2]
• yplot: 绘图区域的下方与上方的半径长度差别
• cell.width: 单元格宽度，计算公式为 xplot[1] - xplot[2]) %% 360
• cell.height: 单元格高度，计算公式为 yplot[2] - yplot[1]
• cell.start.degree: 等同于 xplot[1]
• cell.end.degree: 等同于 xplot[2]
• cell.bottom.radius: 等同于 yplot[1]
• cell.top.radius: 等同于 yplot[2]
• track.margin: 单元格边距
• cell.padding: 单元格空白填充

例如，我们可以在每个单元格中间添加标签

circos.track(ylim = ylim, panel.fun = function(x, y) {
    sector.index = get.cell.meta.data("sector.index")
    xcenter = get.cell.meta.data("xcenter")
    ycenter = get.cell.meta.data("ycenter")
    circos.text(xcenter, ycenter, sector.index)
})

如果想要在 panel.fun 的函数外部使用 get.cell.meta.data()，需要传递对应的单元格索引 sector.index 和 track.index

CELL_META 变量和 get.cell.meta.data() 一样，但是更加简洁，例如，上面的代码可以改写为

circos.track(ylim = ylim, panel.fun = function(x, y) {
    circos.text(CELL_META$xcenter, CELL_META$ycenter, 
        CELL_META$sector.index)
})

需要注意的是，CELL_META 只表示当前单元格的信息，所以无法在函数之外使用

如果想在 panel.fun 函数外部为某一单元格添加一些图形，可以使用 set.current.cell() 来设置当前单元格的位置，而免去重复的设置 sector.index = ..., track.index = ...

set.current.cell(sector.index, track.index)

circos.text(get.cell.meta.data("xcenter"),
            get.cell.meta.data("ycenter"),
            get.cell.meta.data("sector.index"))

更简便的方法是

circos.text(CELL_META$xcenter, CELL_META$ycenter, CELL_META$sector.index)

6. 实用函数

6.1 坐标转换

circlize 数据转换的核心函数是 circlize()，用于将单元格的数据坐标转换为极坐标，其逆转换函数 reverse.circlize() 用于将极坐标转换为数据坐标

例如，对于如下圆形布局

sectors = c("a", "b")
circos.initialize(sectors, xlim = c(0, 1))
circos.track(ylim = c(0, 1))

将 a1 上的点 c(0.5, 0.5) 转换为极坐标

> circlize(0.5, 0.5, sector.index = "a", track.index = 1)
     theta  rou
[1,] 270.5 0.94

将极坐标 c(90, 0.9) 转换为数据坐标

> reverse.circlize(90, 0.9, sector.index = "a", track.index = 1)
            x     y
[1,] 1.519774 -0.06

将 b1 的c(90, 0.9) 转换为数据坐标

> reverse.circlize(90, 0.9, sector.index = "b", track.index = 1)
             x     y
[1,] 0.5028249 -0.06

可以看到不同单元格的同一个坐标点，其数据坐标是不一样的

我们可以使用 circlize:::polar2Cartesian() (该函数接口未暴露，需要这种引用方式)将极坐标转换为画布上的坐标，这样就可以为添加一些特殊的图形。

6.2 绝对单位

在使用包的时候，我们经常需要对宽度或高度进行一些修改，circlize 包提供了一些绝对单位的转换函数，例如

mm_h(), cm_h(), inches_h()/inch_h() 用于将绝对单位：毫米、厘米、英寸转换为画布坐标，如果要转换字符串宽度和高度，可以使用 strheight() 或 strwidth() 函数

mm_h(2) # 2mm
cm_h(1) # 1cm

还有一些函数用于将绝对单位转换为数据坐标：mm_x/y()、cm_x/y()、inches_x/y()/inch_x/y()

mm_x(2)
mm_x(1, sector.index, track.index)
mm_y(2)
mm_y(1, sector.index, track.index)

例如

sectors = letters[1:10]
circos.par(cell.padding = c(0, 0, 0, 0), track.margin = c(0, 0))
circos.initialize(sectors, xlim = cbind(rep(0, 10), runif(10, 0.5, 1.5)))
# 轨迹高度为 5mm
circos.track(
  ylim = c(0, 1), track.height = mm_h(5),
  panel.fun = function(x, y) {
    circos.lines(c(0, 0 + mm_x(5)), c(0.5, 0.5), col = "blue")
  }
)
# 轨迹高度为 1cm
circos.track(
  ylim = c(0, 1), track.height = cm_h(1),
  track.margin = c(0, mm_h(2)),
  panel.fun = function(x, y) {
    xcenter = get.cell.meta.data("xcenter")
    # 绘制长度为 1cm 的线
    circos.lines(c(xcenter, xcenter), c(0, cm_y(1)), col = "red")
  }
)
# 轨迹高度为 1 英寸
circos.track(
  ylim = c(0, 1), track.height = inch_h(1),
  track.margin = c(0, mm_h(5)),
  panel.fun = function(x, y) {
    line_length_on_x = cm_x(1 * sqrt(2) / 2)
    line_length_on_y = cm_y(1 * sqrt(2) / 2)
    circos.lines(c(0, line_length_on_x), c(0, line_length_on_y), col = "orange")
  }
)

7. 设置间距

set_track_gap() 函数可以设置轨迹之间的间距

circos.initialize(letters[1:10], xlim = c(0, 1))
circos.track(ylim = c(0, 1), bg.border = "red")
# 设置第二个轨迹与第一个轨迹之间的间距为 2mm
set_track_gap(mm_h(2)) 
circos.track(ylim = c(0, 1), bg.border = "blue")
# 设置第三个轨迹与第二个轨迹之间的间距为 0.5cm
set_track_gap(cm_h(0.5)) 
circos.track(ylim = c(0, 1), bg.border = "orange")