EVOLUTION-MANAGER
Edit File: theory-faq-coercion.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: FAQ - How does coercion work in vctrs?</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for theory-faq-coercion {vctrs}"><tr><td>theory-faq-coercion {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>FAQ - How does coercion work in vctrs?</h2> <h3>Description</h3> <p>This is an overview of the usage of <code>vec_ptype2()</code> and <code>vec_cast()</code> and their role in the vctrs coercion mechanism. Related topics: </p> <ul> <li><p> For an example of implementing coercion methods for simple vectors, see <code><a href="howto-faq-coercion.html">?howto-faq-coercion</a></code>. </p> </li> <li><p> For an example of implementing coercion methods for data frame subclasses, see <code><a href="howto-faq-coercion-data-frame.html">?howto-faq-coercion-data-frame</a></code>. </p> </li> <li><p> For a tutorial about implementing vctrs classes from scratch, see <code>vignette("s3-vector")</code>. </p> </li></ul> <h4>Combination mechanism in vctrs</h4> <p>The coercion system in vctrs is designed to make combination of multiple inputs consistent and extensible. Combinations occur in many places, such as row-binding, joins, subset-assignment, or grouped summary functions that use the split-apply-combine strategy. For example: </p> <div class="sourceCode r"><pre>vec_c(TRUE, 1) #> [1] 1 1 vec_c("a", 1) #> Error in `vec_c()`: #> ! Can't combine `..1` <character> and `..2` <double>. vec_rbind( data.frame(x = TRUE), data.frame(x = 1, y = 2) ) #> x y #> 1 1 NA #> 2 1 2 vec_rbind( data.frame(x = "a"), data.frame(x = 1, y = 2) ) #> Error in `vec_rbind()`: #> ! Can't combine `..1$x` <character> and `..2$x` <double>. </pre></div> <p>One major goal of vctrs is to provide a central place for implementing the coercion methods that make generic combinations possible. The two relevant generics are <code>vec_ptype2()</code> and <code>vec_cast()</code>. They both take two arguments and perform <strong>double dispatch</strong>, meaning that a method is selected based on the classes of both inputs. </p> <p>The general mechanism for combining multiple inputs is: </p> <ol> <li><p> Find the common type of a set of inputs by reducing (as in <code>base::Reduce()</code> or <code>purrr::reduce()</code>) the <code>vec_ptype2()</code> binary function over the set. </p> </li> <li><p> Convert all inputs to the common type with <code>vec_cast()</code>. </p> </li> <li><p> Initialise the output vector as an instance of this common type with <code>vec_init()</code>. </p> </li> <li><p> Fill the output vector with the elements of the inputs using <code>vec_assign()</code>. </p> </li></ol> <p>The last two steps may require <code>vec_proxy()</code> and <code>vec_restore()</code> implementations, unless the attributes of your class are constant and do not depend on the contents of the vector. We focus here on the first two steps, which require <code>vec_ptype2()</code> and <code>vec_cast()</code> implementations. </p> <h4><code>vec_ptype2()</code></h4> <p>Methods for <code>vec_ptype2()</code> are passed two <em>prototypes</em>, i.e. two inputs emptied of their elements. They implement two behaviours: </p> <ul> <li><p> If the types of their inputs are compatible, indicate which of them is the richer type by returning it. If the types are of equal resolution, return any of the two. </p> </li> <li><p> Throw an error with <code>stop_incompatible_type()</code> when it can be determined from the attributes that the types of the inputs are not compatible. </p> </li></ul> <h5>Type compatibility</h5> <p>A type is <strong>compatible</strong> with another type if the values it represents are a subset or a superset of the values of the other type. The notion of “value” is to be interpreted at a high level, in particular it is not the same as the memory representation. For example, factors are represented in memory with integers but their values are more related to character vectors than to round numbers: </p> <div class="sourceCode r"><pre># Two factors are compatible vec_ptype2(factor("a"), factor("b")) #> factor(0) #> Levels: a b # Factors are compatible with a character vec_ptype2(factor("a"), "b") #> character(0) # But they are incompatible with integers vec_ptype2(factor("a"), 1L) #> Error: #> ! Can't combine `factor("a")` <factor<4d52a>> and `1L` <integer>. </pre></div> <h5>Richness of type</h5> <p>Richness of type is not a very precise notion. It can be about richer data (for instance a <code>double</code> vector covers more values than an integer vector), richer behaviour (a <code>data.table</code> has richer behaviour than a <code>data.frame</code>), or both. If you have trouble determining which one of the two types is richer, it probably means they shouldn’t be automatically coercible. </p> <p>Let’s look again at what happens when we combine a factor and a character: </p> <div class="sourceCode r"><pre>vec_ptype2(factor("a"), "b") #> character(0) </pre></div> <p>The ptype2 method for <code style="white-space: pre;"><character></code> and <code style="white-space: pre;"><factor<"a">></code> returns <code style="white-space: pre;"><character></code> because the former is a richer type. The factor can only contain <code>"a"</code> strings, whereas the character can contain any strings. In this sense, factors are a <em>subset</em> of character. </p> <p>Note that another valid behaviour would be to throw an incompatible type error. This is what a strict factor implementation would do. We have decided to be laxer in vctrs because it is easy to inadvertently create factors instead of character vectors, especially with older versions of R where <code>stringsAsFactors</code> is still true by default. </p> <h5>Consistency and symmetry on permutation</h5> <p>Each ptype2 method should strive to have exactly the same behaviour when the inputs are permuted. This is not always possible, for example factor levels are aggregated in order: </p> <div class="sourceCode r"><pre>vec_ptype2(factor(c("a", "c")), factor("b")) #> factor(0) #> Levels: a c b vec_ptype2(factor("b"), factor(c("a", "c"))) #> factor(0) #> Levels: b a c </pre></div> <p>In any case, permuting the input should not return a fundamentally different type or introduce an incompatible type error. </p> <h5>Coercion hierarchy</h5> <p>The classes that you can coerce together form a coercion (or subtyping) hierarchy. Below is a schema of the hierarchy for the base types like integer and factor. In this diagram the directions of the arrows express which type is richer. They flow from the bottom (more constrained types) to the top (richer types). </p> <p><img src="../help/figures/coerce.png" alt="coerce.png" /> </p> <p>A coercion hierarchy is distinct from the structural hierarchy implied by memory types and classes. For instance, in a structural hierarchy, factors are built on top of integers. But in the coercion hierarchy they are more related to character vectors. Similarly, subclasses are not necessarily coercible with their superclasses because the coercion and structural hierarchies are separate. </p> <h5>Implementing a coercion hierarchy</h5> <p>As a class implementor, you have two options. The simplest is to create an entirely separate hierarchy. The date and date-time classes are an example of an S3-based hierarchy that is completely separate. Alternatively, you can integrate your class in an existing hierarchy, typically by adding parent nodes on top of the hierarchy (your class is richer), by adding children node at the root of the hierarchy (your class is more constrained), or by inserting a node in the tree. </p> <p>These coercion hierarchies are <em>implicit</em>, in the sense that they are implied by the <code>vec_ptype2()</code> implementations. There is no structured way to create or modify a hierarchy, instead you need to implement the appropriate coercion methods for all the types in your hierarchy, and diligently return the richer type in each case. The <code>vec_ptype2()</code> implementations are not transitive nor inherited, so all pairwise methods between classes lying on a given path must be implemented manually. This is something we might make easier in the future. </p> <h4><code>vec_cast()</code></h4> <p>The second generic, <code>vec_cast()</code>, is the one that looks at the data and actually performs the conversion. Because it has access to more information than <code>vec_ptype2()</code>, it may be stricter and cause an error in more cases. <code>vec_cast()</code> has three possible behaviours: </p> <ul> <li><p> Determine that the prototypes of the two inputs are not compatible. This must be decided in exactly the same way as for <code>vec_ptype2()</code>. Call <code>stop_incompatible_cast()</code> if you can determine from the attributes that the types are not compatible. </p> </li> <li><p> Detect incompatible values. Usually this is because the target type is too restricted for the values supported by the input type. For example, a fractional number can’t be converted to an integer. The method should throw an error in that case. </p> </li> <li><p> Return the input vector converted to the target type if all values are compatible. Whereas <code>vec_ptype2()</code> must return the same type when the inputs are permuted, <code>vec_cast()</code> is <em>directional</em>. It always returns the type of the right-hand side, or dies trying. </p> </li></ul> <h4>Double dispatch</h4> <p>The dispatch mechanism for <code>vec_ptype2()</code> and <code>vec_cast()</code> looks like S3 but is actually a custom mechanism. Compared to S3, it has the following differences: </p> <ul> <li><p> It dispatches on the classes of the first two inputs. </p> </li> <li><p> There is no inheritance of ptype2 and cast methods. This is because the S3 class hierarchy is not necessarily the same as the coercion hierarchy. </p> </li> <li> <p><code>NextMethod()</code> does not work. Parent methods must be called explicitly if necessary. </p> </li> <li><p> The default method is hard-coded. </p> </li></ul> <h4>Data frames</h4> <p>The determination of the common type of data frames with <code>vec_ptype2()</code> happens in three steps: </p> <ol> <li><p> Match the columns of the two input data frames. If some columns don’t exist, they are created and filled with adequately typed <code>NA</code> values. </p> </li> <li><p> Find the common type for each column by calling <code>vec_ptype2()</code> on each pair of matched columns. </p> </li> <li><p> Find the common data frame type. For example the common type of a grouped tibble and a tibble is a grouped tibble because the latter is the richer type. The common type of a data table and a data frame is a data table. </p> </li></ol> <p><code>vec_cast()</code> operates similarly. If a data frame is cast to a target type that has fewer columns, this is an error. </p> <p>If you are implementing coercion methods for data frames, you will need to explicitly call the parent methods that perform the common type determination or the type conversion described above. These are exported as <code><a href="df_ptype2.html">df_ptype2()</a></code> and <code><a href="df_ptype2.html">df_cast()</a></code>. </p> <h5>Data frame fallbacks</h5> <p>Being too strict with data frame combinations would cause too much pain because there are many data frame subclasses in the wild that don’t implement vctrs methods. We have decided to implement a special fallback behaviour for foreign data frames. Incompatible data frames fall back to a base data frame: </p> <div class="sourceCode r"><pre>df1 <- data.frame(x = 1) df2 <- structure(df1, class = c("foreign_df", "data.frame")) vec_rbind(df1, df2) #> x #> 1 1 #> 2 1 </pre></div> <p>When a tibble is involved, we fall back to tibble: </p> <div class="sourceCode r"><pre>df3 <- tibble::as_tibble(df1) vec_rbind(df1, df3) #> # A tibble: 2 x 1 #> x #> <dbl> #> 1 1 #> 2 1 </pre></div> <p>These fallbacks are not ideal but they make sense because all data frames share a common data structure. This is not generally the case for vectors. For example factors and characters have different representations, and it is not possible to find a fallback time mechanically. </p> <p>However this fallback has a big downside: implementing vctrs methods for your data frame subclass is a breaking behaviour change. The proper coercion behaviour for your data frame class should be specified as soon as possible to limit the consequences of changing the behaviour of your class in R scripts. </p> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>