Getting started with the new Jupyter Notebook paper template!

3 Likes

While Jupyter Notebooks have been around for a long time and SAS has been supporting them for a number of years, it hasn't been possible to submit your SAS Global Forum paper as a Jupyter Notebook - until now!

We're really excited that, starting with SAS Global Forum 2021, those presenting will have the ability to submit their paper as a Jupyter notebook. The notebook will be hosted as an asset in the proceedings and hosted on Github as an interactive item that people can engage with in more interesting ways than the humble PDF.

There is lots of information contained within the README of the Jupyter notebook template, but this article is designed for those who would like to explore submitting their paper as a Jupyter notebook but might not be familiar with Jupyter, Git/Github, and Python. This article describes how to install Git, the latest version of Python (3.9 at the time of writing) and Jupyter, and how to get started with using the SAS Global Forum 2021 Jupyter Notebook template.

Git and Github

Git is the most popular version control system in the world. You'll have likely seen references to it in your familiar SAS client applications like SAS Enterprise Guide and SAS Studio.

Github is a code hosting site for the Git projects that allows people to share their projects and collaborate. SAS Global Forum has been using Github as a way for people to share SAS programs and other supporting materials for the SAS Global Forum papers since 2018.

With SAS Global Forum 2021, we are using Github to host the Jupyter Notebook template. The easiest way to get started with Git, and to download and upload our paper and the template, is to run the Github Desktop App.

Download the app from this link.
Once you click run the application will deploy the files that it needs and present you with a screen where you can sign in or sign up. If you don't already have a Github account you should create one, without an account you won't be able to publish your notebook to Github. If you do have an account, go ahead and sign in.
During the sign in process you might be prompted to authorize the Github Desktop app to use your account. Select "Authorize desktop"
After you have authorized the Github Desktop application you will be prompted to go back to the Github Desktop application. The screen you'll see prompts you to configure Git with the display name and email address that you want to be associated with your commits. Edit if you need to, then click continue.
The final setup screen asks if you want to periodically report usage statistics to Github. Depending on your privacy preferences, you can either leave this ticked or de-select this item.
At this time you should be presented with the Github Desktop app home screen. If you are already a Github user you may see a list of your existing repositories. For now, we are going to minimize this application. We'll come back to it later.

Installing Python

Python is a high-level programming language that's increasingly popular. Its easy to learn and easy to read. One of it's most powerful features is that its supports packages and modules which makes it really easy to extend the core functionality of Python with exciting things. One of those things is Jupyter Notebooks. Jupyter is actually just a Python module.

In order to be able to run Python modules, it won't surprise you that we need to install Python. Jupyter requires Python 3+. At the time of writing, the latest version of Python is Python 3.9.1.

Download the latest version of Python by going to https://www.python.org/downloads/ and selecting the big, bright "Download Python" button.
Run the installer. On the setup screen, ensure that "Add Python to PATH is selected". Ensure that **install launcher for all users** is deselected (this removes the requirement for Administrative permissions in many cases) and select "Install Now".

After a couple of minutes, the installation should complete successfully:
Once the installation has completed, open the Command Prompt (Start> type "cmd") and check that Python starts and is in the PATH environment variable by running the following command: python --version. Python should output the version (3.9.x) and then exit.

Downloading and installing the template

Since we've got our machine configured for Git and Github and we have installed Python, we're ready to get into the exciting part: downloading the template and installing the dependencies.

We've included a file in the Jupyter notebook template folder (requirements.txt) that contains all of the dependencies needed for getting the template up and running.

Open you Github Desktop app again and select "Clone a repository from the internet...". In the popup that appears, select the URL tab, and paste the following URL: https://github.com/sascommunities/sas-global-forum-2021.git
By default, the application will clone new repositories into a "Github" folder of your user's Documents folder. If this is OK with you, you can go ahead and click "Clone". Once the cloning is complete, you should see something like this:
If you've worked with a source control management system before you'll know that its power lies in the way that we can create multiple different versions of files by branching.

We're going to create a branch for our paper so that we can work on it, and publish it to Github, without affecting other people.
Within the Github Desktop app, select "Branch" from the top menu bar and select "New branch...". In the pop-up that is displayed, paper number followed with a hyphen and then your last name, for example "0000-2021-Blake".

When the command has completed successfully, you should see something like this:
Minimize the Github desktop app and, using Windows Explorer, open the location where you cloned the repository to. You should see a new sas-global-forum-2021" folder.
Copy the "jupyter-notebook" folder from within the "templates" folder to the "papers" folder. Once you have copied it to the papers folder, rename the folder to be the ID of your paper followed with a hyphen and then your last name. For example, `0000-2021-Blake`.
Change directory into your newly created `0000-2021-Blake` folder then, in the address bar at the top, enter "cmd" where the full path to the folder was (tip: highlight the full path then type over it). This will open up a command prompt in your current directory.

Pressing enter after the above screen shot will result in a new command prompt window opening that looks like the following:
Enter the following commands into the command prompt to create a python virtual environment¹ called env and then "enable" the newly created virtual environment. The first command may take a few seconds to execute and the second command will result in a `(env)` being prepended to the path in the command prompt window.
```
python -m venv env
.\env\Scripts\activate
```
Enter the following command into the command prompt to install of the SAS Global Forum 2021 Notebook template pre-requisites, including Jupyter, to the newly created virtual environment. This process will download a number of packages from the internet and may take a few minutes.
```
pip install -r requirements.txt
```
Once the process is completed, you should see something that looks like the following:

Configure access to your SAS environment

Within the folder for your paper there is a file called `sascfg_personal.py`. This file is what is used by the [SAS Kernel]() to connect from the Notebook to your SAS installation. This could be Base SAS running on the same Windows machine that you are running the Notebook on or it could be a remote SAS9 or Viya environment on either Windows or Linux.

If you open the file you will see that there are lots of instructions for ensuring that you pick the correct configuration depending on your environment. If you have any issues make sure you checkout the documentation , blogs , and papers before creating an issue .

In the example below I am connecting from my Windows 10 machine to a SAS9 instance running on Linux using the included winiomlinux configuration. I have added the `encoding` option to match the encoding of my SAS installation:

When I run the cells of my notebook (we're going to get to this in the next section, I promise) either by clicking Shift + Enter, or clicking the double right arrow >>, I am prompted for the configuration I want to use as well as my SAS username and password.

Starting and modifying the template

Finally, we're here. We've installed Git and downloaded the template from Github. We've created a new branch for our paper and copied the template to our new paper folder so that we can start writing. And we've installed Python and all of the dependencies for running the template.

In our command prompt that we started from within out paper folder, lets start Jupyter.
```
.\env\Scripts\activate
jupyter notebook
```
Remember to ensure that you are within your python virtual environment:
From here you should be able to rename and open the Jupyter notebook (SASGF2021-Proceedings-Paper-Template), and start writing your content!
The very first cell of the Template provides more information on writing in Markdown including links to the My ST cheat sheet , and of course, the rest of the template provides instructions and examples of how to create all different kinds of content in your paper.

I hope that you found this step-by-step guide useful. Please don't hesitate to add any questions you might have in the comments section below. I am very excited to see all the incredible Jupyter contributions at SAS Global Forum 2021 and I hope to see you at the conference, virtually, of course!

¹Python virtual environments are a way that we can install libraries and scripts in an isolated way. If you need to install specific versions of a package to run an application you can do this without affecting the system-wide installed version. In general, its could practice to create a virtual environment for each of your Python projects.