using_jupyter_notebooks.Rmd

---
title: "Using Jupyter Notebooks and Binder"
author: "Clarke Iakovakis"
output: 
  html_document:
    df_print: paged
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
    toc_depth: 2
---

```{r setup, include = FALSE, echo = FALSE}
knitr::opts_chunk$set(cache = TRUE, eval = FALSE)
```

# Binder link to this notebook:
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ciakovx/ciakovx.github.io/master?filepath=using_jupyter_notebooks.ipynb)

<https://mybinder.org/v2/gh/ciakovx/ciakovx.github.io/master?filepath=using_jupyter_notebooks.ipynb>


This brief notebook provides an introduction to Jupyter Notebooks and Binder to prepare you for the course.

# Licensing

This walkthrough is distributed under a [Creative Commons Attribution 4.0 International (CC BY 4.0) License](https://creativecommons.org/licenses/by/4.0/)


# Binder

[The Binder Project](https://mybinder.readthedocs.io/) is an open community that makes it possible to create sharable, interactive, reproducible environments that can be shared and used by many remote users. It is powered by [BinderHub](https://github.com/jupyterhub/binderhub), which is an open-source tool that deploys the Binder service in the cloud. 

We are using Binder to launch interactive Jupyter Notebooks. This will allow you to execute R code and use R packages that are installed and run remotely (in the cloud) rather than your  local computer. This will help with various installation issues that go along with using R and R Studio. Furthermore, by interacting with R in these notebooks, you will be able to execute code that I have already written, and see explanations of it first hand. 
In addition, as described below, it allows text to be weaved with executable code. 

It is also possible to launch R Studio and Python environments using Binder, but we are not doing that for this class. See <https://mybinder.readthedocs.io/en/latest/examples.html> for interesting Binder repositories from around the web.

Each Jupyter Notebook we use in these sessions will include a **launch binder** badge like that at the top of this page. That will launch the specific Jupyter Notebook and allow you to run it. Please note that none of the changes you make will be saved. If you do make changes or notes, you will need to download the notebook to your own computer by clicking **File > Download as > Notebook (.ipynb)**. 

# Jupyter 

## Project Jupyter

[Project Jupyter](https://jupyter.org/about) is a non-profit, open-source project, born out of the [IPython Project](https://ipython.org/) in 2014 as it evolved to support interactive data science and scientific computing across all programming languages. It is developed in the open on GitHub, through the consensus of the Jupyter community.

## Jupyter Notebooks

According to the [Jupyter help documentation](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.html), the Jupyter Notebook is an interactive computing environment that enables users to author notebook documents that include: - Live code - Interactive widgets - Plots - Narrative text - Equations - Images - Video. 

Notebook documents contain the inputs and outputs of an interactive session as well as narrative text that accompanies the code but is not meant for execution. Rich output generated by running code, including HTML, images, video, and plots, is embedded in the notebook, which makes it a complete and self-contained record of a computation.

Notebook files have a `.ipynb` extension.

Jupyter Notebooks are often run in the [Anaconda](https://docs.anaconda.com/anaconda/install/) software and served locally on your own computer. However, as described above, we are interacting with it in the cloud using Binder. 

## Kernels

A `kernel` is a program that runs code in Jupyter Notebooks. For each notebook document that a user opens, the application starts a kernel that runs the code for that notebook. This particular Jupyter Notebook is running an `R` kernel, which allows us to write and execute R code. 

A number of other kernels are available for Jupyter Notebooks, including `Python`, `C++`, `SQL`, and [many more](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). You can try some of these without installing Anaconda by visiting the [Project Jupyter](https://jupyter.org/try) website. You can see available kernels in the Jupyter Notebook by navigating to the menu at the top and selecting **Kernel > Change Kernel**. See also below section on **Session expiration**.

## Notebook Interface

When you create a new notebook document, you will be presented with the notebook name, a menu bar, a toolbar and an empty code cell.

**Notebook name:** The name displayed at the top of the page, next to the Jupyter logo, reflects the name of the `.ipynb` file. 

**Menu bar:** The menu bar presents different options that may be used to manipulate the way the notebook functions.

**Toolbar:** The tool bar gives a quick way of performing the most-used operations within the notebook, by clicking on an icon.

**Code cell:** the default type of cell; read on for an explanation of cells.

## Structure of a notebook document

The notebook consists of a sequence of cells. A cell is a text input field, and its contents can be executed by using `Shift-Enter`, or by clicking either the “Play” button the toolbar, or Cell, Run in the menu bar. The execution behavior of a cell is determined by the cell’s type. There are three types of cells: code cells, markdown cells, and raw cells. Every cell starts off being a code cell, but its type can be changed by using a drop-down on the toolbar (which will be “Code”, initially), or via keyboard shortcuts.

### Code cells

A code cell allows you to edit and write new code, with full syntax highlighting and tab completion. Since the kernel for our Notebook is R, all code cells are configured to run R code. 

When a code cell is executed, code that it contains is sent to the kernel associated with the notebook. The results that are returned from this computation are then displayed in the notebook as the cell’s output. 

### Markdown

Jupyter uses the [Markdown](https://www.markdownguide.org/) language for drafting text. I have already done this, so you don't need to learn or know Markdown to understand this course. If you wish to learn more about using Markdown in Jupyter, see this [Working with Markdown Cells example notebook](https://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Working%20With%20Markdown%20Cells.ipynb)


## Jupyter Input Modes

Jupyter Notebooks have two different keyboard input modes:

* **Command Mode** - Make changes on the Notebook level. Indicated by a grey cell border with a blue left margin. Press `Esc` to enter Command Mode.
* **Edit Mode** - Make changes to an individual cell. Indicated by a green cell border. Press `Enter` to enter Edit Mode.

A new cell will always start as a **Code** cell, where you can type in R code and execute it here in your Jupyter notebook. As mentioned, all code in this notebook is in R.

Useful keyboard shortcurts when you are in Command Mode:
* **Enter** to enter Edit Mode to edit the cell
* **B** to create new cell below the current cell
* **A** to create new cell above the current cell
* **Y** to change a Markdown cell to Code
* **M** to change a Code cell to Markdown
* Press **D** twice to delete the cell
  
Shortcuts when you are in Edit Mode:
* **Esc** to enter Command Mode
* **Ctrl + Enter** to Run cell and stay in the cell
* **Shift + Enter** to Run cell and select the next cell
* **Alt (or option on Mac) + Enter** to Run cell and insert a new cell below.
* **Ctrl (or Cmd on Mac) + Z**: Undo

---
**TRY IT YOURSELF**

Select the below cell in Edit Mode by double clicking in it, or by clicking it on the margin and pressing **Enter**. It should have a green border. Notice that this is a **Code** cell. Press Shift + Enter to execute the code. This will print the output and select the next cell.

Then, when you are in the next cell, press Ctrl + Enter. This will print the output and stay in the same cell.

Then, press the down arrow on your keyboard to to to the next cell. Enter Edit Mode (green border) by pressing Enter. Press Alt (or option on Mac) + Enter. This will print the output and create a new cell.

Then press the down arrow or select the new empty cell. Make sure you are in Command Mode (blue border). Press D twice to delete the new cell.</a>

```{r}
# press Shift + Enter
print("You just ran the cell and selected the next cell")
```

```{r}
# press Ctrl + Enter
print("You just ran this cell and the focus stayed here in this cell")
```

```{r}
# press Alt (or option on Mac) + Enter
print("You just ran the cell and inserted a new cell below it")
```

Notice the text in the above cells that starts with a hash **#** character. The hash indicates a **comment**. Anything following the hash symbol will not be evaluated. 

Congratulations! You not only executed code in Jupyter Notebooks, but you specifically executed R code. `print()` is a function in R that prints any output to the console. Notice that we put the content we wanted to print in quotation marks. This designates a `character` string. See more on this in the [RBasics](https://ciakovx.github.io/RBasics.html) lesson.

## Important Notes

### Session expiration

Binder is meant for interactive and ephemeral interactive coding, meaning that it is ideally suited for relatively short sessions. Binder will automatically shut down user sessions that have more than 10 minutes of inactivity (if you leave your window open, this will be counted as “activity”). If your session times out, first try selecting **Kernel > Reconnect** in the above menu. If that doesn't work, you'll have to select **Kernel > Restart** and go back and rerun any previously run code chunks.

### Saving changes

Because we are working in Binder, and Binder sessions are meant to be ephemeral, it is not possible for you to save any changes you make to your Jupyter Notebook. As stated above, if you do make changes or notes, you will need to download the notebook to your own computer by clicking **File > Download as > Notebook (.ipynb)**. The only way you will be able to run these is if you download software to your own computer, described below:

# Downloading software on your own computer (optional)

We are running everything in Binder during this class, so you don't have to download anything. However, you do have the option of downloading Anaconda and running the Jupyter Notebooks on your own machine (so you can save changes and create your own Notebooks), or downloading R and R Studio and opening the `Rmd` (R Markdown) files. While this class is ongoing, I may not be able to provide full support for installation, but please follow up with me on the conclusion of the class if you have questions. 

## Option 1: Downloading Anaconda to open IPYNB files

This step will allow you to open and execute the IPYNB files essentially just as they looked in Binder.

1. Download and install Anaconda: https://docs.anaconda.com/anaconda/install/
1. Go to <https://www.r-project.org/> to download R. Click on CRAN (Comprehensive R Archive Network) under Download, and scroll down to your country. Select the download link corresponding to the city that is geographically closest to you. Open the file and install.
2. Install IR kernel:
    * On PC, search for **Anaconda Prompt** in your computer, right click, and run As Adminstrator. In the prompt, type `conda install -c r r-irkernel`. During the installation process, Anaconda might ask if you `want to proceed ([y]/n)?`` Just type ‘y’.
    * On Mac, open terminal. Enter `conda config --add channels r` then `conda install --yes r-irkernel`
4. Following [these instructions](https://docs.anaconda.com/anaconda/navigator/tutorials/r-lang/), open Anaconda and select **Environments** to create an new environment. Click **Create**.
3. In Name, type **my_r_environment**. Next to Packages, select **Python 3.7** and **R**. Select **r** from the dropdown menu. Click **Create**.
4. Click the arrow next to **my_r_environment** and select **Open with Jupyter Notebook**. It will open in a web browser.
5. You can download the IPYNB files directly from the GitHub repo that underlies the course website, at <https://github.com/ciakovx/ciakovx.github.io>. To download an individual IPYNB file, click on it in the repo, then look for the **Raw** button in the upper right corner of the window. Right click on **Raw** and choose **File > Save Link As** (this language may vary by browser).

## Option 2: Downloading R and R Studio to open Rmd files.

This step will allow you to open and execute the Rmd (R Markdown) files in the R Studio environment. While the contents of the files are largely the same, you will execute the code within R Studio rather than Jupyter Notebooks.

1. Go to <https://www.r-project.org/> to download R. Click on CRAN (Comprehensive R Archive Network) under Download, and scroll down to your country. Select the download link corresponding to the city that is geographically closest to you. Open the file and install.
2. Go to <https://www.rstudio.com/products/RStudio/#Desktop> to download the RStudio desktop software. Open the file and install.
3. R Studio does not run IPYNB files. Instead, use the Rmd files in the GitHub repo that underlies the course website, at <https://github.com/ciakovx/ciakovx.github.io>. To download an individual Rmd file, click on it in the repo, then look for the **Raw** button in the upper right corner of the window. Right click on **Raw** and choose **File > Save Link As** (this language may vary by browser).