EVOLUTION-MANAGER
Edit File: order-radix.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: Order and sort vectors</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 order-radix {vctrs}"><tr><td>order-radix {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Order and sort vectors</h2> <h3>Description</h3> <p><code>vec_order_radix()</code> computes the order of <code>x</code>. For data frames, the order is computed along the rows by computing the order of the first column and using subsequent columns to break ties. </p> <p><code>vec_sort_radix()</code> sorts <code>x</code>. It is equivalent to <code>vec_slice(x, vec_order_radix(x))</code>. </p> <h3>Usage</h3> <pre> vec_order_radix( x, ..., direction = "asc", na_value = "largest", nan_distinct = FALSE, chr_proxy_collate = NULL ) vec_sort_radix( x, ..., direction = "asc", na_value = "largest", nan_distinct = FALSE, chr_proxy_collate = NULL ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>A vector</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>These dots are for future extensions and must be empty.</p> </td></tr> <tr valign="top"><td><code>direction</code></td> <td> <p>Direction to sort in. </p> <ul> <li><p> A single <code>"asc"</code> or <code>"desc"</code> for ascending or descending order respectively. </p> </li> <li><p> For data frames, a length <code>1</code> or <code>ncol(x)</code> character vector containing only <code>"asc"</code> or <code>"desc"</code>, specifying the direction for each column. </p> </li></ul> </td></tr> <tr valign="top"><td><code>na_value</code></td> <td> <p>Ordering of missing values. </p> <ul> <li><p> A single <code>"largest"</code> or <code>"smallest"</code> for ordering missing values as the largest or smallest values respectively. </p> </li> <li><p> For data frames, a length <code>1</code> or <code>ncol(x)</code> character vector containing only <code>"largest"</code> or <code>"smallest"</code>, specifying how missing values should be ordered within each column. </p> </li></ul> </td></tr> <tr valign="top"><td><code>nan_distinct</code></td> <td> <p>A single logical specifying whether or not <code>NaN</code> should be considered distinct from <code>NA</code> for double and complex vectors. If <code>TRUE</code>, <code>NaN</code> will always be ordered between <code>NA</code> and non-missing numbers.</p> </td></tr> <tr valign="top"><td><code>chr_proxy_collate</code></td> <td> <p>A function generating an alternate representation of character vectors to use for collation, often used for locale-aware ordering. </p> <ul> <li><p> If <code>NULL</code>, no transformation is done. </p> </li> <li><p> Otherwise, this must be a function of one argument. If the input contains a character vector, it will be passed to this function after it has been translated to UTF-8. This function should return a character vector with the same length as the input. The result should sort as expected in the C-locale, regardless of encoding. </p> </li></ul> <p>For data frames, <code>chr_proxy_collate</code> will be applied to all character columns. </p> <p>Common transformation functions include: <code>tolower()</code> for case-insensitive ordering and <code>stringi::stri_sort_key()</code> for locale-aware ordering.</p> </td></tr> </table> <h3>Value</h3> <ul> <li> <p><code>vec_order_radix()</code> an integer vector the same size as <code>x</code>. </p> </li> <li> <p><code>vec_sort_radix()</code> a vector with the same size and type as <code>x</code>. </p> </li></ul> <h3>Differences with <code>order()</code></h3> <p>Unlike the <code>na.last</code> argument of <code>order()</code> which decides the positions of missing values irrespective of the <code>decreasing</code> argument, the <code>na_value</code> argument of <code>vec_order_radix()</code> interacts with <code>direction</code>. If missing values are considered the largest value, they will appear last in ascending order, and first in descending order. </p> <p>Character vectors are ordered in the C-locale. This is different from <code>base::order()</code>, which respects <code>base::Sys.setlocale()</code>. Sorting in a consistent locale can produce more reproducible results between different sessions and platforms, however, the results of sorting in the C-locale can be surprising. For example, capital letters sort before lower case letters. Sorting <code>c("b", "C", "a")</code> with <code>vec_sort_radix()</code> will return <code>c("C", "a", "b")</code>, but with <code>base::order()</code> will return <code>c("a", "b", "C")</code> unless <code>base::order(method = "radix")</code> is explicitly set, which also uses the C-locale. While sorting with the C-locale can be useful for algorithmic efficiency, in many real world uses it can be the cause of data analysis mistakes. To balance these trade-offs, you can supply a <code>chr_proxy_collate</code> function to transform character vectors into an alternative representation that orders in the C-locale in a less surprising way. For example, providing <code><a href="../../base/html/chartr.html">base::tolower()</a></code> as a transform will order the original vector in a case-insensitive manner. Locale-aware ordering can be achieved by providing <code>stringi::stri_sort_key()</code> as a transform, setting the collation options as appropriate for your locale. </p> <p>Character vectors are always translated to UTF-8 before ordering, and before any transform is applied by <code>chr_proxy_collate</code>. </p> <p>For complex vectors, if either the real or imaginary component is <code>NA</code> or <code>NaN</code>, then the entire observation is considered missing. </p> <h3>Dependencies of <code>vec_order_radix()</code></h3> <ul> <li> <p><code><a href="vec_proxy_compare.html">vec_proxy_order()</a></code> </p> </li></ul> <h3>Dependencies of <code>vec_sort_radix()</code></h3> <ul> <li> <p><code><a href="order-radix.html">vec_order_radix()</a></code> </p> </li> <li> <p><code><a href="vec_slice.html">vec_slice()</a></code> </p> </li></ul> <h3>Examples</h3> <pre> if (FALSE) { x <- round(sample(runif(5), 9, replace = TRUE), 3) x <- c(x, NA) vec_order_radix(x) vec_sort_radix(x) vec_sort_radix(x, direction = "desc") # Can also handle data frames df <- data.frame(g = sample(2, 10, replace = TRUE), x = x) vec_order_radix(df) vec_sort_radix(df) vec_sort_radix(df, direction = "desc") # For data frames, `direction` and `na_value` are allowed to be vectors # with length equal to the number of columns in the data frame vec_sort_radix( df, direction = c("desc", "asc"), na_value = c("largest", "smallest") ) # Character vectors are ordered in the C locale, which orders capital letters # below lowercase ones y <- c("B", "A", "a") vec_sort_radix(y) # To order in a case-insensitive manner, provide a `chr_proxy_collate` # function that transforms the strings to all lowercase vec_sort_radix(y, chr_proxy_collate = tolower) } </pre> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>