Notebook

The PiCloud Notebook is a Python console in your browser optimized for data analysis and collaboration. Unlike a traditional console, a notebook lets you intermingle code and descriptive text. The best way to get a feel for how it works is to see it:

_images/notebook.png

Your notebook is an IPython Notebook running on the PiCloud Platform. There are several advantages to using a cloud-based notebook:

  • Your research is accessible from anywhere.
  • You can share your work with collaborators.
  • You can work efficiently with your data stored on PiCloud or AWS.
  • You can get comfortable with the environment your jobs run in.

Note

You do not need to use the Notebook to utilize any of our other compute or storage features.

Getting Started

Log into your account, and click on the Notebook tab. This brings you to your Notebook Machine.

Think of your Notebook Machine as a computer dedicated to you sitting on the cloud. When you open a notebook, your Notebook Machine is started if it isn’t already. And when you’re done, you should shutdown the machine to avoid wasting resources.

By default, a notebook named “Primer” is available, which will walk you through our introductory Primer. Click on it to open your first notebook. Use your PiCloud account password when prompted.

Warning

Browser Compatibility

The notebook makes extensive use of Websockets. As of this writing, the latest version of all major web browsers (Chrome, Firefox, IE, Safari, and Opera) support WebSockets. If you are running an incompatible version, you will receive a pop up notification when opening a notebook.

Using a Notebook

Cell

Each box in your notebook is called a cell. Cells can hold code, or various types of markup (Markdown, headers, or raw text). Unlike in a traditional Python console, pressing enter in a cell will create a new line, but not execute it. This makes it easy to write multi-line functions and sequences of commands.

Executing Code

When you want to execute a cell, whether it’s code or markup, press shift+enter. Note the number indicating the order of execution on the left side of the cell, “In [X]“. Unlike a traditional console, you can execute and re-execute a cell at any time, and cells are thus not necessarily in order of execution. While it takes some time to get used to, it’s very handy when you’re continuously iterating your code.

Executing Shell Commands

While the primary use case of the notebook is for writing Python code, it’s also convenient for running shell commands. To execute a shell command, just prefix a command with “!”. For example, you can run “!ls”, “!pwd”, or even the PiCloud command-line interface (CLI), “!picloud”.

_images/notebook_shell.png

Visualization

Your notebook can also display rich media including images, graphs, videos, and more!

_images/notebook_visualization.png

What Else?

The IPython Notebook has most of the functionality of IPython, and more. Here are places to learn more:

Where are Notebooks Stored?

Notebooks are stored as objects in your Bucket with prefix notebook/. You can see them in your Bucket Panel. You can also put an existing notebook into your bucket to use it with your PiCloud Notebook.

Understanding the Filesystem

Notebooks let you easily explore the filesystem that your jobs see. You can do the following:

  • ls around the filesystem to understand what files live where.
  • Import Python libraries to check availability and version.
  • Run non-Python programs
  • Inspect the changes you’ve made in your custom environment, and whether they’re working as expected.

Modifications are not Persistent

Note that modifications to the filesystem are not persisted in between notebook machine shutdowns and restarts. This is expected as each notebook machine is run in a separate job, and jobs do not have their filesystems persist. Be sure to save any data you need into your Bucket, a Volume, or somewhere else.

What is Your Notebook Machine?

When you first click on “new notebook” or an existing notebook, we start a “notebook machine.” Your notebook machine is an actual CPU core that is dedicated to your notebook. We launch your notebook machine as a job, which you’ll see in your Jobs Panel with label “picloud notebook”.

Because your notebook machine runs as a job, you are charged as you would be for any other job. So be sure to shutdown your notebook machine when you’re done with it. Shutting down kills the job.

When you open a notebook on your notebook machine, the IPython Notebook creates a new Python Kernel, which can be understood as another Python interpreter. Each open notebook has its own interpreter, which you can forcibly kill from the notebook itself, or from the notebook dashboard.

Killing a kernel, either forcibly, or by shutting down your notebook machine, loses the state of your notebook. Upon re-opening the notebook, you’ll notice that while all your inputs and outputs were recorded, none of the Python interpreter state, such as variables, remains. Thus, you’ll need to re-execute the code to get back to where you left off.

Configuration

Settings are retained even after notebook shutdowns so it’s easy to start where you left off.

Core Type and Multicore

To increase the amount of processing power and memory available to your notebook, choose a suitable core type, and even leverage multiple cores. A common issue is getting a “kernel died” error, which is often caused by your notebook running out of memory. To verify, check the job that is running your notebook for memory allocation failures.

Environment

Only custom environments based off of the Ubuntu 12.04 Precise base environment can be selected. This is due to it having the necessary dependencies to run the IPython Notebook.

Volumes

You can select as many volumes as you need to be mounted so that your code and datasets are available.

Secondary Password

By default, you log into your notebook with your account password. Use this field to add a second login password, which we recommend when sharing your notebook with others.

Collaborating

If you want to give collaborators access to use your notebook machine, set a secondary password. Then provide the URL of your notebook to your collaborators. They’ll be prompted for a password.

You can also send a notebook to a collaborator by downloading it (File -> Download as), and sending it using your preferred method.