-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathgran.html
236 lines (175 loc) · 11 KB
/
gran.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
<!doctype html>
<html>
<head>
<!-- ############### VIEWPORT META TAG ############### -->
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no" />
<!-- ################################################# -->
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<title>OWI-R</title>
<link href="css/style.css" rel="stylesheet" type="text/css">
<link href='//fonts.googleapis.com/css?family=Open+Sans:400,700,600' rel='stylesheet' type='text/css'>
<link rel="icon" type="image/ico" href="img/favicon.ico" />
<script src="js/jquery-2.1.3.min.js" type="text/javascript"></script>
<script src="js/handlebars.min_4.0.5.js" type="text/javascript"></script>
<script src="js/application.js" type="text/javascript"></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-53797708-5', 'auto');
ga('send', 'pageview');
</script>
<script type="application/javascript" src="//www2.usgs.gov/scripts/analytics/usgs-analytics.js"></script>
</head>
<body>
<div id="header"></div>
<div id="nav"></div>
<!-- BEGIN Main Content -->
<main>
<article>
<h1 class="page-title-h1">GRAN</h1>
<section class="box content" id="gran_intro">
<h3>What is GRAN?</h3>
<p>
<b>G</b>eological Survey <b>R</b> <b>A</b>rchive <b>N</b>etwork <br> <br>
GRAN is a repository of curated R packages developed by USGS employees for USGS and external use. It allows a user to easily download and install an R package and, in the future, receive updates to that package code as they become available. Inclusion of packages on GRAN does not imply USGS approval; citations and disclaimers associated with package are included upon package load or in the package "CITATION" file. <br> <br>
The objective of GRAN is to facilitate engagement and R tool sharing across the USGS Water Mission Area.
</p>
</section>
<section class="box content" id="use-gran">
<h3>How to use GRAN?</h3>
<p>
There are two ways to take advantage of GRAN tools.<br><br>
<ol class="granNumberList">
<li><h4>Alter the .Rprofile file</h4>
This will tell your R environment to always look in the GRAN repository when installing packages and updating packages. This is the preferred method because of the ability to automatically get GRAN updates. The following command in R will run a script to update your Rprofile file:</li>
<pre class="language-Rcode" >
<code class="language-Rcode">
rprofile_path = file.path(Sys.getenv(<span class="string">"HOME"</span>)<span class="punctuation">,</span> <span class="string">".Rprofile"</span>)
write(<span class="string">'\noptions(repos=c(getOption(\'repos\'),
CRAN=\'https://cloud.r-project.org\',
USGS=\'https://owi.usgs.gov/R\'))\n'</span><span class="punctuation">,</span>
rprofile_path<span class="punctuation">,</span>
append <span class="punctuation">=</span> <span class="variable">TRUE</span>)
cat(<span class="string">'Your Rprofile has been updated to include GRAN.
Please restart R for changes to take effect.'</span>)
</code>
</pre>
It is then possible to simply install the <code class="language-Rcode">smwrData</code> package using: <br>
<pre class="language-Rcode">
<code class="language-Rcode">
install.packages(<span class="string">"smwrData"</span>)
</code>
</pre>
Or to update all installed packages (if needed) with: <br>
<pre class="language-Rcode">
<code class="language-Rcode">
update.packages()
</code>
</pre>
<li><h4>Use the 'repo' argument in the install.packages function</h4>
This will tell install.packages to look at a specific url for package installation. </li>
<pre class="language-Rcode">
<code class="language-Rcode">
install.packages(<span class="string">"smwrData"</span>, <span class="variable">repos</span><span class="punctuation">=</span>c(<span class="string">"https://owi.usgs.gov/R"</span><span class="punctuation">,</span>getOption(<span class="string">"repos"</span>)))
</code>
</pre>
</ol>
</p>
</section>
<section class="box content" id="list-packages">
<h3>What packages are on GRAN?</h3>
<p>
GRAN includes curated packages that can be easily installed. A detailed package list will be added in the future, but one can always use the following command in R to list all packages that are currently available:
<br><br>
<ol class="granNumberList">
<pre class="language-Rcode" >
<code class="language-Rcode">
GRAN_pkg <- available.packages(contrib.url(<span class="string">"https://owi.usgs.gov/R"</span>))
names(GRAN_pkg[,1])
</code>
</pre>
</section>
<section class="box content" id="add-packages">
<h3>How do I add my package to GRAN?<a id="add_package"></a></h3>
<p>
Developers that have an R package that would be useful to others within USGS are encouraged to use GRAN to distribute those packages.
There are a minimum number of required steps before a package is GRAN-ready (see <a href="#gran_policy">guidelines</a>),
which should be completed before submitting a package to GRAN. Assuming a package is compliant, follow the steps for submission below:
</p>
<div id="plain">
<ol class="granNumberList">
<li>Obtain, document, and address peer review of package using the <a href="https://my.usgs.gov/jira/browse/GITPILOT/">my.usgs JIRA system</a>. </li>
<li>Host your full package code on GitHub (preferably within the USGS-R organization)</li>
<li><a href="https://help.github.com/articles/creating-releases/">Create a tagged release</a> of a stable version of your package on github.com</li>
<li>Ensure package builds and passes "as cran" checks with no warnings
<pre class="language-Rcode" >
<code class="language-Rcode">
R CMD check --as-cran {packagename_version}.tar.gz
</code>
</pre>
</li>
<li><a href="https://help.github.com/articles/fork-a-repo/">Fork</a> the USGS-R <code>grantools</code> to your USGS GitHub account.</li>
<li>Add your package location and name (using the format <code>repository/packagename</code>) and tagged release name to the file <code>gran_source_list.tsv</code> </li>
<li>Create a pull request between your fork of grantools and the USGS-R version of grantools</li>
<li>Packages are expect to have zero Notes or Warnings on check. If you would like an exception, explain (in the pull request comments) why each Note and Warning should be allowed.</li>
<li>Receive a notification once your package has been added (usually within one day).</li>
</ol>
</div>
</section>
<section class="box content">
<h3>What are the GRAN guidelines?<a id="gran_policy"></a></h3>
<p>
<div id="plain">
<ol class="granNumberList">
<li>Required: Active tool maintainer with *@usgs.gov email address
If a maintainer becomes inactive, the package will be removed.</li>
<li>Required: Code must be on GitHub USGS-R repository to facilitate the automation of tool builds, checks, and releases:</li>
<ul>
<li>Required: Each GRAN update must be a Github "release". </li>
<li>Recommended: Continuous integration.</li>
<li>Recommended: Maintainer will use Github issues system for issue/bug reporting and tracking. </li>
</ul>
<li>Required: All packages must either print the <a href="#disclaimer">OWI GRAN Software disclaimer<sup>A</sup></a> or a link to the appropriate <a href="packages.html">package category</a>. This is only required for packages that <b>do not</b> have an associated peer-reviewed publication and citation. For example: </li>
<pre class="language-Rcode">
<code class="language-Rcode">
.onAttach <- function(libname, pkgname) {
packageStartupMessage(paste(strwrap(
<span class="string">'USGS Support Package:
https://owi.usgs.gov/R/packages.html#support'</span>)<span class="punctuation">,</span>
collapse=<span class="string">'\n'</span>))
}
</code>
</pre>
<p>Which will show the user:</p>
<pre class="language-Rcode">
<code class="language-Rcode">
library(smwrGraphs)
<span class="string">USGS Support Package:
https://owi.usgs.gov/R/packages.html#support</span>
</code>
</pre>
<li>Required: All packages with a peer-reviewed publication must include proper reference in the package "CITATION" file.</li>
<p><i>Once a CITATION is included, there is no requirement for the package startup message as described above.</i></p>
<li>Initial code import and updates are handled through pull requests to "grantools". New GRAN users should contact <a href="mailto:[email protected]"><[email protected]></a> for support with initial release of software.</li>
<li>Binary packages will be maintained for only the current release version of R.</li>
<li>
Package maintainers are expected to understand and follow the policies of the USGS for code distribution. <a href="http://water.usgs.gov/admin/memo/policy/wrdpolicy09.01.html">Water Policy 2009.01</a> and <a href="https://www2.usgs.gov/usgs-manual/im/IM-OSQI-2016-01.html">Review and Approval of Software for Release</a>.
</li>
<li>USGS best practices for software are described <a href="https://github.com/usgs/best-practices/tree/master/software">here</a>.</li>
</ol>
</div>
</p>
</section>
<section class="box content" id="disclaimer">
<p><sup>A</sup> OWI GRAN Software disclaimer: This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.
</p>
</section>
</article>
</main>
<!-- END Main Content -->
<div id="footer"></div>
</body>
</html>