Skip to contents

sbtools -- getting started

2023-11-17

Source: vignettes/sbtools.Rmd
sbtools.Rmd

sbtools provides access and upload utilities for ScienceBase

Much of sbtools does not require authentication.

## Examples

library(sbtools)

# Query ScienceBase for data about Antarctica
query_sb_text('Antarctica', limit=1)
#> [[1]]
#> <ScienceBase Item> 
#>   Title: Antarctica
#>   Creator/LastUpdatedBy:      / 
#>   Provenance (Created / Updated):   / 
#>   Children: 
#>   Item ID: 6537fe3cd34ee4b6e05bb998
#>   Parent ID: 4f70b292e4b058caae3f8e1d

# Query for a specific DOI
query_sb_doi('10.5066/P92U7ZUT')
#> [[1]]
#> <ScienceBase Item> 
#>   Title: Mainstem Rivers of the Conterminous United States (ver. 2.0, February 2023)
#>   Creator/LastUpdatedBy:      / 
#>   Provenance (Created / Updated):   / 
#>   Children: 
#>   Item ID: 63cb38b2d34e06fef14f40ad
#>   Parent ID: 5474ec49e4b04d7459a7eab2

# Inspect the contents of the above item
children <- item_list_children('5669a79ee4b08895842a1d47')

sapply(children, function(child) child$title)
#>  [1] "Select Regional Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                       
#>  [2] "Select Climate and Water Balance Model Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
#>  [3] "Select Hydrologic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                     
#>  [4] "Select Climate Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                        
#>  [5] "Select Soil Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                           
#>  [6] "Select Land Cover Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                     
#>  [7] "Select Water Use Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                      
#>  [8] "Select Hydrologic Modification Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"        
#>  [9] "Select Chemical Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                       
#> [10] "Select Population Infrastructure Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"      
#> [11] "Select Best Management Practices Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"      
#> [12] "Select Topgraphic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"                     
#> [13] "Select Geologic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"

item_get(children[[1]])
#> <ScienceBase Item> 
#>   Title: Select Regional Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States
#>   Creator/LastUpdatedBy:      / 
#>   Provenance (Created / Updated):  2016-07-12T20:51:42Z / 2023-08-02T15:58:37Z
#>   Children: TRUE
#>   Item ID: 5785585ee4b0e02680bf2fd6
#>   Parent ID: 5669a79ee4b08895842a1d47

sbtools uses an sbitem S3 object that is a list containing the sbjson associated with the item in question.


item <- item_get(children[[1]])

class(item)
#> [1] "sbitem"

class(unclass(item))
#> [1] "list"

Much of sbtools is intended to be used after authentication. This part of sbtools is changing in Winter, 2023-2024 as ScienceBase transitions for password-based authentication to two factor and token based authentication. This next section was rendered with the author’s () private credentials.

The old way used authenticate_sb() with a username and password. The password could be cached using the keyring package.

authenticate_sb(Sys.getenv("sb_user"))
#> authenticate_sb will stop working in favor of initialize_sciencebase_session when sciencebase turns off username and password login

my_home_item <- user_id()

new_item <- item_create(title = 'new test item', parent_id = my_home_item)

test.txt <- file.path(tempdir(), 'test.txt')

writeLines(c('this is','my data file'), test.txt)

item_append_files(new_item, test.txt)
#> <ScienceBase Item> 
#>   Title: new test item
#>   Creator/LastUpdatedBy:     dblodgett@usgs.gov / dblodgett@usgs.gov
#>   Provenance (Created / Updated):  2023-12-19T16:20:06Z / 2023-12-19T16:20:07Z
#>   Children: FALSE
#>   Item ID: 6581c2b6d34e38c885a5d07e
#>   Parent ID: 4f7afec1e4b0b2f259355f30

item_list_files(new_item)$fname
#> [1] "test.txt"

item_rm(new_item)

unlink(test.txt)

# restart or clean session to reauthenticate differently
sbtools:::clean_session()

The new way uses initialize_sciencebase_session() to open a browser window. Once logged in, you can get a token from the user drop down in the upper right. For this example, that token has been saved as an environment variable.

If the token has been entered previously and is still valid, it will not be requested again.

user <- Sys.getenv("sb_user") # this should be your science base user id

initialize_sciencebase_session(user)
#> [1] TRUE

my_home_item <- user_id()

new_item <- item_create(title = 'new test item', parent_id = my_home_item)

test.txt <- file.path(tempdir(), 'test.txt')

writeLines(c('this is','my data file'), test.txt)

item_append_files(new_item, test.txt)
#> <ScienceBase Item> 
#>   Title: new test item
#>   Creator/LastUpdatedBy:     dblodgett@usgs.gov / dblodgett@usgs.gov
#>   Provenance (Created / Updated):  2023-12-19T16:20:15Z / 2023-12-19T16:20:16Z
#>   Children: FALSE
#>   Item ID: 6581c2bfd34e38c885a5d082
#>   Parent ID: 4f7afec1e4b0b2f259355f30

item_list_files(new_item)$fname
#> [1] "test.txt"

item_rm(new_item)

unlink(test.txt)