1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/slice.R
3\name{slice}
4\alias{slice}
5\alias{slice_head}
6\alias{slice_tail}
7\alias{slice_min}
8\alias{slice_max}
9\alias{slice_sample}
10\title{Subset rows using their positions}
11\usage{
12slice(.data, ..., .preserve = FALSE)
13
14slice_head(.data, ..., n, prop)
15
16slice_tail(.data, ..., n, prop)
17
18slice_min(.data, order_by, ..., n, prop, with_ties = TRUE)
19
20slice_max(.data, order_by, ..., n, prop, with_ties = TRUE)
21
22slice_sample(.data, ..., n, prop, weight_by = NULL, replace = FALSE)
23}
24\arguments{
25\item{.data}{A data frame, data frame extension (e.g. a tibble), or a
26lazy data frame (e.g. from dbplyr or dtplyr). See \emph{Methods}, below, for
27more details.}
28
29\item{...}{For \code{slice()}: <\code{\link[=dplyr_data_masking]{data-masking}}> Integer row
30values.
31
32Provide either positive values to keep, or negative values to drop.
33The values provided must be either all positive or all negative.
34Indices beyond the number of rows in the input are silently ignored.
35
36For \code{slice_helpers()}, these arguments are passed on to methods.}
37
38\item{.preserve}{Relevant when the \code{.data} input is grouped.
39If \code{.preserve = FALSE} (the default), the grouping structure
40is recalculated based on the resulting data, otherwise the grouping is kept as is.}
41
42\item{n, prop}{Provide either \code{n}, the number of rows, or \code{prop}, the
43proportion of rows to select. If neither are supplied, \code{n = 1} will be
44used.
45
46If \code{n} is greater than the number of rows in the group (or \code{prop > 1}),
47the result will be silently truncated to the group size. If the
48\code{prop}ortion of a group size is not an integer, it is rounded down.}
49
50\item{order_by}{Variable or function of variables to order by.}
51
52\item{with_ties}{Should ties be kept together? The default, \code{TRUE},
53may return more rows than you request. Use \code{FALSE} to ignore ties,
54and return the first \code{n} rows.}
55
56\item{weight_by}{Sampling weights. This must evaluate to a vector of
57non-negative numbers the same length as the input. Weights are
58automatically standardised to sum to 1.}
59
60\item{replace}{Should sampling be performed with (\code{TRUE}) or without
61(\code{FALSE}, the default) replacement.}
62}
63\value{
64An object of the same type as \code{.data}. The output has the following
65properties:
66\itemize{
67\item Each row may appear 0, 1, or many times in the output.
68\item Columns are not modified.
69\item Groups are not modified.
70\item Data frame attributes are preserved.
71}
72}
73\description{
74\code{slice()} lets you index rows by their (integer) locations. It allows you
75to select, remove, and duplicate rows. It is accompanied by a number of
76helpers for common use cases:
77\itemize{
78\item \code{slice_head()} and \code{slice_tail()} select the first or last rows.
79\item \code{slice_sample()} randomly selects rows.
80\item \code{slice_min()} and \code{slice_max()} select rows with highest or lowest values
81of a variable.
82}
83
84If \code{.data} is a \link{grouped_df}, the operation will be performed on each group,
85so that (e.g.) \code{slice_head(df, n = 5)} will select the first five rows in
86each group.
87}
88\details{
89Slice does not work with relational databases because they have no
90intrinsic notion of row order. If you want to perform the equivalent
91operation, use \code{\link[=filter]{filter()}} and \code{\link[=row_number]{row_number()}}.
92}
93\section{Methods}{
94
95These function are \strong{generic}s, which means that packages can provide
96implementations (methods) for other classes. See the documentation of
97individual methods for extra arguments and differences in behaviour.
98
99Methods available in currently loaded packages:
100\itemize{
101\item \code{slice()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice")}.
102\item \code{slice_head()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice_head")}.
103\item \code{slice_tail()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice_tail")}.
104\item \code{slice_min()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice_min")}.
105\item \code{slice_max()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice_max")}.
106\item \code{slice_sample()}: \Sexpr[stage=render,results=rd]{dplyr:::methods_rd("slice_sample")}.
107}
108}
109
110\examples{
111mtcars \%>\% slice(1L)
112# Similar to tail(mtcars, 1):
113mtcars \%>\% slice(n())
114mtcars \%>\% slice(5:n())
115# Rows can be dropped with negative indices:
116slice(mtcars, -(1:4))
117
118# First and last rows based on existing order
119mtcars \%>\% slice_head(n = 5)
120mtcars \%>\% slice_tail(n = 5)
121
122# Rows with minimum and maximum values of a variable
123mtcars \%>\% slice_min(mpg, n = 5)
124mtcars \%>\% slice_max(mpg, n = 5)
125
126# slice_min() and slice_max() may return more rows than requested
127# in the presence of ties. Use with_ties = FALSE to suppress
128mtcars \%>\% slice_min(cyl, n = 1)
129mtcars \%>\% slice_min(cyl, n = 1, with_ties = FALSE)
130
131# slice_sample() allows you to random select with or without replacement
132mtcars \%>\% slice_sample(n = 5)
133mtcars \%>\% slice_sample(n = 5, replace = TRUE)
134
135# you can optionally weight by a variable - this code weights by the
136# physical weight of the cars, so heavy cars are more likely to get
137# selected
138mtcars \%>\% slice_sample(weight_by = wt, n = 5)
139
140# Group wise operation ----------------------------------------
141df <- tibble(
142  group = rep(c("a", "b", "c"), c(1, 2, 4)),
143  x = runif(7)
144)
145
146# All slice helpers operate per group, silently truncating to the group
147# size, so the following code works without error
148df \%>\% group_by(group) \%>\% slice_head(n = 2)
149
150# When specifying the proportion of rows to include non-integer sizes
151# are rounded down, so group a gets 0 rows
152df \%>\% group_by(group) \%>\% slice_head(prop = 0.5)
153
154# Filter equivalents --------------------------------------------
155# slice() expressions can often be written to use `filter()` and
156# `row_number()`, which can also be translated to SQL. For many databases,
157# you'll need to supply an explicit variable to use to compute the row number.
158filter(mtcars, row_number() == 1L)
159filter(mtcars, row_number() == n())
160filter(mtcars, between(row_number(), 5, n()))
161}
162\seealso{
163Other single table verbs:
164\code{\link{arrange}()},
165\code{\link{filter}()},
166\code{\link{mutate}()},
167\code{\link{rename}()},
168\code{\link{select}()},
169\code{\link{summarise}()}
170}
171\concept{single table verbs}
172