markdown source builds

Auto-generated via {sandpaper}
Source  : 7c5cd2b
Branch  : main
Author  : Pat Bills <billspat@users.noreply.github.com>
Time    : 2023-06-30 13:45:18 +0000
Message : Merge pull request #3 from billspat/2-plotting

closes #2

md5sum.txt

@@ -7,7 +7,7 @@
 "episodes/rstudio-ondemand.Rmd" "70648183bdfe8ad8bdf65a20e2fb953d" "site/built/rstudio-ondemand.md" "2023-06-28"
 "episodes/managing-r-env-packages.Rmd" "ddab4573b923cf6260e68f9f7f0b9a13" "site/built/managing-r-env-packages.md" "2023-06-29"
 "episodes/parallelizing-r-code.Rmd" "c43f3d5d334caebbd643855a3ba39241" "site/built/parallelizing-r-code.md" "2023-06-28"
-"episodes/r-command-line.Rmd" "bd801f0f813de8fd54f2e797779f2902" "site/built/r-command-line.md" "2023-06-28"
+"episodes/r-command-line.Rmd" "7c0bfd10a86ac7adafd7a8d831ec6a44" "site/built/r-command-line.md" "2023-06-30"
 "episodes/r-slurm-jobs.Rmd" "0cc5abe786f9bdaeef672e704887852f" "site/built/r-slurm-jobs.md" "2023-06-28"
 "instructors/instructor-notes.md" "cae72b6712578d74a49fea7513099f8c" "site/built/instructor-notes.md" "2023-05-02"
 "learners/reference.md" "320e2aee7d166827e4e0c6caea1f2019" "site/built/reference.md" "2023-06-28"

r-command-line.md

@@ -7,6 +7,7 @@ exercises: 2
 :::::::::::::::::::::::::::::::::::::: questions 
 
 - How do you run R on the HPCC through the command line?
+- How can I create plots when I'm not using a graphical interface?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -292,13 +293,80 @@ for(i in 1:n) {
 
 ::::::::::::::::::::::::::::::::::::::::::
 
+## Plotting with the command line
+
+You may wonder how you might run a plot using the terminal interface?   For most terminals, if you plot with the command line version of R, either nothing happens or there is an error message.  It may work on some terminals, if X11 Linux graphical interface is installed and the terminal is an X11-capable (for example on MacOS is 'Quartz' is installed, a new windows will appear).  However when running in 'batch' mode using the cluster (described in the next session), there is no interface at all. 
+
+There are the following techniques for handling plots when using R on the command line on HPCC
+
+- split your code into computation and presentation sections:  run computation section using CLI/Batch on HPC, and after the computation is complete, save the output to be read into visualization code that you run on a machine with a graphic user interface (OnDemand Rstudio, or even your laptop)
+- capture all output to a file using commands like PDF()
+- as part of your script, create an RMarkdown file that includes plotting (or other output), and use the [render](https://rmarkdown.rstudio.com/docs/reference/render.html) command in Rmarkdown to PDF or other format to be review later
+
+We'll describe the method to capture output into a PDF here.   
+
+A sample script that uses the `pdf` function to capture plots looks like this: 
+
+```r
+plotfile = 'testplots.pdf'
+pdf(plotfile)
+
+plot(iris$Petal.Length, iris$Petal.Width, pch=21, bg=c("red","green3","blue")[unclass(iris$Species)], main="Edgar Anderson's Iris Data")
+
+dev.off()
+```
+
+For much nore details about using this techinque, see 
+[Chapter 14 Output for Presentation](https://r-graphics.org/chapter-output) of Winston Chang's **R Graphics Cookbook** 
+
+Once you run the script and save the PDFs, the next challenge is to view them because, again, the terminal does not have the GUI to view PDFs.  
+
+You could
+
+ - download the PDF to your computer from the terminal using OnDemand file browser (or the MobaXterm client's file browser)
+ - open with the OneDemand Rstudio. 
+
+
+
+:::::::::::::::::::::::::::::::: challenge
+
+One of the challenges with running scripts repeatedly is that it will overwrite the plot file with the same name.  Modify the plotting script above that accepts a command line parameter for the the name of the PDF file.  BONUS: how would you handle the case where there was no command line argument sent?
+
+:::::::::::::::::::::::: solution
+
+```r
+args <- commandArgs(trailingOnly = TRUE)
+
+# check if there was at least 1 arg
+if length(args) >= 1 {
+
+   #assume the arg is a PDF file name, and use that to capture plots
+   plotfile = args[1]
+   pdf(plotfile)
+
+}
+
+# if not argument is sent, PDF capture is not enabled and the plot will display
+
+plot(iris$Petal.Length, iris$Petal.Width, pch=21, bg=c("red","green3","blue")[unclass(iris$Species)], main="Edgar Anderson's Iris Data")
+
+dev.off()
+
+```
+:::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::::
+
+
+
 ::::::::::::::::::::::::::::::::::::: keypoints 
 
 - Use `module spider R/<version>` to learn how to load a version of R on the HPCC
 - Run `R` from the command line to start an interactive R console
 - Use the `--vanilla` option to ignore extra configuration files
 - Run `Rscript` to run an R script
 - Use `commandArgs` to parse command line arguments in an R script
+- Use `pdf()` to capture plotting into a PDF file
 
 ::::::::::::::::::::::::::::::::::::::::::::::::