add jupyter launch child doc

07-using_platforms_modules.Rmd

@@ -1,3 +1,7 @@
+```{r echo = FALSE}
+knitr::opts_chunk$set(out.width = "100%")
+```
+
 # Using programming platforms on AnVIL
 
 Modules about opening, touring, and closing AnVIL platforms
@@ -13,6 +17,16 @@ cow::borrow_chapter(
 )
 ```
 
+## Launching Jupyter
+
+:::: {.borrowed_chunk}
+```{r, echo = FALSE, results='asis'}
+cow::borrow_chapter(
+  doc_path = "child/_child_jupyter_launch.Rmd",
+  repo_name = "jhudsl/AnVIL_Template"
+)
+```
+::::
 
 ## Video overview on using Galaxy
 
@@ -25,31 +39,36 @@ cow::borrow_chapter(
 
 ## Starting Galaxy
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_galaxy_start.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::
 
 ## Navigating Galaxy
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_galaxy_navigate.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::
 
 ## Deleting Galaxy
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_galaxy_delete.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
-
+::::
 
 ## Video overview on using RStudio
 
@@ -62,36 +81,44 @@ cow::borrow_chapter(
 
 ## Launching RStudio
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_rstudio_launch.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::
 
 ## Touring RStudio
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_rstudio_tour.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::
 
 ## Pausing RStudio
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_rstudio_pause.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::
 
 ## Deleting RStudio
 
+:::: {.borrowed_chunk}
 ```{r, echo = FALSE, results='asis'}
 cow::borrow_chapter(
   doc_path = "child/_child_rstudio_delete.Rmd",
   repo_name = "jhudsl/AnVIL_Template"
 )
 ```
+::::

08-student_modules.Rmd

@@ -1,3 +1,7 @@
+```{r echo = FALSE}
+knitr::opts_chunk$set(out.width = "100%")
+```
+
 # Student instructions
 
 Modules aimed at students in a course or workshop.
@@ -48,6 +52,50 @@ cow::borrow_chapter(
 ```
 ::::
 
+## Student instructions for launching Jupyter
+
+The module below is specially customized for students, allowing you to give more specific instructions on the settings for their Jupyter environment.  There are several other general purpose modules that may also be useful for students (e.g. Pausing Jupyter, Deleting Jupyter) that can be found in other chapters of this book.
+
+The following instructions can be customized by setting certain variables before running `cow::borrow_chapter()`. Developers should create these variables as a list `AnVIL_module_settings`. The following variables can be provided:
+
+- `audience` = Defaults to `general`, telling them to use the default Jupyter settings. If `audience` is set to `student`, it gives more specific instructions.
+- `docker_image` = Optional, it will tell them how to set the image.
+- `startup_script` =  Optional, it will tell them how to set the script.
+
+### Using default Jupyter environment:
+
+:::: {.borrowed_chunk}
+```{r, echo = FALSE, results='asis'}
+# Specify variables
+AnVIL_module_settings <- list(
+  audience = "student"
+)
+
+cow::borrow_chapter(
+  doc_path = "child/_child_jupyter_launch.Rmd",
+  repo_name = "jhudsl/AnVIL_Template"
+)
+```
+::::
+
+### Using custom Jupyter environment:
+
+:::: {.borrowed_chunk}
+```{r, echo = FALSE, results='asis'}
+# Specify variables
+AnVIL_module_settings <- list(
+  audience = "student",
+  docker_image = "example docker",
+  startup_script = "example startup script"
+)
+
+cow::borrow_chapter(
+  doc_path = "child/_child_jupyter_launch.Rmd",
+  repo_name = "jhudsl/AnVIL_Template"
+)
+```
+::::
+
 ## Student instructions for launching RStudio
 
 The module below is specially customized for students, allowing you to give more specific instructions on the settings for their RStudio environment.  There are several other general purpose modules that may also be useful for students (e.g. Pausing RStudio, Deleting RStudio) that can be found in other chapters of this book.

child/_child_jupyter_launch.Rmd

@@ -0,0 +1,210 @@
+```{r, include = FALSE}
+if (!exists("AnVIL_module_settings")) {
+  AnVIL_module_settings <- list(
+    audience = "general"
+    )
+} else if (is.null(AnVIL_module_settings$audience)) {
+  AnVIL_module_settings$audience = "general"
+}
+```
+
+```{r, include=FALSE}
+# settings for warning about controlling costs
+# default
+AnVIL_module_settings$text <- "AnVIL is very versatile and can scale up to use very powerful cloud computers. It's very important that you select a cloud computing environment appropriate to your needs to avoid runaway costs.  If you are uncertain, start with the default settings; it is fairly easy to increase your compute resources later, if needed, but harder to scale down."
+
+
+if (AnVIL_module_settings$audience == "student") {
+  AnVIL_module_settings$text <- "AnVIL is very versatile and can scale up to use very powerful cloud computers. It's very important that you select the cloud computing environment described here to avoid runaway costs."
+}
+```
+
+:::{.warning}
+`r AnVIL_module_settings$text`
+:::
+
+`r if( !(AnVIL_module_settings$audience == "student") ) {'Note that, in order to use Jupyter, you must have access to a Terra Workspace with permission to compute (i.e. you must be a "Writer" or "Owner" of the Workspace).'}`
+
+1. Open Terra - use a web browser to go to [`anvil.terra.bio`](https://anvil.terra.bio/)
+
+1. In the drop-down menu on the left, navigate to "Workspaces". Click the triple bar in the top left corner to access the menu. Click "Workspaces".
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of Terra drop-down menu.  The "hamburger" button to extend the drop-down menu is highlighted, and the menu item "Workspaces" is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g117989bd49c_0_150")
+    ```
+
+1. Click on the name of your Workspace. You should be routed to a link that looks like: `https://anvil.terra.bio/#workspaces/<billing-project>/<workspace-name>`.
+
+1. Click on the cloud icon on the far right to access your Cloud Environment options.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of a Terra Workspace. The cloud icon to create a new cloud environment is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g14ea2db115d_0_22")
+    ```
+
+1. In the dialogue box, click the "Settings" button under Jupyter.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of the Cloud Environment Details dialogue box. The Settings button under Jupyter is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g14ea2db115d_0_18")
+    ```
+
+1. You will see some configuration options for the Jupyter cloud environment, and a list of costs because it costs a small amount of money to use cloud computing.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of the Jupyter Cloud Environment dialogue box. The cost to run the environment is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_0")
+    ```
+
+```{r, include=FALSE}
+# settings for instructions about using the default Jupyter configuration
+
+# default settings
+AnVIL_module_settings$include <- TRUE
+AnVIL_module_settings$text <- '1. Configure any settings you need for your cloud environment.  If you are uncertain about what you need, the default configuration is a reasonable, cost-conservative choice.  It is fairly easy to increase your compute resources later, if needed, but harder to scale down. Scroll down and click the "CREATE" button when you are satisfied with your setup.'
+
+# for students - exclude this, they get more specific instructions below
+if (AnVIL_module_settings$audience == "student") {
+  AnVIL_module_settings$include <- FALSE
+}
+```
+
+```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+cat(AnVIL_module_settings$text)
+```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of the Jupyter Cloud Environment dialogue box. The "CREATE" button is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g14ea2db115d_0_41")
+    ```
+
+```{r, include=FALSE}
+# settings for instructions about using a custom docker image
+
+# default settings
+AnVIL_module_settings$include <- FALSE
+AnVIL_module_settings$text <- NULL
+
+# for students
+if (AnVIL_module_settings$audience == "student") {
+
+  # if there is a custom docker image, include these instructions
+  if ( !is.null(AnVIL_module_settings$docker_image) ) {
+    AnVIL_module_settings$include <- TRUE
+    AnVIL_module_settings$text <- '1. Under "Application configuration" you will see a dropdown menu.  Choose "Custom Environment".  Then copy the following link into "Container image" textbox:'
+  }
+  # otherwise exclude these instructions
+  else {
+    AnVIL_module_settings$include <- FALSE
+  }
+}
+```
+
+```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+cat(AnVIL_module_settings$text)
+```
+
+    ```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+     cat(paste("`", AnVIL_module_settings$docker_image, "`"))
+    ```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of the Jupyter Cloud Environment "Application configuration" dropdown. The option "Custom Environment" is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_8")
+    ```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of the Jupyter Cloud Environment dialog box. "Custom Environment" has been selected in the "Application configuration" dropdown menu, and the "Container image" textbox is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_14")
+    ```
+
+```{r, include=FALSE}
+# settings for instructions about using a custom startup script
+# default settings
+AnVIL_module_settings$include <- FALSE
+AnVIL_module_settings$text <- NULL
+
+# for students
+if (AnVIL_module_settings$audience == "student") {
+
+  # if there is a custom docker image, include this slide
+  if ( !is.null(AnVIL_module_settings$startup_script) ) {
+    AnVIL_module_settings$include <- TRUE
+    AnVIL_module_settings$text <- '1. Under "Startup script" you will see textbox.  Copy the following link into the box:'
+  }
+  # otherwise exclude this slide
+  else {
+    AnVIL_module_settings$include <- FALSE
+  }
+}
+```
+
+```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+cat(AnVIL_module_settings$text)
+```
+
+    ```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+     cat(paste("`", AnVIL_module_settings$startup_script, "`"))
+    ```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of the Jupyter Cloud Environment customization dialogue box. The textbox labeled "Startup script" is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_48")
+    ```
+
+```{r, include=FALSE}
+# student instructions to click "Create"
+# default settings (non-students get different instructions)
+AnVIL_module_settings$include <- FALSE
+AnVIL_module_settings$text <- NULL
+# for students
+if (AnVIL_module_settings$audience == "student") {
+      AnVIL_module_settings$include <- TRUE
+    AnVIL_module_settings$text <- '1. Leave everything else as-is. To create your Jupyter Cloud Environment, scroll down and click the "CREATE" button.'
+
+}
+```
+
+```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+cat(AnVIL_module_settings$text)
+```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of the Jupyter Cloud Environment dialogue box. The "CREATE" button is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g14ea2db115d_0_41")
+    ```
+
+1. The dialogue box will close and you will be returned to your Workspace.  You can see the status of your cloud environment by hovering over the Jupyter icon.  It will take a few minutes for Terra to request computers and install software.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of a Terra Workspace. The hovertext for the Jupyter icon is highlighted, and indicates that the status of the environment is "Creating".'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_60")
+    ```
+
+1. When your environment is ready, its status will change to "Running".  Click on the "ANALYSES" tab to create or open a Jupyter Notebook.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of a Terra Workspace. The hovertext for the Jupyter icon is highlighted, and indicates that the status of the environment is "Running".  The ANALYSES tab is also highlighted'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_66")
+    ```
+
+1. From the ANALYSES tab, you can click on the name of an existing Jupyter Notebook to view and launch it, or click the "START" button to create a new Notebook.
+
+    ```{r, echo=FALSE, fig.alt='Screenshot of Terra Workspace with the "ANALYSES" tab selected and highlighted.  The page shows a list of Jupyter Notebooks.  The Notebook names and the START button are highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_73")
+    ```
+
+```{r, include=FALSE}
+# settings for instructions about opening a Jupyter Notebook
+
+# default settings
+AnVIL_module_settings$include <- TRUE
+AnVIL_module_settings$text <- '1. Clicking on a Notebook name will open a static preview of the Notebook.  To edit and run the Notebook, click the "OPEN" button.'
+
+# for students - exclude this, they may not be launching a Notebook right away.  Individual books / courses can give more specific instructions about which Notebook to open and when to open it.
+if (AnVIL_module_settings$audience == "student") {
+  AnVIL_module_settings$include <- FALSE
+}
+```
+
+```{r, echo=FALSE, results='asis', eval=AnVIL_module_settings$include}
+cat(AnVIL_module_settings$text)
+```
+
+    ```{r, echo=FALSE, eval=AnVIL_module_settings$include, fig.alt='Screenshot of a preview of a Jupyter Notebook in a Terra Workspace.  The "OPEN" button is highlighted.'}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1-IU5l40UxmpoBqFimSUmT1PNEUij2UnXMslOsiG5ncE/edit#slide=id.g25442045568_0_82")
+    ```
+
+```{r, include = FALSE}
+AnVIL_module_settings <<- NULL
+```

child/_child_rstudio_launch.Rmd

@@ -41,7 +41,7 @@ ottrpal::include_slide("https://docs.google.com/presentation/d/1a35Mb8f0M-bQkBcH
 ottrpal::include_slide("https://docs.google.com/presentation/d/1a35Mb8f0M-bQkBcHa1cyQc6YxXoBLtExCz96nv08vkA/edit#slide=id.g14ea2db115d_0_22")
     ```
 
-1. In the dialogue box, click the "Settings" button under RStudio
+1. In the dialogue box, click the "Settings" button under RStudio.
 
     ```{r, echo=FALSE, out.width = '100%', fig.alt='Screenshot of the Cloud Environment Details dialogue box. The Settings button under RStudio is highlighted.'}
 ottrpal::include_slide("https://docs.google.com/presentation/d/1a35Mb8f0M-bQkBcHa1cyQc6YxXoBLtExCz96nv08vkA/edit#slide=id.g14ea2db115d_0_18")