forked from swcarpentry/r-novice-inflammation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path08-making-packages-R.html
152 lines (148 loc) · 10.2 KB
/
08-making-packages-R.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<title>Software Carpentry: Programming with R</title>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap.css" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap-theme.css" />
<link rel="stylesheet" type="text/css" href="css/swc.css" />
<link rel="alternate" type="application/rss+xml" title="Software Carpentry Blog" href="http://software-carpentry.org/feed.xml"/>
<meta charset="UTF-8" />
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body class="lesson">
<div class="container card">
<div class="banner">
<a href="http://software-carpentry.org" title="Software Carpentry">
<img alt="Software Carpentry banner" src="img/software-carpentry-banner.png" />
</a>
</div>
<article>
<div class="row">
<div class="col-md-10 col-md-offset-1">
<a href="index.html"><h1 class="title">Programming with R</h1></a>
<h2 class="subtitle">Making packages in R</h2>
<section class="objectives panel panel-warning">
<div class="panel-heading">
<h2 id="learning-objectives"><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2>
</div>
<div class="panel-body">
<p>Quick summary on how (and why) making R packages</p>
</div>
</section>
<p>Why should you make your own R packages?</p>
<p><strong>Reproducible research!</strong></p>
<p>An R package is the <strong>basic unit of reusable code</strong>. If you want to reuse code later or want others to be able to use your code, you should put it in a package.</p>
<p>An R package requires two components: - a DESCRIPTION file with metadata about the package - an R directory with the code</p>
<p><em>There are other optional components. Go <a href="http://adv-r.had.co.nz/Package-basics.html">here</a> for much more information.</em></p>
<h2 id="description-file">DESCRIPTION file</h2>
<pre><code>Package: Package name
Title: Brief package description
Description: Longer package description
Version: Version number(major.minor.patch)
Author: Name and email of package creator
Maintainer: Name and email of package maintainer (who to contact with issues)
License: Abbreviation for an open source license</code></pre>
<p>The package name can only contain letters and numbers and has to start with a letter.</p>
<h2 id="r-files">.R files</h2>
<p>Functions don’t all have to be in one file or each in separate files. How you organize them is up to you. Suggestion: organize in a logical manner so that you know which file holds which functions.</p>
<h2 id="making-your-first-r-package">Making your first R package</h2>
<p>Let’s turn our temperature conversion functions into an R package.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">fahr_to_kelvin <-<span class="st"> </span>function(temp) {
<span class="co">#Converts Fahrenheit to Kelvin</span>
kelvin <-<span class="st"> </span>((temp -<span class="st"> </span><span class="dv">32</span>) *<span class="st"> </span>(<span class="dv">5</span>/<span class="dv">9</span>)) +<span class="st"> </span><span class="fl">273.15</span>
kelvin
}</code></pre></div>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">kelvin_to_celsius <-<span class="st"> </span>function(temp) {
<span class="co">#Converts Kelvin to Celsius</span>
Celsius <-<span class="st"> </span>temp -<span class="st"> </span><span class="fl">273.15</span>
Celsius
}</code></pre></div>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">fahr_to_celsius <-<span class="st"> </span>function(temp) {
<span class="co">#Converts Fahrenheit to Celsius using fahr_to_kelvin() and kelvin_to_celsius()</span>
temp_k <-<span class="st"> </span><span class="kw">fahr_to_kelvin</span>(temp)
result <-<span class="st"> </span><span class="kw">kelvin_to_celsius</span>(temp_k)
result
}</code></pre></div>
<p>We will use the <code>devtools</code> and <code>roxygen2</code> packages, which make creating packages in R relatively simple. First, install the <code>devtools</code> package, which will allow you to install the <code>roxygen2</code> package from GitHub (<a href="https://github.com/klutometis/roxygen">code</a>).</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">install.packages</span>(<span class="st">"devtools"</span>)
<span class="kw">library</span>(<span class="st">"devtools"</span>)
<span class="kw">install_github</span>(<span class="st">"klutometis/roxygen"</span>)
<span class="kw">library</span>(<span class="st">"roxygen2"</span>)</code></pre></div>
<p>Set your working directory, and then use the <code>create</code> function to start making your package. Keep the name simple and unique. - package_to_convert_temperatures_between_kelvin_fahrenheit_and_celsius (BAD) - tempConvert (GOOD)</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">setwd</span>(parentDirectory)
<span class="kw">create</span>(<span class="st">"tempConvert"</span>)</code></pre></div>
<p>Add our functions to the R directory. Place each function into a separate R script and add documentation like this:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="co">#' Convert Fahrenheit to Kelvin</span>
<span class="co">#'</span>
<span class="co">#' This function converts input temperatures in Fahrenheit to Kelvin.</span>
<span class="co">#' @param temp The input temperature.</span>
<span class="co">#' @export</span>
<span class="co">#' @examples</span>
<span class="co">#' fahr_to_kelvin(32)</span>
fahr_to_kelvin <-<span class="st"> </span>function(temp) {
<span class="co">#Converts Fahrenheit to Kelvin</span>
kelvin <-<span class="st"> </span>((temp -<span class="st"> </span><span class="dv">32</span>) *<span class="st"> </span>(<span class="dv">5</span>/<span class="dv">9</span>)) +<span class="st"> </span><span class="fl">273.15</span>
kelvin
}</code></pre></div>
<p>The <code>roxygen2</code> package reads lines that begin with <code>#'</code> as comments to create the documentation for your package. Descriptive tags are preceded with the <code>@</code> symbol. For example, <code>@param</code> has information about the input parameters for the function. Now, we will use <code>roxygen2</code> to convert our documentation to the standard R format.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">setwd</span>(<span class="st">"./tempConvert"</span>)
<span class="kw">document</span>()</code></pre></div>
<p>Take a look at the package directory now. The /man directory has a .Rd file for each .R file with properly formatted documentation.</p>
<p>Now, let’s load the package and take a look at the documentation.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">setwd</span>(<span class="st">".."</span>)
<span class="kw">install</span>(<span class="st">"tempConvert"</span>)
?fahr_to_kelvin</code></pre></div>
<p>Notice there is now a tempConvert environment that is the parent environment to the global environment.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">search</span>()</code></pre></div>
<p>Now that our package is loaded, let’s try out some of the functions.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">fahr_to_celsius</span>(<span class="dv">32</span>)</code></pre></div>
<pre class="output"><code>[1] 0
</code></pre>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">fahr_to_kelvin</span>(<span class="dv">212</span>)</code></pre></div>
<pre class="output"><code>[1] 373.15
</code></pre>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">kelvin_to_celsius</span>(<span class="fl">273.15</span>)</code></pre></div>
<pre class="output"><code>[1] 0
</code></pre>
<section class="challenge panel panel-success">
<div class="panel-heading">
<h2 id="challenge---creating-a-package-for-distribution"><span class="glyphicon glyphicon-pencil"></span>Challenge - Creating a package for distribution</h2>
</div>
<div class="panel-body">
<ul>
<li>Create some new functions for your tempConvert package to convert from Kelvin to Fahrenheit or from Celsius to Kelvin or Fahrenheit.</li>
<li>Create a package for our <code>analyze</code> function so that it will be easy to load when more data arrives.</li>
</ul>
</div>
</section>
</div>
</div>
</article>
<div class="footer">
<a class="label swc-blue-bg" href="http://software-carpentry.org">Software Carpentry</a>
<a class="label swc-blue-bg" href="https://github.com/swcarpentry/r-novice-inflammation">Source</a>
<a class="label swc-blue-bg" href="mailto:[email protected]">Contact</a>
<a class="label swc-blue-bg" href="LICENSE.html">License</a>
</div>
</div>
<!-- Javascript placed at the end of the document so the pages load faster -->
<script src="http://software-carpentry.org/v5/js/jquery-1.9.1.min.js"></script>
<script src="css/bootstrap/bootstrap-js/bootstrap.js"></script>
<script src='https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></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','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-37305346-2', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>