Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/program--/hsclientr

R :package: for accessing the HydroShare API
https://github.com/program--/hsclientr

api-wrapper cuashi hydrology hydroshare r rstats water-resources

Last synced: 24 days ago
JSON representation

R :package: for accessing the HydroShare API

Awesome Lists containing this project

README

        

# HSClientR - A [HydroShare](https://www.hydroshare.org) API Client for R

**Usage**|**Development**
:-----:|:-----:
[![CRAN status](https://www.r-pkg.org/badges/version/HSClientR)](https://CRAN.R-project.org/package=HSClientR)|[![R-CMD-check](https://github.com/program--/HSClientR/workflows/R-CMD-check/badge.svg)](https://github.com/program--/HSClientR/actions)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)|[![Travis build status](https://travis-ci.com/program--/HSClientR.svg?branch=master)](https://travis-ci.com/program--/HSClientR)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)|[![test-coverage](https://github.com/program--/HSClientR/workflows/test-coverage/badge.svg)](https://github.com/program--/HSClientR/actions)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)|[![Codecov test coverage](https://codecov.io/gh/program--/HSClientR/branch/master/graph/badge.svg)](https://codecov.io/gh/program--/HSClientR)

HSClientR is an API wrapper for
[HydroShare](https://www.hydroshare.org). Using HSClientR, you can
access resources from HydroShare directly in your R environment, either
by the package functions or the in-development
[`R6 Class`](https://r6.r-lib.org/reference/R6Class.html).

## Installation

You can install the developmental version of HSClientR with:

``` r
# install.packages("remotes")
remotes::install_github("program--/HSClientR")
```

## Documentation

- [Package Website](https://hsclientr.justinsingh.me)
- [HydroShare API](https://www.hydroshare.org/hsapi/)

## Example Using Package Functions

This is a basic example which shows you how to access a resource. We’ll
access the resource [Hydrologic Terrain Analysis Using Web Based
Tools](https://www.hydroshare.org/resource/e1d4f2aff7d84f79b901595f6ea48368/),
as well as some additional functionality.

### Authenticating with HydroShare

``` r
# To set auth headers
hs_auth(set_headers = TRUE)
```

This function will begin an [OAuth 2.0](https://oauth.net/2/) dance between your R session and the
HydroShare API. This is only needed if you are utilizing `hs_user()`/`hs_userDetails()` or any of the
`DELETE`, `POST`, and `PUT` functions. Most of the `GET` functions are publicly accessible.

``` r
# Search for resources
hs_resource(
text = "Hydrologic Terrain Analysis Using Web Based Tools",
author = "David Tarboton"
)

# Alternatively, if you want to use specific functions,
# you can call hs_search() with the same parameters

#> $.next
#> [1] NA
#>
#> $.prev
#> [1] NA
#>
#> $results
#> # A tibble: 5 x 10
#> id title author abstract contributor subject availability content_type
#>
#> 1 c1be8… Clearin… Tarbo… "Can your… "" #gisDay… public Composite, …
#> 2 1302d… Clearin… Tarbo… "Can your… "" AGU2015 public Composite, …
#> 3 e1d4f… Hydrolo… Tarbo… "Digital … "" TauDEM,… public Presentatio…
#> 4 66fd9… Materia… Tarbo… "Material… "" Worksho… public Presentatio…
#> 5 d752e… The Mod… Tarbo… "Model My… "" present… public Presentatio…
#> # … with 2 more variables: metadata , geodata
```

Another way of finding resources is via the Discover API.
This is equivalent to accessing the "Discover" page directly
on the HydroShare website. It returns the first 40 results.

> It is preferred to use `hs_resource()` or any of the other `hs_*` functions,
> as they have better support/flexibility in contrast to `hs_discover()`.

``` r
hs_discover()

#> # A tibble: 40 x 6
#> title link author abstract short_id metadata
#>
#> 1 SUMMA Simulat… https://hydr… Choi, Young… "These are examp… 03dc01d36… 2 SUMMA Simulat… https://hydr… Choi, Young… "These are examp… ac54c8046… 3 NLDAS Forcing… https://hydr… Choi, Young… "This resource w… a28685d2d… 4 SHAW model in… https://hydr… Marshall, A… "This dataset su… 5a355d673… 5 Application o… https://hydr… Pedrazas, M… "Fluvio-deltaic … cf3c26339… 6 ModelMyWaters… https://hydr… Ensign, Sco… "A watershed mul… a10bfc16d… 7 Wasatch Envir… https://hydr… University … "This dataset co… 5057577e8… 8 Wasatch Envir… https://hydr… University … "This dataset co… 252980b3b… 9 Wasatch Envir… https://hydr… University … "This dataset co… 6445418c7… 10 Wasatch Envir… https://hydr… University … "This dataset co… 74dc57ed7… # … with 30 more rows
```

You can also call hs_resource() with no parameters to do basic pagination searches.

> This is usually preferred over hs_discover().

``` r
hs_resource()

#> $.next
#> [1] "https://www.hydroshare.org/hsapi/resource/search?page=2"
#>
#> $.prev
#> [1] NA
#>
#> $results
#> # A tibble: 100 x 10
#> id title author abstract contributor subject availability content_type
#>
#> 1 73aae… 00_Ze… Arscot… "Stroud … "" mmw, mo… public Geographic F…
#> 2 73ad4… 00_Ze… Gisond… "Second … "" osi, mo… public Geographic F…
#> 3 ea93a… 00_Ze… Gisond… "Part of… "" osi, mo… public Geographic F…
#> 4 a2a5c… 01_Pe… Gish, … "Aggrega… "" cbf, mm… public Geographic F…
#> 5 5002f… 01_Ze… Gisond… "Part of… "" osi, mo… public Geographic F…
#> 6 1048d… 02_Ma… Gish, … "Aggrega… "" cbf, mm… public Geographic F…
#> 7 b4b3c… 02_Ze… Gisond… "Second … "" osi, mo… public Geographic F…
#> 8 fb70e… 02_Ze… Gisond… "Part of… "" osi, mo… public Geographic F…
#> 9 74704… 03_Cl… Gish, … "Aggrega… "" cbf, mm… public Geographic F…
#> 10 737cf… 03_Mo… Gisond… "Second … "" osi, mo… public Geographic F…
#> # … with 90 more rows, and 2 more variables: metadata , geodata
```

You can also find resources by HydroShare alphanumeric IDs:

``` r
hs_resource(id = "e1d4f2aff7d84f79b901595f6ea48368")

#> # A tibble: 1 x 19
#> resource_title resource_type resource_id abstract authors creator doi public
#>
#> 1 Hydrologic Ter… CompositeReso… e1d4f2aff7… "Digita… David … David … NA TRUE
#> # … with 11 more variables: discoverable , shareable , immutable ,
#> # published , date_created , date_last_updated , bag_url ,
#> # science_metadata_url , resource_map_url , resource_url ,
#> # content_types
```

For more details on using `hs_resource()`, refer to the
[documentation site](https://hsclientr.justinsingh.me/reference/hs_resource.html).

## Example Using R6 HydroShare Client Class

> Note: functionality for queries and discover traversal still need to
> be implemented. The example below may change as the object matures.

``` r
# Create new HSClient object
hs_client <- HSClient$new()

#> R6-based client still in-development.
#> Full functionality may not exist.
#>
#> HSClientR - R6 Client
#> =======================================
#> Thanks for using HSClientR! ♥
#> You can start a query with $query()
#> Make sure to authenticate with $authenticate()
#> =======================================

hs_client$print()

#> It looks like you haven't authenticated yet...
#> Please call $authenticate() on this object to get
#> OAuth2 authentication set up with HydroShare! :)

# Begin authentication (hs_auth)
hs_client$authenticate()

# OAuth2 Dance will begin and a web browser
# will open to HydroShare's login/authorization
# page. Once you login, an access token will be
# sent back to a local httpuv web server for
# your R session.

# Search for a resource (hs_resource)
hs_client$query(text = "NHDPlus VAA")

#> # A tibble: 2 x 18
#> text author abstract contributor subject availability created modified
#>
#> 1 " \n ba… Rea, A… "The NHDPl… "" NHDPlus,… public 2019-0… 2019-08…
#> 2 " \n 60… Johnso… "These fil… "" roughnes… public 2020-1… 2021-02…
#> # … with 10 more variables: coverage_type , east , northlimit ,
#> # eastlimit , southlimit , westlimit , start_date ,
#> # end_date , resource_type , content_type

# $query uses hs_search() to perform the query,
# and while a tibble is outputted, the object returns
# itself invisibly. Once the query is performed, we can
# print our object to see our last query and its results:

hs_client$print()

#> Authenticated as:
#> Justin Singh-Mohudpur
#> User: jsinghm
#> ID: 8409
#> Org: University of California, Santa Barbara
#> =======================================
#> Last Query ($query): text = "NHDPlus VAA"
#> Query Results:
#>
#> 6092c8a62fac45be97a09bfd0b0bf726
#>
#> NHDPlus Value Added Attributes - no geometries
#> These files contain a curated set ...
```

## Meta

* Please [report any issues or bugs](https://github.com/program--/HSClientR/issues).
* License: MIT
* Please note that this package is released with a [Contributor Code of Conduct](https://hsclientr.justinsingh.me/code_of_conduct). By contributing to this project, you agree to abide by its terms.