Requirements for PICSciE Virtual Workshops

This page details setup requirements for:

The links above will take you to the corresponding section of the page.

Overarching requirements

The following requirements apply to ALL PICSciE virtual workshops.

Princeton NetID

Unless otherwise indicated, all PICSciE workshops (in-person or virtual) require advance registration at www.princeton.edu/training. You must have an active Princeton NetID to register, and you must be enabled for Duo two-factor authentication.

Registration slots for virtual workshops are typically quite limited, so we ask that you not take up a slot unless you've read the course description to ensure it's an appropriate fit and you can commit to attending the entire workshop and (for hands-on workshops) participating actively.

Zoom requirements

All PICSciE virtual workshops are conducted over Zoom. Registrants receive a Zoom link via email 1-3 days prior to the workshop, along with additional instructions.   You must be logged into Zoom using your Princeton credentials in order to join a workshop.   More information on enabling a Princeton Zoom account (and on installing and using Zoom) can be found on University informational pages here and here.  While it is possible to join Zoom meetings by phone, participants in our hands-on workshops should plan to join using a laptop or desktop.

 

Workshops that use Adroit

Some of PICSciE's hands-on workshops use the Adroit training cluster (any workshops conducted on Adroit will clearly state so  in the workshop description).  If you do not already have an account on Adroit, you should request one at least two days before the start of a workshop.

Getting an account

You may request an Adroit account using this form.  Once provisioned, your username on Adroit will be the same NetID you use for all other Princeton services (along with its associated password).

VPN for off-campus connections

To connect to Adroit from off campus, you must use a VPN.  The University has instructions for installing and configuring Princeton's preferred VPN client -- called GlobalProtect  (accessing the instructions requires Duo authentication).

Connecting to Adroit

Adroit offers two ways to connect to the system: a web interface, and an SSH connection over the command-line (each is described below).

Web portal

Adroit offers a web portal at https://myadroit.princeton.edu (Duo authentication required; VPN required for off-campus access).  The MyAdroit portal provides access to a graphical file browser (select "Files" from the menu along the top of the page) as well as to a shell that runs in your browser (from the same top menu, choose "Clusters" ---> "Adroit Cluster Shell Access").  The web portal also furnishes an interface to run servers for Jupyter notebooks,  RStudio, MATLAB, or Stata.

ssh connection

For most workshops, the preferred way to connect to Adroit is via an SSH (Secure Shell) client, a piece of software for establishing secure connections to remote machines. Linux and macOS have always had a built-in SSH client, and as of April 2018, so does Windows 10 (if for some reason you don't have SSH enabled under Windows 10, follow this guide to enable it).

To connect to Adroit via SSH on Linux, macOS, or Windows 10 (Windows 8 is discussed separately below):

1) Access a command-line on your laptop
  • Linux: open a Terminal window (usually by pressing Ctrl+Alt+t --- i.e. press and hold Ctrl, and without releasing it, press and hold Alt, and then without releasing either of those two keys, type 't')
  • macOS: open a Terminal window (by launching the Terminal app located in /Applications/Utilities)
  • Windows 10: Windows 10 has a few different ways to access a command-line interface
    • PowerShell or Command Prompt --- these are a couple of Window-native (DOS-like) command-line environments. To access them, press Win+x (i.e., while holding down the Windows key, type 'x'). This opens the so-called "Power Users" menu in Windows. Select either "Command Prompt" or "PowerShell" (usually you'll see one or the other, depending on which Windows updates you've installed). Note that the Command Prompt and the PowerShell are not equivalent command-line environments in general, but for the purposes of using SSH, they work the same and either will do.
    • Windows Subsystem for Linux (WSL) --- WSL is an optional feature you can enable that furnishes a genuine Linux command-line within Windows. If you have WSL enabled, then you should have an SSH client on the Linux side by default, just as you would in a regular Linux operating system.
2) SSH into Adroit

The syntax for using ssh is the same in all of the above scenarios.  Remember to make sure you're on a Princeton VPN, and then on the command line you accessed in the previous step, type

ssh <YourNetID>@adroit.princeton.edu

So for instance, if your NetID is abc1, you would type:

ssh abc1@adroit.princeton.edu

If this is your first time connecting to Adroit from whatever computer you're on, you will then see a comment about a fingerprint along with the question  Are you sure you want to continue connecting (yes/no)? Answer 'yes' and hit Enter.

You will now be prompted for your usual Princeton password.  Enter it.

NOTE: there are no asterisks or dots to indicate how many characters you've typed, so if you think you've made a typo, hit Backspace many times and enter the password from scratch

NOTE: If you've previously connected to Adroit and set up SSH keys, you will be connected without being prompted for a password first.

Depending on whether you're on a VPN and how it's configured, you may now be prompted to enter a Duo code (if you are, do so).

That's it -- you should now be connected to Adroit and see its Linux command-line prompt instead of the one for  your local computer.

3) Ending the SSH connection to Adroit

To close the SSH connection, simply type exit at the Adroit command line and press Enter. This should close the connection, and your local computer's command-line prompt should reappear.

Windows 8

Windows 8 does not have a built-in SSH client, nor does it have a WSL that offers native access to a Linux command line. So if you run Windows 8 and want to make an SSH connection from within Windows (as opposed to, say, by running Linux inside VirtualBox and connecting to Adroit from within that virtual Linux session), then you need to install a separate SSH client.

We recommend either PuTTY or MobaXTerm.  These lightweight clients (MobaXTerm has more features) have a graphical interface to initiate SSH connections.

This video shows briefly how to connect to a remote server using Putty (starting at timestamp 0:54).  In the field for "Host Name", enter adroit.princeton.edu (leave the port number as 22). When you connect and it prompts you "login as: ", enter your NetID and then your password (again, you may be asked to Duo authenticate after entering your password). You should then be logged into Adroit and see its Linux command-line prompt. For more detailed information about Putty, consult this guide.

MobaXTerm should work fairly similarly.

 

Workshops that use Jupyter notebooks

Some of our Python workshops require that you have the Anaconda distribution of Python installed on your laptop and be able to access Jupyter notebooks in a browser.  This section details those steps and shows how to validate that you have performed the setup correctly.

Installing Anaconda Python

During the classroom sessions we will be using the Anaconda Python distribution and the Jupyter development environment that is included in Anaconda.

If you already have Anaconda installed (or think you do), skip to the section for validating your installation. If the validation fails, then either you do not have Anaconda installed (and you should come back to this section) or you do but there is some other issue (in which case you should visit one of our Setup Assistance Sessions (see the section of this page titled "Virtual Workshop Logistics").  If you are in doubt as to what is happening, come to a Setup Assistance Session.

Anaconda is free and runs on Windows, Mac OS X, and Linux. The installation takes about 20 to 30 minutes.

Note that we will be using Python 3! (Support for Python 2 officially ended in 2020, and a Python 2 installation of Anaconda is no longer easily available on the anaconda.org website).

To download and install Anaconda

(Note that you may be asked for the password to your laptop during some of the installation steps.  This is normal.)

  • In a web browser, visit anaconda.org .
  • Click “Download Anaconda” menu item at the top right of the page.
  • Scroll down to the bottom of the page and select the installer for Windows, macOS, or Linux as appropriate:
    • For Windows, use the 64-Bit Graphical Installer
    • For MacOS, use the 64-Bit Graphical Installer
    • For Linux, choose the installer for your hardware (unless your laptop has IBM Power CPUs, then you almost certainly want the 64-bit (x86) installer)
  • Open the installer that you downloaded (if it doesn’t automatically open).
  • Click “Next” or “Continue” as needed and agree to the license.
  • Keep the default destination folder.
  • If asked, install Anaconda for “Just Me”.
  • If asked, answer NO to "add Anaconda3 to my PATH environment variable".
  • If asked, answer YES to "register Anaconda3 as my default Python 3.8".

 

Starting Jupyter

Once you have downloaded and installed Anaconda, check that you can start Jupyter, as follows:

  • Windows -- In the Start menu, select Anaconda3 (64-bit) ----> Jupyter Notebook (Anaconda3)
  • Mac -- Open a Terminal (type “terminal” in Spotlight (the magnifying glass)). In the Terminal, type (the $ is just the prompt -- type only what is after the $):

    $ jupyter notebook

  • Linux -- Open a Terminal and, in the Terminal, type:

    $ jupyter notebook

A web browser should open automatically, displaying a list of files and directories in your home folder. If the web browser does not open automatically, go back to your Terminal (for Mac and Linux users), where you should see some URLs on the screen that start with “http:”. Copy/paste any of these URLs from the Terminal into a web browser and try to load that URL.

Either, the web browser should show you something similar to what is in the screenshot below:

Screenshot of home folder as seen in Jupyter

Download & Run a specific iPython notebook to validate your setup

Download a "test" iPython notebook

Visit https://github.com/mcahn/anaconda-jupyter-python-test.  Click on the green "Code" button and choose" Download ZIP" from the menu (and save the downloaded file, if asked what to do with it). Unless you indicate a different destination for saving the zip file, it should download to the "Downloads" folder on your laptop:

  • On a Mac it should automatically extract (unzip). 
  • On Linux, you should be able to unzip the file by double-clicking it or by typing

    $ unzip </put/path/to/zip file/here/>anaconda-jupyter-python-test-master.zip

    in a Terminal.  So, for instance, if your username on your machine is "joe" and you saved the zip file to a folder called "myfiles" inside your "Documents" folder, you would type:

    $ unzip /home/joe/Documents/anaconda-jupyter-python-test-master.zip

  •  On Windows, it may be necessary to extract the zip file yourself in Windows Explorer.  Find the file in your Downloads folder, right-click on it, and choose “Extract all…”.

Verify that you can open the test notebook successfully

In Jupyter, navigate to your Downloads folder, as shown in the screenshot (or navigate to whatever folder the downloaded zip file was unzipped into):

Screenshot of Downloads folder seen in Jupyter

and then click on the folder called "anaconda-jupyter-python-test-master" (not on the zip file!):

Screenshot of unzippped folder seen in Jupyter

Click on Anaconda-Jupyter-test-notebook.ipynb, and you should see:

Screenshot of test notebook without output

To verify that your Python installation works:

  • Click on the cell containing “import sys”, and then
  • Click the "Run" button on the Jupyter menu bar.

The Python version should print out, as seen below:

Screenshot of test notebook with output

If you have Python 3.5 or newer, congratulations -- you have a working Anaconda Jupyter and Python installation. If you have a version older than 3.5, or no version is printed, consider re-installing Anaconda by going back to the section above, or come to one of the Setup Assistance Sessions.

You can now shut down Jupyter by typing Ctrl-c twice in the command window, or by quitting the command window and then closing the browser tabs or windows that had been opened.

Workshops that use RStudio

Some workshops require that users have R and RStudio installed on their local laptops.

Installing R and RStudio

A detailed set of instructions for installing both R and RStudio on Windows, macOS, or Linux systems can be found on this page from McMaster University.  We recommend reading the section appropriate to your operating system and following the steps carefully.  The executive summary is:

  • First, you will install R by visiting the CRAN site (Comprehensive R Archive Network) at https://cran.r-project.org/ .
  • Second, you will download and install the free version of RStudio for your operating system from the RStudio download page.  Allow its installer to detect the R installation you just did and install RStudio on top of that.

Our partners at Digital and Statistical Services (DSS) maintain summary documentation with this same information.

Basic tutorial for RStudio

Once you have installed RStudio, you should familiarize yourself with the basics of navigating within and using RStudio as a composition environment for R.

DSS provides an extensive tutorial on RStudio basics, with screenshots.  We strongly recommend reading through that tutorial (and following along in RStudio!) in advance of your workshop. Doing so will help you familiarize yourself with where different buttons and menus can be found in RStudio.

In addition, running some of the examples in the tutorial will allow you to validate that your installation was successful (additional examples in R can be found on the DSS training page). Pay particular attention to the caveats on page 7 of that tutorial about setting the working directory before importing datasets for analysis.