Contents

macOS Software Stack¶

These instructions will walk you through installing the required Data Science software stack for DATA 301 or COSC 301. Before starting, ensure that your laptop meets the minimum requirements:

  • Runs macOS Catalina (10.15.x) or macOS BigSur (11.4). BigSur is recommended; older operating systems are possible but not recommended unless there is no other choice.

  • Can connect to networks via a wireless connection

  • Has at least 25 GB disk space available

  • Has at least 4 GB of RAM (more is better, 8GB is recommended)

  • Uses a 64-bit CPU

  • Is at most 6 years old at the start of the program (4 years old or newer is recommended)

  • Student user has full administrative access to the computer

If your compuer does not meet any of the requirements above, please don’t just drop the course!! Let me know first and we can discuss alternate possibilities so you can still take the course.

Installation notes¶

If you have already installed Git, Latex, or any of the Python related packages please uninstall these and follow the instructions below to install and configure them correcty (make sure to also remove any user configuration files and backup them if desired). In order to be able to support you effectively and minimize setup issues and software conflicts, we require all students to install the software stack the same way.

In all the sections below, if you are presented with the choice to download either a 64-bit (also called x64) or a 32-bit (also called x86) version of the application always choose the 64-bit version.

Once you have completed these installation instructions, make sure to follow the post-installation notes at the end to check that all software is setup correctly.

UBC Student Email¶

Please sign up for a UBC Student Email. This account will also grant you access to a range of other UBC services (not used in this course), including Microsoft Teams and OneDrive. To do so navigate to https://it.ubc.ca/services/email-voice-internet/ubc-student-email-service and follow the instructions under “Get Started”.

Web browser¶

You are welcome to use most modern browsers that have a WebKit or Gecko backend. Safari, Firefox, Vivaldi, Brave, Edge are all recommended. Google Chrome is not recommended because of the well-documented privacy and tracking issues with Google.

Microsoft Office¶

UBC students have free access to a Microsoft Office 365 annual subscription, which is renewed for students enrolled in at least one course. Office 365 includes Word, Excel, PowerPoint, Outlook, and OneNote, and is available on a variety of platforms.

To get your free Office 365 license and download the installer files, visit UBC IT for the installation instructions. Note that you will need your CWL login credentials in order to download the software and activate your license from portal.office.com.

In this course, you will need Microsoft Excel.

Python¶

We will be using Python for a large part of the course, and conda will be our Python package manager. We will be using the Miniconda installer (read more here) to install both python and conda at the same time. Miniconda also provides us with a minimum number of useful packages so installation is quick, and relatively painless.

Installing conda and python¶

The latest Miniconda installer can be downloaded from here: Miniconda macOSX 64-bit pkg install.

After installation, restart the terminal. If the installation was successful, you will see (base) prepending to your prompt string. To confirm that conda is working, you can ask it which version was installed:

conda --version

which should return something like this:

conda 4.8.2

Note: If you see zsh: command not found: conda, see the section on Terminal above to set your default Terminal shell to Bash as opposed to Zsh.

Next, type the following to ask for the version of Python:

python --version

which should return something like this:

Python 3.8.3

Note: If instead you see Python 2.7.X you installed the wrong version. Uninstall the Miniconda you just installed (which usually lives in the /opt directory), and try the installation again, selecting Python 3.8 (or higher).

Essential Python packages¶

conda installs Python packages from different online repositories which are called “channels”. A package needs to go through thorough testing before it is included in the default channel, which is good for stability, but also means that new versions will be delayed and fewer packages are available overall. There is a community-driven effort called the conda-forge (read more here), which provides more up-to-date packages. To enable us to access the most recent versions of the Python packages we are going to use, we will add this channel. To add the conda-forge channel type the following in a Terminal window:

conda config --add channels conda-forge

To install packages individually, we can now use the following command: conda install "<package-name>". Let’s install the key packages needed (you will note that we’re also specifying certain versions of the package with = X.Y):

conda install \
 "jupyterlab=3.*" \
 "numpy=1.*" \
 "pandas=1.*" \
 "flake8=3.*" \
 "black=19.*" \
 "nbconvert=6.*"

conda will show you the packages that will be downloaded, and you can press enter to proceed with the installation.

Visual Studio Code¶

The open-source text editor Visual Studio Code (VS Code) is both a powerful text editor and a full-blown Python IDE, which we will use for more complex analysis. You can download and install the macOS version of VS Code from the VS code website https://code.visualstudio.com/download. Once the download is finished, click “Open with Archive utility”, and move the extracted VS Code application from “Downloads” to “Applications”. Make sure you are able to open VS Code by clicking on the application.

VS Code extensions¶

The real magic of VS Code is in the extensions that let you add languages, debuggers, and tools to your installation to support your specific workflow. Now that we have installed all our other Data Science tools, we can install the VS Code extensions that work really well with them. From within VS Code you can open up the Extension Marketplace (read more here) to browse and install extensions by clicking on the Extensions icon in the Activity Bar indicated in the figure below.

Pointing to the left sidebar to where extensions can be installed.

To install an extension, you simply search for it in the search bar, click the extension you want, and then click “Install”. There are extensions available to make almost any workflow or task you are interested in more efficient! Here we are interested in setting up VS Code as a Python IDE. To do this, search for and install the following extensions:

  • Python

  • Python Extension Pack (for notebooks, debugging, linting, formatting, etc.)

  • markdownlint (markdown linting and style checking extension)

  • (Optional) Bracket Pair Colorizer 2 (add colour to help distinguish your brackets: (), [], {})

This video tutorial is an excellent introduction to using VS Code in Python.

Terminal¶

Apple recently changed the Mac default shell in the Terminal to Zsh - though the reasons for this are complicated, it is a huge improvement over the out-dated Bash version that came pre-installed on macOS.

If you are already on macOS BigSur, this change is made for you. But if you are on Catalina, you should switch your shell.

To check which shell you are running, open a new Terminal (Applications-->Utilities-->Terminal or activate Spotlight and type in Terminal). You will see a new window pop up and a blinking cursor. Type in the following command:

echo $0

If you are running a bash shell, you will see the output as bash. If you are running a zsh shell, you will see the output as -zsh. To make sure your shell is set to zsh, run this command:

chsh -s $(which zsh)

You may be prompted for your macOS administrative user password. Enter the password, quit the terminal (File-->Quit or Command+Q), and open it up again.

You should now proceed to do some more configuration via the Terminal.

Configure VS Code to launch from the Terminal¶

  1. Launch VS Code.

  2. Open the Command Palette (⇧⌘P ; Shift+Command+P).

  3. Type ‘shell command’ to find the “Shell Command: Install ‘code’ command in PATH” command.

  4. Hit Enter

  5. Restart the Terminal for the new $PATH value to take effect.

You can open files in VS Code from the Terminal! Alternatively, just type code . in any folder to start editing files in that folder.

You can test that VS Code is installed and can be opened from Terminal by restarting Terminal and typing the following command in a Terminal:

code --version

you should see something like this if you were successful:

1.57.1
507ce72a4466fbb27b715c3722558bb15afa9f48
x64

Manual install instructions are here, but remember you’re using the zsh now! steps as well.

Setting VS Code as the default editor¶

To make programs run from the Terminal (such as git) use VS Code by default, we will modify ~/.z_profile. First, open it using VS Code:

code ~/.z_profile

Note

If you see any existing lines in your ~/.z_profile related to a previous Python or R installation, please remove these.

Paste the following lines to the new file that opens up:

# Set the default editor for programs launch from Terminal
EDITOR="code --wait"
VISUAL=$EDITOR  # Use the same value as for "EDITOR" in the line above

Then save the file and exit VS Code.

Most Terminal programs will read the EDITOR environmental variable when determining which editor to use, but some read VISUAL, so we’re setting both to the same value.

[Optional] Install Ohmyzsh to get Terminal colours, and highlighting¶

You may now customize your Terminal with themes (see screenshots of themes here) by [following the directions here](“https://github.com/ohmyzsh/ohmyzsh#selecting-a-theme”].

Oh My Zsh is installed by running the following command in your Terminal:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Git and GitHub¶

We will use the publicly available GitHub.com.

Sign up for a free account at GitHub.com if you don’t have one already.

Install Git on your computer¶

We will be using the command line version of Git as well as Git through RStudio and JupyterLab. Some of the Git commands we will use are only available since Git 2.23, so if your Git is older than this version, we ask you to update it using the Xcode command line tools (not all of Xcode), which includes Git.

Open Terminal and type the following command to install Xcode command line tools:

xcode-select --install

After installation, in Terminal type the following to ask for the version:

git --version

you should see something like this (does not have to be the exact same version) if you were successful:

git version 2.30.1 (Apple Git-130)

Note

If you run into trouble, this is the time to post on Ed Discussion with your error message and ask for help!

Configuring Git user info¶

Next, we need to configure Git by telling it your name and email. To do this type the following into the Terminal (the same ones you used to sign up for GitHub):

git config --global user.name "YOUR NAME HERE"
git config --global user.email YOUR@EMAIL.com

Note

To ensure that you haven’t made a typo in any of the above, you can view your global Git configurations by either opening the configuration file in a text editor (e.g. via the command code ~/.gitconfig) or by typing git config --list --global.

Tree¶

“Tree is a recursive directory listing program that produces a depth indented listing of files.” This is very useful to explore your directory and file structure to figure out which files are where.

You can install the tree package using this command:

conda install -c conda-forge tree

Test JupyterLab¶

To test that your JupyterLab installation is functional, open a new Terminal window. Then type jupyter lab and then hit 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 and hold Ctrl while pressing c twice.

You should see something like this in your browser:

You’re all done!

Attributions¶

Important

These instructions have been adapted and remixed from the original version provided by the UBC-Vancouver MDS Install stack under a CC-BY-SA 4.0 license. They were originally written by Anmol Jawandha but have since been updated by Firas Moosvi, Joel Ostblom, Tomas Beuzen, Rodolfo Lourenzutti, & Tiffany Timbers, and others.