Link to this notebook

Examples

This notebook contains simple examples for using the JupyterInstruct python package. Not all features are included but some basic ones are hear to help get people started.

1. Validating Notebooks

Run the following code to validate a notebook. This python file has the least amount of internal dependances and should be easy to use on it's own.

from jupyterinstruct.nbvalidate import validate
validate("Accessable_Jupyter_content_for_INSTRUCTORS.ipynb")

2. Answer Cells

One key aspect of Instructor notebooks is the use of ANSWER cells. These are cells that are avaliable in the instructor version but are deleted entirely from the student version. An answer cell is any cell containing the ##ANSWER## hashtag. For clarity the hashtag is included at the beginning and end of each ANSWER cell to make it clear to future readers what will NOT be included. For example:

##ANSWER##

print("this is an example code cell which will not be included in the student version")

##ANSWER##

ANSWER

Here is an example markdown cell that will not be included in the student version.

ANSWER

To convert from the Instructor notebook to the student notebook and strip out the ANSWER cells use the following command:

filename="Examples.ipynb"

from jupyterinstruct.InstructorNotebook import makestudent
makestudent(filename, studentfolder='./docs/')

_CAUTION__ Make sure you save your notebook file before trying to generate the student version.

3. Content tags

Some content often changes semester to semester. to help facilitate content that changes a tag based merge option is include. Tags are just dictionaries with key values that are strings representing the tag name and values representing the content to be incerted inside the tag. Here is an example tag dictionary:

tags = {'YEAR': '2021', 
        'Semester': 'Spring',
        'Instructor':'Dirk Colbry',
        'Classroom':'On-Line'}

Tags are denoted inside a jupyter notebook document using three has tags (###) followed by the tag name and then three more hash tags (###). For example:

Welcome to ###Semester### semester ###YEAR### of CMSE101.

Your instructor is ###Instructor### and you will be meeting ###Classroom###.

filename="Examples.ipynb"

from jupyterinstruct.InstructorNotebook import makestudent
makestudent(filename, './docs/', tags)

Special Tags

There are a few special tags that can be included in notebooks these include:

• Empty Tags including ENDHEADER and STARTFOOTER. These tages typically have an empty string as a value and just get deleted from the student version. They are used as placeholders or other features.
• YEAR tag - As shown above the year tag can help create a long form of data which include days of the week. This allows notebooks to be stored in a MMDD (Month, Day) prefix format.
• The LINKS tag is the only tage to store a list instead of a string. The list allows common links to be grouped together.
• The NEW_ASSIGNMENT is the name of the student file.

For example:

tags = {'YEAR': '2021', 
        'Semester': 'Spring',
        'Instructor':'Dirk Colbry',
        'Classroom':'On-Line',
        'LINKS': ['Website', 'GitHub', 'Instructor_Website'],
        'Website': 'https://colbrydi.github.io/jupyterinstruct/',
        'GitHub': 'https://github.com/colbrydi/jupyterinstruct',
        'Instructor_Website': 'http://www.dirk.colbry.com/',
        'ENDHEADER': '',
        'STARTFOOTER': ''}

This file is called ###NEW_ASSIGNMENT###

Here are some important links:

LINKS

filename="Examples.ipynb"

from jupyterinstruct.InstructorNotebook import makestudent
makestudent(filename, './docs/', tags)

Course Tag files

Typically tags used for a course are stored in a course tag file. this way all the notebooks can access the same file and changes only need to be made in one location. Typically this file is stored in the main course directory and has the name thiscourse.py. An example file is as follows

%%writefile thiscourse.py
def tags():
    tags=dict()
    tags['COURSE_CODE']='CMSE401'
    tags['YEAR']='2021'
    tags['LINKS']=['Website','GitHub']
    tags['TOC']=''
    tags['TODO']=''
    tags['Syllabus']=''
    tags['Schedule']=''
    tags['D2L']=''
    tags['ZOOM']=''
    tags['SLACK']=''
    tags['LinkText']='Link to this document\'s Jupyter Notebook'
    tags['LINKURL']='https://raw.githubusercontent.com/colbrydi/jupyterinstruct/master/'
    tags['Website']='https://colbrydi.github.io/jupyterinstruct/'
    tags['GitHub'] = 'https://github.com/colbrydi/jupyterinstruct'
    tags['ENDHEADER']=''
    tags['STARTFOOTER']=''
    tags['Semester']='Spring'
    tags['Instructor']='Dirk Colbry'
    tags['Classroom']='On-Line'
    return tags

To use these tags the notebook only needs to import the course file

import thiscourse
tags = thiscourse.tags()
tags

4. Automatic Grading system

Michigan State University (MSU) has a jupyterhub server with nbgrader parcially installed. Since the hub does not included shared file systems, many of the nbgrader features are not avaliable. To get around this problem the jupyterinstruct package has some functions inside hubgrader designed to help instructors.

Step 1: Use the right server

In order to use nbgrader at MSU you need to log onto the http://jupyter-grader.msu.edu server. This is the only one with nbgrader installed.

Step 2: Convert the INSTRUCTOR notebook to an "assignment"

In the jupyter menu select "View-->Cell Toolbar--Assignment" This will add the assignment options to the current notebook's cells. Modify the cells for grading and autograding following the nbgrader tutorials.

Step 3: Generate and verify the student version of the notebook

Generate the student version of the INSTRUCTOR notebook and verify it is written as expected.

Step 4: Import student version into NBGrader system

Run the following cell which takes the student version filename and imports it into the nbgrader database.

from jupyterinstruct import hubgrader 
output = hubgrader.importnb(studentfile)

Step 5: Publish notebook to D2L (or wherever)

Click on the generated link to download the released version of the notebook

---

5. Self Referncing Files

Jupyter instruct often will work best as commands included inside the instructor notebooks. This allows instructors to easily publish a notebook the are working on from within the notebook. the trick to make this work is that the notebook needs to know the file name. This requires running some embedded javascript inside the notebook. fortunately, just loading the library will run that command and store the current notebook in a variable called this_notebook (You can also just use the InstructorNotebook.getname() function).

WARNING Since this function uses javascript you need to get the name in a different cell and wait to use the name.

WARNING #2 These Javascript functions will NOT work in Jupyterlab without some extensions installed.

It is recommended that the following cells be added to the footer of each INSTRUCTOR notebook (The third cell is only for autograder assignments). This will provide the instructor flexibility when submitting files.

##ANSWER## 
#this cell gets the name of the current notebook.
from jupyterinstruct import InstructorNotebook

import thiscourse
tags = thiscourse.tags()
##ANSWER## 

##ANSWER## 
#This cell runs the converter which removes ANSWER feilds, renames the notebook and cleans out output fields. 
studentnotebook = InstructorNotebook.makestudent(this_notebook, "./docs/", tags)
InstructorNotebook.validate(studentnotebook)
##ANSWER## 

##ANSWER##
from jupyterinstruct import hubgrader 
output = hubgrader.importnb(studentfile)
##ANSWER##

---

Written by Dr. Dirk Colbry, Michigan State University
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

---