General User Guide for Noteable

When you click a link to Noteable, you'll probably see the following screen. Some of the text on the screen may be different. The important thing to look at here is the dropdown menu. If this is your first time using Noteable, and you would like to follow this walk through, then set this to Standard Notebook (click on the down arrow to see all options). Then press the Start button.

Great! You've just started your first Standard Notebook!

A Standard Notebook is for use with Python 3. Have a scroll through the other options on the dropdown to have a look at the kinds of Notebook Servers available on your account. You can start any kind of Notebook Server you would like when you log in - your folders and files will still be there regardless of which Notebook Server you choose.

A Standard Notebook is not the only type you can use. There are different Notebook Servers you can start depending on what programming language you would like to code in, or whether you need specific libraries for your code. You can choose any of the available Notebooks from the dropdown menu.

Currently, the following Notebooks are available on Noteable:

• Standard Notebook (Python 3)
• Geoscience Notebook (Python 3 with specialised libraries)
• Chemistry Notebook (Python 3 with specialised libraries)
• Language and Machine Learning (nltk, spacy, & tensorflow)
• RStudio
• R with Stan
• Sage Notebook

If you require a different type of specialized Notebook Server (i.e. need specific libraries or another type of kernel) get in touch with Noteable to discuss the possibility of developing such a Notebook for you.

Standard Notebook

This Notebook has a Python 3 kernel with a wide range of pre-installed Python libraries aimed at general data processing and visualization such as matplotlib, numpy and pandas. These are aimed at general purpose use including basic data analysis and plotting libraries so this notebook is especially useful for general tutorials and introduction to Python courses.

Geoscience Notebook

This Notebook has a Python 3 kernel with specialized libraries, such as cartopy, geopandas, and folium, that are useful for analyzing and visualizing geospatial data. This notebook is aimed at courses with a focus on analyzing geospatial data as its processing and plotting requires libraries which can do spatial operations of geometric types.

Chemistry Notebook

This Notebook has a Python 3 kernel with specialized libraries, such as biopython, chemspipy, and py3dmol, that are useful for analyzing and visualizing bio-chemistry data. This notebook is aimed at courses with a focus on analyzing bio-chemistry data as its processing and plotting requires libraries which can do 3D rendering of molecules.

Language and Machine Learning

This Notebook has a Python 3 kernel with specialized libraries for Natural Language processing and machine Learning. It comes with the nltk, spacy, and tensorflow packages, and includes the entire NLTK dataset, the en_core_web_sm spacy language model, and the official TensorFlow Model & Datasets.

R with Stan Notebook

Notebooks can be run in a R with Stan or Python 3 kernel containing pre-installed Stan-specific and R libraries as well as the same Python libraries as in the Standard Notebook.

RStudio

This opens up an RStudio interface overlayed on a Jupyter notebook with an extensive selection of R libraries along with the Python libraries from the Standard Notebook. Whilst this option opens the RStudio interface, although note that it does not provide access to the RStudio cloud service, or provide access to any facilities the RStudio cloud service provides (such as sharing notebooks or making notebooks public).

Sage Notebook Notebook

SageMaths plugin added to the Python 3 Standard Notebook.

The files and folders you see when you start a Notebook server are yours to keep. When you log in (assuming you use the same account each time) your folders will be there waiting for you. We'll talk about saving your work later. But for now, it's just important to understand that if you did some work, closed your browser, and followed the steps above again in a few days, your work would still be there.

You can click the Noteable logo on the top right of the screen to get back to the launch page and choose a new Notebook Server from the dropdown menu. Before you can start up a new Notebook, you need to shut down your current Notebook.

Alternatively, you can close down Noteable and go back into it. Shut down the current Notebook Server then choose the desired Notebook from the dropdown menu.

A folder can be used to group lots of different files, just like on your computer. To create a new folder, click New on the top right of the page. The drop down has lots of options - if some look unfamiliar, that's ok. For now, click Folder. Since "Untitled Folder" is not a very informative name, we'll rename it. I'm going to name this one "PracticeFolder", but you can choose a different name if you would like. To rename it, first click the checkbox on the left of your folder and click the Rename button above the checkboxes. Replace the text "Untitled Folder" with the name of your file and press the Rename button. You have just created an empty folder, and named it!

When you choose a name for folders or files, you should:
• Avoid using the "/" and "-" characters and spaces, as this may confuse the file system.
• If the name of your file contains several words, try capitalizing the first letter of each word or using "_" instead of spaces. For example: "BiologyProject" or "Biology_project".
• Try to give the folder or file an informative name - if it contains code for a Biology project, call it "BiologyProject".

Click on the folder name to have a look at what's inside. By clicking on the folder, we moved from the home directory one step further into PracticeFolder. So now the path to any files you create or upload into this folder will be "home/jovyan/Practicefolder".

It's easy to remember the path if you only have one folder, but if you have a more complex tree of folders, you can find out the path all the way from the home directory to your current location from the bold blue text next to the checkboxes. Since we haven't put any files in the folder, it is empty except for the folder named "..". Don't worry, that's meant to be there (in fact, it will be in all the folders you create). Try clicking on the name of the folder. To get back to your home directory, you can click on the ".." or on the folder icon in the path.

If you wish to create a notebook, click “New/Python 3” from any folder:

There are several templates and example notebooks available from the Noteable exemplar repository to get you started . If you or your students have never used notebooks before, it may be useful to refer to the beginner guide notebook which outlines the basics of interacting with notebooks.

If you are a Unix user, you may be familiar with terminals. Terminal is available on Noteable, just click New and then Terminal to get one running.

You can also run commands from a notebook code cell by prefacing the command with !.

Note: exercise caution when issuing commands that require further input from you on the command line - this will usually be easier to do by opening a terminal.

Noteable notebooks have a wide range of libraries pre-installed. To check which packages are included in which Notebook Server, you can visit the page on the Noteable website called Notebook Descriptions. Alternatively, you can use pip list in the terminal (or !pip list within the notebook) to list all the Python libraries in the Notebook Server currently running.

The Noteable Notebooks have a large number of libraries pre-installed, but in case you would like to use one specific library that isn't on the page on the Noteable website called Notebook Descriptions, you are free to install it yourself! You can either do this straight from the terminal or from within the notebook (prefacing commands with !) . For more information on how to access and use the terminal, please refer to the subsection labelled The terminal.

The two main ways to install Python libraries are with pip or conda. For example, within your notebook, you can either write !pip install <libraryname> or !conda install <libraryname>. From the terminal, you would only need to put in pip install <libraryname> or conda install <libraryname>.

Using pip is a much quicker way to install packages, but it has an added risk of causing dependancy issues. This is why conda is a safer, although slower, way to install a new package as it confirms that the installation won't cause any harm to existing packages before actually installing it.

However, the package that you install will only remain installed in your current session as it is not saved in your home directory (the only persistent directory). This means that the library has to be re-installed each time you would like to use it in a new session, so using ! within the notebook is often more convenient.

After installing it, you can import the library to any of your notebooks, as you would with any of the pre-installed libraries.

If the notebook isn't running, then clicking the checkbox next to the filename will give you a range of possible operations. A Move button will appear above the checkboxes.

If the notebook you want to move is running, you can only duplicate the file, the Move button won't show up. The easiest way to get around this issue is to save your notebook and click Shutdown. Now, if you click the checkbox, the Move option should reappear. Enter the new path for the file in the pop-up window and click Move. Note that all folders you would like to move the file to have to exist before using the Move button. You can move folders the same way by selecting them and clicking Move.

The more complicated option would be to create a copy of the file using Save as and write out the path you want the copy to have. Your original file will still exist in its original directory.

For example, to move the file "fileA.ipynb" to the folder "folderB", click Save as, then type "/folderB/fileA-copy". fileA will still exist in the home directory, but there will now also be a copy in folderB.

When loading or reading data files in a notebook, you need to specify the path to the data file you would like to access. Therefore the relative location of the data file with respect to the notebook file is important, otherwise the code will generate an error. The easiest method is to store the data in the same directory as the notebook file. If the notebook "Notebook1.ipynb" and data files "data.csv" are located in "~/folder1", you can use "./data.csv" within the notebook. You can use "../data.csv" if you need to go back one directory to reach the location of the data file.

Saving the work you did in your notebook is quite straightforward in Noteable. While you are editing the notebook, Noteable autosaves it frequently (after 2 minutes of non-use) so that even if you lose your current session, everything you did before the most recent autosave will be remembered.

The other possibility would be to click Save and checkpoint either using the Save icon or by selecting it from the dropdown options under File. Once you have checkpointed your notebook, you can keep editing it. The idea is that you can always revert back to the most recent checkpoint in case you want to delete everything new you added after it. If you choose to go back to your previous checkpoint, it can't be undone, so make sure you are happy to delete anything new before actually using this option. Of course, you can also use Save as from the dropdown menu under File, where you can specify a new file path for the copy.

If you have a notebook open and running, the dropdown list of the File tab includes an option called Download as. This gives you a list of file formats you can download the notebook as:

• AsciiDoc (.asciidoc)
• HTML (.html)
• LaTeX (.tex)
• PDF via LaTeX (.pdf)
• Markdown (.md)
• Notebook (.ipynb)
• reST (.rst), Python (.py)
• Reveal.js files (.slides.html)

When a notebook is downloaded as a PDF via LaTeX, markdown cells aren’t rendered correctly because LaTeX doesn’t know markdown notation. Any markdown formatting such as <br>, <b>bold</b>, <i>italic</i>, embedded code, coloured textboxes, bulleted, numbered or checklists written in markdown shows up as a block of text as they are ignored by LaTeX while it’s converting the notebook to pdf.

One way to avoid this would be to download it as a html file instead, this renders markdown correctly. Alternatively, LaTeX notation can be used instead as the Notebooks have a LaTeX tool. Any markdown notations that overlap with their equivalent in LaTeX are rendered correctly (eg: **bold**).

Shutting down your notebook means you are shutting down the kernel within the notebook, so that it stops running in the background if you aren't working on it. If the notebook icon is green, then your notebook is running. If you have the notebook open in a new window, you can shut it down by selecting Close and Halt from the dropdown list under File. You can also shut it down by ticking the checkbox next to its name and clicking Shutdown, a button with a brown background.

Shutting down your Noteable means that you are ending your current session. You can do this by clicking on the Noteable logo on the top right when you are on your launch page. This takes you back to the starting page where you chose the type of Notebook Server you wanted to use. If you click Shutdown here, you will end your session and any packages you installed will be lost.

Folders in Noteable work in a similar way to folders on your computer (like in finder, or windows explorer). Folders are there to hold files, and sometimes other folders, which will hold files (folders all the way down)... To find more information on creating folders in Noteable, please refer to the subsection labelled Creating a folder.

When you start your Standard Notebook, (if unsure how to do this, refer to the subsection labelled Starting up a Notebook Server), this is what you will see:

As you can see, there are 3 tabs you can choose from: Files, Running and Assignments.

Files will be the tab that is automatically opened when you start up a Notebook. It lists all your files, folders and notebooks that are stored within your Noteable.

Clicking on Running shows you all the notebook files and terminals that are currently running. You should be able to shut them down individually or open them up again. However, it is a known bug that notebooks can't be shut down from here. If you are unsure how to shut down a notebook, refer to the subsection labelled Shutting down your notebook/Noteable.

If you click on Assignments, you will find all the assignments (newly released, submitted and graded with feedback) for your courses that use Noteable. How assignments work in Noteable from the students' point of view are explained in this video tutorial created by the University of Edinburgh.

If you click on the Jupyter Logo on the top left corner, it will take you back to your root folder under the Files tab, so you'll get back to the page that your chosen Notebook Server starts up with.

Clicking on the Noteable Logo in the top right corner will take you back to the launch page of Noteable, where you can shut down your current Notebook and start up another one by selecting it from the dropdown list. If you are unsure how to do this, please refer to the subsection labelled Shutting down your notebook/Noteable.

+GitRepo is a user interface button that enables you to clone a public repository through git without having to use the terminal. For more information, refer to the subsection labelled Upload through +GitRepo.

The Empty trash button deletes hidden files that could fill up your disk space. These hidden files appear when you delete a non empty folder, or clone git repositories, so if the Disk meter shows that the disk space is filling up, it is useful to empty your trash.

The Upload button lets you upload a file from your computer.

The New button has a dropdown menu where you can choose to create a notebook (with a specific kernel available in your Notebook Server), create a folder or text file or start up a new terminal.

Refresh will update your launch page to the latest changes within your directories.

There are also several options to sort your folders and files by: Name (alphabetical order), Last modified and File size.

If you have a complex system of folders and files, remembering the path to the file could become difficult. Thankfully, the path to your current location is always displayed over the grey bar in line with the Sort by buttons. You can navigate through the folders within your path by clicking on them. To get back to your root folder, click the folder icon to the right of the checkbox.

If you haven't already, download or create the notebook file (name ends in ".ipynb") that you would like to upload to Noteable - make sure you know where it's downloaded on your computer. Once you've followed the steps to Starting up a Notebook Server, and have reached the screen below, click Upload. You can select the file from the files on your computer. So go to the location that the notebook was downloaded into on your computer and select it. The notebook is now within your Noteable directory. One last step - Press Upload next to the file name.

There it is! - now you can click on it to open it. Don't worry you don't have to do this each time you start up your Noteable, the file you just uploaded will be stored there, as long as you don't delete it.

If you are using git to upload a new file, there are three main options for you to do this within Noteable:

• Using git through the terminal within Noteable.
• Using git from the notebook interface (within a cell of a running notebook) by using "!" at beginning of command.
• Using the button +GitRepo for open source notebooks (which don't require a username and password).

Note: You cannot use git from a terminal on your machine - use the terminal in Noteable!

The following github repository will be used to show how to upload repositories with git: https://github.com/robyngreene/tutorialsNoteable.git

If you would like to use git commands on Noteable, open up a terminal by clicking New and selecting Terminal from the dropdown menu. This will open in a new tab. You can now use git commands such as git clone <url> by using the link from gitlab or github as you would with the files on your machine. Remember that "~" in the path correlates with your home directory on Noteable, not your computer, and you will only be able to access folders and files that are on Noteable and the file you are uploading will only be uploaded to Noteable.

From the launch page, click +GitRepo and paste the url of the repo. This will clone the repository and any files it contains onto your Noteable account. Any changes you make to this file will not alter the original repository.

+GitRepo only works for public repos, as a private repo requires you to put in your username and password to clone it. If the repo you want to upload is private, use the terminal.

You can use the same commands as you would in the terminal, the only difference being that you need to add a ! in front of the commands. If the repo you want to upload is private, use the terminal.

This tab holds common operations, such as Save as, Open and Rename. The more interesting ones would be Save and Checkpoint, Revert to Checkpoint (for more information, refer to the subsection labelled Saving your work in a notebook ) and Download as. The latter gives you a list of possible formats you could download your notebook as onto your computer. For more information on downloading a notebook, refer to the subsection labelled Downloading a notebook.

This holds a lot of useful actions related to the cells: copying, deleting, splitting and moving them as well as to attachments. The most interesting button would be Find and Replace, it does exactly what it sounds like, you can find all the places where a certain phrase is used and replace it by something else at all of these places.

This is where you find how to hide the header, toolbar and line numbers (counting the number of lines of code). You can also call the cell toolbar and edit the cell's metadata, tags or attachments and choose the slide type for a presentation.

This holds your standard insert a cell below or above actions.

This includes all the actions related to running the cells, choosing the cell type and clearing the output.

This is where you can restart, interrupt or change the kernel for the notebook you are currently viewing.

You can manage the widget state you have in the notebook.

You can use the User Interface Tool to explain what you can see on the menu and toolbar. There's also a useful list for keyboard shortcuts and references to common Python libraries.