Inspired by writing an answer to this question on StackOverflow, I decided to write up a more detailed description of creating a new transformation using the scales
package (and also to make sure that I understood all the details about how to really do it).
To start with, it helps to understand the philosophy behind the scales
package. From the description of the scales
package:
Scales map data to aesthetics, and provide methods for automatically determining breaks and labels for axes and legends.
Within the realm of scales
, a transformation allows for a maniuplation of the data space prior to its mapping to an aesthetic. In particular, it is responsible for
There are two main use cases for a transformation:
These variable transformations take place before any stat
s are performed on the data. In fact, they are equivalent, in terms of effects on data, as putting a transform in as the variable itself (though the axes breaks and labels are different). Quoting from ggplot2: Elegent Graphics for Data Analysis (page 100):
Of course, you can also perform the transformation yourself. For example, instead of using
scale_x_log()
, you could plotlog10(x)
. That produces an identical result inside the plotting region, but the axis and tick labels won’t be the same. If you use a transformed scale, the axes will be labelled in the original data space. In both cases, the transformaiton occurs before the statistical summary.
I reproduce Figure 6.4 using the current version of the code because it is different than what was published.
qplot(log10(carat), log10(price), data=diamonds)
qplot(carat, price, data=diamonds) +
scale_x_log10() + scale_y_log10()
The pieces that are needed to create a transformation are described on the help page for trans_new
, but I’ll go through them in more detail.
transform
and inverse
These are the workhorses of the transformation and define the functions that map from the original data space to the intermediate data space (transform
) and back again (inverse
). These can be specified as a function (an anonymous function or a function object) or as a character string which will cause a function of that name to be used (as determined by match.fun
).
Each of these functions should take a vector of values and return a vector of values of the same length. Callilng inverse
on the results of transform
should result in the original vector (to within any error introduced by floating point arithmetic). That is all.equal(inverse(tranform(x)), x)
should be TRUE
for any x
(for which transform
is defined; see domain
below).
Both of these functions are required.
breaks
breaks
is a function which takes a vector of length 2 which represents the range of the data, expressed in the original data space, that is to be represented. This will include any requested expansion, in addition to the actual data values. breaks
should return a vector of whatever length it deems appropriate such that each break is represented by one element of the vector. Optionally, the vector can be a named vector. If it is, the default formatter will use the names as the displayed version of the values.
In general, this is a hard problem, primarily because breaks should look “nice” which is difficult for an algorithm to determine. Luckily, others have spent time working on the problem and often much of what they have learned and implemented can be used without having to do much yourself. In partciular, there are existing break determination algorithms in scales
such as pretty_breaks
(which is based on base::pretty
) which find breaks for a simple numeric scale, extended_breaks
which is based on extensions of work by Wilkinson which covers the same terrirory, log_breaks
which give integer breaks on a log-transformed scale, and date_breaks
which works with date data.
All these functions are generators, meaning that they are functions which return functions which do the actual work of finding the breaks. These function can take parameters which define the properties of the breaking algorithm, such as the number of breaks, the base of the logarithm, or the spacing in time between dates.
This argument is optional, and if not supplied a default algorithm is used which will evenly space the ticks in the original data space.
format
format
is a function which takes a vector of values in the original data space (those returned by the breaks
function) and returns either a character vector of the same length or a list of expressions of the same length. The latter is useful for making expressions that can be handled by plotmath.
scales
includes many formatting functions including comma_format
which puts commas between thousands, millions, billions, etc.; dollar_format
which rounds to either cents or dollars (threshold definable in generator) and adds a “$” in front and commas; percent_format
which multiples by 100 and add a percent sign (“%”); and parse_format
and math_format
which aid in making plotmath expressions for lables.
As with breaks
, all the functions are generators which means that they are functions which return functions. The returned function is the one that takes a single vector, and is what is assigned to the format
argument.
This argument is optional and if not supplied, the default algorithm will use any names returned with the breaks. If there are no names, then format
is called on the passed values.
domain
The domain
is the values over which the transform
function is defined. For example, square root and logarithm are only defined for positive values (ggplot does not deal with complex values); and arcsine transformation would only be defined between -1 and 1. This is represented by a length 2 vector of the endpoints (inclusive) of the defined range.
This argument is optional, and if missing it is assumed that the transformation if valid over all numeric values.
name
A character string to identify the transformation. It is used in summary output, but has no computational value.
There are built in transformations for logarithms and for reversing a scale, but there is not one to do both at once (largest to smallest, left to right). The code for each of these, taken from the scales
package, is
log_trans <- function(base = exp(1)) {
trans <- function(x) log(x, base)
inv <- function(x) base ^ x
trans_new(str_c("log-", format(base)), trans, inv,
log_breaks(base = base), domain = c(1e-100, Inf))
}
reverse_trans <- function() {
trans_new("reverse", function(x) -x, function(x) -x)
}
To make a reversed log scale, the breaks
are the same as for a regular log scale, so that part does not need to be recreated. In fact, much of log_trans
can be reused with changes being made to just the transformation and inverse functions.
reverselog_trans <- function(base = exp(1)) {
trans <- function(x) -log(x, base)
inv <- function(x) base^(-x)
trans_new(paste0("reverselog-", format(base)), trans, inv,
log_breaks(base = base), domain = c(1e-100, Inf))
}
I have opted here to follow the general pattern of the other trans functions making this a generator of the transformation, parameterizable by the base of the logarithm. Since I’ve used the _trans
naming convention, I can also just call it (with the default parameters) as a string in the trans
argument of scale_x_continuous
. Some examples of it at work:
dat <- data.frame(x=1:20, y=1:20)
ggplot(dat, aes(x,y)) + geom_point() +
scale_x_continuous(trans="reverselog")
ggplot(dat, aes(x,y)) + geom_point() +
scale_x_continuous(trans=reverselog_trans(base=2))
R-2.15.1, ggplot2-0.9.1, scales-0.2.1
code available at https://github.com/BrianDiggs/trans