Workflow

There are many ways to use the JupyterHub infrastructure to teach your connector course. This page is a place to store some attempts at crystallizing a workflow derived from past connectors. If you'd like to share your particular workflow, please add a link to the list below.

Past Connector Workflows

• Patty Frontera's workflow on using notebooks on the cluster

Data 8 workflow

Here's a rough overview of the workflow that's used in Data 8 to create, distribute, and collect student notebooks. Feel free to add/remove steps as fit for your course.

Click a link to jump to that section of this guide.

1. Create a notebook.
2. Push the notebook to Github.
3. Distribute the notebook to students.
4. Students work on notebooks.
5. Students submit their completed notebooks to you.

Here's a diagram of the steps.

Let's talk in more detail about each of these steps.

Creating notebooks

This guide is intended for those with no prior experience with Jupyter, git, or Github. Feel free to develop your own workflow if you know what you're doing.

Setting up your repo

First, visit https://datahub.berkeley.edu/ and log in. You should see a screen that looks something like the one below. Click the "Terminal" button as marked:

You should see a screen that looks like this:

This is a terminal that allows you to run commands. Type the following into the terminal:

git clone https://github.com/data-8/<repo_name>

Where the <repo_name> is the name of the repository for your connector. The repository names are listed at https://github.com/data-8. For example, if you are the instructor for the Health connector, you'd write:

git clone https://github.com/data-8/health-connector

Adding your content

After this step, you should be able to see your connector's folder at https://datahub.berkeley.edu/ . Once your folder is there, you do not have to repeat the steps in the Setting up your repo section.

Click on your folder to go inside that directory.

You should see a screen like the one below. Click the button marked by the arrow in the below image to create a new notebook. You may create a notebook in any folder as long as the folder is in your connector folder. That is, in the above example you may create a notebook in ~/health-connector/foo/bar/, but not ~/some_other_folder.

Fill in the notebook with your content.

Example notebooks: For examples of notebooks, you can see the table demos or find all raw notebooks for the textbook here. Data 8 uses notebooks for lectures, labs, and projects.

Adding datasets: If you have datasets/other needed files to distribute or use in a notebook, you can upload them using the button as labeled below:

Pushing your notebooks to Github

Once your notebook is ready for distribution, you must to upload it to Github so that it can publicly accessed online.

For those who are familiar with git and Github, push your file(s) to the gh-pages of your repo. The file(s) should then be available at http://data8.org/<repo_name>/<file_name>.

If you are not familiar with git/Github, follow the instructions below.

1. On datahub.berkeley.edu, open a new terminal. (New -> Terminal)

2. Type in

    cd <repo_name>
   

   Where the <repo_name> is the name of your repository (eg. health-connector).

3. Type

    git status
   

   You should see something that lists the files you've changed. If your changed files don't show up, ensure that they are in your repo's folder.

4. Type the following commands:

    git add -A
    git commit -m 'Update'
    git push origin gh-pages
   

   If you run into something that looks like:

    ERROR: Permission to data-8/some-connector.git denied
   

   Contact our support team. This means that you don't have the right access to Github.

5. Verify that you can access your file by visiting http://data8.org/<repo_name>/<file_name>. For example, for the Demo2.ipynb file in the health-connector repo you'd use the link: http://data8.org/health-connector/Demo2.ipynb .

If the last step doesn't work, double the check the steps above and contact us on a persisting issue.

Distributing notebooks

Once your notebook is uploaded to Github, you can give your students links that work like the Interact buttons in the textbook.

Automatically creating a link can be done with this jupyter notebook. This will open a mini python session along with a function we've written to make creating interact links easy.

Alternatively, manually create a link like the following:

http://datahub.berkeley.edu/user-redirect/interact?repo=<repo_name>&path=<path_name>

Where the <repo_name> is replaced with your repo name and <path_name> is replaced with the path to a file or folder in the repo.

For example, if you have a working link of http://data8.org/health-connector/Demo2.ipynb, the link you'd give students is:

https://datahub.berkeley.edu/user-redirect/interact?repo=health-connector&path=Demo2.ipynb

Any student that visits this link will end up with their own copy of the Demo2.ipynb file in a folder called health-connector their datahub.berkeley.edu account. You can repeat this for any file, not just notebooks.

I want to push a folder of content to students. You can! If you have a folder called datasets in the health-connector repo, you'd give students:

https://datahub.berkeley.edu/user-redirect/interact?repo=health-connector&path=datasets

I made a typo and want students to get an updated version. Sure! If you update a file, students can grab the update by visiting the original link again.

Note that in some cases an update would conflict with students' work (eg. updating a notebook that students have filled out). In such a case, the system will give up trying to update the file in favor of preserving the students' work.

A student messed up his work. Can he/she start over? Certainly. Have the student delete or rename the bad file/folder, then visit the link again. The original file/folder will appear good as new!

Student work

You can use notebooks as a supplement to a lecture. For example, here's a cool notebook about probability. Here's a notebook we use to explore literature in the first chapter of the textbook.

You can also use notebooks as assignments (the Data 8 class does both). You can check out the notebook we use for Lab 1 for Data 8 as an example of this.

As you can see from the lab, we have cells that the students fill in. You can make notebooks like this as well and distribute them to students in the same way as detailed above.

In that example above, we give Data 8 students this link to get the lab (and its related files):

https://datahub.berkeley.edu/user-redirect/interact?repo=data8assets&path=labs/lab01

Student submission

As of right now we don't have an easy way for students to submit their work programmatically. You can accept submissions through email, bCourses, or otherwise.

Students are currently able to download their notebooks off their datahub.berkeley.edu accounts in multiple formats, including .pdf, .py, and .ipynb. They can download a notebook by opening it, turning Edit mode on, then navigating to File -> Download as -> Format of choice.

An easy way to collect work is for students to export a notebook as a PDF file and then submit to bCourses. We have autograding for Data 8 but it requires set up. Let us know if you'd like to learn how to set that up.