PCP Teaser

Unit 1: Get Started

Overview and Learning Objectives

In this first unit, we briefly introduce how to use the PCP notebooks and start interacting with them using the Jupyter notebook framework. If a static view of the PCP notebooks is enough for you, the exported HTML versions can be used right away without any installation. Suppose you want to execute, modify, and experiment with the Python code contained in the notebooks' code cells. In that case, you need to install Python, some additional Python packages, and the Jupyter software underlying the web-based interactive computational environment for creating notebook documents. In the following, we discuss the required software components and explain the steps necessary to install them.

At the end of this unit, you should be able to run the PCP notebooks locally on your computer. Since the steps for installing PCP notebooks are typical for many software projects, we strongly recommend that students carry out these steps themselves while getting familiar with the software concepts involved. As an alternative for locally executing the notebooks, you may also use web-based services such as Google colab or binder. We refer to the PCP notebooks' GitHub repository for further details.

Downloading PCP Notebooks (Option 1): GitHub

The latest version of the PCP notebooks is hosted on GitHub. GitHub is a platform for software development and version control using Git. To use Git, please download and install the latest version for your operating system. For more information on how to setup and use Git, we refer to sources such as the GitHub Quickstart Guide and the Git Tutorial. You can download ("clone") the PCP GitHub repository by calling

git clone https://github.com/meinardmueller/PCP.git.
Note that the repository can also be run in interactive online Jupyter environments such as Binder without further installation steps. See the Readme.md of the repository for further information.

Downloading PCP Notebooks (Option 2): AudioLabs Website

Alternatively, you can download a zip-compressed archive containing the PCP notebooks and all data. You can find this archive at

https://www.audiolabs-erlangen.de/resources/MIR/PCP/PCP_1.1.3.zip

Decompress the archive and store it on your local computer.

Package Management System

Conda is an open source package manager that helps finding and installing packages. It runs on Windows, macOS, and Linux. The Conda package and environment manager is included in Anaconda and its slim version Miniconda, which are free and open-source distributions of Python. Miniconda can make installing Python quick and easy even for new users. Download and install Miniconda for your platform from the following website:

https://docs.conda.io/en/latest/miniconda.html

The following steps and commands may be useful to get started:

  • Install Anaconda or Miniconda (slim version of Anaconda).
  • On Windows: Start with opening the terminal Anaconda Prompt.
    On Linux/MacOS: You can use a usual shell.
  • Verify that conda is installed: conda --version
  • Update conda (it is recommended to always keep conda updated to the latest version): conda update conda
  • Default environment is named base
  • Create a new environment and install a package in it. For example:
    conda create --name PCP python=3 numpy scipy matplotlib jupyter
    creates a Python environment including the packages numpy, scipy, matplotlib, and jupyter

  • List of all environments: conda info --envs
  • Activate environment: conda activate PCP
  • Python version in current environment: python --version
  • List packages contained in environment: conda list
  • Remove environment: conda env remove --name PCP

Python Environment Files

To simplify the installation of Python and Jupyter, we recommend to create an environment from an environment.yml file, which exactly specifies the packages (along with specific versions).

  • We already provide such a file for the PCP notebooks. To create the environment named PCP, you need to call
    conda env create -f environment.yml

  • To update the environment, you can call
    conda env update -f environment.yml

  • Sometimes it may be easier to first remove the environment and than install it again:
    conda env remove -n PCP
    conda env create -f environment.yml

  • Once the environment has been installed, you need to activate it using:
    conda activate PCP

The current PCP environment can be listed as follows:

In [1]:
import os

fn = os.path.join('environment.yml')
with open(fn, 'r', encoding='utf-8') as stream:
    env = stream.read()

print(env)

name: PCP  # the name of the environment

channels:  # conda channels from which packages are downloaded
  - defaults
  - conda-forge

dependencies:
  - python=3.9.*  # Plain Python
  - pip=23.2.*  # Package installer for Python
  - numpy=1.25.*  # NumPy
  - matplotlib=3.7.*  # Matplotlib
# Jupyter Notebook dependencies:
  - ipython=8.12.*
  - jupyter=1.0.*  # prevents server error
  - jupyter_contrib_nbextensions=0.7.*  # spell checker
  - pip:  # Packages that are installed via pip
    - nbstripout==0.6.*  # strip notebook output
    - nbconvert==7.7.*  # HTML export

Creating Conda Environment

We provide an environment file with all packages needed for interacting with the PCP notebooks. Open the Anaconda Prompt on Windows or your default shell on Linux/macOS. Then change to the directory that contains the file environment.yml, e.g. by calling cd ./PCP/. Create the environment with the following command:

conda env create -f environment.yml

Starting Jupyter Server

After creating the PCP environment, you need to activate the environment using the following command:

conda activate PCP

Finally, one needs to change to the directory containing the PCP notebooks and to start the Jupyter server by using the following command:

jupyter notebook

This should open a browser, displaying the folder structure of the PCP notebooks. You then can open the overview notebook by selecting the file PCP.ipynb. You can also directly open any PCP notebook by selecting a file in any subdirectory with the file extension .ipynb. Within the Jupyter session, you need to follow the IPYNB links to keep the code cells executable. Furthermore note that, within the Jupyter session, you can only access files that are contained in the directory you used for launching the Jupyter server or in any of its subdirectories.

Jupyter Notebook

Jupyter is a non-profit, open-source project, born out of the IPython project. It exists to develop open-source software, open-standards, and services for interactive computing across dozens of programming languages. The Jupyter notebook framework allows for keeping code, images, comments, formulas and plots together. Here are some further links and comments:

  • For details we refer to the Jupyter Notebook QuickStart.
  • Some more advanced hints can be found ad the post 28 Jupyter Notebook tips, tricks, and shortcuts.
  • To start the notebook server from the command line, use the command jupyter notebook. This opens the default web browser at the URL http://localhost:8888
  • You may configure Jupyter notebook in various ways. For example, to disable cross-site-request-forgery protection (allowing remote content to be shown) you may use the command
    jupyter notebook --NotebookApp.disable_check_xsrf=True
  • Text can be added to Jupyter notebooks using markdown cells. In these cells, one can use traditional HTML, certain LaTeX commands, and also the popular text-to-HTML conversion language Markdown.

Keyboard Shortcuts

Keyboard shortcuts save lots of time. To access these shortcuts, note that Jupyter notebook operates in two modes:

  • In the edit mode (indicated by a green cell border) one can type into the cell in the usual way.
  • In the command mode (indicated by a gray cell border with a blue left margin) one is able to edit the notebook using keyboard shortcuts.

To enter the command mode, one can either press Esc or use the mouse to click outside a cell's editor area. Being in command mode, one can use the following keyboard shortcuts:

  • Esc: switch to command mode
  • H: access help menue with keyboard shortcuts
  • P: open the command palette
  • Ctrl + Enter: run selected cells
  • Shift + Enter: run cell, select below
  • A: insert a new cell above current cell
  • B: insert a new cell below current cell
  • Ctrl + Shift + -: split cell at current cursor position
  • Y: change cell to code
  • M: change cell to markdown
  • D + D (press the key twice): delete current cell
  • Z: undo cell deletion
  • Shift + J or Shift + Down: select cells downwards
    Shift + K or Shift + Up: select cells upwards
    Once cells are selected, one can delete/copy/cut/paste/run them as a batch.
  • Shift + M: merge selected cells
  • X: cut selected cells
  • C: copy selected cells
  • V: paste cells below

HTML Export

Jupyter notebooks can be exported in a variety of different formats, including .pdf, .tex, and .html. The export can either be done via the Jupyter menu (File$\rightarrow$Download As) or via the command line. The following commands show the HTML export on the example of the notebook Unit 2.

jupyter nbconvert --to notebook --ClearOutputPreprocessor.enabled=True --clear-output PCP_02_python.ipynb (clear output)
jupyter nbconvert --ExecutePreprocessor.timeout=3600 --to notebook --execute --inplace PCP_02_python.ipynb (execute)
jupyter nbconvert --to html PCP_02_python.ipynb (HTML export)

To export all PCP notebooks at once, we provide a Python script notebook_batch.py which can be used as follows:

python notebook_batch.py --mode clean . (clean all notebooks)
python notebook_batch.py --mode execute . (execute all notebooks)
python notebook_batch.py --mode html . (export all notebooks)

Note: The HTML export is optional and not required for completing this course. We recommend closing all notebooks before executing these commands.

Further Notes

Here is a list of useful commands, which may be helpful when working with Conda and Jupyter notebooks:

Updating, removing, and creating Python environments:

conda update conda
conda env update -f environment.yml
conda env remove -n PCP
conda env create -f environment.yml

Install package to strip output from IPython notebooks:

conda activate PCP
nbstripout --install

Install spell checker:

jupyter notebook
jupyter contrib nbextension install --user
jupyter nbextension enable spellchecker/main

Configure notebook to disable cross-site-request-forgery protection:

jupyter notebook --NotebookApp.disable_check_xsrf=True
PCP License