1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/group_map.R
3\name{group_map}
4\alias{group_map}
5\alias{group_modify}
6\alias{group_walk}
7\title{Apply a function to each group}
8\usage{
9group_map(.data, .f, ..., .keep = FALSE)
10
11group_modify(.data, .f, ..., .keep = FALSE)
12
13group_walk(.data, .f, ...)
14}
15\arguments{
16\item{.data}{A grouped tibble}
17
18\item{.f}{A function or formula to apply to each group.
19
20If a \strong{function}, it is used as is. It should have at least 2 formal arguments.
21
22If a \strong{formula}, e.g. \code{~ head(.x)}, it is converted to a function.
23
24In the formula, you can use
25\itemize{
26\item \code{.} or \code{.x} to refer to the subset of rows of \code{.tbl}
27for the given group
28\item \code{.y} to refer to the key, a one row tibble with one column per grouping variable
29that identifies the group
30}}
31
32\item{...}{Additional arguments passed on to \code{.f}}
33
34\item{.keep}{are the grouping variables kept in \code{.x}}
35}
36\value{
37\itemize{
38\item \code{group_modify()} returns a grouped tibble. In that case \code{.f} must return a data frame.
39\item \code{group_map()} returns a list of results from calling \code{.f} on each group.
40\item \code{group_walk()} calls \code{.f} for side effects and returns the input \code{.tbl}, invisibly.
41}
42}
43\description{
44\Sexpr[results=rd, stage=render]{lifecycle::badge("experimental")}
45
46\code{group_map()}, \code{group_modify()} and \code{group_walk()} are purrr-style functions that can
47be used to iterate on grouped tibbles.
48}
49\details{
50Use \code{group_modify()} when \code{summarize()} is too limited, in terms of what you need
51to do and return for each group. \code{group_modify()} is good for "data frame in, data frame out".
52If that is too limited, you need to use a \link[=group_nest]{nested} or \link[=group_split]{split} workflow.
53\code{group_modify()} is an evolution of \code{\link[=do]{do()}}, if you have used that before.
54
55Each conceptual group of the data frame is exposed to the function \code{.f} with two pieces of information:
56\itemize{
57\item The subset of the data for the group, exposed as \code{.x}.
58\item The key, a tibble with exactly one row and columns for each grouping variable, exposed as \code{.y}.
59}
60
61For completeness, \code{group_modify()}, \code{group_map} and \code{group_walk()} also work on
62ungrouped data frames, in that case the function is applied to the
63entire data frame (exposed as \code{.x}), and \code{.y} is a one row tibble with no
64column, consistently with \code{\link[=group_keys]{group_keys()}}.
65}
66\examples{
67
68# return a list
69mtcars \%>\%
70  group_by(cyl) \%>\%
71  group_map(~ head(.x, 2L))
72
73# return a tibble grouped by `cyl` with 2 rows per group
74# the grouping data is recalculated
75mtcars \%>\%
76  group_by(cyl) \%>\%
77  group_modify(~ head(.x, 2L))
78
79if (requireNamespace("broom", quietly = TRUE)) {
80  # a list of tibbles
81  iris \%>\%
82    group_by(Species) \%>\%
83    group_map(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
84
85  # a restructured grouped tibble
86  iris \%>\%
87    group_by(Species) \%>\%
88    group_modify(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
89}
90
91# a list of vectors
92iris \%>\%
93  group_by(Species) \%>\%
94  group_map(~ quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)))
95
96# to use group_modify() the lambda must return a data frame
97iris \%>\%
98  group_by(Species) \%>\%
99  group_modify(~ {
100     quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)) \%>\%
101     tibble::enframe(name = "prob", value = "quantile")
102  })
103
104iris \%>\%
105  group_by(Species) \%>\%
106  group_modify(~ {
107    .x \%>\%
108      purrr::map_dfc(fivenum) \%>\%
109      mutate(nms = c("min", "Q1", "median", "Q3", "max"))
110  })
111
112# group_walk() is for side effects
113dir.create(temp <- tempfile())
114iris \%>\%
115  group_by(Species) \%>\%
116  group_walk(~ write.csv(.x, file = file.path(temp, paste0(.y$Species, ".csv"))))
117list.files(temp, pattern = "csv$")
118unlink(temp, recursive = TRUE)
119
120# group_modify() and ungrouped data frames
121mtcars \%>\%
122  group_modify(~ head(.x, 2L))
123
124}
125\seealso{
126Other grouping functions:
127\code{\link{group_by}()},
128\code{\link{group_nest}()},
129\code{\link{group_split}()},
130\code{\link{group_trim}()}
131}
132\concept{grouping functions}
133