# Tutorial 3: Setting line attributes

The code for setting line attributes has changed a lot during recent updates. As with point attributes, changes to line attributes are possible by supplying lists of arguments to the `plot.control` command within `circleplot`.

Shape
Perhaps the most obvious aspect of figures drawn using `circleplot` is the fact that points are joined using curves; or more accurately, parabolas. The curvature of these parabolas is determined by two numbers, which can be altered by supplying a length-2 vector to `line.curvature`. Each of these numbers is a proportion. The first is the proportional curvature of all lines: setting this value to zero provides a straight line between two connected points, while setting it to one gives a parabola that intersects the two points and the origin (i.e. the centre of the circle). The second number is multiplicative by distance; points that are further apart have more extreme curves when this value is >0.

The default settings have been chosen to present connections between points in the clearest possible manner, but other permutations are possible. This allows some interesting changes to the appearance of `circleplot` figures, including use of straight lines instead of curves. However, values over 0.5 can make the plot difficult to interpret, as shown here:

```# create a symmetric, lower-triangular, binary matrix
binary.matrix<-matrix(
data=cut(rnorm(11**2), breaks=c(-20, 0, 20), labels=FALSE)-1,
nrow=11, ncol=11)
binary.dis<-as.dist(binary.matrix)
attr(binary.dist, "Labels")<-LETTERS[1:11]

# demonstrate the effect of a change in line.curvature values
par(mfrow=c(3, 3))
for(i in 1:3){
for(j in 1:3){
x<-c(0, 0.2, 0.5)[i]
y<-c(0, 0.2, 0.5)[j]
circleplot(binary.dist, plot.control=list(
line.curvature=c(x, y),
line.cols=rgb(1-(x+y), x, (x+y), maxColorValue=1)
))
mtext(paste("c(", x, ", ", y, ")", sep=""), 1, adj=0, line=-3, cex=0.7)
}}
par(mfrow=c(1, 1))
```

Colour & Thickness
The function that likely to be most useful to most users is the ability to alter line colour and thickness. For binary matrices, this is typically a case of setting some global colours (using `line.cols`) and sizes (using `line.widths`). However, there are two other options that users might be interested in. First is the degree of tapering of connecting lines towards their edges, set using `line.expansion`. As with line.curvature, this is a proportion, however in this case it refers to the amount that the line thickens towards the centre (where it matches the value given by `line.widths`). The second useful option for binary matrices has already been discussed in our discussion of point attributes, and allows the colour of a line to fade between the colours of the two points that it connects using `line.gradient`. Note that this only makes sense if the points being connected are different colours:

```par(mfrow=c(1, 3))
circleplot(binary.dist, plot.control=list(
line.widths=1.5, line.cols="darkred"))
circleplot(binary.dist, plot.control=list(
line.widths=3, line.cols="darkgreen", line.expansion=0.5))
circleplot(binary.dist, plot.control=list(
par(mfrow=c(1, 1))
```

For numeric matrices, a common task is to change how lines are displayed according to their values. `circleplot` allows users to change either the line colour or thickness by specifying `line.breaks` and their associated `line.cols` and `line.widths`

```# create a numeric matrix
numeric.matrix<-matrix(data=rnorm(11**2), nrow=11, ncol=11)
numeric.dist<-as.dist(numeric.matrix) # lower triangular

# compare default and manual plots
par(mfrow=c(1, 2))
circleplot(numeric.dist)
mtext("Default", side=3, cex=0.7, line=-1) # default
circleplot(numeric.dist, plot.control=list(
line.breaks=c(-2:2),
line.cols=brewer.pal(4, "BrBG")[4:1],
line.width=c(2, 1, 1, 2)
))
mtext("Manual", side=3, cex=0.7, line=-1)
par(mfrow=c(1, 1))
```

next: comparing datasets

## 3 thoughts on “Tutorial 3: Setting line attributes”

1. R Fields says:

Hi Again,

I am trying my best to figure out how the line.breaks and line.cols work so that I can be sure I am interpreting my graph correctly. I’ve been reading through both the tutorials here as well as the code on github. In the example above, you define line.breaks = c(-2:2) [equal to c(-2,-1,0,1,2)]

I noticed that the code requires the length of colors defined to be 1 less than number of breaks. Do I interpret this to mean that the 4 colors defined will represent the Odds Ratios in between: (-2 and -1); (-1 and 0); (0 and 1); (1 and 2)?

One other question, I noticed that there were nice legends on most of your plots corresponding to different OR. Is this a feature of circleplot, or did you mannually add them later? I suspect it is the latter, and that I why I want to understand exactly how circleplot is deturmining what colors to use.

Thank you, this is a really cool package!

1. Hi! You are right on both counts. The line.breaks argument is simply passed as the ‘breaks’ argument to cut(), so your interpretation of line values is correct. As for the legend, I don’t like the default legends so I did draw this manually (by adding a new panel with split.screen, if I remember correctly) – it’s slower but looks better.

2. R Fields says:

Thank you! As a follow-up: What are the default line.breaks set to?