sbtools – getting started

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

dblodgett@usgs.gov

2023-11-17

## 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 (dblodgett@usgs.gov) private credentials.

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

NOTE: This method no longer works and is shown here for reference with regard to old code and workflows.

authenticate_sb(Sys.getenv("sb_user"))

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)

item_list_files(new_item)$fname

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)

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):  2024-03-21T02:38:47Z / 2024-03-21T02:38:49Z
#>   Children: FALSE
#>   Item ID: 65fb9db7d34e64ff1548d13b
#>   Parent ID: 4f7afec1e4b0b2f259355f30

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

item_rm(new_item)

unlink(test.txt)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.