Ctrl+K

Instructions for Developers

1.7. Instructions for Developers#

1.7.1. Getting started#

  1. Download the source material from Speech-Interaction-Technology-Aalto-U/itsp.

  2. Install required packages with e.g. conda/anaconda

    conda install jupyter-book

  3. Many chapters require further packages, which you should install if you plan to compile the whole book (not always required).

    conda install numpy scipy matplotlib ipython ipywidgets jupyterlab=4.1
conda install pytorch torchvision torchaudio -c pytorch 
pip install itikz
conda install texlive

  4. The typical use case is that markdown (.md) and notebooks (.ipynb) are written with JupyterLab, which can be started (in the folder of the project) by

    jupyter lab &

    The easiest way to start is to write static Markdown files. This disadvantage is that then you cannot use live code-examples in your document. Upgrading from markdown to notebooks is however easy.

  5. Once you are reasonably happy with your new content, compile the html-book (in the folder of the project) by

    jupyter-book build .


    Verify that the html-book looks like intended - some elements might work slightly differently.

1.7.2. Tips and tricks#

1.7.2.1. Audio#

Recording with python/jupyter is a nightmare, but playing audio works like a dream when using IPython and ipywidgets. See Vocoder for an example.

1.7.2.2. Interactive elements#

Some demonstrations are best when readers get to modify parameters themselves and to observe the output. IPython and ipywidgets allows doing that. Unfortunately, some of the more advanced interactive elements currently require a running jupyter/python kernel (i.e. have to run the notebook on a server). For an example, check out Representations/Spectrogram and the STFT.

1.7.2.3. Flow graphs and other static visualizations#

Tikz and PGF is a combination powerful tool for visualizations inside LaTeX documents. These can be incorporated in jupyter notebooks through itikz. For examples, see Security and Privacy.

Tip: In some scenarios, characters will get messed up when having multiple itikz-elements in a single document. If you’re having this issue, please see the solution at the discussion on Itikz-github.

1.7.2.4. Hidden and removed codeblocks in Jupyter notebooks#

Codeblocks can be used as pedagogical elements, but often there also codeblocks which are just to plot stuff, which is not very interesting for a reader. It is then recommended to hide the codeblock to avoid visual clutter. A button “click to show” button then appears where the reader can see how the backend works.

An alternative is to remove the codeblock from the output entirely. This is best in cases where the codeblock does not have any pedagogic purpose, like when creating flowgraphs with itikz (see above).

Both functions can be achieved with “tags” in the jupyter notebook. This can be found by clicking on the “Property inspector” logo at the far right side of the jupyter notebook. There it is possible to add either “hide-input” or “remove-input” for respective functions. For more information see Jupyter-book/Hide or remove content.

For an example of the use of both hidden and removed codeblocks, see Enhancement/Noise attenuation.

1.7.2.5. References and citations#

We use a bibtex based approach stored at references.bib. For instructions, see e.g. Jupyter-book/citations and references. For an example, see Computational_models_of_human_language_processing.

1.7.2.6. Executing notebooks / MyBinder badge#

To allow for the user to run the code in notebooks, there needs to be a jupyter server. Such a server can be installed locally (see Using this document), but importantly, there are public servers which can be used as well. The simplest approach is to use mybinder.org. To make it simple to use, please place a badge on top of the notebook, which directly runs the notebook on the server with the following steps:

  1. Find the github url, folder and filename.

  2. Enter the above in the form at mybinder.org.

  3. This autogenerates a command to generate the badge; copy that code to the top of your jupyter notebook.

  4. Be sure to test it by clicking the badge. For an example of use, see the page Noise attenuation.

Contents