Scale: Scales
In hadley/ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
Scale R Documentation
Scales
Description
All scale_*() functions (like scale_fill_continuous()) return a Scale*
object. The main purpose of these objects is to translate data values to
aesthetic values and populating breaks and labels.
Details
All scale_* functions like scale_x_continuous() return a Scale* object
like ScaleContinuous. Each of the Scale* objects is a ggproto() object
descended from the top-level Scale.
Scales generally need to track three types of spaces:
Data space. These are values as they are evaluated from the plot
or layer mapping, prior to any transformation.
Transformed space. This is the space after original data has been
transformed. Effectively, scales internally operate in transformed space
in that ranges and breaks get passed around in this space. Discrete scales
don't do transformations, so for these scales, transformed space is the
same as untransformed space.
Aesthetic space. Graphic values that are mapped from the transformed
space. This is dependent on the palette field for most scales and on the
rescaler field for continuous position scales.
The user is expected to give any vector-based minor_breaks, breaks or
limits in data space. When breaks, limits or labels is a function,
its input is expected to be in data space.
Before you attempt to create a new Scale* class of your own, it is
recommended to think through whether your aims cannot be implemented with
one of the existing classes. Making a wrapper for the continuous_scale(),
discrete_scale() and binned_scale() should cover many cases, and should
be considered prior to commiting to build a Scale* extension.
For example, if you aim to develop a scale for a new data type, it should
generally be possible to create a new transformation
instead. One reason to implement your own Scale* class is to accommodate
a data type does not lend itself for continuous or discrete range training.
In such case, you can override the following:
The range field.
The transform, train and map methods.
The get_limits(), get_breaks() and get_labels() methods.
Fields
callA call object with the user-facing constructor
function, for use in error messaging. This field is populated by scale
constructors.
rangeA Range class object, like
scales::ContinuousRange or scales::DiscreteRange. These are 'trained'
to keep track of the data range (continuous) or data levels (discrete).
Continuous ranges are tracked in transformed space.
aesthetics,palette,name,breaks,labels,limits,name,guide,position,na.value,expandFields populated by the scale constructor that can take on the same values
as described in e.g. ?continuous_scale.
Note that limits is expected in transformed space.
transform_df,transformDescription
A function method for orchestrating the transformation of aesthetics in a
data frame. Data transformation occurs before stats are computed.
The transform_df() method ensures the transform() method is applied
to the correct columns.
Usage
Scale$transform_df(df)
Scale$transform(x)
Arguments
dfA data frame with the layer's data.
xA vector of the relevant aesthetic.
Value
For transform() a vector of transformed values.
For transform_df(), a named list with transformed values for each
transformed aesthetic.
train_df,trainDescription
A function method for orchestrating scale training for keeping track of
the data range or levels. The train_df() method ensures the train()
method is applied to the correct columns.
Usage
Scale$train_df(df)
Scale$train(x)
Arguments
dfA data frame with the layer's data.
xA vector of the relevant aesthetic.
Value
Nothing, these are called for their side effect of updating the range
field.
map_df,mapDescription
A function method for orchestrating the mapping of data values to
aesthetics. The map_df() method ensures the map() method is applied
to the correct columns. When the scale uses a palette() function, it is
applied in the map() method.
Usage
Scale$map_df(df, i)
Scale$map(x, limits)
Arguments
dfA data frame with the layer's data.
iAn integer vector giving an index to map a subset of data.
The default, NULL, will map all rows.
xA vector of the relevant aesthetic.
limitsA vector of the relevant aesthetic, usually via
the get_limits() method.
Value
For map() a vector of mapped values in aesthetics space.
For map_df(), a named list with mapped values for each
aesthetic.
recaleDescription
A function method for applying the recale function in the rescaler field.
It is used during the continuous map() and Coord$transform() methods
to ensure values are in the 0-1 range.
Usage
Scale$rescale(x, limits, range)
Arguments
xA vector of values to rescale. Can contain out-of-bounds
or missing values depending on the map() method.
limitsA length two vector giving the limits of the relevant
aesthetic, usually via the get_limits() method.
rangeA length two vector giving the range that should coincide
with the 0-1 points. For most purpuses, this should be the same as the
limits argument.
Value
A vector of values between 0 and 1 for in-bounds values of x.
get_limitsDescription
A function method for resolving user input and getting the scale limits.
Usage
Scale$get_limits()
Value
The scale limits, without any expansion applied, in transformed space.
dimensionDescription
A function method for getting a continuous representation of the limits of
position scales. For continuous scales, the dimension is the same concept
as the limits. For discrete scales the dimension is the continuous range
occupied by the mapped breaks, which by default take integer positions.
Usage
Scale$dimension(expand, limits)
Arguments
expandA length 4 vector giving scale expansion.
This is optional and defaults to no expansion.
limitsA vector of the relevant aesthetic, usually via
the get_limits() method.
Value
A numeric vector of length 2
get_breaks,get_breaks_minorDescription
A function method for resolving user input and getting the scale breaks
or minor breaks. Note that these may return out-of-bounds values for the
purpose of coordinating with the get_labels() method.
Usage
Scale$get_breaks(limits)
Scale$get_breaks_minor(n, b, limits)
Arguments
limitsA vector of the relevant aesthetic, usually via
the get_limits() method.
nAn integer setting the desired number of minor breaks per
major break. Note that the resulting minor breaks may coincide with
major breaks.
bA vector of mapped major breaks from the get_breaks()
method.
Value
A vector of breaks in transformed space.
get_labelsDescription
A function method for resolving user input and getting the scale labels for
a set of breaks.
Usage
Scale$get_labels(breaks)
Arguments
breaksA vector of unmapped major breaks from the get_breaks()
method, in transformed space.
Value
A vector of labels of the same length as breaks.
get_transformationDescription
A helper method to access the scale's transformation object.
Usage
Scale$get_transformation()
Value
A transform object.
break_infoDescription
A function method for getting all break related information for position
scales. It is in use by coords that do not use the modern Guide system
and secondary axes.
Usage
Scale$break_info(range)
Arguments
rangeA vector of the relevant aesthetic.
Value
A named list with the following structure:
-
range a length 2 vector giving continuous range
-
labels a character or expression vector of the same length as major breaks.
-
major a numeric vector with mapped numeric values for major breaks.
-
major_source a numeric vector with (transformed) data values for major breaks.
-
minor a numeric vector with mapped numeric values for minor breaks.
-
minor_source a numeric vector with (transformed) data values for minor breaks.
break_positionDescription
A function method for getting mapped break positions. It is in use as a
default value in get_breaks_minor(), but is otherwise vestigial.
Usage
Scale$break_info(range)
Arguments
rangeA vector of the relevant aesthetic.
Value
A vector with mapped break positions
make_title,make_sec_titleDescription
A function method for picking the title to use. This is usually called in
the Guide$extract_params() or Layout$resolve_label() methods.
The hierarchy of titles goes from guide (highest priority), to scale, to
labs (lowest priority).
When the guide or scale title are functions, they're applied to the next
in line. The make_sec_title() method by default re-uses the primary
make_title() method and only applies to position aesthetics.
Usage
Scale$make_title(guide_title, scale_title, label_title)
Scale$make_sec_title(...)
Arguments
guide_titleThe title parameter coming from a guide.
scale_titleThe name field of the Scale.
label_titleThe relevant entry in the plot$labels field.
...By default, arguments forwarded to the make_title()
method
Value
A scalar character or expression title
axis_orderDescription
A function method for setting the order of axes titles used to coordinate
with Facet$draw_labels().
Usage
Scale$axis_order()
Value
Either c("primary", "secondary") or c("secondary", "primary").
cloneDescription
A function method for making an untrained copy of the scale. Due to
reference semantics of ggproto objects, in contrast to copy-on-modify
semantics, scales need to be cloned at the start of plot building.
The cloned scale can be trained independently of the original.
Usage
Scale$clone()
Value
A Scale object.
resetDescription
A function method for to reset the range field, effectively 'untraining'
the scale. This is used in the Layout$reset_scales() method, so that
scales can be re-trained on data with final position aesthetics.
For discrete scales, only the continuous range (range_c) is reset.
Usage
Scale$clone()
Value
None, called for the side-effect of resetting the range.
is_emptyDescription
A function method for determining whether a scale is empty, i.e. when no
information with which to calculate limits.
Usage
Scale$is_empty()
Value
A scalar boolean value.
is_emptyDescription
A function method for determining whether a scale is discrete.
Usage
Scale$is_discrete()
Value
A scalar boolean value.
Conventions
The object name that a new class is assigned to is typically the same as the
class name. Scale class names are in UpperCamelCase and start with the
Scale* prefix, like ScaleNew.
In scales, there is a difference between user-facing and developer-facing
constructors. Developer facing constructors have the shape
{foundation}_scale(), like discrete_scale() corresponding to
ScaleDiscrete. User-facing constructors have the scale_{aesthetic}_{type}
as name. If you implement a new Scale* class, you like want both these
types of constructor.
Examples
# TODO: find easy to digest example
NULL
hadley/ggplot2 documentation built on June 13, 2025, 12:51 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Scale | R Documentation |
Scales
Description
All scale_*() functions (like scale_fill_continuous()) return a Scale*
object. The main purpose of these objects is to translate data values to
aesthetic values and populating breaks and labels.
Details
All scale_* functions like scale_x_continuous() return a Scale* object
like ScaleContinuous. Each of the Scale* objects is a ggproto() object
descended from the top-level Scale.
Scales generally need to track three types of spaces:
Data space. These are values as they are evaluated from the plot or layer mapping, prior to any transformation.
Transformed space. This is the space after original data has been transformed. Effectively, scales internally operate in transformed space in that ranges and breaks get passed around in this space. Discrete scales don't do transformations, so for these scales, transformed space is the same as untransformed space.
Aesthetic space. Graphic values that are mapped from the transformed space. This is dependent on the
palettefield for most scales and on therescalerfield for continuous position scales.
The user is expected to give any vector-based minor_breaks, breaks or
limits in data space. When breaks, limits or labels is a function,
its input is expected to be in data space.
Before you attempt to create a new Scale* class of your own, it is
recommended to think through whether your aims cannot be implemented with
one of the existing classes. Making a wrapper for the continuous_scale(),
discrete_scale() and binned_scale() should cover many cases, and should
be considered prior to commiting to build a Scale* extension.
For example, if you aim to develop a scale for a new data type, it should
generally be possible to create a new transformation
instead. One reason to implement your own Scale* class is to accommodate
a data type does not lend itself for continuous or discrete range training.
In such case, you can override the following:
The
rangefield.The
transform,trainandmapmethods.The
get_limits(),get_breaks()andget_labels()methods.
Fields
callA call object with the user-facing constructor function, for use in error messaging. This field is populated by scale constructors.
rangeA
Rangeclass object, likescales::ContinuousRangeorscales::DiscreteRange. These are 'trained' to keep track of the data range (continuous) or data levels (discrete). Continuous ranges are tracked in transformed space.aesthetics,palette,name,breaks,labels,limits,name,guide,position,na.value,expandFields populated by the scale constructor that can take on the same values as described in e.g.
?continuous_scale. Note thatlimitsis expected in transformed space.transform_df,transformDescription
A function method for orchestrating the transformation of aesthetics in a data frame. Data transformation occurs before stats are computed. The
transform_df()method ensures thetransform()method is applied to the correct columns.Usage
Scale$transform_df(df) Scale$transform(x)
Arguments
dfA data frame with the layer's data.
xA vector of the relevant aesthetic.
Value
For
transform()a vector of transformed values. Fortransform_df(), a named list with transformed values for each transformed aesthetic.train_df,trainDescription
A function method for orchestrating scale training for keeping track of the data range or levels. The
train_df()method ensures thetrain()method is applied to the correct columns.Usage
Scale$train_df(df) Scale$train(x)
Arguments
dfA data frame with the layer's data.
xA vector of the relevant aesthetic.
Value
Nothing, these are called for their side effect of updating the
rangefield.map_df,mapDescription
A function method for orchestrating the mapping of data values to aesthetics. The
map_df()method ensures themap()method is applied to the correct columns. When the scale uses apalette()function, it is applied in themap()method.Usage
Scale$map_df(df, i) Scale$map(x, limits)
Arguments
dfA data frame with the layer's data.
iAn integer vector giving an index to map a subset of data. The default,
NULL, will map all rows.xA vector of the relevant aesthetic.
limitsA vector of the relevant aesthetic, usually via the
get_limits()method.
Value
For
map()a vector of mapped values in aesthetics space. Formap_df(), a named list with mapped values for each aesthetic.recaleDescription
A function method for applying the recale function in the
rescalerfield. It is used during the continuousmap()andCoord$transform()methods to ensure values are in the 0-1 range.Usage
Scale$rescale(x, limits, range)
Arguments
xA vector of values to rescale. Can contain out-of-bounds or missing values depending on the
map()method.limitsA length two vector giving the limits of the relevant aesthetic, usually via the
get_limits()method.rangeA length two vector giving the range that should coincide with the 0-1 points. For most purpuses, this should be the same as the
limitsargument.
Value
A vector of values between 0 and 1 for in-bounds values of
x.get_limitsDescription
A function method for resolving user input and getting the scale limits.
Usage
Scale$get_limits()
Value
The scale limits, without any expansion applied, in transformed space.
dimensionDescription
A function method for getting a continuous representation of the limits of position scales. For continuous scales, the dimension is the same concept as the limits. For discrete scales the dimension is the continuous range occupied by the mapped breaks, which by default take integer positions.
Usage
Scale$dimension(expand, limits)
Arguments
expandA length 4 vector giving scale expansion. This is optional and defaults to no expansion.
limitsA vector of the relevant aesthetic, usually via the
get_limits()method.
Value
A numeric vector of length 2
get_breaks,get_breaks_minorDescription
A function method for resolving user input and getting the scale breaks or minor breaks. Note that these may return out-of-bounds values for the purpose of coordinating with the
get_labels()method.Usage
Scale$get_breaks(limits) Scale$get_breaks_minor(n, b, limits)
Arguments
limitsA vector of the relevant aesthetic, usually via the
get_limits()method.nAn integer setting the desired number of minor breaks per major break. Note that the resulting minor breaks may coincide with major breaks.
bA vector of mapped major breaks from the
get_breaks()method.
Value
A vector of breaks in transformed space.
get_labelsDescription
A function method for resolving user input and getting the scale labels for a set of breaks.
Usage
Scale$get_labels(breaks)
Arguments
breaksA vector of unmapped major breaks from the
get_breaks()method, in transformed space.
Value
A vector of labels of the same length as
breaks.get_transformationDescription
A helper method to access the scale's transformation object.
Usage
Scale$get_transformation()
Value
A transform object.
break_infoDescription
A function method for getting all break related information for position scales. It is in use by coords that do not use the modern Guide system and secondary axes.
Usage
Scale$break_info(range)
Arguments
rangeA vector of the relevant aesthetic.
Value
A named list with the following structure:
-
rangea length 2 vector giving continuous range -
labelsa character or expression vector of the same length as major breaks. -
majora numeric vector with mapped numeric values for major breaks. -
major_sourcea numeric vector with (transformed) data values for major breaks. -
minora numeric vector with mapped numeric values for minor breaks. -
minor_sourcea numeric vector with (transformed) data values for minor breaks.
break_positionDescription
A function method for getting mapped break positions. It is in use as a default value in
get_breaks_minor(), but is otherwise vestigial.Usage
Scale$break_info(range)
Arguments
rangeA vector of the relevant aesthetic.
Value
A vector with mapped break positions
make_title,make_sec_titleDescription
A function method for picking the title to use. This is usually called in the
Guide$extract_params()orLayout$resolve_label()methods. The hierarchy of titles goes from guide (highest priority), to scale, to labs (lowest priority). When the guide or scale title are functions, they're applied to the next in line. Themake_sec_title()method by default re-uses the primarymake_title()method and only applies to position aesthetics.Usage
Scale$make_title(guide_title, scale_title, label_title) Scale$make_sec_title(...)
Arguments
guide_titleThe
titleparameter coming from a guide.scale_titleThe
namefield of the Scale.label_titleThe relevant entry in the
plot$labelsfield....By default, arguments forwarded to the
make_title()method
Value
A scalar character or expression title
axis_orderDescription
A function method for setting the order of axes titles used to coordinate with
Facet$draw_labels().Usage
Scale$axis_order()
Value
Either
c("primary", "secondary")orc("secondary", "primary").cloneDescription
A function method for making an untrained copy of the scale. Due to reference semantics of ggproto objects, in contrast to copy-on-modify semantics, scales need to be cloned at the start of plot building. The cloned scale can be trained independently of the original.
Usage
Scale$clone()
Value
A Scale object.
resetDescription
A function method for to reset the
rangefield, effectively 'untraining' the scale. This is used in theLayout$reset_scales()method, so that scales can be re-trained on data with final position aesthetics. For discrete scales, only the continuous range (range_c) is reset.Usage
Scale$clone()
Value
None, called for the side-effect of resetting the range.
is_emptyDescription
A function method for determining whether a scale is empty, i.e. when no information with which to calculate limits.
Usage
Scale$is_empty()
Value
A scalar boolean value.
is_emptyDescription
A function method for determining whether a scale is discrete.
Usage
Scale$is_discrete()
Value
A scalar boolean value.
Conventions
The object name that a new class is assigned to is typically the same as the
class name. Scale class names are in UpperCamelCase and start with the
Scale* prefix, like ScaleNew.
In scales, there is a difference between user-facing and developer-facing
constructors. Developer facing constructors have the shape
{foundation}_scale(), like discrete_scale() corresponding to
ScaleDiscrete. User-facing constructors have the scale_{aesthetic}_{type}
as name. If you implement a new Scale* class, you like want both these
types of constructor.
Examples
# TODO: find easy to digest example
NULL
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.