You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# The easiest way to use TidierData.jl for complex data transformation operations is to connect them together using pipes. Julia comes with the built-in `|>` pipe operator, but TidierData.jl also includes and re-exports the `@chain` macro from the Chain.jl package. On this page, we will show you how to use both approaches.
2
+
3
+
# First, let's load a dataset.
4
+
5
+
using TidierData
6
+
using RDatasets
7
+
8
+
movies =dataset("ggplot2", "movies");
9
+
10
+
# ## Julia's built-in `|>` pipe
11
+
12
+
# If we wanted to figure out the number of rows in the `movies` data frame, one way to do this is to apply the `nrow()` function to movies. The most straightforward way is to write it like this:
13
+
14
+
nrow(movies)
15
+
16
+
# Another perfectly valid way to write this expression is by piping `movies` into `nrow` using the `|>` pipe operator.
17
+
18
+
movies |> nrow
19
+
20
+
# Why might we want to do this? Well, whereas the first expression would naturally be read as "Calculate the number of rows of movies," the second expression reads as "Start with movies, then calculate the number of rows." For a simple expression, these are easy enough to reason about. However, as we start to pipe more and more functions in a single expression, the piped version becomes much easier to reason about.
21
+
22
+
# One quick note about Julia's built-in pipe: writing `movies |> nrow()` would *not* be considered valid. This is because Julia's built-in pipe always expects a function and *not* a function call. Writing `nrow` by itself is *naming* the function, whereas writing `nrow()` is *calling* the function. This quickly becomes an issue once we want to supply arguments to the function we are calling.
23
+
24
+
# Consider another approach to calculating the number of rows:
25
+
26
+
size(movies, 1)
27
+
28
+
# In this case, the `size()` function returns a tuple of `(rows, columns)`, and if you supply an optional second argument specifying the index of the tuple, it returns only that dimension. In this case, we called `size()` with a second argument of `1`, indicating that we only wanted the function to return the number of rows.
29
+
30
+
# How would we write this using Julia's built-in pipe?
31
+
32
+
movies |>
33
+
x ->size(x, 1)
34
+
35
+
# You might have wanted to write `movies |> size(1)`, but because `size(1)` would represent a function *call*, we have to wrap the function call within an anonymous function, which is easily accomplished using the `x -> func(x, arg1, arg2)` syntax, where `func()` refers to any function and `arg1` and `arg2` refer to any additional arguments that are needed.
36
+
37
+
# Another way we could have accomplished this is to calculate `size`, which returns a tuple of `(rows, columns)`, and then to use an anonymous function to grab the first value. Since we are calculating `size` without any arguments, we can simply write `size` within the pipe. However, to grab the first value using the `x[1]` syntax, we have to define an anonymous function. Putting it all together, we get this approach to piping:
38
+
39
+
movies |>
40
+
size |>
41
+
x -> x[1]
42
+
43
+
# ## Using the `@chain` macro
44
+
45
+
# The `@chain` macro comes from the Chain.jl package and is included and re-exported by TidierData.jl. Let's do this same series of exercises using `@chain`.
46
+
47
+
# Let's calculate the number of rows using `@chain`.
48
+
49
+
@chain movies nrow
50
+
51
+
# One of the reasons we prefer the use of `@chain` in TidierData.jl is that it is so concise. There is no need for any operator. Another interesting thing is that `@chain` doesn't care whether you use a function *name* or a function *call*. Both approaches work. As a result, writing `nrow()` instead of `nrow` is equally valid using `@chain`.
52
+
53
+
@chain movies nrow()
54
+
55
+
# There are two options for writing out multi-row chains. The preferred approach is as follows, where the starting item is listed, followed by a `begin-end` block.
56
+
57
+
@chain movies begin
58
+
nrow
59
+
end
60
+
61
+
# `@chain` also comes with a built-in placeholder, which is `\_`. To calculate the `size` and extract the first value, we can use this approach:
62
+
63
+
@chain movies begin
64
+
size
65
+
_[1]
66
+
end
67
+
68
+
# You don't have to list the data frame before the `begin-end` block. This is equally valid:
69
+
70
+
@chainbegin
71
+
movies
72
+
size
73
+
_[1]
74
+
end
75
+
76
+
# The only time this approach is preferred is when instead of simply naming the data frame, you are using a function to read in the data frame from a file or database. Because this function call may include the path of the file, which could be quite long, it's easier to write this on it's own line within the `begin-end` block.
77
+
78
+
# While the documentation for TidierData.jl follows the convention of placing piped functions on separate lines of code using `begin-end` blocks, this is purely convention for ease of readability. You could rewrite the code above without the `begin-end` block as follows:
79
+
80
+
@chain movies size _[1]
81
+
82
+
# For simple transformations, this approach is both concise and readable.
83
+
84
+
# ## Using `@chain` with TidierData.jl
85
+
86
+
# Returning to our convention of multi-line pipes, let's grab the first five movies that were released since 2000 and had a rating of at least 9 out of 10. Here is one way that we could write this:
87
+
88
+
@chain movies begin
89
+
@filter(Year >=2000&& Rating >=9)
90
+
@slice(1:5)
91
+
end
92
+
93
+
# Note: we generally prefer using `&&` in Julia because it is a "short-cut" operator. If the first condition evaluates to `false`, then the second condition is not even evaluated, which makes it faster (because it takes a short-cut).
94
+
95
+
# In the case of `@filter`, multiple conditions can be written out as separate expressions.
96
+
97
+
@chain movies begin
98
+
@filter(Year >=2000, Rating >=9)
99
+
@slice(1:5)
100
+
end
101
+
102
+
# Another to write this expression is take advantage of the fact that Julia macros can be called without parentheses. In this case, we will add back the `&&` for the sake of readability.
103
+
104
+
@chain movies begin
105
+
@filter Year >=2000&& Rating >=9
106
+
@slice1:5
107
+
end
108
+
109
+
# Lastly, TidierData.jl also supports multi-line expressions within each of the macros that accept multiple expressions. So you could also write this as follows:
110
+
111
+
@chain movies begin
112
+
@filterbegin
113
+
Year >=2000
114
+
Rating >=9
115
+
end
116
+
@slice1:5
117
+
end
118
+
119
+
# What's nice about this approach is that if you want to remove some criteria, you can easily comment out the relevant parts. For example, if you're willing to consider older movies, just comment out the `Year >= 2000`.
120
+
121
+
@chain movies begin
122
+
@filterbegin
123
+
## Year >= 2000
124
+
Rating >=9
125
+
end
126
+
@slice1:5
127
+
end
128
+
129
+
# ## Which approach to use?
130
+
131
+
# The purpose of this page was to show you that both Julia's native pipes and the `@chain` macro are perfectly valid and capable. We prefer the use of `@chain` because it is a bit more flexible and concise, with a syntax that makes it easy to comment out individual operations. We have adopted a similar `begin-end` block functionality within TidierData.jl itself, so that you can spread arguments out over multiple lines if you prefer. In the end, the choice is up to you!
Copy file name to clipboardExpand all lines: docs/src/index.md
+1-6Lines changed: 1 addition & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ Powered by the DataFrames.jl package and Julia’s
8
8
extensive meta-programming capabilities, TidierData.jl is an R user’s love
9
9
letter to data analysis in Julia.
10
10
11
-
`TidierData.jl` has three goals, which differentiate it from other data analysis
11
+
`TidierData.jl` has two goals, which differentiate it from other data analysis
12
12
meta-packages in Julia:
13
13
14
14
```@raw html
@@ -45,11 +45,6 @@ meta-packages in Julia:
45
45
Broadcasting trips up many R users switching to Julia because R users are used to most functions being vectorized. `TidierData.jl` currently uses a lookup table to decide which functions *not* to vectorize; all other functions are automatically vectorized. Read the documentation page on "Autovectorization" to read about how this works, and how to override the defaults. An example of where this issue commonly causes errors is when centering a variable. To create a new column `a` that centers the column `b`, `TidierData.jl` lets you simply write `a = b - mean(b)` exactly as you would in R. This works because `TidierData.jl` knows to *not* vectorize `mean()` while also recognizing that `-` *should* be vectorized such that this expression is rewritten in `DataFrames.jl` as `:b => (b -> b .- mean(b)) => :a`. For any user-defined function that you want to "mark" as being non-vectorized, you can prefix it with a `~`. For example, a function `new_mean()`, if it had the same functionality as `mean()` *would* normally get vectorized by `TidierData.jl` unless you write it as `~new_mean()`.
46
46
```
47
47
48
-
```@raw html
49
-
??? tip "Make scalars and tuples mostly interchangeable."
50
-
In Julia, the function `across(a, mean)` is dispatched differently than `across((a, b), mean)`. The first argument in the first instance above is treated as a scalar, whereas the second instance is treated as a tuple. This can be very confusing to R users because `1 == c(1)` is `TRUE` in R, whereas in Julia `1 == (1,)` evaluates to `false`. The design philosophy in `TidierData.jl` is that the user should feel free to provide a scalar or a tuple as they see fit anytime multiple values are considered valid for a given argument, such as in `across()`, and `TidierData.jl` will figure out how to dispatch it.
0 commit comments