Sbtools modify lesson #271

lindsayplatt · 2017-07-07T15:21:42Z

Fixes #115.

Known issues are all called out in the lesson. The first and fourth are the only ones that this lesson is waiting on to be complete.

adding multiple items at once does not behave as expected, items_create ignores multiple parents DOI-USGS/sbtools#242
item_upload_create default name is the first file, item_upload_create should support an arg for "title" DOI-USGS/sbtools#49
item_upload_create doesn't always work for multiple complex files, item_upload_create only posts the first file DOI-USGS/sbtools#39
Using item_upsert. item_upsert never updates DOI-USGS/sbtools#239 & could item_upsert be more flexible or rigid? DOI-USGS/sbtools#240

…btools-modify

aappling-usgs

added a bunch of comments, but many of them are conversational or optional. looks good, especially given how many sbtools foibles you had to deal with for this lesson

aappling-usgs · 2017-07-13T22:49:29Z

content/usgs-packages/sbtools_Modify.Rmd

+sbtools::authenticate_sb(un, pw)
+```
+
+All the functions used here will have either `parent_id` or `sb_id` as the first argument. `parent_id` is looking for information on the location to create a new item or folder. Sometimes this defaults to your user account, but can be overridden with an object of class `sbitem` or the ScienceBase ID as a character value. The `sb_id` argument does not have a default and is looking for an object of class `sbitem` or the ID of the ScienceBase item you are modifying. 


"or the ID of the ScienceBase" -> "or the character ID of the ScienceBase"

aappling-usgs · 2017-07-13T22:50:26Z

content/usgs-packages/sbtools_Modify.Rmd

+
+All the functions used here will have either `parent_id` or `sb_id` as the first argument. `parent_id` is looking for information on the location to create a new item or folder. Sometimes this defaults to your user account, but can be overridden with an object of class `sbitem` or the ScienceBase ID as a character value. The `sb_id` argument does not have a default and is looking for an object of class `sbitem` or the ID of the ScienceBase item you are modifying. 
+
+In these functions, you might notice some `parent_id` arguments defaulting to `user_id()`. This is a function that returns the id for your ScienceBase account, and is frequently used when creating items. It can also be useful with the `item_list_*` functions taught in the previous lesson to see what items are saved under your account. If you are not authenticated, this will return an error.


"id for your ScienceBase account" -> "id for your ScienceBase account's home item"

aappling-usgs · 2017-07-13T22:59:14Z

content/usgs-packages/sbtools_Modify.Rmd

+* `item_create`
+* `items_create`
+
+First, we will create a folder named "usgs-r-pkgs-test". Make this folder "top-level" under your user account by using the default for the `parent_id` argument, `user_id()`. Then, use `item_get` (introduced in the previous lesson) to see if the folder was actually created. It should return an error if the item does not exist.


is there a link available yet for "the previous lesson"?

oops - I'll add the link here, just won't be functional until #272 is merged

aappling-usgs · 2017-07-13T23:01:05Z

content/usgs-packages/sbtools_Modify.Rmd

+"usgs-r-pkgs-test" == item_get_parent(new_item)$title
+```
+
+Next, add three items at once. Nest the first two items under the new folder, and the last one as a top-level folder. Note that this currently does not do the expected behavior - it just puts everything under the new folder. This is a [known issue](https://github.com/USGS-R/sbtools/issues/242) in sbtools.


"sbtools" -> "sbtools"

aappling-usgs · 2017-07-13T23:08:53Z

content/usgs-packages/sbtools_Modify.Rmd

+  sapply(add_mult, function(item) item_get_parent(item)$title)
+```
+
+If you want to confirm with your own eyes, navigate to your user account. You should see two items: "top-level item" and the folder "usgs-r-pkgs-test" with 3 child items named "single item", "item 1", and "item 2". **AGAIN, "top-level item" will not actually be top-level until [this issue](https://github.com/USGS-R/sbtools/issues/242) has been fixed, so the third item will return FALSE for the second verification step.**


"navigate to your user account" got me wishing for a link. i don't see a url that does it by default, but you can call

# eval=FALSE browseURL(item_get(sb_id=user_id())$link$url)

and then log in interactively in your browser if needed. what do you think - is adding another line of R code more helpful or more distracting? do students need practice navigating by browser, too, such that this code is also denying them a chance to practice that skill? or is it convenient?

I'll do both to give people options!

aappling-usgs · 2017-07-13T23:42:34Z

content/usgs-packages/sbtools_Modify.Rmd

+Add identifiers to the item stored as the R object `test_item`. 
+
+```{r sbtools-identifier}
+item_update_identifier(test_item, scheme="example", type="sbtools", key="number 1")


not sure it's worth the time to find a truly meaningful example, but sciencebase has made efforts to offer some standardized schemes. see https://www.sciencebase.gov/vocab/categories?offset=0&max=10&parentId=528e99f7e4b05d51c7038afd. for example, here's an item defining the Coast Mole using three different standardized schemes: https://www.sciencebase.gov/catalog/item/547f2de3e4b09357f05fff3f

i don't see a huge need to change what you have written; just sharing what i just learned by poking around

How did you find the standardized schemes? It looks like it's just a search result. I tried searching "vocabularies" and got your result, but searching "terms" returned more options. Do you know the difference?

i don't remember exactly how i found the standardized schemes...i probably followed a link from the identifiers of a ScienceBase item, though it must have been some other item because the item mentioned above doesn't have a specific enough scheme link to be useful.

i also don't know the difference between vocabularies and terms. maybe a vocabulary is a collection of terms? there's evidence of deep thought and discussion on vocabularies and use cases for them at https://www.sciencebase.gov/catalog/item/550c9bc2e4b02e76d759d7e0...

and that's all i know for now. if we wanted to dig deeper, looks like the authors at https://www.sciencebase.gov/catalog/item/5320a400e4b0224be0a97a18 (hey, luke!) would be good people to tap. and i'm sure blodgett and/or kreft knows a lot about this. but if we dug deeper, it would be out of curiosity rather than for the sake of this sbtools lesson, which i think is fine already.

OK, I'll put diving into that any further into my "rainy days" list :)

aappling-usgs · 2017-07-13T23:44:22Z

content/usgs-packages/sbtools_Modify.Rmd

+
+## Editing and removing your files
+
+In addition to updating ScienceBase items, `sbtools` has functions to edit files. You can rename, replace, or remove files within SB items. 


maybe "to edit files" -> "to manage files"? "edit" made me think of editing the contents rather than the location/metadata of the file

also updated the title of this section

aappling-usgs · 2017-07-13T23:45:04Z

content/usgs-packages/sbtools_Modify.Rmd

+* `item_replace_files`
+* `item_rm_files`
+
+To rename files of a ScienceBase item, you need to provide a vector of the file names and a vector of new file names in the same order. Try renaming the `books.json` file to `bookinfo.json` using the `item_rename_files` function.


how about, "provide a vector of the file names" -> "provide a vector of the file paths"?

are they really file paths? They should all be under the same item, so aren't you just giving the file names?

erm...yes. don't know why i was thinking that, sorry.

aappling-usgs · 2017-07-17T21:45:36Z

content/usgs-packages/sbtools_Modify.Rmd

+removed_item <- item_rm(moved_item)
+
+# verify that this no longer exists under the `new_folder`
+sapply(item_list_children(new_folder), function(item) item$title)


could alternatively use identifier_exists here if desired

aappling-usgs · 2017-07-17T21:46:42Z

content/usgs-packages/sbtools_Modify.Rmd

+In this lesson, we've added a few more items: "usgs-r-pkgs-test" folder and "top-level" item. Let's remove these to get back to our original state. We already removed the "books.json" item, so remove the "usgs-r-pkgs-test" folder and the "top-level" item which were saved as the `sbitems` `new_folder` and `add_mult[[3]]`, respectively. Note: the item saved in R as `new_folder` has child items, and you need to set the argument `recursive` to `TRUE` in order to remove an item that has children. 
+
+```{r sbtools-reset-state}
+item_rm(new_folder, recursive = TRUE)


good idea for a final activity!

lindsayplatt · 2017-07-18T18:28:42Z

Merging since it has been approved already.

Lindsay Carr added 19 commits July 3, 2017 16:42

first part of modifying sb

78d87d9

self-reminder for user_id()

ca31e60

update language about item_ vs items_

ad55b43

upload and append files

5af25f6

file uploads

39670de

more "modify" content

d0eff05

more cleanup for modify

389e545

better words!

bf9a3ed

next section of word-improving

54f9de0

even more updates!

147aae8

user_id() info

75000c6

item_udpate content

4f06938

item_replace_files content

f8a5fb5

note about creating multiple items at once bug

0535964

more touch ups

77578e5

getting authentication to work to eval each code chunk + cleanup

658fa22

additional cleanup

0645174

Merge branch 'master' of github.com:USGS-R/training-curriculum into s…

ae4a0fd

…btools-modify

added link for browseCategories to discovery page

e70ebe3

lindsayplatt requested a review from aappling-usgs July 7, 2017 15:22

aappling-usgs approved these changes Jul 17, 2017

View reviewed changes

aappling-usgs mentioned this pull request Jul 17, 2017

sbtools get #272

Merged

updates from aappling feedback

53684fb

lindsayplatt merged commit 8e193bf into USGS-R:master Jul 18, 2017

lindsayplatt deleted the sbtools-modify branch August 9, 2017 22:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sbtools modify lesson #271

Sbtools modify lesson #271

lindsayplatt commented Jul 7, 2017

aappling-usgs left a comment

aappling-usgs Jul 13, 2017

aappling-usgs Jul 13, 2017

aappling-usgs Jul 13, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 13, 2017

aappling-usgs Jul 13, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 13, 2017

aappling-usgs Jul 13, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 18, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 18, 2017

aappling-usgs Jul 13, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 13, 2017

lindsayplatt Jul 18, 2017

aappling-usgs Jul 18, 2017

aappling-usgs Jul 17, 2017

aappling-usgs Jul 17, 2017

lindsayplatt commented Jul 18, 2017


		All the functions used here will have either `parent_id` or `sb_id` as the first argument. `parent_id` is looking for information on the location to create a new item or folder. Sometimes this defaults to your user account, but can be overridden with an object of class `sbitem` or the ScienceBase ID as a character value. The `sb_id` argument does not have a default and is looking for an object of class `sbitem` or the ID of the ScienceBase item you are modifying.

		In these functions, you might notice some `parent_id` arguments defaulting to `user_id()`. This is a function that returns the id for your ScienceBase account, and is frequently used when creating items. It can also be useful with the `item_list_*` functions taught in the previous lesson to see what items are saved under your account. If you are not authenticated, this will return an error.


		## Editing and removing your files

		In addition to updating ScienceBase items, `sbtools` has functions to edit files. You can rename, replace, or remove files within SB items.

Sbtools modify lesson #271

Sbtools modify lesson #271

Conversation

lindsayplatt commented Jul 7, 2017

aappling-usgs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lindsayplatt commented Jul 18, 2017