Installation

We will use jupyter-book as a verbose form of the lecture slides. This is essentially a collective lecture notes, scribed by the students. The source code for the the book is hosted in the github repo.

Local build

To run and build the course jupyter-book locally, you need to first install jupyter-book. You can install juptyerbook using the pip command:

pip install -U jupyter-book

If you are using conda, you can install it using:

conda install -c conda-forge jupyter-book

For more details regarding the installation you can check the link.

We assume you have python and some of the machine learning libraries used in the course installed. Next, you need to download the repository in your local machine. Run the below command to clone the repository in your machine

git clone git@github.com:swing-research/prbook.git

The above command downloads the course jupyter-book files from Github into your local directory. This might take some times as there are several media files to be downloaded. Once downloaded you will have a folder called prbook. The prbook folder should look something like:

./prbook
├── book_data
├── _build
├── _config.yml
├── denoise-deblur.md
├── filtering.md
├── images
├── installation.md
├── introduction.md
├── intro.md
├── linear-methods.md
├── logo.png
├── logo_sada-lab_black.svg
├── modeling-knowledge.md
├── perceptron.py
├── __pycache__
├── references.bib
├── requirements.txt
└── _toc.yml

You are ready to build prbook and generate the HTML files. Now run the following command:

jupyter-book build prbook

This will generate a functional HTML site. The site is placed in ./prbook/_build/. You can open index.html in the directory /prbook/_build/html/ folder to view the contents of the book. For more details on building and troubleshooting jupyter-book builds follow the link

Scribing

This is an optional task for students to get extra credit or for people who missed some lectures with recorded attendance. You will be assigned certain lectures to scribe. Based on the assigned lectures you need to fill the corresponding Markdown document with python code snippets and explanations pertaining to the lecture. If a file for the lecture is not present you are free to create a new file with an appropriate name, however it is better to give us a prior notification. The file’s name must then be added in the proper sequence to _toc.yml. You can use Introduction, Denoising, and Wiener filter as examples of the tone and level of each topic’s explanations.

Editing and Style Convention

The prefered way of editing and creating the lecture notes is through Markdown files as done in prbook. But you can create the books using jupyter notebook as well. You can look at ./prbook/introduction.md on how to write down the markdown files which contains python snippets from the slides and explanation. Latex macros from ./prbook/_config.yml, should be used for equations in the explanation part of the text. Use Latex for equations and math terms. Follow the notation scheme in Denoising and deblurring whenever possible.

Submitting

The best method for uploading your work is to submit it as a pull request (PR), complete with your modifications. A sample PR is provided below Your commit messages should be detailed. After reviewing your changes, we will decide whether to accept them as is or ask you to make some improvements. You will receive full credit for the assignment given to you if the PR is examined and merged into the main branch, marking the task as successful.

Email is another option for submitting your work. We assess it after that and let you know if it is appropriate or not.

Pull request Example

Here, we’ll take a look at an example pull request for editing Installation to change a phrase. You should first create a local branch in your machine. This can be done by running the command:

git checkout -b <local branch name>

This can records each update you make. By initially uploading your branch using the command listed below, you can save it in the server.

git push origin <local branch name>

The swing-research/prbook github website now shows your branch. You can switch to your branch in your machine by typing the command git checkout <local branch name> . Make sure to update your local branch with the modifications. Once your local branch has been chosen, open installation.md and navigate to line 86. Replace ‘<local branch name>’ with ‘<branch name>’ or alter it to your any name of your choice. After making modifications, you must upload them to the github server. To push the modifications, enter the following command.

git add ./instruction.md 
git commit -m 'changing the branch in line 86' 
git push

If you see the error ‘The current branch <local branch name> has no upstream branch’ for the first time, you must use the command git push --set-upstream origin <local branch name> instead of git push. You may just use the standard push command to make additional changes.

Your entire history of changes will be kept in github as a distinct branch. Click the Compare & pull request button on the repo website to finally upload your modifications to the main branch. This prompts you to provide a title and remarks about your changes; once you’ve added all the necessary details, click the create pull request to submit your pull request.

Alternatively, you can create a Pull request by first Forking the repository into your account. You should first launch your browser and access the github repo. For you to contribute your changes, a github account is required. You must fork the repository once you are on the prbook github page (click the Fork button in the top right corner). The repository is duplicated in your account as a result. You must clone your copy of the reposity onto your local machine after it has been forked. The syntax for the clone command is:

git clone git@github.com:< your github username >/prbook.git

You will have the personal copy of prbook downloaded in your local machine. Open the file ./prbook/installation.md and go to line ‘109’ and change the text from ‘<your github username>’ to ‘<username>’ or you can change it your github user name as well. Once changed, you need push the local changes to the github server. You can run the following command to push the changes.

git add ./instruction.md 
git commit -m 'changing the user name in line 109' 
git push

NOTE: Be specific in your commit messages, this helps in debugging if there are any errors.

The above command uploads the local changes to your copy of prbook in the github server. You must now access your copy of the prbook on your github page. Your copy’s hyperlink should read https://github.com/<username>/prbook. The modifications are also visible in the browser. Now you are ready to push the changes to the main jupyter-book. There is a button labeled contribute on the browser. This button provides you the choice to start a pull request when you click it. You are taken to the ‘Open a pull request’ page when you click this. You get an option to add title and to comment on your changes. Once done, click on the Create pull request button. Now your pull request is submmitted.

You can check the comments regarding your updates in the pull request tab after a reviewer has been assigned to it.