All <code>scale_*()</code> functions (like <code>scale_fill_continuous()</code>) return a <code>Scale*</code>
object. The main purpose of these objects is to translate data values to
aesthetic values and populating breaks and labels.

Scale

A system for 'declaratively' creating graphics, based on "The
Grammar of Graphics". You provide the data, tell 'ggplot2' how to map
variables to aesthetics, what graphical primitives to use, and it
takes care of the details.

Thomas Lin Pedersen

ggplot2

Create Elegant Data Visualisations Using the Grammar of Graphics

Hadley Wickham

Winston Chang

Lionel Henry

Kohske Takahashi

Claus Wilke

Kara Woo

Hiroaki Yutani

Dewey Dunnington

Teun van den Brand

Posit, PBC 

Scale function

Scales — Scale

<dl>
<dt><code>call</code></dt>
<dd>A <a href='https://rdrr.io/r/base/call.html'>call</a> object with the user-facing constructor
function, for use in error messaging. This field is populated by scale
constructors.</dd>


<dt><code>range</code></dt>
<dd>A <code><a href='https://scales.r-lib.org/reference/Range.html'>Range</a></code> class object, like
<code><a href='https://scales.r-lib.org/reference/Range.html'>scales::ContinuousRange</a></code> or <code><a href='https://scales.r-lib.org/reference/Range.html'>scales::DiscreteRange</a></code>. These are 'trained'
to keep track of the data range (continuous) or data levels (discrete).
Continuous ranges are tracked in transformed space.</dd>


<dt><code>aesthetics,palette,name,breaks,labels,limits,name,guide,position,na.value,expand</code></dt>
<dd>Fields populated by the scale constructor that can take on the same values
as described in e.g. <code>?continuous_scale</code>.
Note that <code>limits</code> is expected in transformed space.</dd>


<dt><code>transform_df,transform</code></dt>
<dd>Description
A function method for orchestrating the transformation of aesthetics in a
data frame. Data transformation occurs before stats are computed.
The <code>transform_df()</code> method ensures the <code><a href='https://rdrr.io/r/base/transform.html'>transform()</a></code> method is applied
to the correct columns.
Usage
<div class="sourceCode r"><pre><code>Scale$transform_df(df)
Scale$transform(x)
</code></pre></div>
Arguments<dl>
<dt><code>df</code></dt>
<dd>A data frame with the layer's data.</dd>

<dt><code>x</code></dt>
<dd>A vector of the relevant aesthetic.</dd>


</dl>

Value
For <code><a href='https://rdrr.io/r/base/transform.html'>transform()</a></code> a vector of transformed values.
For <code>transform_df()</code>, a named list with transformed values for each
transformed aesthetic.</dd>


<dt><code>train_df,train</code></dt>
<dd>Description
A function method for orchestrating scale training for keeping track of
the data range or levels. The <code>train_df()</code> method ensures the <code>train()</code>
method is applied to the correct columns.
Usage
<div class="sourceCode r"><pre><code>Scale$train_df(df)
Scale$train(x)
</code></pre></div>
Arguments<dl>
<dt><code>df</code></dt>
<dd>A data frame with the layer's data.</dd>

<dt><code>x</code></dt>
<dd>A vector of the relevant aesthetic.</dd>


</dl>

Value
Nothing, these are called for their side effect of updating the <code>range</code>
field.</dd>


<dt><code>map_df,map</code></dt>
<dd>Description
A function method for orchestrating the mapping of data values to
aesthetics. The <code>map_df()</code> method ensures the <code>map()</code> method is applied
to the correct columns. When the scale uses a <code><a href='https://rdrr.io/r/grDevices/palette.html'>palette()</a></code> function, it is
applied in the <code>map()</code> method.
Usage
<div class="sourceCode r"><pre><code>Scale$map_df(df, i)
Scale$map(x, limits)
</code></pre></div>
Arguments<dl>
<dt><code>df</code></dt>
<dd>A data frame with the layer's data.</dd>

<dt><code>i</code></dt>
<dd>An integer vector giving an index to map a subset of data.
The default, <code>NULL</code>, will map all rows.</dd>

<dt><code>x</code></dt>
<dd>A vector of the relevant aesthetic.</dd>

<dt><code>limits</code></dt>
<dd>A vector of the relevant aesthetic, usually via
the <code>get_limits()</code> method.</dd>


</dl>

Value
For <code>map()</code> a vector of mapped values in aesthetics space.
For <code>map_df()</code>, a named list with mapped values for each
aesthetic.</dd>


<dt><code>recale</code></dt>
<dd>Description
A function method for applying the recale function in the <code>rescaler</code> field.
It is used during the continuous <code>map()</code> and <code>Coord$transform()</code> methods
to ensure values are in the 0-1 range.
Usage
<div class="sourceCode r"><pre><code>Scale$rescale(x, limits, range)
</code></pre></div>
Arguments<dl>
<dt><code>x</code></dt>
<dd>A vector of values to rescale. Can contain out-of-bounds
or missing values depending on the <code>map()</code> method.</dd>

<dt><code>limits</code></dt>
<dd>A length two vector giving the limits of the relevant
aesthetic, usually via the <code>get_limits()</code> method.</dd>

<dt><code>range</code></dt>
<dd>A length two vector giving the range that should coincide
with the 0-1 points. For most purpuses, this should be the same as the
<code>limits</code> argument.</dd>


</dl>

Value
A vector of values between 0 and 1 for in-bounds values of <code>x</code>.</dd>


<dt><code>get_limits</code></dt>
<dd>Description
A function method for resolving user input and getting the scale limits.
Usage
<div class="sourceCode r"><pre><code>Scale$get_limits()
</code></pre></div>
Value
The scale limits, without any expansion applied, in transformed space.</dd>


<dt><code>dimension</code></dt>
<dd>Description
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
<div class="sourceCode r"><pre><code>Scale$dimension(expand, limits)
</code></pre></div>
Arguments<dl>
<dt><code>expand</code></dt>
<dd>A length 4 vector giving scale expansion.
This is optional and defaults to no expansion.</dd>

<dt><code>limits</code></dt>
<dd>A vector of the relevant aesthetic, usually via
the <code>get_limits()</code> method.</dd>


</dl>

Value
A numeric vector of length 2</dd>


<dt><code>get_breaks,get_breaks_minor</code></dt>
<dd>Description
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 <code>get_labels()</code> method.
Usage
<div class="sourceCode r"><pre><code>Scale$get_breaks(limits)
Scale$get_breaks_minor(n, b, limits)
</code></pre></div>
Arguments<dl>
<dt><code>limits</code></dt>
<dd>A vector of the relevant aesthetic, usually via
the <code>get_limits()</code> method.</dd>

<dt><code>n</code></dt>
<dd>An integer setting the desired number of minor breaks per
major break. Note that the resulting minor breaks may coincide with
major breaks.</dd>

<dt><code>b</code></dt>
<dd>A vector of mapped major breaks from the <code>get_breaks()</code>
method.</dd>


</dl>

Value
A vector of breaks in transformed space.</dd>


<dt><code>get_labels</code></dt>
<dd>Description
A function method for resolving user input and getting the scale labels for
a set of breaks.
Usage
<div class="sourceCode r"><pre><code>Scale$get_labels(breaks)
</code></pre></div>
Arguments<dl>
<dt><code>breaks</code></dt>
<dd>A vector of unmapped major breaks from the <code>get_breaks()</code>
method, in transformed space.</dd>


</dl>

Value
A vector of labels of the same length as <code>breaks</code>.</dd>


<dt><code>get_transformation</code></dt>
<dd>Description
A helper method to access the scale's transformation object.
Usage
<div class="sourceCode r"><pre><code>Scale$get_transformation()
</code></pre></div>
Value
A transform object.</dd>


<dt><code>break_info</code></dt>
<dd>Description
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
<div class="sourceCode r"><pre><code>Scale$break_info(range)
</code></pre></div>
Arguments<dl>
<dt><code>range</code></dt>
<dd>A vector of the relevant aesthetic.</dd>


</dl>

Value
A named list with the following structure:<ul>
<li><code>range</code> a length 2 vector giving continuous range</li>
<li><code>labels</code> a character or expression vector of the same length as major breaks.</li>
<li><code>major</code> a numeric vector with mapped numeric values for major breaks.</li>
<li><code>major_source</code> a numeric vector with (transformed) data values for major breaks.</li>
<li><code>minor</code> a numeric vector with mapped numeric values for minor breaks.</li>
<li><code>minor_source</code> a numeric vector with (transformed) data values for minor breaks.</li>
</ul></dd>


<dt><code>break_position</code></dt>
<dd>Description
A function method for getting mapped break positions. It is in use as a
default value in <code>get_breaks_minor()</code>, but is otherwise vestigial.
Usage
<div class="sourceCode r"><pre><code>Scale$break_info(range)
</code></pre></div>
Arguments<dl>
<dt><code>range</code></dt>
<dd>A vector of the relevant aesthetic.</dd>


</dl>

Value
A vector with mapped break positions</dd>


<dt><code>make_title,make_sec_title</code></dt>
<dd>Description
A function method for picking the title to use. This is usually called in
the <code>Guide$extract_params()</code> or <code>Layout$resolve_label()</code> 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 <code>make_sec_title()</code> method by default re-uses the primary
<code>make_title()</code> method and only applies to position aesthetics.
Usage
<div class="sourceCode r"><pre><code>Scale$make_title(guide_title, scale_title, label_title)
Scale$make_sec_title(...)
</code></pre></div>
Arguments<dl>
<dt><code>guide_title</code></dt>
<dd>The <code>title</code> parameter coming from a guide.</dd>

<dt><code>scale_title</code></dt>
<dd>The <code>name</code> field of the Scale.</dd>

<dt><code>label_title</code></dt>
<dd>The relevant entry in the <code>plot$labels</code> field.</dd>

<dt><code>...</code></dt>
<dd>By default, arguments forwarded to the <code>make_title()</code>
method</dd>


</dl>

Value
A scalar character or expression title</dd>


<dt><code>axis_order</code></dt>
<dd>Description
A function method for setting the order of axes titles used to coordinate
with <code>Facet$draw_labels()</code>.
Usage
<div class="sourceCode r"><pre><code>Scale$axis_order()
</code></pre></div>
Value
Either <code>c("primary", "secondary")</code> or <code>c("secondary", "primary")</code>.</dd>


<dt><code>clone</code></dt>
<dd>Description
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
<div class="sourceCode r"><pre><code>Scale$clone()
</code></pre></div>
Value
A Scale object.</dd>


<dt><code>reset</code></dt>
<dd>Description
A function method for to reset the <code>range</code> field, effectively 'untraining'
the scale. This is used in the <code>Layout$reset_scales()</code> method, so that
scales can be re-trained on data with final position aesthetics.
For discrete scales, only the continuous range (<code>range_c</code>) is reset.
Usage
<div class="sourceCode r"><pre><code>Scale$clone()
</code></pre></div>
Value
None, called for the side-effect of resetting the range.</dd>


<dt><code>is_empty</code></dt>
<dd>Description
A function method for determining whether a scale is empty, i.e. when no
information with which to calculate limits.
Usage
<div class="sourceCode r"><pre><code>Scale$is_empty()
</code></pre></div>
Value
A scalar boolean value.</dd>


<dt><code>is_empty</code></dt>
<dd>Description
A function method for determining whether a scale is discrete.
Usage
<div class="sourceCode r"><pre><code>Scale$is_discrete()
</code></pre></div>
Value
A scalar boolean value.</dd>


</dl>

Fields

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
<code>Scale*</code> prefix, like <code>ScaleNew</code>.
In scales, there is a difference between user-facing and developer-facing
constructors. Developer facing constructors have the shape
<code>{foundation}_scale()</code>, like <code>discrete_scale()</code> corresponding to
<code>ScaleDiscrete</code>. User-facing constructors have the <code>scale_{aesthetic}_{type}</code>
as name. If you implement a new <code>Scale*</code> class, you like want both these
types of constructor.

Conventions

Scales

Scale: Scales

Description

Arguments

Details

Examples