forked from STAT545-UBC/STAT545-UBC-original-website
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathblock011_write-your-own-function-02.html
422 lines (368 loc) · 16.2 KB
/
block011_write-your-own-function-02.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />
<title>Write your own R functions, part 2</title>
<script src="libs/jquery-1.11.3/jquery.min.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="libs/bootstrap-3.3.5/css/bootstrap.min.css" rel="stylesheet" />
<script src="libs/bootstrap-3.3.5/js/bootstrap.min.js"></script>
<script src="libs/bootstrap-3.3.5/shim/html5shiv.min.js"></script>
<script src="libs/bootstrap-3.3.5/shim/respond.min.js"></script>
<script src="libs/navigation-1.1/tabsets.js"></script>
<link href="libs/highlightjs-9.12.0/default.css" rel="stylesheet" />
<script src="libs/highlightjs-9.12.0/highlight.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-68219208-1', 'auto');
ga('send', 'pageview');
</script>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
pre:not([class]) {
background-color: white;
}
</style>
<script type="text/javascript">
if (window.hljs) {
hljs.configure({languages: []});
hljs.initHighlightingOnLoad();
if (document.readyState && document.readyState === "complete") {
window.setTimeout(function() { hljs.initHighlighting(); }, 0);
}
}
</script>
<style type="text/css">
h1 {
font-size: 34px;
}
h1.title {
font-size: 38px;
}
h2 {
font-size: 30px;
}
h3 {
font-size: 24px;
}
h4 {
font-size: 18px;
}
h5 {
font-size: 16px;
}
h6 {
font-size: 12px;
}
.table th:not([align]) {
text-align: left;
}
</style>
<link rel="stylesheet" href="libs/local/main.css" type="text/css" />
<link rel="stylesheet" href="libs/local/nav.css" type="text/css" />
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" type="text/css" />
</head>
<body>
<style type = "text/css">
.main-container {
max-width: 940px;
margin-left: auto;
margin-right: auto;
}
code {
color: inherit;
background-color: rgba(0, 0, 0, 0.04);
}
img {
max-width:100%;
height: auto;
}
.tabbed-pane {
padding-top: 12px;
}
.html-widget {
margin-bottom: 20px;
}
button.code-folding-btn:focus {
outline: none;
}
</style>
<div class="container-fluid main-container">
<!-- tabsets -->
<style type="text/css">
.tabset-dropdown > .nav-tabs {
display: inline-table;
max-height: 500px;
min-height: 44px;
overflow-y: auto;
background: white;
border: 1px solid #ddd;
border-radius: 4px;
}
.tabset-dropdown > .nav-tabs > li.active:before {
content: "";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li.active:before {
content: "";
border: none;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open:before {
content: "";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.tabset-dropdown > .nav-tabs > li.active {
display: block;
}
.tabset-dropdown > .nav-tabs > li > a,
.tabset-dropdown > .nav-tabs > li > a:focus,
.tabset-dropdown > .nav-tabs > li > a:hover {
border: none;
display: inline-block;
border-radius: 4px;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li {
display: block;
float: none;
}
.tabset-dropdown > .nav-tabs > li {
display: none;
}
</style>
<script>
$(document).ready(function () {
window.buildTabsets("TOC");
});
$(document).ready(function () {
$('.tabset-dropdown > .nav-tabs > li').click(function () {
$(this).parent().toggleClass('nav-tabs-open')
});
});
</script>
<!-- code folding -->
<header>
<div class="nav">
<a class="nav-logo" href="index.html">
<img src="static/img/stat545-logo-s.png" width="70px" height="70px"/>
</a>
<ul>
<li class="home"><a href="index.html">Home</a></li>
<li class="faq"><a href="faq.html">FAQ</a></li>
<li class="syllabus"><a href="syllabus.html">Syllabus</a></li>
<li class="topics"><a href="topics.html">Topics</a></li>
<li class="people"><a href="people.html">People</a></li>
</ul>
</div>
</header>
<div class="fluid-row" id="header">
<h1 class="title toc-ignore">Write your own R functions, part 2</h1>
</div>
<div id="TOC">
<ul>
<li><a href="#where-were-we-where-are-we-going">Where were we? Where are we going?</a></li>
<li><a href="#load-the-gapminder-data">Load the Gapminder data</a></li>
<li><a href="#restore-our-max-minus-min-function">Restore our max minus min function</a></li>
<li><a href="#generalize-our-function-to-other-quantiles">Generalize our function to other quantiles</a></li>
<li><a href="#get-something-that-works-again">Get something that works, again</a></li>
<li><a href="#turn-the-working-interactive-code-into-a-function-again">Turn the working interactive code into a function, again</a></li>
<li><a href="#argument-names-freedom-and-conventions">Argument names: freedom and conventions</a></li>
<li><a href="#what-a-function-returns">What a function returns</a></li>
<li><a href="#default-values-freedom-to-not-specify-the-arguments">Default values: freedom to NOT specify the arguments</a></li>
<li><a href="#check-the-validity-of-arguments-again">Check the validity of arguments, again</a></li>
<li><a href="#wrap-up-and-whats-next">Wrap-up and what’s next?</a></li>
<li><a href="#resources">Resources</a></li>
</ul>
</div>
<div id="where-were-we-where-are-we-going" class="section level3">
<h3>Where were we? Where are we going?</h3>
<p>In <a href="block011_write-your-own-function-01.html">part 1</a> we wrote our first R function to compute the difference between the max and min of a numeric vector. We checked the validity of the function’s only argument and, informally, we verified that it worked pretty well.</p>
<p>In this part, we generalize this function, learn more technical details about R functions, and set default values for some arguments.</p>
</div>
<div id="load-the-gapminder-data" class="section level3">
<h3>Load the Gapminder data</h3>
<p>As usual, load the Gapminder data.</p>
<pre class="r"><code>library(gapminder)</code></pre>
</div>
<div id="restore-our-max-minus-min-function" class="section level3">
<h3>Restore our max minus min function</h3>
<p>Let’s keep our previous function around as a baseline.</p>
<pre class="r"><code>mmm <- function(x) {
stopifnot(is.numeric(x))
max(x) - min(x)
}</code></pre>
</div>
<div id="generalize-our-function-to-other-quantiles" class="section level3">
<h3>Generalize our function to other quantiles</h3>
<p>The max and the min are special cases of a <strong>quantile</strong>. Here are other special cases you may have heard of:</p>
<ul>
<li>median = 0.5 quantile</li>
<li>1st quartile = 0.25 quantile</li>
<li>3rd quartile = 0.75 quantile</li>
</ul>
<p>If you’re familiar with <a href="http://en.wikipedia.org/wiki/Box_plot">box plots</a>, the rectangle typically runs from the 1st quartile to the 3rd quartile, with a line at the median.</p>
<p>If <span class="math inline">\(q\)</span> is the <span class="math inline">\(p\)</span>-th quantile of a set of <span class="math inline">\(n\)</span> observations, what does that mean? Approximately <span class="math inline">\(pn\)</span> of the observations are less than <span class="math inline">\(q\)</span> and <span class="math inline">\((1 - p)n\)</span> are greater than <span class="math inline">\(q\)</span>. Yeah, you need to worry about rounding to an integer and less/greater than or equal to, but these details aren’t critical here.</p>
<p>Let’s generalize our function to take the difference between any two quantiles. We can still consider the max and min, if we like, but we’re not limited to that.</p>
</div>
<div id="get-something-that-works-again" class="section level3">
<h3>Get something that works, again</h3>
<p>The eventual inputs to our new function will be the data <code>x</code> and two probabilities.</p>
<p>First, play around with the <code>quantile()</code> function. Convince yourself you know how to use it, for example, by cross-checking your results with other built-in functions.</p>
<pre class="r"><code>quantile(gapminder$lifeExp)
## 0% 25% 50% 75% 100%
## 23.5990 48.1980 60.7125 70.8455 82.6030
quantile(gapminder$lifeExp, probs = 0.5)
## 50%
## 60.7125
median(gapminder$lifeExp)
## [1] 60.7125
quantile(gapminder$lifeExp, probs = c(0.25, 0.75))
## 25% 75%
## 48.1980 70.8455
boxplot(gapminder$lifeExp, plot = FALSE)$stats
## [,1]
## [1,] 23.5990
## [2,] 48.1850
## [3,] 60.7125
## [4,] 70.8460
## [5,] 82.6030</code></pre>
<p>Now write a code snippet that takes the difference between two quantiles.</p>
<pre class="r"><code>the_probs <- c(0.25, 0.75)
the_quantiles <- quantile(gapminder$lifeExp, probs = the_probs)
max(the_quantiles) - min(the_quantiles)
## [1] 22.6475</code></pre>
</div>
<div id="turn-the-working-interactive-code-into-a-function-again" class="section level3">
<h3>Turn the working interactive code into a function, again</h3>
<p>I’ll use <code>qdiff</code> as the base of our function’s name. I copy the overall structure from our previous “max minus min” work but replace the guts of the function with the more general code we just developed.</p>
<pre class="r"><code>qdiff1 <- function(x, probs) {
stopifnot(is.numeric(x))
the_quantiles <- quantile(x = x, probs = probs)
max(the_quantiles) - min(the_quantiles)
}
qdiff1(gapminder$lifeExp, probs = c(0.25, 0.75))
## [1] 22.6475
IQR(gapminder$lifeExp) # hey, we've reinvented IQR
## [1] 22.6475
qdiff1(gapminder$lifeExp, probs = c(0, 1))
## [1] 59.004
mmm(gapminder$lifeExp)
## [1] 59.004</code></pre>
<p>Again we do some informal tests against familiar results and external implementations.</p>
</div>
<div id="argument-names-freedom-and-conventions" class="section level3">
<h3>Argument names: freedom and conventions</h3>
<p>I want you to understand the importance of argument names.</p>
<p>I can name my arguments almost anything I like. Proof:</p>
<pre class="r"><code>qdiff2 <- function(zeus, hera) {
stopifnot(is.numeric(zeus))
the_quantiles <- quantile(x = zeus, probs = hera)
return(max(the_quantiles) - min(the_quantiles))
}
qdiff2(zeus = gapminder$lifeExp, hera = 0:1)
## [1] 59.004</code></pre>
<p>While I can name my arguments after Greek gods, it’s usually a bad idea. Take all opportunities to make things more self-explanatory via meaningful names.</p>
<p>If you are going to pass the arguments of your function as arguments of a built-in function, consider copying the argument names. Unless you have a good reason to do your own thing (some argument names are bad!), be consistent with the existing function. Again, the reason is to reduce your cognitive load. This is what I’ve been doing all along and now you know why:</p>
<pre class="r"><code>qdiff1
## function(x, probs) {
## stopifnot(is.numeric(x))
## the_quantiles <- quantile(x = x, probs = probs)
## max(the_quantiles) - min(the_quantiles)
## }
## <bytecode: 0x7fdb289c3d38></code></pre>
<p>We took this detour so you could see there is no <em>structural</em> relationship between my arguments (<code>x</code> and <code>probs</code>) and those of <code>quantile()</code> (also <code>x</code> and <code>probs</code>). The similarity or equivalence of the names <strong>accomplishes nothing</strong> as far as R is concerned; it is solely for the benefit of humans reading, writing, and using the code. Which is very important!</p>
</div>
<div id="what-a-function-returns" class="section level3">
<h3>What a function returns</h3>
<p>By this point, I expect someone will have asked about the last line in my function’s body. Look above for a reminder of the function’s definition.</p>
<p>By default, a function returns the result of the last line of the body. I am just letting that happen with the line <code>max(the_quantiles) - min(the_quantiles)</code>. However, there is an explicit function for this: <code>return()</code>. I could just as easily make this the last line of my function’s body:</p>
<pre class="r"><code>return(max(the_quantiles) - min(the_quantiles))</code></pre>
<p>You absolutely must use <code>return()</code> if you want to return early based on some condition, i.e. before execution gets to the last line of the body. Otherwise, you can decide your own conventions about when you use <code>return()</code> and when you don’t.</p>
</div>
<div id="default-values-freedom-to-not-specify-the-arguments" class="section level3">
<h3>Default values: freedom to NOT specify the arguments</h3>
<p>What happens if we call our function but neglect to specify the probabilities?</p>
<pre class="r"><code>qdiff1(gapminder$lifeExp)
## Error in quantile(x = x, probs = probs): argument "probs" is missing, with no default</code></pre>
<p>Oops! At the moment, this causes a fatal error. It can be nice to provide some reasonable default values for certain arguments. In our case, it would be crazy to specify a default value for the primary input <code>x</code>, but very kind to specify a default for <code>probs</code>.</p>
<p>We started by focusing on the max and the min, so I think those make reasonable defaults. Here’s how to specify that in a function definition.</p>
<pre class="r"><code>qdiff3 <- function(x, probs = c(0, 1)) {
stopifnot(is.numeric(x))
the_quantiles <- quantile(x, probs)
return(max(the_quantiles) - min(the_quantiles))
}</code></pre>
<p>Again we check how the function works, in old examples and new, specifying the <code>probs</code> argument and not.</p>
<pre class="r"><code>qdiff3(gapminder$lifeExp)
## [1] 59.004
mmm(gapminder$lifeExp)
## [1] 59.004
qdiff3(gapminder$lifeExp, c(0.1, 0.9))
## [1] 33.5862</code></pre>
</div>
<div id="check-the-validity-of-arguments-again" class="section level3">
<h3>Check the validity of arguments, again</h3>
<p>EXERCISE FOR THE READER: upgrade our argument validity checks in light of the new argument <code>probs</code></p>
<pre class="r"><code>## problems identified during class
## we're not checking that probs is numeric
## we're not checking that probs is length 2
## we're not checking that probs are in [0,1]</code></pre>
</div>
<div id="wrap-up-and-whats-next" class="section level3">
<h3>Wrap-up and what’s next?</h3>
<p>Here’s the function we’ve written so far:</p>
<pre class="r"><code>qdiff3
## function(x, probs = c(0, 1)) {
## stopifnot(is.numeric(x))
## the_quantiles <- quantile(x, probs)
## return(max(the_quantiles) - min(the_quantiles))
## }
## <bytecode: 0x7fdb2d3c2268></code></pre>
<p>What we’ve accomplished:</p>
<ul>
<li>we’ve generalized our first function to take a difference between arbitrary quantiles</li>
<li>we’ve specified default values for the probabilities that set the quantiles</li>
</ul>
<p>Where to next? In <a href="block011_write-your-own-function-03.html">Part 3</a>, we tackle <code>NA</code>s, the special <code>...</code> argument, and formal unit testing.</p>
</div>
<div id="resources" class="section level3">
<h3>Resources</h3>
<p>Hadley Wickham’s book <a href="http://adv-r.had.co.nz">Advanced R</a></p>
<ul>
<li>Section on <a href="http://adv-r.had.co.nz/Functions.html#function-arguments">function arguments</a></li>
<li>Section on <a href="http://adv-r.had.co.nz/functions.html#return-values">return values</a></li>
</ul>
</div>
<div class="footer">
This work is licensed under the <a href="http://creativecommons.org/licenses/by-nc/3.0/">CC BY-NC 3.0 Creative Commons License</a>.
</div>
</div>
<script>
// add bootstrap table styles to pandoc tables
function bootstrapStylePandocTables() {
$('tr.header').parent('thead').parent('table').addClass('table table-condensed');
}
$(document).ready(function () {
bootstrapStylePandocTables();
});
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>