'Notebook' seems to mean many things, why?The term is a generic one, and can either apply to 'Notebook App', 'Notebook Dashboard', or 'Notebook document'. See 'What is a computational notebook' below.
Which programming languages are supported on Noteable?Noteable currently supports Python 3 and R. We have experience with notebooks using Haskell, Julia, and Stata kernels. Talk to us about other languages.
Can I share notebook documents/files with other users?
Notebook servers have
git tools installed. See "How can I use Git in Noteable?" for details on that.
You can also download and upload files using the Download and Upload functions in the Jupyter classic, JupyterLab and RStudio interfaces.
Most notebook servers have an extension called “nbgrader”. This allows instructors to make assignments available for courses.
How can I use Git in Noteable?
Git is a "Version Control System", which allows people to save [and to share] snapshots of a set of files.
In Noteable, you can use Git with the standard command-line tool in a terminal, or through one of the graphical interfaces [which will vary depending on the notebook server that you are using]
Command Line Tools
To use the command-line tools, you will need to start a Terminal:
- In RStudio, there is a tab for this - by default this is in the left-hand pane, with
- In the notebook servers that use the JupyterLab interface, there is a button for this in the
Othersection of the Launcher
- In notebook servers with the classic interface, under
Newyou will see an option for
Once one has a Terminal open in Noteable, then the standard
git clone ...,
git checkout ..., etc will all work.
There is extensive external documentation about Git on the internet.
The graphical tools for Git vary, depending on the notebook server's interface:
- In RStudio, under
Git-> provide details
- This is a fairly simplistic cloning tool, so you will need to specify user credentials in the URL if it is a private repo.
- The tool will only clone or update a repo, you will need to refer to the command-line tools for additional functions.
- Project directory name allows you to change the name of the directory that the files are cloned into.
- You must select a value for "Create project as a subdirectory of:".... even if it is just your home directory.
- In the notebook servers that use the JupyterLab interface (specifically, the
Collaborativenotebook servers), there is a menu item in the top header for 'Git'
- This is a fairly simplistic cloning tool, so you will need to specify user credentials in the URL if it is a private repo.
- The tool provides a range of Git functions: pull, push, merge, etc.
- The tool clones into the current directory.
- In notebook servers with the classic interface, we provide the +GitRepo tool
- See below for the fields that the +GitRepo form is looking for.
- The tool with only clone or update a repo, you will need to refer to the command-line tools for additional functions.
- The tool will always clone into a directory at the top of your home directory, this is whatever directory your interface is looking at.
The +GitRepo popup is a wrapper for the
nbgitpuller tool. When you click on the button, it pops up a window to ask for the repository details:
- Git Repository URL : The https URL for repo to clone. eg
- Branch : By default, clones into the main branch, but you may specify a specific branch to use.
- Username and Password : Some repositories may be private, and require logging into.
Personal Access Tokens
Note that places like GitHub may require
Personal Access Tokens rather than simple username and password . This is beyond the purview of this guidance, however nbgitpuller [and thus +GitRepo] will use Tokens if they are set up.
Can I collaborate with others in my notebook?Yes, you can collaborate with others on your course by sharing a link to your notebook where they can follow your coding. You can share access to a notebook file you are working on using the 'Collaborative session' notebook servers available in Noteable. Note that collaborative sessions use the JupyterLab interface. Find out more information about this feature in the Collaborative Coding section.
Does Noteable support assignments and grading?Yes, Noteable uses nbgrader to provide course-specific assignments, grading, and feedback. See the documentation for Student Guide to Assignments and Instructor Guide to Assignments.
Is Noteable compatible with existing Jupyter notebooks?Yes.
Can I install my own packages on Noteable?
For most notebooks
In an early cell in your notebook, install the package - use either of these options:
!mamba install -y package-name
!pip install package-name
mamba is much slower, but checks version dependencies to ensure there are no problems.
pip will just install the library.
You can install Python packages as above (and many r-libraries are available as conda or pip libraries).
For libraries from the R repository you can either use
Install packages in the
Tools menu, via a
R -e 'install.packages('testthat', repo='http://cran.rstudio.com/')'will install the
R -e 'install.packages(c('testthat', 'alr3', 'funkyPigeon'), repo='http://cran.rstudio.com/')'will install all three libraries
In all cases - the libraries will not be present when you next start a notebook server.
How does Noteable connect to my institution's Learning Management System/Virtual Learning Environment?
Noteable creates a trusted relationship with the LMS/VLE, and thus accepts the details of the authenticated user that LMS/VLE sends over that [authenticated] connection.
- For Scottish schools: Noteable has an agreement in place with the GLOW Digital Learning Platform. Speak to your Local Authority to gain access to Noteable as a free tool in GLOW.
- For VLE/LMS systems using LTI: Contact us through the form on the top-right of the website, and we will send you configuration details that will be specific to your platform.
Connections provide Noteable with five pieces of data:
- The customer (inferred from the trusted configuration)
usernameof the user
- The short-form course code (eg
- The course name (eg "Mathematics 101 - an introduction to Bayesian statistics")
- role ('Instructor' or anything else)
"Customer" and "Username" allow us to provide home directories for each user, and "course" and "role" details are used my the Assignments system to provide appropriate tools.
Can I log into noteable if I don't have access to an LMS/VLE?No. Authentication is always done by the subscribing organisation (but see Trials below)
Can I clear old assignments from my home directory?
Absolutely. The way you do it is slightly different for student & instructors
For a student, you can delete the folder
<course code>/<assignment code>
For an instructor it's more complicated: There is data in your grading database, your original files, and the multiple student submissions & graded files.
The easy solution is to used the
archive-assignment script from a terminal session.
Noteable High-Level Design Description
What is a computational notebook?
computational notebook is an electronic 'notebook' designed to allow computation/calculation within the document. Whilst the likes of a word-processor may allow embedded tables and graphs, they don't have the capacity for general-purpose computation. Likewise, a programming editor will allow comments for code, but is not really any good for actually creating narrative notes.
We have to recognise that the term 'notebook' is often over-used, so let's break this down into four parts:
- The 'notebook document' is the file, in
ipynbformat, that contains the (markdown) text, the source code, and the output of your work.
- There's the backend bit that takes the source code and computes it. This is language-specific, and is called the 'kernel'.
- There's the front-end 'notebook dashboard', which is mainly used to open notebook documents and manage files. This is the Classic Notebook Interface, or the Jupyterlab Interface.
- Finally, the 'notebook app' (or 'notebook server') is the term for the behind-the-scenes application that provides the web-server which powers all this.
Where do 'notebooks' come from?
'Notebooks' come from wanting to provide a simple, interactive, programming environment - however to get there, there's some background to cover:
Let's start with 3rd generation programming languages (3GL) - machine independent, abstracted, programmer-centric. The source code is written, then compiled into another form, which is then executed.
3GL programmers often use an integrated development environment (IDE) tool to write, compile, and execute code all from the same place. IDEs often come with additional helpful features such as syntax highlighting, code-completion, and debugging. 3GL programming means a developer can use an IDE on their workstation, with locally installed libraries, to create a compiled application that can be distributed & executed as is on other computers.
iPython took the renowned programming language Python and wrapped an interactive shell around it - so it would compile & execute sections of code in sections. iPython came with a command-line shell, and a game-changing IDE: a web-based interface.
iPython's main goal is not application development, but data analysis, exploration & modelling.
Jupyter Notebooks are a language-agnostic IDE wrapped around iPython, and also bring a wealth of visual & user-centric improvements to the tool. These developments, primarily open-source and developer-community oriented, are the building blocks of the Noteable service.
Where does Noteable come from?
Noteable was born from the want to have notebooks available for teaching, at scale. Providing a 'notebook' for oneself is easy. Providing 'notebooks' for a single class is not difficult. Providing 'notebooks' for a whole University is hard.
Noteable uses Cloud Infrastructure to provide Containerised 'Notebooks' - which thus meets the goals of standardisation, repeatability, and scaling.
What is a docker container?
A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.
The important part for us is 'includes everything needed to run an application'.
What does Noteable do?
The problem with a Notebook App is that is runs on the user's computer, and needs the user to have all the libraries installed that they want to use in their notebook documents.
If we can put the Notebook App plus all the desired libraries into a docker container, we have a distributable service that we know is complete & correct.
Noteable is, at this level, two things:
- A mechanism to provide authenticated access to a range of different Docker App containers
- The infrastructure to launch notebook apps into a private, secure cloud
What is the Jupyter Project?The Jupyter Project is a spin-off project from the I-Python project, which initially provided an interface only for the Python language and continues to make available the canonical Python kernel for Jupyter. The name Jupyter itself is derived from the combination of Julia, Python, and R.
What is Jupyterhub?Jupyterhub is a web-application that provides a mechanism for users to connect to a machine and start a containerized Jupyter notebook app. Noteable does not use Jupyterhub.
- Noteable provides the tools and support, for lecturers, students and researchers, whatever their level of skill or knowledge, to deliver narratively rich, coded solutions.
- Noteable enables computational narratives to be readily created, shared and reused within and across teaching and learning contexts.
- In order for data, and the computations that process and visualize that data to be useful and meaningful for humans, they must be embedded into a narrative - a computational narrative - that tells a story for a particular audience and context.
- Our tools are designed by lecturers and researchers to support lecturers and researchers.
- They are easily integrated into your existing Virtual Learning Environment solutions.
- Tailorable to your teaching: Notebooks can be discipline specific or designed to be bespoke for your needs.
- We can support researchers working with data as well: To provide more CPU or more data storage, niche language kernel support and Big Data tooling.
- Your student numbers may change but our infrastructure makes sure your Notebooks still work smoothly. All without recourse to local IT support.
What is 'Trial Access', and can I have one?
We have a Trial Access system for potential customers. By default, users will be given "Instructor"-level access, and will have access to the full service without artifical restriction.
We run a Moodle system specifically for this.