-
Notifications
You must be signed in to change notification settings - Fork 11
/
packages.html
466 lines (375 loc) · 23.6 KB
/
packages.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
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
<!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">USGS-R Packages</h1>
<section class="box content" id="package_intro">
<p>Clear communication about package expectations is very important. Package developers should be transparent about the maintenance, development, and user support associated with their package so that potential users are aware. To help with this communication for USGS R packages, we have created the following categories:</p>
<ul>
<li><a href="#core">Core:</a> Widely used and carefully designed</li>
<li><a href="#research">Research:</a> More narrow usage and limited long-term support.</li>
<li><a href="#support">Support:</a> Limited users with high-impact needs.</li>
<li><a href="#orphan">Orphan:</a> Packages looking for a maintainer and support.</li>
</ul>
<p>
Each is described in detail below. In general, they go from most support and outreach ("Core") to least ("Orphan"). See also the <a href="https://owi.usgs.gov/R/training-curriculum/r-package-dev/maintenance/">maintenance</a> section in our "R-package development" training: for a deeper conversation on additional package considerations.
</p>
</section>
<section class="box content" id="core">
<h4>USGS Core</h4>
<p>
A package with the designation "Core" has several key features:</p>
<div id="plain">
<ul>
<li>Critically important to a wide and general audience</li>
<li>Published, peer-reviewed documentation on the package</li>
<li>A statement of long-term support should be included in the README. This should communicate the source, timeline, and extent of support.</li>
<p><i>
For example:
<ol>
<li>
Source, e.g., "USGS Water Mission Area"
</li>
<li>
Timeline, e.g., "funding is stable through FY18 and is likely to be renewed into FY19 and beyond"
</li>
<li>
Extent, e.g., "funding is available for new features, with priorities determined by the development team"
</li>
</ol>
</i></p>
<li>Reasonable effort to make prompt responses for the following:</li>
<ul>
<li>Bug fixes</li>
<li>R version upgrades</li>
<li>Upstream R-package dependency change</li>
<li>User support and troubleshooting</li>
</ul>
<p><i>We recommend that maintainers attempt to acknowledge bugs and other issues as soon as they are discovered via a standard public channel such as a GitHub Issue. Then, publicly track the work, giving estimates of time and effort along the way.</i></p>
<li>An active USGS employee is designated as maintainer</li>
<li>Development and maintenance of core packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer. This increases the <a href="https://en.wikipedia.org/wiki/Bus_factor">Bus Factor</a> ("many individuals know enough to carry on and the project could still succeed even in very adverse events").</li>
<li>The package is well tested</li>
<p><i>For example, all critical functions should be tested for expected results using the <a href="https://cran.r-project.org/package=testthat">testthat</a> package. The coverage of testing can be measured using the <a href="https://coveralls.io/">coveralls</a> or <a href="https://codecov.io/">codecov</a> services.</i></p>
<li>The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are <a href="https://travis-ci.org/">Travis CI</a>, and <a href="https://www.appveyor.com/">AppVeyor</a></li>
<li>All external functions have clear documentation and working examples</li>
</ul>
</div>
<p>
A user of USGS core packages can expect prompt feedback from bug reports and general-use questions. Users can expect smooth transitions of maintainers since the package is well-tested, well-documented, and multiple developers have collaborated on the project. Enhancements should be carefully considered, "scope-creep" should be actively avoided (that is, give careful thought to adding new features). The general scope of the package should not change over time.</p>
<h3>Example Core Packages</h3>
<div id="wrapper" class="grid clearfix">
<div id="repoContainer">
<a href="https://github.com/USGS-R/dataRetrieval" target="_blank">
<div class="repos coreColor">
<h2>dataRetrieval</h2>
<p class="repoDescription">This R package for downloading and importing USGS and EPA water data.</p>
<p class="underDevelopment">Core</p>
</div>
</a>
<a href="https://github.com/USGS-R/geoknife" target="_blank">
<div class="repos coreColor">
<h2>geoknife</h2>
<p class="repoDescription">Tools for geo-web processing of gridded data. geoknife slices up data according to overlap with irregular features.</p>
<p class="underDevelopment">Core</p>
</div>
</a>
</div>
</div>
</section>
<section class="box content" id="research">
<h4>Research</h4>
<p>Research packages have two distinct phases: Development and Archive. Published but still active packages can seamlessly flow between Archive and Development, with expectations that the relevant requirements from both categories are fulfilled.</p>
<p>The following disclaimer applies to all research packages that do not have an associated peer-reviewed article included in a CITATION file.</p>
<h3>Disclaimer</h3>
<p><i>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.</i></p>
<p>Refer to <a href="https://www2.usgs.gov/fsp/fsp_disclaimers.asp" target="_blank">https://www2.usgs.gov/fsp/fsp_disclaimers.asp</a> for more information.</p>
<h3>Development</h3>
<p>Package development may include an exploratory phase when it's unclear whether an idea will ever become an active, publicly supported package. These packages should remain on personal github repositories or local computers. These packages offer value to only a small number of people for a limited time.</p>
<p>A more mature package during active development has several key features:</p>
<div id="plain">
<ul>
<li>The package is in active development and there is no guarantee of future behavior.</li>
<li>An official disclaimer is shown on the README, and any vignette</li>
<li>The package startup message needs to either include the above disclaimer, or link to this page:</li>
<pre class="language-Rcode">
<code class="language-Rcode">
.onAttach <- function(libname, pkgname) {
packageStartupMessage(paste(strwrap(
<span class="string">'USGS Research Package:
https://owi.usgs.gov/R/packages.html#research'</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(toxEval)
<span class="string">USGS Research Package:
https://owi.usgs.gov/R/packages.html#research</span>
</code>
</pre>
<li>The development of the package is being driven by a research topic, and should include input from both researchers and software developers.</li>
<li>The end goal should be one or more peer-reviewed journal publications.</li>
<li>A statement of support should be included in the README. This should communicate the source, timeline, and extent of support.</li>
<p><i>
For example:
<ol>
<li>
Source, e.g., "Water Mission Area"
</li>
<li>
Timeline, e.g., "funding is stable through FY17 and might be renewed into FY18 and beyond"
</li>
<li>
Extent, e.g., "funding is available for new features, with priorities determined by the development team" or "support is primarily for maintenance rather than new features" or "support covers maintenance and bug fixes, but we're awfully short on time for user questions, sorry"
</li>
</ol>
</i></p>
<li>It is encouraged to include a "sunset" date in the README or package startup message.</li>
<pre class="language-Rcode">
<code class="language-Rcode">
.onAttach <- function(libname, pkgname) {
packageStartupMessage(paste(strwrap(
<span class="string">'USGS Research Package:
https://owi.usgs.gov/R/packages.html#research
Funding for toxEval expires summer 2017,
after which bug fixes & new features will be minimal'</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(toxEval)
<span class="string">USGS Support Package:
https://owi.usgs.gov/R/packages.html#support
Funding for toxEval expires summer 2017,
after which bug fixes & new features will be minimal
</span>
</code>
</pre>
<li>Emphasis should still be placed on testing key features and good documentation during development.</li>
<li>Since the goal is a published article, the expectation should be that outside users will use this package to test the reproducibility of the primary author’s data analysis, as well as reproducing the analysis on new data.</li>
<li>During development, the package version should remain below v1.0.0.</li>
</ul>
</div>
<p>It is important to clearly communicate to any known or unknown users the risk they take with using a package that is in the active research development phase. See <code>?packageStartupMessage</code> to learn how to add a message to that gets displayed whenever a user loads the package.</p>
<h3>Example Research Packages</h3>
<div id="wrapper" class="grid clearfix">
<div id="repoContainer">
<a href="https://github.com/USGS-R/streamMetabolizer" target="_blank">
<div class="repos researchColor">
<h2>streamMetabolizer</h2>
<p class="repoDescription">Uses inverse modeling to estimate aquatic metabolism from time series data on dissolved oxygen, water temperature, depth, and light.</p>
<p class="underDevelopment">Research</p>
</div>
</a>
<a href="https://github.com/USGS-R/toxEval" target="_blank">
<div class="repos researchColor">
<h2>toxEval</h2>
<p class="repoDescription">Initial code for studying ToxCast data in relation to measured.</p>
<p class="underDevelopment">Research</p>
</div>
</a>
<a href="https://github.com/USGS-R/loadflex" target="_blank">
<div class="repos researchColor">
<h2>loadflex</h2>
<p class="repoDescription">Models and Tools for Watershed Flux Estimates.</p>
<p class="underDevelopment">Research</p>
</div>
</a>
</div>
</div>
<h3>Archive</h3>
<p>A package that has completed the main development concluding with a published document can be archived. Archive packages have several key features:</p>
<div id="plain">
<ul>
<li>The development of the package was completed with the publishing of a scientific, peer-reviewed journal or report</li>
<li>A reproducible work-flow is included either within a vignette or via the final product (such as the journal article)</li>
<li>There are no official expectations that bug fixes and R version upgrades will happen. The expectations need to be clearly communicated to the users</li>
<li>The package maintainer should have an active email.</li>
<li>The package version should be updated to v1.0.0 once a stable version is released.</li>
<li>Once the final version is released, the maintainer should provide the output of <code>devtools::session_info()</code> for an archive of the environment in which the code was last tested and verified as stable.</li>
</ul>
</div>
<p>
It should be clearly communicated that the package has a well-documented final product. An archived research R-package can certainly maintain development such as bug fixes and required changes to R version updates. Maintaining the package and interacting with users can be very beneficial for professional development. However, it is important to communicate the official level of support for future users. See <code>?packageStartupMessage</code> to learn how to add a message to that gets displayed whenever a user loads the package.
</p>
<h3>Example Archive Research Packages</h3>
<div id="wrapper" class="grid clearfix">
<div id="repoContainer">
<a href="https://github.com/USGS-R/EGRET" target="_blank">
<div class="repos researchColor">
<h2>EGRET</h2>
<p class="repoDescription">An R-package for the analysis of long term changes in water quality and streamflow</p>
<p class="underDevelopment">Research</p>
</div>
</a>
<a href="https://github.com/USGS-R/EGRETci" target="_blank">
<div class="repos researchColor">
<h2>EGRETci</h2>
<p class="repoDescription">A bootstrap method for estimating uncertainty of water quality trends.</p>
<p class="underDevelopment">Research</p>
</div>
</a>
</div>
</div>
</section>
<section class="box content" id="support">
<h4>Support</h4>
<p>A package with the designation "Support" may not have a research component, and also may not be intended for a wide, general audience. However, these packages may be critically important to other projects throughout the USGS. Therefore, it is important to follow best-practices in the package development, as well as clearly communicate the intent and level of support for these packages. See <code>?packageStartupMessage</code> to learn how to add a message to that gets displayed whenever a user loads the package.</p>
<p>The following disclaimer applies to all support packages that do not have an associated peer-reviewed article included in a CITATION file.</p>
<h3>Disclaimer</h3>
<p><i>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.</i></p>
<p>Refer to <a href="https://www2.usgs.gov/fsp/fsp_disclaimers.asp" target="_blank">https://www2.usgs.gov/fsp/fsp_disclaimers.asp</a> for more information.</p>
<div id="plain">
<ul>
<li>An active USGS employee is designated as maintainer. Development and maintenance of support packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer.</li>
<li>The package is well tested</li>
<p><i>For example, all critical functions should be tested for expected results using the <a href="https://cran.r-project.org/package=testthat">testthat</a> package. The coverage of testing can be measured using the <a href="https://coveralls.io/">coveralls</a> or <a href="https://codecov.io/">codecov</a> services.</i></p>
<li>The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are <a href="https://travis-ci.org/">Travis CI</a>, and <a href="https://www.appveyor.com/">AppVeyor</a></li>
<li>Key functions should have clear documentation and working examples. </li>
<li>An official disclaimer is shown on the README, and any vignettes:</li>
<li>The package startup message needs to either include the above disclaimer, or link to this page:</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>
</ul>
</div>
<h3>Example Support Packages</h3>
<div id="wrapper" class="grid clearfix">
<div id="repoContainer">
<a href="https://github.com/USGS-R/sbtools" target="_blank">
<div class="repos supportColor">
<h2>sbtools</h2>
<p class="repoDescription">Tools for interfacing R with ScienceBase data services.</p>
<p class="underDevelopment">Support</p>
</div>
</a>
<a href="https://github.com/USGS-R/gsplot" target="_blank">
<div class="repos supportColor">
<h2>gsplot</h2>
<p class="repoDescription">plotting foundation for timeseries reporting</p>
<p class="underDevelopment">Support</p>
</div>
</a>
<a href="https://github.com/USGS-R/repgen" target="_blank">
<div class="repos supportColor">
<h2>repgen</h2>
<p class="repoDescription">report generation in R</p>
<p class="underDevelopment">Support</p>
</div>
</a>
<a href="https://github.com/USGS-R/grantools" target="_blank">
<div class="repos supportColor">
<h2>grantools</h2>
<p class="repoDescription">Tools for the Geological survey R Archive Network</p>
<p class="underDevelopment">Support</p>
</div>
</a>
<a href="https://github.com/USGS-R/smwrGraphs" target="_blank">
<div class="repos supportColor">
<h2>smwrGraphs</h2>
<p class="repoDescription">Graphical USGS water science R functions.</p>
<p class="underDevelopment">Support</p>
</div>
</a>
</div>
</div>
</section>
<section class="box content" id="orphan">
<h4>Orphan</h4>
<p>A package with the designation "Orphan" does not have an active USGS employee designated as maintainer. The odds of a package becoming orphaned can be minimized during the package-creation phase by using a team of developers to collaborate, emphasizing clear documentation and high test-coverage. Community efforts to troubleshoot issues and submit bug-fixes are encouraged. Orphan packages should include some communication on both the readme and package startup message that the status is "orphan" and information on whom to contact to volunteer to take over maintainer duties.</p>
<p>The following disclaimer applies to all orphan packages that do not have an associated peer-reviewed article included in a CITATION file.</p>
<p>
Training from USGS-sponsored courses should avoid orphan packages until they have designated an active maintainer and have addressed long-term resource commitments. </p>
<div id="plain">
<h3>Disclaimer</h3>
<p><i>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.</i></p>
<p>Refer to <a href="https://www2.usgs.gov/fsp/fsp_disclaimers.asp" target="_blank">https://www2.usgs.gov/fsp/fsp_disclaimers.asp</a> for more information.</p>
</div>
<h3>Current Orphan Packages</h3>
<p>If you are interested in taking over maintainer status for any of the following packages, please email <a href="mailto:[email protected]"><[email protected]></a>. USGS-R admins will make a strong effort to communicate the status of orphan packages.</p>
<div id="wrapper" class="grid clearfix">
<div id="repoContainer">
<a href="https://github.com/USGS-R/rloadest" target="_blank">
<div class="repos orphanColor">
<h2>rloadest</h2>
<p class="repoDescription">USGS water science R functions for LOAD ESTimation of constituents in rivers and streams.</p>
<p class="underDevelopment">Orphan</p>
</div>
</a>
<a href="https://github.com/USGS-R/smwrQW" target="_blank">
<div class="repos orphanColor">
<h2>smwrQW</h2>
<p class="repoDescription">Water quality USGS water science R functions.</p>
<p class="underDevelopment">Orphan</p>
</div>
</a>
<a href="https://github.com/USGS-R/restrend" target="_blank">
<div class="repos orphanColor">
<h2>restrend</h2>
<p class="repoDescription">USGS water science R functions for EStimate TRENDs.</p>
<p class="underDevelopment">Orphan</p>
</div>
</a>
<a href="https://github.com/USGS-R/DVstats" target="_blank">
<div class="repos orphanColor">
<h2>DVstats</h2>
<p class="repoDescription">USGS water science R functions for the analysis of daily-values data.</p>
<p class="underDevelopment">Orphan</p>
</div>
</a>
</div>
</div>
</section>
</article>
</main>
<!-- END Main Content -->
<div id="footer"></div>
</body>
</html>