Author: dblodgett@usgs.gov
Date: 2023-11-17

# sbtools – getting started

#### dblodgett@usgs.gov

#### 2023-11-17

`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 Soil Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #>  [3] "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"
    #>  [4] "Select Hydrologic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #>  [5] "Select Climate Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #>  [6] "Select Water Use Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #>  [7] "Select Land Cover 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 Topgraphic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #> [11] "Select Geologic Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #> [12] "Select Best Management Practices Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States"
    #> [13] "Select Population Infrastructure 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 / 2025-06-25T14:35:21Z
    #>   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 <- get_username()

    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):  2025-07-11T18:21:09Z / 2025-07-11T18:21:09Z
    #>   Children: FALSE
    #>   Item ID: 68715615d4be026e1750f242
    #>   Parent ID: 4f7afec1e4b0b2f259355f30

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

    item_rm(new_item)

    unlink(test.txt)