Merge pull request #237 from UBC-DSCI/review_installation

Review installation chapter

Author: ttimbers

_bookdown.yml

@@ -3,4 +3,4 @@ language:
   ui:
     chapter_name: "Chapter "
 delete_merged_file: true
-rmd_files: ["index.Rmd", "intro.Rmd", "reading.Rmd", "wrangling.Rmd", "viz.Rmd", "classification1.Rmd", "classification2.Rmd", "regression1.Rmd", "regression2.Rmd", "clustering.Rmd", "inference.Rmd", "jupyter.Rmd", "version-control.Rmd", "setup.Rmd", "references.Rmd"]
+rmd_files: ["index.Rmd", "intro.Rmd", "reading.Rmd", "wrangling.Rmd", "viz.Rmd", "classification1.Rmd", "classification2.Rmd", "regression1.Rmd", "regression2.Rmd", "clustering.Rmd", "inference.Rmd", "jupyter.Rmd", "version-control.Rmd", "setup.Rmd", "references.Rmd", "appendixA.Rmd"]

appendixA.Rmd

@@ -0,0 +1,27 @@
+\cleardoublepage
+
+```{r echo=FALSE, results='asis'}
+if(!knitr::is_latex_output()){
+  cat("# (APPENDIX) Appendix {-}")
+} else {
+  cat("\\appendix")
+}
+```
+
+# Download files from a JupyterHub for later local use {#appendixA}
+
+This section will help you
+save your work from the JupyterHub web-based platform to your own computer. 
+
+First, in JupyterHub, open a terminal by clicking "terminal" in the Launcher tab. 
+Next, type the following in the terminal to create a 
+compressed `.zip` archive for the work you are interested in downloading:
+
+```
+zip -r hub_folder.zip your_folder
+```
+
+After the compressing process is complete, right-click on `hub_folder.zip`
+in the JupyterHub file browser
+and click "Download". You should be able to use your computer's software to unzip
+the compressed folder by double-clicking on it. 

img/chapter_overview.001.jpeg

@@ -2,63 +2,52 @@
 
 ## Overview
 
-Throughout this book, we have assumed that you are working on a web-based platform
-(e.g., JupyterHub) that already has Jupyter, R, a number of R packages, and Git set up and ready to use. 
-In this chapter, you'll learn how to install all of that software on your own computer in case
-you don't have a preconfigured JupyterHub available to you.
+In this chapter, you'll learn how to install all of that software 
+needed to do this data science covered in this book on your own computer.
 
 ## Chapter learning objectives
 
 By the end of the chapter, readers will be able to:
 
-- install Git and the miniconda Python distribution
+- install the Git version control software
 - install and launch a local instance of JupyterLab with the R kernel
-- download files from a JupyterHub for later local use
-
 
 ## Installing software on your own computer
 
-In this section we will provide instructions for installing the software 
-required by this book on our own computer. 
-Given that installation instructions can vary widely based on the computer setup
+This section will provide instructions for installing the software required by 
+this book on our own computers. 
+Given that installation instructions can vary widely based on the computer setup,
 we have created instructions for multiple operating systems.
 In particular, the installation instructions below have been verified to work
 on a computer that:
 
-- runs one of the following operating systems: MacOS 10.15.X (Catalina); Ubuntu 20.04; Windows 10, version 2004.
+- runs one of the following operating systems: Ubuntu 20.04, macOS Big Sur (version 11.4.x or 11.5.x), Windows 10 Professional, Enterprise or Education (version 2004, 20H2, or 21H1).
 - can connect to networks via a wireless connection
 - uses a 64-bit CPU
 - uses English as the default language
 
-**For macOS users only:** Apple recently changed the default shell in the terminal to Zsh.
-However, the programs we need work better with the Bash shell. Thus, we recommend you change 
-the default shell to Bash by opening the terminal 
-([how to video](https://youtu.be/5AJbWEWwnbY)) and typing:
-
-```
-chsh -s /bin/bash
-```
-
-You will have to quit all instances of open terminals and then restart the 
-terminal for this to take effect.
-
 ### Git
 
-As shown in the version control chapter, Git is a very useful tool for version
-controlling your projects, as well as sharing your work with others.
+As shown in Chapter \@ref(Getting-started-with-version-control), 
+Git is a very useful tool for version controlling your projects, 
+as well as sharing your work with others. Here's how to install Git on 
+the following operating systems: 
 
 **Windows:** To install
-Git on Windows go to <https://git-scm.com/download/win> and download the windows 
-version of git. Once the download has finished, run the installer and accept 
+Git on Windows, go to <https://git-scm.com/download/win> and download the Windows 
+version of Git. Once the download has finished, run the installer and accept 
 the default configuration for all pages.
 
-**MacOS:** To install Git on Mac OS open the terminal and type the following command:
+**MacOS:** To install Git on Mac OS, 
+open the terminal ([how-to video](https://youtu.be/5AJbWEWwnbY)) 
+and type the following command:
 
 ```
 xcode-select --install
 ```
 
-**Ubuntu:** To install Git on Ubuntu open the terminal and type the following commands:
+**Ubuntu:** To install Git on Ubuntu, open the terminal 
+and type the following commands:
 
 ```
 sudo apt update
@@ -68,34 +57,37 @@ sudo apt install git
 
 ### Miniconda
 
-To run Jupyter notebooks on our computers we will need to install a program 
-similar to the one we used as our web-based platform. One such program is 
-JupyterLab. But JupyterLab relies on Python; we can install this via
+To run Jupyter notebooks on our computers, 
+we will need to install the web-based platform JupyterLab. 
+But JupyterLab relies on Python; we can install this via
 the [miniconda Python package distribution](https://docs.conda.io/en/latest/miniconda.html).
 
 **Windows:** To install miniconda on Windows, download 
-the [Python 3.8 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe). 
-Once the download has finished, run the installer and accept the default 
-configuration for all pages. After installation, you can open the Anaconda Prompt
+the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe). 
+Once the download has finished, run the installer 
+and accept the default configuration for all pages. 
+After installation, you can open the Anaconda Prompt
 by opening the Start Menu and searching for the program called 
-"Anaconda Prompt (miniconda3)". When this opens you will see a prompt similar to 
+"Anaconda Prompt (miniconda3)". 
+When this opens, you will see a prompt similar to 
 `(base) C:\Users\your_name`. 
 
 **MacOS:** To install miniconda on MacOS, download 
-the [Python 3.8 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg). 
+the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg). 
 After the download has finished, run the installer and accept the default 
 configuration for all pages.
 
 **Ubuntu:** To install miniconda on Ubuntu, we first download
-the [Python 3.8 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh). 
+the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh). 
 After the download has finished, open the terminal and execute the following 
 commands:
 
 ```
 bash path/to/Miniconda3-latest-Linux-x86_64.sh
 ```
 
-> Note: most often this file is downloaded to the Downloads directory, and thus the command will look like this:
+> Note: most often, this file is downloaded to the Downloads directory, 
+and thus the command will look like this:
 > ```
 > bash Downloads/Miniconda3-latest-Linux-x86_64.sh
 > ```
@@ -104,7 +96,7 @@ bash path/to/Miniconda3-latest-Linux-x86_64.sh
 The instructions for the installation will then appear:
 
 (1) Press Enter.
-(2) Once the licence agreement shows, you can press space scroll down, or press `q` to skip reading it.
+(2) Once the licence agreement shows, you can press space scroll down or press `q` to skip reading it.
 (3) Type `yes` and press enter to accept the licence agreement.
 (4) Press enter to accept the default installation location.
 (5) Type `yes` and press enter to instruct the installer to run `conda init`, which makes `conda` available from the terminal/shell.
@@ -117,42 +109,45 @@ Type the following into the Anaconda Prompt (Windows) or the terminal (MacOS and
 
 ```
 conda install -c conda-forge -y jupyterlab
-conda install -y nodejs=10.*
+conda install -y nodejs
 pip install --upgrade jupyterlab-git
-jupyter lab build
 ```
 
 To test that your JupyterLab installation is functional, you can type 
-`jupyter lab` into the Anaconda Prompt (Windows) or terminal (MacOS and Ubuntu) and press enter. This should open a new 
+`jupyter lab` into the Anaconda Prompt (Windows) 
+or terminal (MacOS and Ubuntu) and press enter. This should open a new 
 tab in your default browser with the JupyterLab interface. To exit out of 
 JupyterLab you can click `File -> Shutdown`, or go to the terminal from which 
-you launched JupyterLab, hold `Ctrl`, and press `c` twice.
+you launched JupyterLab, hold `Ctrl`, and press `C` twice.
 
 ### R and the IRkernel
 
-To have R available to you in JupyterLab, you will need to install the R programming language and the IRkernel. 
+To have R available to you in JupyterLab, 
+you will need to install the R programming language and the IRkernel R package. 
 To install these, type the following into 
 the Anaconda Prompt (Windows) or terminal (MacOS and Ubuntu):
 
 ```
-conda install -c conda-forge -y r-base
+conda install -c conda-forge -y r-base">=4.1.1"
 conda install -c conda-forge -y r-irkernel
 ```
 
 To improve the experience of using R in JupyterLab, we will add an extension 
 that allows us to setup keyboard shortcuts for inserting text.
-By default, this extension creates shortcuts for inserting two of the most common R 
-operators: `<-` and `%>%`. Type the following in the Anaconda Prompt (Windows)
+By default, 
+this extension creates shortcuts for inserting two of the most common R 
+operators: `<-` and `|>`. Type the following in the Anaconda Prompt (Windows)
 or terminal (MacOS and Ubuntu) and press  enter:
 
 ```
 jupyter labextension install @techrah/text-shortcuts
-jupyter lab build
 ```
 
 ### R packages
 
-To install the packages used in this book, type the following in the Anaconda Prompt (Windows) or terminal (MacOS and Ubuntu) and press enter:
+To install the packages used in this book, 
+type the following in the Anaconda Prompt (Windows) 
+or terminal (MacOS and Ubuntu) and press enter:
 
 ```
 conda install -c conda-forge -y \
@@ -166,6 +161,7 @@ conda install -c conda-forge -y \
   r-rsqlite \
   r-testthat \
   r-tidymodels \
+  r-tidyverse \
   r-tinytex \
   unixodbc
 ```
@@ -175,10 +171,23 @@ conda install -c conda-forge -y \
 To be able to render `.ipynb` files to `.pdf` you need to install a LaTeX 
 distribution. These can be quite large, so we will opt to use `tinytex`, a 
 light-weight cross-platform, portable, and easy-to-maintain LaTeX distribution 
-based on TeX Live. To install it open JupyterLab by typing `jupyter lab` 
+based on TeX Live. 
+
+**MacOS:** To install `tinytex` 
+we need to make sure that `/usr/local/bin` is writable. 
+To do this, type the following in the terminal:
+
+```
+sudo chown -R $(whoami):admin /usr/local/bin
+```
+
+> *Note: You might be asked to enter your password during installation.*
+
+**All operating systems:** 
+To install LaTeX open JupyterLab by typing `jupyter lab` 
 in the Anaconda Prompt (Windows) or terminal (MacOS and Ubuntu) and press enter.
 Then from JupyterLab open an R console and type the commands listed below and 
-press Shift + enter to install `tinytex`:
+press `Shift` + `enter` to install `tinytex`:
 
 ```
 tinytex::install_tinytex()
@@ -203,19 +212,24 @@ tinytex::tlmgr_install(c("eurosym",
                          "upquote"))
 ```
 
-## Moving files to your computer
-This section will help you
-save your work from the JupyterHub web-based platform to your own computer. 
-
-First in JupyterHub, open a terminal by clicking "terminal" in the Launcher tab. 
-Next, type the following in the terminal to create a 
-compressed `.zip` archive for the work you are interested in downloading:
+**Ubuntu:** 
+To append the TinyTex executables to our `PATH` we need to edit our `.bashrc file`. 
+The TinyTex executables are usually installed in `~/bin`. 
+Thus, add the lines below to the bottom of your `.bashrc` file 
+(which you can open by `nano ~/.bashrc` and save the file:
 
 ```
-zip -r hub_folder.zip your_folder
+# Append TinyTex executables to the path
+export PATH="$PATH:~/bin"
 ```
 
-After the compressing process is complete, right-click on `hub_folder.zip`
-in the JupyterHub file browser
-and click "Download". You should be able to use your computer's software to unzip
-the compressed folder by double-clicking on it. 
+> Note: If you used `nano` to open your `.bashrc` file, 
+follow the keyboard shortcuts at the bottom of the nano text editor 
+to save and close the file.
+
+## Finishing up installation
+
+It is good practice to restart all the programs you used when installing this
+software stack before you proceed to doing your data analysis.
+This will ensure all the software and settings you put in place are 
+correctly sourced. This includes JupyterLab, terminal or Anaconda Prompt.