├── .nojekyll ├── 90-references.Rmd ├── now.json ├── icons ├── note.png ├── tip.png ├── caution.png ├── note_2x.png ├── tip_2x.png ├── warning.png ├── caution2.png ├── important.png ├── caution2_2x.png ├── caution_2x.png ├── important_2x.png ├── warning_2x.png └── icons.txt ├── images ├── jigsaw.png ├── favicon.ico ├── chapter50.png ├── chapter52.png ├── chapter53.png ├── chapter54.png ├── hurricanes.png ├── processing.png ├── shocktube.png ├── Fig_notebook.png ├── nbtutor_next1.png ├── nbtutor_next3.png ├── oldenburg-geosci.jpg ├── DC-layered-earth-app.png ├── exit-ticket-student.png ├── activity-magic-student.png ├── exit-ticket-instructor.png ├── activity-magic-instructor.png ├── notebook-matplotlib-interact.png └── engcomp2lesson4-life-expectancy.png ├── .dir-locals.el ├── fonts ├── texgyrepagella-bold.otf ├── texgyrepagella-math.otf ├── texgyrepagella-italic.otf ├── texgyrepagella-regular.otf └── texgyrepagella-bolditalic.otf ├── DESCRIPTION ├── Dockerfile ├── _build.sh ├── .gitignore ├── bookdown-demo.Rproj ├── .travis.yml ├── _deploy.sh ├── _bookdown.yml ├── contributors.md ├── _output.yml ├── style.css ├── Makefile ├── README.md ├── preamble.tex ├── toc.css ├── CODE-OF-CONDUCT.md ├── index.Rmd ├── book.bib ├── 09-glossary.md ├── CONTRIBUTING.md ├── 08-about-the-authors.md ├── 07-usage-case-studies.md ├── LICENSE.md ├── 02-why-jupyter.md ├── apa.csl └── 05-jupyter-ecosystem.md /.nojekyll: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /90-references.Rmd: -------------------------------------------------------------------------------- 1 | # References {-} 2 | -------------------------------------------------------------------------------- /now.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "static", 3 | "public": true 4 | } 5 | -------------------------------------------------------------------------------- /icons/note.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/note.png -------------------------------------------------------------------------------- /icons/tip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/tip.png -------------------------------------------------------------------------------- /icons/caution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/caution.png -------------------------------------------------------------------------------- /icons/note_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/note_2x.png -------------------------------------------------------------------------------- /icons/tip_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/tip_2x.png -------------------------------------------------------------------------------- /icons/warning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/warning.png -------------------------------------------------------------------------------- /images/jigsaw.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/jigsaw.png -------------------------------------------------------------------------------- /icons/caution2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/caution2.png -------------------------------------------------------------------------------- /icons/important.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/important.png -------------------------------------------------------------------------------- /images/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/favicon.ico -------------------------------------------------------------------------------- /.dir-locals.el: -------------------------------------------------------------------------------- 1 | ((nil . ((show-trailing-whitespace . t))) 2 | (markdown-mode . ((fill-column . 80)))) 3 | -------------------------------------------------------------------------------- /icons/caution2_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/caution2_2x.png -------------------------------------------------------------------------------- /icons/caution_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/caution_2x.png -------------------------------------------------------------------------------- /icons/important_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/important_2x.png -------------------------------------------------------------------------------- /icons/warning_2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/icons/warning_2x.png -------------------------------------------------------------------------------- /images/chapter50.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/chapter50.png -------------------------------------------------------------------------------- /images/chapter52.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/chapter52.png -------------------------------------------------------------------------------- /images/chapter53.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/chapter53.png -------------------------------------------------------------------------------- /images/chapter54.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/chapter54.png -------------------------------------------------------------------------------- /images/hurricanes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/hurricanes.png -------------------------------------------------------------------------------- /images/processing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/processing.png -------------------------------------------------------------------------------- /images/shocktube.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/shocktube.png -------------------------------------------------------------------------------- /images/Fig_notebook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/Fig_notebook.png -------------------------------------------------------------------------------- /images/nbtutor_next1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/nbtutor_next1.png -------------------------------------------------------------------------------- /images/nbtutor_next3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/nbtutor_next3.png -------------------------------------------------------------------------------- /images/oldenburg-geosci.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/oldenburg-geosci.jpg -------------------------------------------------------------------------------- /fonts/texgyrepagella-bold.otf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/fonts/texgyrepagella-bold.otf -------------------------------------------------------------------------------- /fonts/texgyrepagella-math.otf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/fonts/texgyrepagella-math.otf -------------------------------------------------------------------------------- /icons/icons.txt: -------------------------------------------------------------------------------- 1 | icons 2 | 3 | source for custom block icons (caution, tip, etc): https://material.io/tools/icons/ 4 | 5 | -------------------------------------------------------------------------------- /fonts/texgyrepagella-italic.otf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/fonts/texgyrepagella-italic.otf -------------------------------------------------------------------------------- /fonts/texgyrepagella-regular.otf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/fonts/texgyrepagella-regular.otf -------------------------------------------------------------------------------- /images/DC-layered-earth-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/DC-layered-earth-app.png -------------------------------------------------------------------------------- /images/exit-ticket-student.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/exit-ticket-student.png -------------------------------------------------------------------------------- /images/activity-magic-student.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/activity-magic-student.png -------------------------------------------------------------------------------- /images/exit-ticket-instructor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/exit-ticket-instructor.png -------------------------------------------------------------------------------- /fonts/texgyrepagella-bolditalic.otf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/fonts/texgyrepagella-bolditalic.otf -------------------------------------------------------------------------------- /images/activity-magic-instructor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/activity-magic-instructor.png -------------------------------------------------------------------------------- /images/notebook-matplotlib-interact.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/notebook-matplotlib-interact.png -------------------------------------------------------------------------------- /images/engcomp2lesson4-life-expectancy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jupyter4edu/jupyter-edu-book/HEAD/images/engcomp2lesson4-life-expectancy.png -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: placeholder 2 | Type: Book 3 | Title: Teaching and Learning with Jupyter 4 | Version: 0.0.1 5 | Imports: bookdown 6 | Remotes: rstudio/bookdown 7 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM conoria/alpine-r-bookdown 2 | 3 | WORKDIR /usr/src 4 | 5 | COPY . . 6 | 7 | RUN R -q -e 'bookdown::render_book("index.Rmd", "bookdown::gitbook")' && mv _book /public 8 | -------------------------------------------------------------------------------- /_build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -ev 4 | 5 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')" 6 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')" 7 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::epub_book')" 8 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | .DS_Store 3 | 4 | .Rproj.user 5 | .Rhistory 6 | .RData 7 | .DS_Store 8 | README.html 9 | CONTRIBUTING.html 10 | PANDOC.html 11 | issues/ 12 | inst/doc 13 | vignettes/*.R 14 | vignettes/*.html 15 | revdep 16 | 17 | packages.bib 18 | 19 | *~ 20 | \#* 21 | _book/ 22 | jupyter-edu-book.{Rmd,log,tex} 23 | -------------------------------------------------------------------------------- /bookdown-demo.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Website 19 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | 3 | language: r 4 | pandoc_version: 2.7.2 5 | 6 | cache: 7 | packages: yes 8 | directories: 9 | - $TRAVIS_BUILD_DIR/_bookdown_files 10 | 11 | before_script: 12 | - chmod +x ./_build.sh 13 | - chmod +x ./_deploy.sh 14 | - Rscript -e "install.packages('devtools', repos='https://cran.rstudio.com')" 15 | - Rscript -e "devtools::install_github('rstudio/bookdown')" 16 | 17 | script: 18 | - ./_build.sh 19 | - ./_deploy.sh 20 | -------------------------------------------------------------------------------- /_deploy.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | [ -z "${GITHUB_PAT}" ] && exit 0 6 | [ "${TRAVIS_BRANCH}" != "master" ] && exit 0 7 | 8 | git config --global user.email "kyle.niemeyer@gmail.com" 9 | git config --global user.name "Kyle Niemeyer" 10 | 11 | git clone -b gh-pages https://${GITHUB_PAT}@github.com/${TRAVIS_REPO_SLUG}.git book-output 12 | cd book-output 13 | cp -r ../_book/* ./ 14 | git add --all * 15 | git commit -m"Update the book" || true 16 | git push -q origin gh-pages 17 | -------------------------------------------------------------------------------- /_bookdown.yml: -------------------------------------------------------------------------------- 1 | book_filename: "jupyter-edu-book" 2 | language: 3 | ui: 4 | chapter_name: "Chapter " 5 | delete_merged_file: true 6 | rmd_files: ["index.Rmd", 7 | "02-why-jupyter.md", 8 | "03-notebooks-in-teaching-and-learning.md", 9 | "04-a-catalogue-of-pedagogical-patterns.md", 10 | "05-jupyter-ecosystem.md", 11 | "06-getting-your-class-going-with-jupyter.md", 12 | "07-usage-case-studies.md", 13 | "08-about-the-authors.md", 14 | "09-glossary.md", 15 | "90-references.Rmd", 16 | ] 17 | -------------------------------------------------------------------------------- /contributors.md: -------------------------------------------------------------------------------- 1 | # Contributor Recognition 2 | 3 | The following individuals have contributed to the book. The authors 4 | are grateful for these contributions which improve the book for future 5 | readers. Thank you :bouquet:. 6 | 7 | ## Contributor Instructions 8 | 9 | _Please add a line below in alphabetical order by family name:_ 10 | 11 | Example: `Family name, First name (GitHub username)` 12 | 13 | - Smith, Mary (marysmith) 14 | 15 | ## Contributors 16 | 17 | - `Drake, Peter (PeterDrake)` 18 | - `Gorgolewski, Chris (chrisfilo)` 19 | - `McCluskey, Andrew (arm61)` 20 | - `del Razo, Mauricio (maojrs)` 21 | -------------------------------------------------------------------------------- /_output.yml: -------------------------------------------------------------------------------- 1 | bookdown::gitbook: 2 | css: style.css 3 | pandoc_args: ["--csl", "apa.csl"] 4 | config: 5 | toc: 6 | before: | 7 |
  • Teaching and Learning with Jupyter
    • 8 | after: | 9 |
  • Published with bookdown
    • 10 | edit: https://github.com/jupyter4edu/jupyter-edu-book/edit/master/%s 11 | download: ["pdf", "epub"] 12 | bookdown::pdf_book: 13 | includes: 14 | in_header: preamble.tex 15 | latex_engine: xelatex 16 | citation_package: none 17 | pandoc_args: ["--csl", "apa.csl"] 18 | keep_tex: yes 19 | bookdown::epub_book: 20 | dev: svglite 21 | stylesheet: style.css 22 | -------------------------------------------------------------------------------- /style.css: -------------------------------------------------------------------------------- 1 | p.caption { 2 | color: #777; 3 | margin-top: 10px; 4 | } 5 | p code { 6 | white-space: inherit; 7 | } 8 | pre { 9 | word-break: normal; 10 | word-wrap: normal; 11 | } 12 | pre code { 13 | white-space: inherit; 14 | } 15 | .rmdcaution, 16 | .rmdimportant, 17 | .rmdnote, 18 | .rmdtip, 19 | .rmdwarning { 20 | padding: 1em 1em 1em 4em; 21 | margin-bottom: 10px; 22 | background: #f5f5f5 5px center/3em no-repeat; 23 | } 24 | .rmdcaution { 25 | background-image: url("icons/caution_2x.png"); 26 | } 27 | .rmdimportant { 28 | background-image: url("icons/important_2x.png"); 29 | } 30 | .rmdnote { 31 | background-image: url("icons/note_2x.png"); 32 | } 33 | .rmdtip { 34 | background-image: url("icons/tip_2x.png"); 35 | } 36 | .rmdwarning { 37 | background-image: url("icons/warning_2x.png"); 38 | } 39 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | PYTHON := /usr/bin/env python 2 | 3 | html : _book/index.html 4 | 5 | pdf : _book/jupyter-edu-book.pdf 6 | 7 | epub : _book/jupyter-edu-book.epub 8 | 9 | view-html : _book/index.html 10 | $(PYTHON) -c 'import webbrowser; webbrowser.open("$^")' 11 | 12 | view-pdf : _book/jupyter-edu-book.pdf 13 | $(PYTHON) -c 'import webbrowser; webbrowser.open("$^")' 14 | 15 | clean : 16 | $(RM) -r _book/* 17 | 18 | SOURCES := $(wildcard [0-9]*.md [0-9]*.Rmd book.bib) _bookdown.yml index.Rmd 19 | 20 | _book/index.html : $(SOURCES) 21 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')" 22 | 23 | _book/jupyter-edu-book.pdf : $(SOURCES) preamble.tex 24 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')" 25 | 26 | _book/jupyter-edu-book.epub : $(SOURCES) 27 | Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::epub_book')" 28 | 29 | .PHONY: html pdf epub view-html view-pdf clean 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Teaching and Learning with Jupyter 2 | 3 | [![Build Status](https://travis-ci.com/jupyter4edu/jupyter-edu-book.svg?branch=master)](https://travis-ci.com/jupyter4edu/jupyter-edu-book) 4 | 5 | An open book about Jupyter and its use in teaching and learning. 6 | 7 | This repository is the source materials for the book "Teaching and Learning with Jupyter." It can be found here: 8 | https://jupyter4edu.github.io/jupyter-edu-book/ 9 | 10 | To view the book as HTML, and download it as PDF and other formats, please visit: 11 | https://jupyter4edu.github.io/jupyter-edu-book/ 12 | 13 | If you would like to contribute to this book, please see the file [CONTRIBUTING.md](CONTRIBUTING.md). 14 | 15 | 16 | ## Code of Conduct 17 | 18 | Please note that this project is released with a Contributor Code of Conduct 19 | based on the [Contributor Covenant](http://contributor-covenant.org) code of conduct. 20 | The full code of conduct is available in the 21 | [CODE_OF_CONDUCT.md](CODE-OF-CONDUCT.md) 22 | file. By participating in this project you agree to abide by its terms. 23 | -------------------------------------------------------------------------------- /preamble.tex: -------------------------------------------------------------------------------- 1 | \usepackage{booktabs} 2 | \usepackage{amsthm} 3 | \usepackage{framed,color} 4 | \definecolor{shadecolor}{RGB}{248,248,248} 5 | \setmainfont{texgyrepagella}[ 6 | Path = fonts/, 7 | Extension = .otf, 8 | UprightFont = *-regular, 9 | BoldFont = *-bold, 10 | ItalicFont = *-italic, 11 | BoldItalicFont = *-bolditalic] 12 | \setmathfont{fonts/texgyrepagella-math.otf} 13 | \makeatletter 14 | \def\thm@space@setup{% 15 | \thm@preskip=8pt plus 2pt minus 4pt 16 | \thm@postskip=\thm@preskip 17 | } 18 | 19 | \makeatletter 20 | 21 | \newenvironment{kframe}{% 22 | \medskip{} 23 | \setlength{\fboxsep}{.8em} 24 | \def\at@end@of@kframe{}% 25 | \ifinner\ifhmode% 26 | \def\at@end@of@kframe{\end{minipage}}% 27 | \begin{minipage}{\columnwidth}% 28 | \fi\fi% 29 | \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep 30 | \colorbox{shadecolor}{##1}\hskip-\fboxsep 31 | % There is no \\@totalrightmargin, so: 32 | \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}% 33 | \MakeFramed {\advance\hsize-\width 34 | \@totalleftmargin\z@ \linewidth\hsize 35 | \@setminipage}}% 36 | {\par\unskip\endMakeFramed% 37 | \at@end@of@kframe} 38 | \makeatother 39 | 40 | \makeatletter 41 | \@ifundefined{Shaded}{ 42 | }{\renewenvironment{Shaded}{\begin{kframe}}{\end{kframe}}} 43 | \makeatother 44 | 45 | \newenvironment{rmdblock}[1] 46 | { 47 | \begin{itemize} 48 | \renewcommand{\labelitemi}{ 49 | \raisebox{-.7\height}[0pt][0pt]{ 50 | {\setkeys{Gin}{width=3em,keepaspectratio}\includegraphics{icons/#1}} 51 | } 52 | } 53 | \setlength{\fboxsep}{1em} 54 | \begin{kframe} 55 | \item 56 | } 57 | { 58 | \end{kframe} 59 | \end{itemize} 60 | } 61 | \newenvironment{rmdnote} 62 | {\begin{rmdblock}{note}} 63 | {\end{rmdblock}} 64 | \newenvironment{rmdcaution} 65 | {\begin{rmdblock}{caution}} 66 | {\end{rmdblock}} 67 | \newenvironment{rmdimportant} 68 | {\begin{rmdblock}{important}} 69 | {\end{rmdblock}} 70 | \newenvironment{rmdtip} 71 | {\begin{rmdblock}{tip}} 72 | {\end{rmdblock}} 73 | \newenvironment{rmdwarning} 74 | {\begin{rmdblock}{warning}} 75 | {\end{rmdblock}} 76 | 77 | \makeatother 78 | -------------------------------------------------------------------------------- /toc.css: -------------------------------------------------------------------------------- 1 | #TOC ul, 2 | #TOC li, 3 | #TOC span, 4 | #TOC a { 5 | margin: 0; 6 | padding: 0; 7 | position: relative; 8 | } 9 | #TOC { 10 | line-height: 1; 11 | border-radius: 5px 5px 0 0; 12 | background: #141414; 13 | background: linear-gradient(to bottom, #333333 0%, #141414 100%); 14 | border-bottom: 2px solid #0fa1e0; 15 | width: auto; 16 | } 17 | #TOC:after, 18 | #TOC ul:after { 19 | content: ''; 20 | display: block; 21 | clear: both; 22 | } 23 | #TOC a { 24 | background: #141414; 25 | background: linear-gradient(to bottom, #333333 0%, #141414 100%); 26 | color: #ffffff; 27 | display: block; 28 | padding: 19px 20px; 29 | text-decoration: none; 30 | text-shadow: none; 31 | } 32 | #TOC ul { 33 | list-style: none; 34 | } 35 | #TOC > ul > li { 36 | display: inline-block; 37 | float: left; 38 | margin: 0; 39 | } 40 | #TOC > ul > li > a { 41 | color: #ffffff; 42 | } 43 | #TOC > ul > li:hover:after { 44 | content: ''; 45 | display: block; 46 | width: 0; 47 | height: 0; 48 | position: absolute; 49 | left: 50%; 50 | bottom: 0; 51 | border-left: 10px solid transparent; 52 | border-right: 10px solid transparent; 53 | border-bottom: 10px solid #0fa1e0; 54 | margin-left: -10px; 55 | } 56 | #TOC > ul > li:first-child > a { 57 | border-radius: 5px 0 0 0; 58 | } 59 | #TOC.align-right > ul > li:first-child > a, 60 | #TOC.align-center > ul > li:first-child > a { 61 | border-radius: 0; 62 | } 63 | #TOC.align-right > ul > li:last-child > a { 64 | border-radius: 0 5px 0 0; 65 | } 66 | #TOC > ul > li.active > a, 67 | #TOC > ul > li:hover > a { 68 | color: #ffffff; 69 | box-shadow: inset 0 0 3px #000000; 70 | background: #070707; 71 | background: linear-gradient(to bottom, #262626 0%, #070707 100%); 72 | } 73 | #TOC .has-sub { 74 | z-index: 1; 75 | } 76 | #TOC .has-sub:hover > ul { 77 | display: block; 78 | } 79 | #TOC .has-sub ul { 80 | display: none; 81 | position: absolute; 82 | width: 200px; 83 | top: 100%; 84 | left: 0; 85 | } 86 | #TOC .has-sub ul li a { 87 | background: #0fa1e0; 88 | border-bottom: 1px dotted #31b7f1; 89 | filter: none; 90 | display: block; 91 | line-height: 120%; 92 | padding: 10px; 93 | color: #ffffff; 94 | } 95 | #TOC .has-sub ul li:hover a { 96 | background: #0c7fb0; 97 | } 98 | #TOC ul ul li:hover > a { 99 | color: #ffffff; 100 | } 101 | #TOC .has-sub .has-sub:hover > ul { 102 | display: block; 103 | } 104 | #TOC .has-sub .has-sub ul { 105 | display: none; 106 | position: absolute; 107 | left: 100%; 108 | top: 0; 109 | } 110 | #TOC .has-sub .has-sub ul li a { 111 | background: #0c7fb0; 112 | border-bottom: 1px dotted #31b7f1; 113 | } 114 | #TOC .has-sub .has-sub ul li a:hover { 115 | background: #0a6d98; 116 | } 117 | #TOC ul ul li.last > a, 118 | #TOC ul ul li:last-child > a, 119 | #TOC ul ul ul li.last > a, 120 | #TOC ul ul ul li:last-child > a, 121 | #TOC .has-sub ul li:last-child > a, 122 | #TOC .has-sub ul li.last > a { 123 | border-bottom: 0; 124 | } 125 | #TOC ul { 126 | font-size: 1.2rem; 127 | } 128 | -------------------------------------------------------------------------------- /CODE-OF-CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at [lorena.barba@gmail.com](mailto:lorena.barba@gmail.com). All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /index.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Teaching and Learning with Jupyter" 3 | author: > 4 | Lorena A. Barba, 5 | Lecia J. Barker, 6 | Douglas S. Blank, 7 | Jed Brown, 8 | Allen B. Downey, 9 | Timothy George, 10 | Lindsey J. Heagy, 11 | Kyle T. Mandli, 12 | Jason K. Moore, 13 | David Lippert, 14 | Kyle E. Niemeyer, 15 | Ryan R. Watkins, 16 | Richard H. West, 17 | Elizabeth Wickes, 18 | Carol Willing, and 19 | Michael Zingale 20 | date: "`r Sys.Date()`" 21 | site: bookdown::bookdown_site 22 | output: bookdown::gitbook 23 | documentclass: book 24 | bibliography: book.bib 25 | biblio-style: apa 26 | link-citations: yes 27 | github-repo: jupyter4edu/jupyter-edu-book 28 | description: "A handbook on teaching and learning with Jupyter notebooks." 29 | favicon: "images/favicon.ico" 30 | --- 31 | 32 | # Introduction {#intro} 33 | 34 | This handbook is for any educator teaching a topic that includes data analysis 35 | or computation in order to support learning. It is not just for educators teaching courses in engineering or 36 | science, but also data journalism, business and quantitative economics, 37 | data-based decision sciences and policy, quantitative health sciences, and 38 | digital humanities. It aims to provide an entry point, and a broad overview of 39 | Jupyter in education. Whether you are already using Jupyter to teach, you have 40 | found learning materials built on Jupyter that piqued your curiosity, or have 41 | never heard of Jupyter, the material in this open book can empower you to 42 | use this technology in your teaching. 43 | 44 | [Project Jupyter](http://jupyter.org/) is a broad collaboration that develops 45 | open-source tools for interactive and exploratory computing. The tools include: 46 | over 100 computer languages (with a focus on Python), the Jupyter Notebook, JupyterHub, 47 | and an ecosystem of extensions 48 | contributed by a large community. The Jupyter Notebook has exploded in popularity since 49 | late 2014, fueled by its adoption as the favorite environment for doing data 50 | science. It has also grown as a platform to use in the classroom, to develop 51 | teaching materials, to share lessons and tutorials, and to create 52 | computational stories. Notebooks are documents containing text narratives with images and math, 53 | combined with executable code (many languages are supported) and the output of 54 | that code. This marriage of content and code makes for a powerful new form of 55 | data-based communication. Educators everywhere are adopting Jupyter for 56 | teaching. 57 | 58 | Educators newly adopting Jupyter can be overwhelmed by having to navigate the 59 | ecosystem of tools and content. They could study many examples, or consume a 60 | myriad of blog posts and videos of talks to distill the patterns of good practices 61 | and technical solutions to serve their students best. Several early adopters, 62 | having much experience to share, decided to begin collecting this know-how, and 63 | share open documentation about using Jupyter for teaching and learning. The 64 | result is this open book: a living document that captures the experiences of 65 | community members using Jupyter in education. 66 | 67 | The Jupyter Community Workshop in Washington, DC (November 2018) began that 68 | process, with a book sprint aimed at producing the first version of this 69 | handbook. The collaboratively written book consolidates explanations and 70 | examples covering key topics, including: what is Jupyter, how to try Jupyter, 71 | sharing notebooks with students, locally installing Jupyter, cloud offerings, 72 | finding example notebooks, writing lessons in Jupyter, making collections for a 73 | course, exporting to other formats with nbconvert, writing textbooks with 74 | Jupyter, using Binder and JupyterHub, making assignments and auto-grading, 75 | making online courses, teaching with Jupyter in the classroom, active learning 76 | and flipped learning pedagogies with Jupyter, and guiding learners to create 77 | their own content in Jupyter. This open handbook will grow to encompass all you 78 | need to know about Jupyter in teaching and learning. 79 | 80 | If you find these materials helpful or inspiring, give us a shout-out on Twitter 81 | using `#Jupyter4Edu`. We hope you do! 82 | 83 | 84 | ## Acknowledgments {-} 85 | 86 | The book sprint was held at the George Washington University in Washington, DC, 87 | on 28–30 November 2018, and organized by Lorena A. Barba. Funding to support the 88 | logistics and travel of all [participants](#authors) was possible thanks to a 89 | grant from Bloomberg to Project Jupyter, and managed by NumFOCUS. The group was 90 | fêted at a reception sponsored by Leidos. Participants traveled from all over 91 | the country and volunteered their precious time and hard work to give this work 92 | to the Jupyter community, with a heartfelt sense of gratitude to all the 93 | contributors to the software projects we love and depend on. Thank you! 94 | 95 | GitHub repository for this book: 96 | 97 | Content under a Creative Commons Attribution [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode) International license. 98 | -------------------------------------------------------------------------------- /book.bib: -------------------------------------------------------------------------------- 1 | @Book{xie2015, 2 | title = {Dynamic Documents with {R} and knitr}, 3 | author = {Yihui Xie}, 4 | publisher = {Chapman and Hall/CRC}, 5 | address = {Boca Raton, Florida}, 6 | year = {2015}, 7 | edition = {2nd}, 8 | note = {ISBN 978-1498716963}, 9 | url = {http://yihui.name/knitr/}, 10 | } 11 | @article{sweller2006worked, 12 | title={The worked example effect and human cognition}, 13 | author={Sweller, John}, 14 | journal={Learning and Instruction}, 15 | year={2006}, 16 | volume = {16}, 17 | issue = {2}, 18 | pages = {165--169}, 19 | doi = {10.1016/j.learninstruc.2006.02.005} 20 | } 21 | @article{chen2015worked, 22 | title={The worked example effect, the generation effect, and element interactivity}, 23 | author={Chen, Ouhao and Kalyuga, Slava and Sweller, John}, 24 | journal={Journal of Educational Psychology}, 25 | volume={107}, 26 | number={3}, 27 | pages={689}, 28 | year={2015}, 29 | doi = {10.1037/edu0000018} 30 | } 31 | @article{freeman2014active, 32 | title={Active learning increases student performance in science, engineering, and mathematics}, 33 | author={Freeman, Scott and Eddy, Sarah L and McDonough, Miles and Smith, Michelle K and Okoroafor, Nnadozie and Jordt, Hannah and Wenderoth, Mary Pat}, 34 | journal={Proceedings of the National Academy of Sciences}, 35 | volume={111}, 36 | number={23}, 37 | pages={8410--8415}, 38 | year=2014, 39 | doi = {10.1073/pnas.1319030111} 40 | } 41 | @misc{moore1989three, 42 | doi = {10.1080/08923648909526659}, 43 | year = 1989, 44 | volume = {3}, 45 | number = {2}, 46 | pages = {1--7}, 47 | author = {Michael G. Moore}, 48 | title = {Editorial: Three types of interaction}, 49 | journal = {American Journal of Distance Education} 50 | } 51 | @article{barbacfd, 52 | doi = {10.21105/jose.00021}, 53 | year = 2018, 54 | volume = {1}, 55 | number = {9}, 56 | pages = {21}, 57 | author = {Lorena Barba and Gilbert Forsyth}, 58 | title = {{CFD} {Python}: the 12 steps to {Navier}--{Stokes} equations}, 59 | journal = {Journal of Open Source Education} 60 | } 61 | @article{HallerKrauss2002, 62 | title={Misinterpretations of significance: A problem students share with their teachers}, 63 | author={Haller, Heiko and Krauss, Stefan}, 64 | journal={Methods of Psychological Research}, 65 | volume={7}, 66 | number={1}, 67 | pages={1--20}, 68 | year={2002}, 69 | url={http://www.dgps.de/fachgruppen/methoden/mpr-online/issue16/art1/haller.pdf} 70 | } 71 | @book{raymond1996new, 72 | title={The New Hacker's Dictionary}, 73 | author={Eric S Raymond}, 74 | year=1996, 75 | publisher={MIT Press} 76 | } 77 | @article{Meurer2017, 78 | doi = {10.7717/peerj-cs.103}, 79 | year = {2017}, 80 | volume = {3}, 81 | pages = {e103}, 82 | author = {Aaron Meurer and Christopher P. Smith and Mateusz Paprocki and Ond{\v{r}}ej {\v{C}}ert{\'{\i}}k and Sergey B. Kirpichev and Matthew Rocklin and AMiT Kumar and Sergiu Ivanov and Jason K. Moore and Sartaj Singh and Thilina Rathnayake and Sean Vig and Brian E. Granger and Richard P. Muller and Francesco Bonazzi and Harsh Gupta and Shivam Vats and Fredrik Johansson and Fabian Pedregosa and Matthew J. Curry and Andy R. Terrel and {\v{S}}t{\v{e}}p{\'{a}}n Rou{\v{c}}ka and Ashutosh Saboo and Isuru Fernando and Sumith Kulal and Robert Cimrman and Anthony Scopatz}, 83 | title = {{SymPy}: symbolic computing in {Python}}, 84 | journal = {{PeerJ} Computer Science} 85 | } 86 | @book{coleman2012coding, 87 | title={Coding Freedom: The Ethics and Aesthetics of Hacking}, 88 | author={Coleman, E Gabriella}, 89 | year=2012, 90 | publisher={Princeton University Press} 91 | } 92 | @misc{OC1998, 93 | title = {About OpenContent}, 94 | howpublished = {Retrieved 18 December 2002 from \url{http://opencontent.org/}}, 95 | year = 1998, 96 | author = {{OpenContent}}, 97 | } 98 | @article{roache2004bpc, 99 | title={Building {PDE} codes to be verifiable and validatable}, 100 | author={Roache, P.J.}, 101 | journal={Computing in Science \& Engineering}, 102 | volume={6}, 103 | number={5}, 104 | pages={30--38}, 105 | year={2004}, 106 | doi={10.1109/MCSE.2004.33}, 107 | } 108 | @article{mishra2015accurate, 109 | title={Accurate numerical schemes for approximating initial-boundary value problems for systems of conservation laws}, 110 | author={Mishra, Siddhartha and Spinolo, Laura V}, 111 | journal={Journal of Hyperbolic Differential Equations}, 112 | volume={12}, 113 | number={01}, 114 | pages={61--86}, 115 | year={2015}, 116 | publisher={World Scientific}, 117 | doi={10.1142/S0219891615500034}, 118 | } 119 | @book{brenner2008mathematical, 120 | title={{The mathematical theory of finite element methods}}, 121 | author={Brenner, S.C. and Scott, L.R.}, 122 | isbn={0387759336}, 123 | year={2008}, 124 | publisher={Springer Verlag} 125 | } 126 | @book{leveque2002finite, 127 | title={Finite volume methods for hyperbolic problems}, 128 | author={LeVeque, R.J.}, 129 | year={2002}, 130 | publisher={Cambridge University Press} 131 | } 132 | @article{chapelle1993inf, 133 | title={{The inf-sup test}}, 134 | author={Chapelle, D. and Bathe, K.J.}, 135 | journal={Computers and Structures}, 136 | volume={47}, 137 | pages={537--537}, 138 | year={1993}, 139 | publisher={Pergamon Press}, 140 | doi={10.1016/0045-7949(93)90340-J}, 141 | } 142 | @book{trefethen1997numerical, 143 | title={{Numerical linear algebra}}, 144 | author={Trefethen, L.N. and Bau, D.}, 145 | isbn={0898713617}, 146 | year={1997}, 147 | publisher={Society for Industrial Mathematics} 148 | } 149 | -------------------------------------------------------------------------------- /09-glossary.md: -------------------------------------------------------------------------------- 1 | # Glossary {#glossary} 2 | 3 | **Anaconda**: a free, open-source package manager, environment manager, Python distribution, 4 | and collection of 5 | [over 1,500+ open source packages](https://docs.anaconda.com/anaconda/packages/pkg-docs/) 6 | including and also Jupyter. 7 | 8 | 9 | **API (Application Programming Interface)**: a specification of what a 10 | programmer must write or define to interact with a software library. 11 | 12 | **Binder**: a hosted service that allows anyone to launch their own sandboxed notebook environment from 13 | a Git repository. 14 | 15 | **cell**: the area in a Jupyter notebook where you can enter markdown, or computer code. 16 | 17 | **cloud, in the**: used to describe software or documents hosted on a remote computer 18 | accessed over the internet. 19 | 20 | **CSV (Comma Separated Values)**: referring to a comma-separated value file. 21 | A plain-text file format such that each line is a list of data separated by commas. 22 | 23 | **DataFrame** A common tabular data structure with rows and columns available 24 | in R and in Python through Pandas. 25 | 26 | **execute**: technical term for having the computer perform the instructions of your program. 27 | Alias for "run it." 28 | 29 | **extension, Jupyter**: in this instance, it is not a request for more time. 30 | Rather, a Jupyter extension is a bit of code, often developed by a third-party, 31 | that adds additional functionality to Jupyter. For example, a popular extension is a 32 | Table of Contents creator. 33 | 34 | **flipped classroom**: a teaching style where students work on their own outside of class 35 | to learn new material (sometimes by watching recorded lectures or reading descriptive/interactive 36 | notebooks) and the come together in the classroom to practice what they've learned through 37 | exercises or experiments. 38 | 39 | **Git**: a popular version control system (VCS) used for keeping track of changes of files over time. 40 | 41 | **IDE (Integrated Development Environment)**: software that assists in the development 42 | of additional software. 43 | 44 | **Jupyter**: The term "Jupyter" may refer to one of a couple of different things: 45 | a community of users and developers focused on the open source software; the collection 46 | of tools and standards that, together, allow projects like the Jupyter Notebook to operate. 47 | The name refers to the three core programming languages supported: 48 | Julia, Python, and R. 49 | 50 | **JupyterHub**: a cloud service that can provide access to Jupyter notebooks and 51 | environments to multiple users via a modern web browser. 52 | 53 | **kernel**: In Jupyter, a kernel is the packaging up of a language, and related programs 54 | needed to run it. For example, Python2 and Python3 are separate kernels. 55 | 56 | **LMS (Learning Management System)**: a cloud service that helps instructors manage 57 | aspects of classrooms. 58 | 59 | **load**: how many students can a computer support? 60 | 61 | **Markdown**: a text format that allows for basic formatting (headers, text styles, links) 62 | mixed inline with the text. Markdown files usually have the extension `.md` and 63 | can be rendered natively by GitHub and other tools. 64 | 65 | **magic**: a meta-command typically starting with one or two percent signs. 66 | Changes the meaning of the contents of a line (one percent sign, `%`) or the cell 67 | (two percent signs, `%%`) from code to a particular meta-instruction. 68 | For example, `%%R` indicates that the cell contents will be interpreted as commands 69 | to the R language. Magics are kernel-specific (e.g., vary with the kernel in use). 70 | 71 | **nbgrader**: a tool for creating, handling, and automatically grading assignments 72 | based on Jupyter notebooks. 73 | 74 | **nbviewer**: a web application for rendering Jupyter notebooks as static web pages, 75 | providing a URL to share and view them with a modern web browser. 76 | 77 | **nbconvert**: a tool for converting Jupyter notebooks into other formats such as 78 | PDF, HTML, LaTeX, Markdown, reStructuredText, and others. 79 | 80 | **notebook hidden state**: a technical term referring to the value of variables 81 | that may have surprising results due to cells having been executed in a non-sequential order. 82 | 83 | **open source**: software and documents that are created in a manner that give you 84 | rights to be able to use, and reproduce. 85 | 86 | **pattern**: A "pattern" is a technical term referring to an abstract description 87 | of a labeled process. For example, "wash, rinse, repeat" is a common pattern for 88 | cleaning various objects. 89 | 90 | **scaffold**: A teaching and learning pattern that provides steps in the 91 | learning process that build on prior learned knowledge. 92 | 93 | **script**: a colloquial term for a computer program. 94 | 95 | **service, JupyterHub**: JupyterHub can take advantage of additional separate, 96 | but integrated, software extensions. These are called "services." 97 | 98 | **software distribution**: A collection of software that is typically installed 99 | in bulk and is designed to ensure interoperability. 100 | 101 | **unit test**: a technical term for a "test" for checking to see if software is operating correctly. 102 | 103 | **URL (Universal Resource Locator)**: the address of a resource (e.g., webpage) on the internet. 104 | 105 | **widget**: a user interface (such as buttons, sliders, and checkboxes) that allow 106 | the easy control of hidden computer code. 107 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guide 2 | 3 | :+1::tada: Welcome! :tada::+1: 4 | 5 | We're pleased that you are thinking about contributing to this open 6 | book on teaching and learning with Jupyter. 7 | This document outlines some expectations that we have for contributors as well 8 | as guidance on how to make a contribution. 9 | 10 | We've tried to be thorough in this guide, but you may have questions or need 11 | clarification. If you do, please [file an issue on this GitHub repo](https://github.com/jupyter4edu/jupyter-edu-book/issues/new) 12 | with your question. We'll do our best to respond in a timely manner. Thanks 13 | in advance for your help improving the book. 14 | 15 | #### Table Of Contents 16 | 17 | [Code of Conduct](#code-of-conduct) 18 | 19 | [I don't want to read this whole thing, I just have a question.](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) 20 | 21 | [How Can I Contribute?](#how-can-i-contribute) 22 | 23 | - [Reporting Bugs](#reporting-bugs) 24 | - [Suggesting Enhancements](#suggesting-enhancements) 25 | 26 | [Your First Content Contribution](#your-first-content-contribution) 27 | 28 | - [GitHub account](#github-account) 29 | - [Edit content](#edit-content) 30 | - [From the book](#from-the-book) 31 | - [From the GitHub UI](#from-the-github-ui) 32 | - [Local development and building](#local-development-building) 33 | - [Pull Requests](#pull-requests) 34 | - [Recognition](#recognition) 35 | 36 | [Styleguides](#styleguides) 37 | 38 | - [Book organization](#book-organization) 39 | - [Git Commit Messages](#git-commit-messages) 40 | - [Formatting Tips](#formatting-tips) 41 | - [Attribution and Citations](#attribution-and-citations) 42 | 43 | ## Code of Conduct 44 | 45 | This project has a [Code of Conduct](CODE-OF-CONDUCT.md) which all contributors 46 | should read and are expected to follow when interacting with the community. 47 | 48 | ## I don't want to read this whole thing I just have a question 49 | 50 | > **Note:** Please check the following resources before asking a question. You'll 51 | > likely get faster results by using the resources below. 52 | 53 | Project Jupyter has an official Google Group for Jupyter in Education which 54 | has several years of archives on many topics of using Jupyter for teaching. 55 | 56 | - [Project Jupyter - Jupyter in Education Google Group](https://groups.google.com/forum/#!forum/jupyter-education) 57 | - [Jupyter documentation resources](https://jupyter.org/documentation) 58 | 59 | If you can't find an answer to your question about this book, please 60 | [file an issue on this GitHub repo](https://github.com/jupyter4edu/jupyter-edu-book/issues/new). 61 | 62 | ## How Can I Contribute 63 | 64 | ### Reporting Bugs 65 | 66 | This section guides you through submitting a bug report. Following these 67 | guidelines helps maintainers and the community understand your report :pencil:, 68 | reproduce the behavior :computer: :computer:, and find related reports :mag_right:. 69 | 70 | Before creating bug reports, please do a cursory search of the issues 71 | to see if the problem has already been reported. If it has 72 | and the issue is still open, add a comment to the existing issue instead 73 | of opening a new one. 74 | 75 | When you are [creating a new bug report](https://github.com/jupyter4edu/jupyter-edu-book/issues/new), 76 | please include as many details as possible. 77 | 78 | ### Suggesting Enhancements 79 | 80 | This section guides you through submitting an enhancement suggestion for the 81 | book, including completely new content and minor improvements to existing 82 | content. Following these guidelines helps maintainers and the community 83 | understand your suggestion :pencil: and find related suggestions :mag_right:. 84 | 85 | If you are interested in making a major change or addition, it is good practice 86 | to open an issue suggesting the enhancement before submitting a pull request. 87 | 88 | ## Your First Content Contribution 89 | 90 | Are you ready to make your first content contribution? Great. 91 | 92 | ### GitHub Account 93 | 94 | In order to contribute directly, you will need a GitHub account. 95 | You can get an account by simply clicking on the "Sign Up" button 96 | at https://github.com 97 | 98 | Once you have an account, you will need to Sign in. 99 | 100 | ### Edit content 101 | 102 | You will edit the content using one of the methods below: 103 | 104 | - From the book 105 | - From the GitHub user interface 106 | - Local development and building 107 | 108 | After making and commiting content changes, you will submit a 109 | [pull request](#pull-requests). 110 | 111 | #### From the book 112 | 113 | At the top of each page in the book, there is a row of light gray icons. 114 | The edit icon (the small box with a pencil inside) can be clicked to make 115 | changes to the page. Clicking the edit button will open the 116 | GitHub user interface for making an edit. You will now follow the 117 | [From the GitHub user interface](#from-the-github-user-interface) section. 118 | 119 | #### From the GitHub user interface 120 | 121 | The easiest way to contribute is to go to the sources of the book: 122 | 123 | https://github.com/jupyter4edu/jupyter-edu-book 124 | 125 | and click on the pencil button. You can edit the page directly 126 | in the browser. Just make the minimal about of change for your 127 | edit. In other words, don't remove spaces, or other formatting 128 | unless it is directly related to the item you would like to 129 | change or add. 130 | 131 | When completed editing a chapter, at the bottom of the page: 132 | 133 | - provide a summary of the changes 134 | - use the second box for more details about the changes 135 | - click the "Commit changes" button 136 | - click the "Create Pull Request" button 137 | 138 | For more extensive changes, we recommend cloning this repository and 139 | using the full power of git using [local development](#local-development). 140 | 141 | #### Local development and building 142 | 143 | The book content can be developed locally. 144 | 145 | If you wish to build your own copy of the book in HTML format you'll need: 146 | 147 | - R 148 | - `bookdown` package 149 | - pandoc 150 | - pandoc-citeproc 151 | 152 | On Ubuntu, you can install these with the following: 153 | 154 | ```shell 155 | sudo apt install littler pandoc pandoc-citeproc 156 | ``` 157 | 158 | Followed by installing the `bookdown` package in R: 159 | 160 | ```shell 161 | $ R 162 | > install.packages("bookdown") 163 | > q() 164 | Save workspace image? [y/n/c]: y 165 | ``` 166 | 167 | If you wish to build your own copy of the book in PDF format you'll 168 | need, in addition to the above, the following: 169 | 170 | - LaTeX 171 | 172 | On Ubuntu, you can install that with the following: 173 | 174 | ```shell 175 | sudo apt install texlive-full 176 | ``` 177 | 178 | Now, to actually build the book, you can: 179 | 180 | - `make html` - makes the HTML 181 | - `make pdf` - makes the PDF 182 | - `make view-html` - open the HTML in your browser 183 | - `make view-pdf` - open the PDF in a viewer 184 | 185 | The book PDF and HTML can be found in the `_book` folder. 186 | 187 | ### Pull Requests 188 | 189 | The process described here has several goals: 190 | 191 | - Maintain the book's quality 192 | - Fix problems that are important to users 193 | - Engage the community in working toward the best possible book 194 | - Enable a sustainable system for the book's maintainers to review contributions 195 | 196 | Please follow these steps to have your contribution considered by the maintainers: 197 | 198 | 1. Follow the [styleguides](#styleguides). 199 | 1. If you would like recognition in the book for your contribution, please follow the steps in the [recognition](#recognition) section. 200 | 1. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing. 201 | 1. Be patient. The maintainers are volunteers and will review at their 202 | earliest convenience. 203 | 1. After review, the maintainer may approve your pull request, make 204 | comments, or request changes. 205 | 1. Make any needed changes. 206 | 1. When the maintainer is satisfied by the changes, they will merge the pull request. 207 | In a few minutes, you should see the changes on the web version of the book. 208 | 1. Congratulate yourself on a job well done. 209 | 210 | ### Recognition 211 | 212 | If you would like to be recognized as a contributor to the book, please edit the `contributors.md` and add your name in the file in alphabetical order by family name. Please submit this modified file in your pull request. 213 | 214 | With each tagged release of the book in Zenodo, we will update the 215 | list of contributors at the end of the book. 216 | 217 | ## Styleguides 218 | 219 | ### Book Organization 220 | 221 | The book is divided into 10 chapters: 222 | 223 | 1. [index.Rmd](index.Rmd) 224 | 2. [02-why-jupyter.md](02-why-jupyter.md) 225 | 3. [03-notebooks-in-teaching-and-learning.md](03-notebooks-in-teaching-and-learning.md) 226 | 4. [04-a-catalogue-of-pedagogical-patterns.md](04-a-catalogue-of-pedagogical-patterns.md) 227 | 5. [05-jupyter-ecosystem.md](05-jupyter-ecosystem.md) 228 | 6. [06-getting-your-class-going-with-jupyter.md](06-getting-your-class-going-with-jupyter.md) 229 | 7. [07-usage-case-studies.md](07-usage-case-studies.md) 230 | 8. [08-about-the-authors.md](08-about-the-authors.md) 231 | 9. [09-glossary.md](09-glossary.md) 232 | 233 | Please feel free to add to or edit these sections. 234 | 235 | ### Git Commit Messages 236 | 237 | - Use the present tense ("Add feature" not "Added feature") 238 | - Use the imperative mood ("Move cursor to..." not "Moves cursor to...") 239 | - Limit the first line to 72 characters or less 240 | - Reference issues and pull requests liberally after the first line 241 | 242 | ### Formatting tips 243 | 244 | We use [markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) with 245 | [bookdown extensions](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html) 246 | for the book's formatting. 247 | 248 | If possible, avoid using unicode characters as they don't always 249 | transfer well into the document formats possible (HTML, PDF, etc.) 250 | Often, you might be able to find unicode replacements by using LaTeX 251 | math symbols and surrounding them by dollar signs (for example, $\neq$ 252 | will render as ≠). 253 | 254 | ### Attribution and Citations 255 | 256 | - Citations: https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html 257 | - Image attribution: Include title, credit, source, copyright notice, and 258 | license info for all images. [Additional information on Creative Commons image attribution](https://wiki.creativecommons.org/wiki/Best_practices_for_attribution#This_is_an_ideal_attribution) 259 | -------------------------------------------------------------------------------- /08-about-the-authors.md: -------------------------------------------------------------------------------- 1 | # About the authors {#authors} 2 | 3 | ## Project lead 4 | 5 | ### Lorena A. Barba {-} 6 | 7 | * George Washington University 8 | * [labarba@email.gwu.edu](mailto:labarba@email.gwu.edu) 9 | * [\@LorenaABarba](https://twitter.com/LorenaABarba) 10 | 11 | Lorena A. Barba is Associate Professor of Mechanical and Aerospace Engineering at the 12 | George Washington University. She adopted Jupyter in 2013 and since then used it in 13 | every course she teaches. Her open course materials are well known and used by 14 | thousands of learners: 15 | [CFD Python](http://lorenabarba.com/blog/cfd-python-12-steps-to-navier-stokes/) and 16 | [Numerical MOOC](https://github.com/numerical-mooc/numerical-mooc) are the best examples. 17 | 18 | ## Authors at the sprint 19 | 20 | ### Lecia J. Barker {-} 21 | 22 | * University of Colorado Boulder 23 | * [lecia.barker@colorado.edu](mailto:lecia.barker@colorado.edu) 24 | * [\@leciab](https://twitter.com/leciab) 25 | 26 | [Lecia Barker](https://www.colorado.edu/cmci/people/information-science/lecia-barker) 27 | is an Associate Professor and Associate Chair of Undergraduate Studies 28 | in the [Department of Information Science](https://www.colorado.edu/cmci/infoscience) 29 | at the University of Colorado Boulder. She is also a Senior Research Scientist for 30 | the [National Center for Women & IT](https://www.ncwit.org/). 31 | Her research group is studying the 32 | [diffusion and adoption of teaching practices](https://csteachingpractices.wordpress.com/) 33 | in undergraduate computer science. Lecia holds a Ph.D. in Communication from CU Boulder 34 | and an MBA in Marketing from San Diego State University. 35 | 36 | ### Douglas Blank {-} 37 | 38 | * Bryn Mawr College 39 | * [dblank@brynmawr.edu](mailto:dblank@brynmawr.edu) 40 | * [\@dougblank](https://twitter.com/dougblank) 41 | 42 | [Douglas Blank](https://cs.brynmawr.edu/~dblank/) is Associate Professor in the 43 | [Department of Computer Science](https://cs.brynmawr.edu/) at 44 | [Bryn Mawr College](http://brynmawr.edu/), a small, all-women's college outside 45 | of Philadelphia, PA, USA. He has a joint Ph.D. in Cognitive Science and Computer 46 | Science from Indiana University, Bloomington. For over 20 years, Douglas has taught 47 | all levels of Computer Science. For the last 4 years, he has used Jupyter notebooks 48 | exclusively in the classroom. Douglas has published in the areas of Computer Science 49 | Education, Robotics, Artificial Intelligence, and Deep Learning. He is on the advisory 50 | board of [Engage-CSEdu.org](https://www.engage-csedu.org), a joint project between 51 | Google and the National Center for Women and Information Technology (NCWIT). 52 | Douglas also writes text and code at his website [douglasblank.com](http://douglasblank.com). 53 | 54 | ### Jed Brown {-} 55 | 56 | * University of Colorado Boulder 57 | * [jed@jedbrown.org](mailto:jed@jedbrown.org) 58 | * [\@five9a2](https://twitter.com/five9a2) 59 | 60 | [Jed Brown](https://jedbrown.org/) is an Assistant Professor of Computer Science 61 | at the University of Colorado Boulder. He has been teaching numerical and scientific 62 | computing courses using Jupyter Notebook and `nbgrader` for three years, and leads a 63 | research group that develops computational methods and community software for 64 | computational science. 65 | 66 | ### Allen Downey {-} 67 | 68 | * Olin College 69 | * [downey@allendowney.com](mailto:downey@allendowney.com) 70 | * [\@AllenDowney](https://twitter.com/AllenDowney) 71 | 72 | [Allen Downey](http://www.allendowney.com/wp/) is a professor of Computer Science 73 | at Olin College and the author of a series of open-source textbooks related to software 74 | and data science, including _Think Python_, _Think Bayes_, and _Think Complexity_, 75 | published by O’Reilly Media. These books, and the classes based on them, use 76 | Jupyter notebooks extensively. Prof Downey holds a Ph.D. in computer science 77 | from U.C. Berkeley, and M.S. and B.S. degrees from MIT. 78 | 79 | ### Tim George {-} 80 | 81 | * Project Jupyter 82 | * [tgeorgeux@gmail.com](mailto:tgeorgeux@gmail.com) 83 | 84 | [Timothy George](https://www.tgeorgeux.com/) is the Lead UI/UX Designer for 85 | [Project Jupyter](https://jupyter.org/), focusing primarily on JupyterLab. 86 | In addition to his formal duties, Tim is also in working with Jupyter on 87 | design strategy, future products, governance, diversity and inclusion. 88 | He studied HCI at UC Irvine's Donald Bren School of Informatics and Computer Science 89 | where he received a Master's Degree. 90 | 91 | ### Lindsey Heagy {-} 92 | 93 | * University of California Berkeley 94 | * [lindseyheagy@gmail.com](mailto:lindseyheagy@gmail.com) 95 | * [\@lindsey_jh](https://twitter.com/lindsey_jh) 96 | 97 | [Lindsey Heagy](https://www.lindseyjh.ca/) is a Postdoctoral Researcher at the 98 | University of California Berkeley working on Project Jupyter and Jupyter in the 99 | geosciences. She recently completed her PhD at the University of British Columbia 100 | in geophysics. She is a project leader of [GeoSci.xyz](http://geosci.xyz), 101 | an effort to build collaborative, interactive, web-based textbooks in the geosciences, 102 | and a core contributor to [SimPEG](https://www.simpeg.xyz/), an open source framework 103 | for geophysical simulation and inversions. The GeoSci.xyz project relies heavily on 104 | Jupyter for making the content come to life. 105 | 106 | ### Kyle Mandli {-} 107 | 108 | * Columbia University 109 | * [kyle.mandli@columbia.edu](mailto:kyle.mandli@columbia.edu) 110 | * [\@KyleMandli](https://twitter.com/KyleMandli) 111 | 112 | [Kyle Mandli](http://www.columbia.edu/~ktm2132/) is an Assistant Professor in the 113 | Department of Applied Physics and Applied Mathematics at Columbia University. 114 | He has developed a set of openly available course notes centered around Jupyter 115 | notebooks and uses Jupyter for homework in conjunction with nbgrader. His other 116 | research interests include development of computational methods for coastal hazards 117 | such as storm surge and tsunamis. 118 | 119 | ### Jason K. Moore {-} 120 | 121 | * University of California, Davis 122 | * [jkm@ucdavis.edu](mailto:jkm@ucdavis.edu) 123 | * [\@moorepants](https://twitter.com/moorepants) 124 | 125 | [Jason K. Moore](http://moorepants.info/) is an Assistant Teaching Professor of 126 | Mechanical and Aerospace Engineering at the University of California, Davis. He 127 | currently teaches dynamics and mechanical design related courses. He utilizes 128 | Jupyter notebooks to teach modeling and simulation and is working on a 129 | [textbook about Mechanical Vibrations](https://moorepants.github.io/resonance). 130 | He is responsible for the Jupyter related features in the [LibreTexts 131 | project](http://libretexts.org) and is also a core developer of the 132 | [SymPy](http://sympy.org/) and [PyDy](http://pydy.org/) projects which utilizes 133 | Jupyter for training workshops, e.g. [PyDy 134 | Tutorial](https://www.sympy.org/scipy-2017-codegen-tutorial/) and [SymPy Code 135 | Generation Tutorial](https://github.com/pydy/pydy-tutorial-human-standing). 136 | Jason has PhD, MSc, and BSc degrees in mechanical engineering from UC Davis and 137 | Old Dominion University. 138 | 139 | ### David Lippert {-} 140 | 141 | * Leidos 142 | 143 | David Lippert is a software engineer at [Leidos](https://www.leidos.com) in Arlington, 144 | Virginia. He utilizes Jupyter notebooks primarily for exploratory data analysis and 145 | for training and evaluating machine learning algorithms. He has written Jupyter 146 | notebooks to create new Dr. Seuss sonnets and to evaluate if the 147 | [Rotten Tomatoes Tomatometer](https://www.rottentomatoes.com/about) can be trusted. 148 | He has a BA in computer science from Middlebury College. 149 | 150 | ### Kyle E. Niemeyer {-} 151 | 152 | * Oregon State University 153 | * [kyle.niemeyer@oregonstate.edu](mailto:kyle.niemeyer@oregonstate.edu) 154 | * [\@kyleniemeyer](https://twitter.com/kyleniemeyer) 155 | 156 | [Kyle Niemeyer](https://niemeyer-research-group.github.io/) is an Assistant Professor 157 | of Mechanical Engineering in the School of Mechanical, Industrial, and Manufacturing 158 | Engineering at Oregon State University. He teaches courses in numerical and analytical 159 | methods for solving differential equations as well as gas dynamics, and recently developed a 160 | [graduate course on software development for engineering research](https://softwaredevengresearch.github.io/syllabus/). 161 | His research group develops and applies methods for modeling combustion and chemically 162 | reacting fluid flows. He is also on the steering committee of the 163 | [Cantera](https://cantera.org/) open-source project for chemical kinetics, thermodynamics, 164 | and transport processes. 165 | 166 | ### Ryan Watkins {-} 167 | 168 | * George Washington University 169 | * [rwatkins@gwu.edu](mailto:rwatkins@gwu.edu) 170 | * [\@parsingscience](https://twitter.com/parsingscience) 171 | 172 | [Ryan Watkins](https://gsehd.gwu.edu/directory/ryan-watkins) is a Professor of Educational 173 | Technology at George Washington University in Washington DC. He leads the 174 | [Human-Technology Collaboration (HTC)](https://go.gwu.edu/phd) PhD program area, 175 | and he teaches courses in needs assessment, instructional design, and research methods. 176 | Ryan's research focuses on how people and organizations define and assess needs. 177 | He is co-host of [Parsing Science](https://parsingscience.org/), a podcast where researchers 178 | share the stories behind their science. He also developed the 179 | [We Share Science](https://wesharescience.org/) platform for sharing video abstracts 180 | of research. 181 | 182 | ### Richard H. West {-} 183 | 184 | * Northeastern University 185 | * [R.West@northeastern.edu](mailto:R.West@northeastern.edu) 186 | * [\@richardhwest](https://twitter.com/richardhwest) 187 | 188 | [Richard West](https://web.northeastern.edu/comocheng/) is Associate Professor of 189 | Chemical Engineering at Northeastern University in Boston. He leads a research group 190 | in computational modeling for complex reacting systems like combustion or catalysis. 191 | He is a core member of the [Cantera](https://cantera.org/) open-source project. 192 | As well as in an elective on "computational modeling in chemical engineering", 193 | he has integrated Python and Jupyter into core classes on chemical kinetics and reactor design, 194 | at both the undergraduate and graduate levels. As part of his NSF CAREER award, 195 | he is developing modules to teach students to use Python and SciPy to solve 196 | chemical engineering problems. 197 | 198 | ### Elizabeth Wickes {-} 199 | 200 | * University of Illinois at Urbana-Champaign 201 | * [wickes1@illinois.edu](mailto:wickes1@illinois.edu) 202 | * [\@elliewix](https://twitter.com/elliewix) 203 | 204 | [Elizabeth Wickes](https://ischool.illinois.edu/people/elizabeth-wickes) is a Lecturer 205 | at the School of Information Sciences at the University of Illinois at Urbana-Champaign. 206 | She teaches foundational programming from an information and data sciences perspective, 207 | as well as other coursework on open data and reproducibility. Her programming course 208 | lectures are written in Jupyter notebooks and the class is taught via live coding. 209 | 210 | ### Carol Willing {-} 211 | 212 | * Cal Poly San Luis Obispo 213 | * [willingc@gmail.com](mailto:willingc@gmail.com) 214 | * [\@WillingCarol](https://twitter.com/WillingCarol) 215 | 216 | [Carol Willing](https://www.willingconsulting.com/about/) is a Research Software Engineer 217 | at Cal Poly San Luis Obispo working full-time on [Project Jupyter](https://jupyter.org/). 218 | She is a Python Software Foundation Fellow and former Director; a Project Jupyter 219 | Steering Council member; and a core developer on CPython and Jupyter. Carol has an 220 | M.S. in Management from MIT and a B.S.E. in Electrical Engineering from Duke. 221 | 222 | ### Michael Zingale {-} 223 | 224 | * Stony Brook University 225 | * [Michael.Zingale@stonybrook.edu](mailto:Michael.Zingale@stonybrook.edu) 226 | * [\@Michael_Zingale](https://twitter.com/Michael_Zingale) 227 | 228 | [Michael Zingale](http://www.astro.sunysb.edu/mzingale/) is an Associate Professor 229 | and computational astrophysicist at Stony Brook University. 230 | He has a PhD from University of Chicago (2000). He frequently teaches 231 | [numerical methods](http://bender.astro.sunysb.edu/classes/numerical_methods/) and 232 | [Python for scientific computing](http://bender.astro.sunysb.edu/classes/python-science/) 233 | graduate courses, relying on Jupyter notebooks and python for much of the presentation. 234 | He is an advocate for open educational resources, as a founder of the 235 | [Open Astrophysics Bookshelf project](https://github.com/Open-Astrophysics-Bookshelf/) 236 | where he hosts his [_Introduction to Computational Astrophysical Hydrodynamics_](http://bender.astro.sunysb.edu/hydro_by_example/CompHydroTutorial.pdf) 237 | text. 238 | -------------------------------------------------------------------------------- /07-usage-case-studies.md: -------------------------------------------------------------------------------- 1 | # Usage case studies {#case-studies} 2 | 3 | Contributors to this chapter: you may increase adoption by new users 4 | if you integrate information about some of the following into your 5 | case: 6 | 7 | 1. Demonstrate that you can increase students' ability to: 8 | 1. Engage material & participate in class 9 | 1. Understand material and perform well 10 | 1. prep their for career 11 | 1. Enjoy learning this way 12 | 1. describe: 13 | 1. how it fits with how their students learn 14 | 1. how it connects to how they teach 15 | 1. the needed resources (support, hardware, etc.) 16 | 1. the necessary logistics (e.g., how much time will it take? Be honest: 17 | time is a consideration, and an important reason that people do not 18 | adopt new practices, but is not a reason that they stopped using one) 19 | 1. what Jupyter does in terms of promoting learning, instructor 20 | affordances 21 | 22 | 23 | ## Jupyter notebooks in support of scaling for large enrollments 24 | 25 | 26 | ### Supporting large enrollment courses at UC Berkeley 27 | 28 | The University of California at Berkeley started a pilot course titled 29 | "Foundations in Data Science" (also known as Data-8) for about 100 30 | incoming undergraduate students in Fall 2015. Data-8, the fastest 31 | growing course in Berkeley's history, is entirely Jupyter-based, 32 | allowing the program to scale the course to 1,400 students in 2018. 33 | This scale is made possible by Jupyter's shared computational 34 | environment. In particular, Jupyter allowed "browser-based 35 | computation, avoiding the need for students to install software, 36 | transfer files, or update libraries" (see The Course of the Future and 37 | the Technology Behind It 38 | [[https://data.berkeley.edu/news/coursefuture](https://data.berkeley.edu/news/coursefuture)]). Data-8 39 | is powered by JupyterHub and all the course materials are published 40 | openly ([http://data8.org](http://data8.org)). 41 | 42 | 43 | ### Large-scale adoption: Jupyter across Canada 44 | 45 | Recognizing the importance of data science, computational research, 46 | and educational resources, the [Pacific Institute for the Mathematical 47 | Sciences (PIMS)](https://www.pims.math.ca/), in partnership with 48 | [Compute Canada](https://www.computecanada.ca/) and 49 | [Cybera](https://www.cybera.ca/), have launched JupyterHub platforms 50 | (under the project name Syzygy) to support researchers and educators 51 | across Canada. Syzygy ([http://syzygy.ca](http://syzygy.ca)) provides 52 | access to cloud-hosted Jupyter resources using existing institutional 53 | credentials and encourages the development of computational and data 54 | science skills. It is currently accessible at 16 institutions across 55 | the country (McMaster, Queen's, SFU, UAlberta, UBC, UCalgary, 56 | ULethbridge, UNewBrunswick, UOttawa, URegina, USask, UToronto, UVic, 57 | UWashington (US), UWaterloo, Yorku) and has been used by over 11,000 58 | people at those institutions. 59 | 60 | Syzygy is extensively used for teaching, but is also being used for 61 | research activities. One notable example is a scientific software 62 | seminar at the University of British Columbia, where graduate students 63 | and post-doctoral researchers meet to share and learn data science 64 | techniques with their peers. Initiatives are also underway, as part of 65 | syzygy, to deepen its relevance into research by providing seamless 66 | access to larger and more varied types of resources (GPUs, parallel 67 | machines, different language kernels etc.). 68 | 69 | Callysto ([https://callysto.ca/](https://callysto.ca/)) is a related 70 | project, also launched by PIMS and Cybera, to bring Jupyter to 71 | students in Canadian middle and high schools (grades 5-12). Callysto 72 | focuses on creating and curating open content 73 | ([https://github.com/callysto](https://github.com/callysto)). This 74 | content forms the basis of project workshops, where teachers can work 75 | through the materials interactively, before taking them back to their 76 | classrooms. The content links to a supporting JupyterHub installation 77 | (integrated with the authentication systems for the networks of school 78 | districts) allowing easy access to the materials and a Jupyter 79 | environment to learn and create in. 80 | 81 | -- Ian Allison 82 | 83 | 84 | ### Quick switch: moving an existing course to Python and Jupyter (at the last minute) 85 | 86 | For many years, our chemical engineering kinetics course had used 87 | software for differential equation and nonlinear simultaneous equation 88 | solving to simulate reactors and solve design problems. The software, 89 | recommended and described by the textbook, was installed in the 90 | college's computer labs, but licenses for student-owned computers were 91 | expensive and it was only available for Windows. In Spring 2015, I 92 | was informed my class now had 52 students, but the largest computer 93 | lab had room for only 40. As the semester progressed and we neared the 94 | chapters that required numerical simulation, I rewrote the examples 95 | using Python and SciPy and created Jupyter notebooks, walking students 96 | through the steps involved in setting up and solving the problems. I 97 | found Lorena Barba's open-source MOOC materials online, and adapted 98 | these for my "getting started" notebooks. I had students install 99 | Anaconda on their own computers, and got everyone up and running 100 | without any central infrastructure or support from the college's IT 101 | staff. I found the Jupyter Notebook format of including "lecture note" 102 | style commentary along with short, unintimidating, snippets of code, 103 | to be extremely effective. A couple of years later I passed on the 104 | course to a new instructor, who took my course materials, taught 105 | himself some Python, and continued to use Jupyter notebooks for 106 | content delivery and assignments. 107 | 108 | The first year was a bit rough around the edges as I introduced it 109 | quite late in the semester. Still, it is clear that the approach 110 | resonated with students. An alumnus from my 2016 course wrote, "I 111 | thought that your course was very successful, especially the use of 112 | Jupyter Notebook as a classroom and assignment tool. I still remember 113 | specific problems that we went over in class (e.g., the microfluidic 114 | reactor array with heterogeneous catalysis), and I feel that the use 115 | of Python to solve problems throughout the course greatly benefited my 116 | understanding of fundamental concepts. I went on to use Python [in 117 | the pharmaceutical industry], where I built tools for bioinformatics 118 | data analysis, mutation network profiling for protein engineering 119 | experiments, and RNA structure prediction from experimental data and 120 | molecular thermodynamics." 121 | 122 | -- Richard West 123 | 124 | 125 | ## The "CFD Python" story: guiding learners at their own pace 126 | 127 | "CFD Python" is a collection of Jupyter notebooks based on a practical 128 | module that I began using in class in my Computational Fluid Dynamics 129 | (CFD) course at Boston University in 2009. The 5-week module develops 130 | worked examples that build on each other to incrementally guide the 131 | learner to create a program to solve the Navier-Stokes equations of 132 | fluid mechanics, in 12 steps. In 2013, I was invited to teach a 133 | mini-course in the Latin-American School in High-Performance 134 | Computing, in Argentina. The Jupyter notebooks platform allowed me to 135 | create a guided narrative to support learners with different 136 | background experience and knowledge. For that event, we wrote 137 | notebooks based on the CFD course module, to use as instructional 138 | scaffolding in the 2-full-days of minicourse. Twenty students worked 139 | through the notebooks as self-paced lessons, while I went from desk to 140 | desk asking and answering questions. About four of the students 141 | completed all the lessons in the 2 days, a bulk of them achieved up to 142 | about Step 8, and a few of them lagged behind in Steps 4 or 5 by the 143 | end of the course. For those who completed the full module, they had 144 | achieved in 2 days what my regular students in the classroom normally 145 | took 5 weeks to do. Seeing that was an eye-opening moment: both the 146 | power of worked examples in code, and the ability to allow learners to 147 | follow their own pace made a remarkable difference in these learners. 148 | 149 | _REF — Barba, Lorena A., and Forsyth, Gilbert F. (2018). CFD Python: 150 | the 12 steps to Navier–Stokes equations. Journal of Open Source 151 | Education, 1(9), 21, 152 | [https://doi.org/10.21105/jose.00021](https://doi.org/10.21105/jose.00021) 153 | _ 154 | 155 | Based on the experience developing the "CFD Python" learning module, 156 | we adopted this basic design pattern for creating lessons using 157 | computable content: 158 | 159 | 1. Break it down into small steps 160 | 1. Chunk small steps into bigger steps 161 | 1. Add narrative and connect 162 | 1. Link out to documentation 163 | 1. Interleave easy exercises 164 | 1. Spice with challenge questions/tasks 165 | 1. Publish openly online 166 | 167 | -- Lorena A. Barba 168 | 169 | 170 | ## Analyzing music with music21 171 | 172 | I became interested in learning more about Python in 2013 after 173 | reading a tutorial by Luciano Ramalho as he was writing Fluent 174 | Python. Since I tend to seek out projects that match my outside 175 | interests (music, art, and nature) I was looking for Python projects 176 | with music and came across Myke Cuthbert's music21 project. Music21, 177 | an open source music theory and analysis library maintained by 178 | Professor Michael Cuthbert at MIT, provides a set of tools to answer 179 | questions about music quickly and simply. Users can create, analyze, 180 | and share music with just a few lines of code. Myke's use of the 181 | notebook hooked me. Unlike many things that I had worked on before, 182 | the notebooks made it easy to get started and to write small code 183 | snippets that did real work! The more I used the notebooks and showed 184 | them to people that I taught at Fab Lab San Diego, the more that I saw 185 | the power of the notebook to engage a user and empower them to explore 186 | and learn. 187 | 188 | Music, a universal language, appeals to learners of all origins, ages, 189 | education levels, and interests. As a subject that casts a wide 190 | appeal, music offers the opportunity to engage and delight 191 | learners. It's an accessible subject that has a low barrier to entry 192 | for learners from disciplines beyond computer science and engineering. 193 | 194 | -- Carol Willing 195 | 196 | **Education benefits** 197 | 198 | * lessons notebooks can be tailored to age appropriate content within music 199 | * multisensory 200 | * ability in K12 to align with the standards 201 | * possibilities for bringing in multi-subject learning 202 | * writing 203 | * history 204 | * math 205 | * science 206 | * accessibility through audio and braille 207 | 208 | **Misc quotes (perhaps pick a couple?):** 209 | 210 | _"I think of music21 as being composed of two parts. The first is 211 | infrastructure, routines for reading, writing, and manipulating 212 | musical scores, while the second consists of a higher-level analytical 213 | toolkit—generating a Roman numeral from a chord and key, putting 214 | chords into normal form, checking for parallel fifths, identifying 215 | scales containing a given pitch or chord, and so on." —Bruce 216 | Tymoczko, Professor of Music, Princeton_ 217 | 218 | Inclusive 219 | 220 | _"It's not exclusive, but inclusive, which is the whole spirit of jazz." — Herbie Hancock_ 221 | 222 | Education 223 | 224 | _"So, you can't stay in one place, no matter how comfortable that 225 | place is. It's all about growing."—Mavis Staples_ 226 | 227 | Universal 228 | 229 | _"Music in the soul can be heard by the universe."—Lao Tzu_ 230 | 231 | Communication 232 | 233 | _Music is the greatest communication in the world. Even if people 234 | don't understand the language that you're singing in, they still know 235 | good music when they hear it."—Lou Rawls_ 236 | 237 | _"In the beginner's mind there are many possibilities. In the 238 | expert's mind there are few." –Shunryu Suzuki_ 239 | 240 | 241 | ## Interactivity in computer science (high school and middle school) 242 | 243 | **Who** 244 | 245 | High school and middle school students at Cal Poly SLO's EPIC program 246 | completed a two hour workshop on Interactivity in Computer 247 | Science. The workshop participants included dual language learners 248 | (English as a Second Language) and students who have had limited 249 | access to computers prior to the workshop. 250 | 251 | **Why** 252 | 253 | Providing early access to at-risk groups who may not see themselves as 254 | capable of learning to code or use computation 255 | 256 | Illustrate that there are many skills beyond math and science that are 257 | needed to create software applications 258 | 259 | **What** 260 | 261 | Two hour workshop that maximizes "hands on" exploration with the goal 262 | of building an ongoing interest in computer science 263 | 264 | * short lectures 265 | * interactive discussion - LISTEN 266 | * hands on - DO/APPLY This section is self-paced to engage different learning styles and prior knowledge 267 | * recap - DISCUSS 268 | * 8 or so projects with achievements outlined 269 | * modern curriculum including p5.js, jupyter, binder, deep learning 270 | and machine learning with TensorFlow and Magenta (art and music) 271 | * Goal is to empower students to understand that they CAN use CS to 272 | solve real world problems 273 | 274 | Instructor Approach 275 | 276 | * Start with high quality engaging content 277 | * Self contained notebooks 278 | * Use widgets to add additional interactivity 279 | 280 | 281 | ## Interactive geophysics with Jupyter 282 | 283 | The GeoSci.xyz project ([https://geosci.xyz](https://geosci.xyz)) is 284 | an effort to develop a community of scientists and educators around 285 | learning resources and software for the geosciences. The project 286 | includes multiple open-source textbooks, each which have associated 287 | Jupyter notebook "apps" that serve as interactive simulation engines 288 | for exploring concepts in geophysics. We have used these resources in 289 | an undergraduate course on applied geophysics at the University of 290 | British Columbia; this course is primarily taken by by geologists and 291 | engineers (non-geophysics majors). In 2017, we delivered a 2 day short 292 | course for professionals, graduate students, and researchers in 26 293 | different countries around the world 294 | ([https://disc2017.geosci.xyz](https://disc2017.geosci.xyz)). In both 295 | of these courses, the goal is to provide learners with an overview of 296 | the various geophysical methods (e.g. magnetics, gravity, seismic, 297 | electromagnetics) and concepts governing the physics; we do not dive 298 | into details of the math nor do we expect students to program or write 299 | any lines of code. The role of Jupyter notebooks in these courses is 300 | to serve as a tool for visualizing and exploring the physics. 301 | 302 | During a lecture, the notebooks as a presentation medium lend to a 303 | dynamic presentation style, where we as instructors can select model 304 | parameters based on student input. Concepts are reinforced as students 305 | then use these same notebooks in labs and assignments. We have found 306 | that the notebook apps are most effective when students are first 307 | asked to critically think about what they expect to see and then 308 | visualize the result. If the resultant image matches their 309 | expectation, then they understand the concept, and if not, it is an 310 | opportunity to learn and further explore. 311 | 312 | -- Lindsey Heagy 313 | 314 | ![Notebook "app" for exploring the direct current resistivity experiment over a 315 | two layer earth 316 | ([https://em.geosci.xyz/apps.html](https://em.geosci.xyz/apps.html)).](images/DC-layered-earth-app.png "DC resistivity") 317 | 318 | 319 | ## Investigating hurricanes 320 | 321 | **Who** 322 | 323 | Middle school and high school students visiting Columbia's School of 324 | Engineering and Applied Sciences on a field trip 325 | 326 | **Why** 327 | 328 | Students often come through looking to tour labs and experience some 329 | of the research that is being done at the school. Unfortunately 330 | certain fields, in this case computational mathematics and hurricane 331 | research, do not lend themselves to these types of events. 332 | 333 | **What** 334 | 335 | Instead of a lab or lecture a computer lab was reserved for an hour 336 | and a Jupyter notebook used to walk students through some basic 337 | visualizations and data analysis encouraging students to change the 338 | code displayed to answer questions such as "Where did Hurricane Sandy 339 | go?" and "What storms occurred during 1981?". This includes a number 340 | of visualizations of hurricane tracks, coloring by strength of storms, 341 | and an analysis of average number of storms per year. Notebook is 342 | available at https://github.com/applied-math/demos. 343 | 344 | -- Kyle T. Mandli 345 | 346 | 347 | 348 | ![Visualization from the notebook at 349 | [https://github.com/applied-math/demos](https://github.com/applied-math/demos) 350 | demonstrating the paths of Atlantic hurricane tracks from 1950-2012 351 | with coloring demonstrating category of storm.](images/hurricanes.png 352 | "Image frome https://github.com/applied-math/demos") 353 | 354 | 355 | ## Riemann Problems and Jupyter Solutions 356 | 357 | We first envisioned this project as a teaching aid to interactively illustrate difficult concepts for a graduate course in numerical methods for conservation laws. These are physical laws in the form of first-order hyperbolic partial differential equations that arise in wave propagation applications such as fluid dynamics, traffic flow, water waves (like tsunamis), and electromagnetic waves among others. The Riemann problem corresponds to a conservation law with a piecewise constant initial condition such that the problem is relatively simple to solve, while still capturing the characteristic dynamics of the conservation law. Due to its discrete nature, its simplicity and its capability to encode the dynamics, the Riemann problem is the key ingredient in modern numerical methods for conservation laws. 358 | 359 | The project naturally evolved into Jupyter notebooks with the idea of compiling an interactive book. Each chapter aims to solve the Riemann problem for a specific application such as acoustics, shallow-water equations, and Euler equations. We further wanted to use our book to encourage the reading and publication of interactive notebooks. Therefore, we decided that our book should also have a printed and an HTML version in addition to notebooks available for downloading, to attract more readers and to encourage more authors and publishers to explore this interactive platform. 360 | 361 | As one would expect, several new problems arose regarding how to make a book that is somewhat compatible across all the different platforms in which we wanted to present the book, particularly since the notebooks make heavy use of interactive widgets and animations. With the help of our publisher (SIAM) and several developers working on Jupyter-based tools for publishing interactive books, we are close to finalizing the project. We are happy to say that this project promoted the development of some of these tools and that is encouraging our publisher to delve more into interactive book publication. 362 | 363 | This book should be completed in the next few months, and the current state can be viewed at http://www.clawpack.org/riemann_book/index.html. 364 | 365 | -- David I. Ketcheson, Randall J. LeVeque, and Mauricio J. del Razo 366 | 367 | ![Visualization from the acoustics equations chapter of the book at 368 | [https://github.com/clawpack/riemann_book](https://github.com/clawpack/riemann_book) 369 | It shows an interactive visualization of the solution to the Riemann problem for acoustics equations, where the initial condition emulates a shock tube.](images/shocktube.png) 370 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /02-why-jupyter.md: -------------------------------------------------------------------------------- 1 | # Why we use Jupyter notebooks 2 | 3 | 4 | ## Why do we use Jupyter? 5 | 6 | As teachers we are responsible for many activities, including creating lessons, 7 | lectures, courses, assignments, and supportive environments; encouraging 8 | engagement and performance in the classroom; helping students learn to think 9 | critically so they can become lifelong learners and problem solvers; making 10 | material relevant and meaningful to students' diverse interests and backgrounds; 11 | assessing student learning (including grading and evaluation); encouraging 12 | students to persist with emotional labor (feedback, communication, etc.); and 13 | trying out teaching and learning practices that improve our ability to do all of 14 | these things. 15 | 16 | In short, we design learning environments and experiences. 17 | 18 | We use Jupyter notebooks to design learning environments to help support these 19 | activities. We believe that incorporating Jupyter notebooks in our teaching has 20 | allowed us to improve students' understanding of course content, increase 21 | student engagement with material and their participation in class, and to make 22 | concepts more meaningful and relevant to students' diverse interests. We 23 | represent a variety of disciplines and have many diverse instructional goals, 24 | all of which have been supported using Jupyter notebooks. The goal of this 25 | handbook is to provide you with ideas to help you address your own instructional 26 | and pedagogical goals. 27 | 28 | Through a series of anecdotes we will illustrate how you, as an educator, can 29 | use Jupyter notebooks to increase your students' 1) engagement, 2) 30 | participation, 3) understanding, 4) performance, and 5) preparation for their 31 | career. These are starting places and we are confident that you will also take 32 | these examples in new and exciting directions. 33 | 34 | 35 | ## But first, what is Jupyter Notebook? 36 | 37 | Project Jupyter is three things: a collection of standards, a 38 | community, and a set of software tools. Jupyter Notebook, one part of 39 | Jupyter, is software that creates a Jupyter notebook. 40 | A Jupyter notebook is a document that supports mixing executable code, equations, 41 | visualizations, and narrative text. Specifically, Jupyter notebooks allow 42 | the user to bring together data, code, and prose, to tell an 43 | interactive, computational story. Whether analyzing a corpus of American 44 | Literature, creating music and art, or illustrating the engineering concepts 45 | behind Digital Signal Processing, the notebooks can combine explanations 46 | traditionally found in textbooks with _the interactivity of an application_. 47 | 48 | ![A Jupyter notebook, starting with a markdown cell containing a title and an explanation (including an equation rendered with LaTeX). Three code cells produce the final inline plot.](images/Fig_notebook.png) 49 | 50 | 51 | 52 | Jupyter is a free, open source platform that is an excellent learning 53 | environment for students. For teachers, it increases our efficiency and 54 | decreases cognitive load so we can engage students. Notebooks can be useful for 55 | achieving your goals as a teacher in numerous environments from STEM labs or 56 | humanities narratives, to podium lectures or flipped classrooms. We use Jupyter 57 | notebooks in small classes and for classes that have hundreds of students. 58 | Jupyter notebooks can be used for teaching part of one lecture or can be used to 59 | teach a whole course. Jupyter notebooks enable us and our students to have a 60 | conversation with a problem and link to resources, like audio, video, images, 61 | visualizations--and even allow students to mix and remix these. And yet students 62 | need to install nothing beyond a modern web browser to use this free software. 63 | 64 | Jupyter notebooks can be used to organize classroom materials and objects, store 65 | and provide access to reading materials for students, present and share lecture 66 | materials, perform live coding, explore and interact with materials, support 67 | self-paced learning, grade students' homework, solve homework problems, or make 68 | materials reusable to others (see Chapters 3 and 4). 69 | 70 | Read on to find out how we have used Jupyter notebooks for teaching and learning 71 | to benefit both our students and ourselves. Jupyter notebooks support a wide 72 | range of learning goals, including learning to program, learning domain 73 | knowledge, and practicing communication skills like storytelling. The authors of 74 | this book have used Jupyter notebooks to teach: 75 | 76 | * Sciences 77 | * Physics and astronomy 78 | * Geoscience 79 | * Biology 80 | * Cognitive science 81 | * Computer science 82 | * Data science 83 | * Statistics 84 | * Social sciences 85 | * Writing 86 | * Writing seminar 87 | * Writing and technical communication 88 | * Digital Humanities 89 | * Music 90 | * Text analysis 91 | * Metadata processing 92 | * Engineering 93 | * Chemical engineering (kinetics and reactor design) 94 | * Mechanical engineering 95 | * Aerospace engineering 96 | * Introduction to Programming 97 | * High school 98 | * College and university-level courses (true introductions through advanced courses) 99 | 100 | Our other use of notebooks for education include: 101 | 102 | * Building models/simulations (with and without programming) 103 | * Using widgets to demonstrate and interact with simulations 104 | * Visualizations of process and data 105 | 106 | 107 | ## Course benefits & anecdotes 108 | 109 | 110 | ### Engagement 111 | 112 | As teachers we routinely struggle to engage our students, especially when we are 113 | constrained by the format of the course (e.g., online, 50-minute lecture), 114 | available technologies, students distractions, and/or other factors. 115 | Nevertheless, it is substantially our responsibility to create environments and 116 | experiences within these limits that engage students in our courses. This is 117 | where notebooks can give you another tool to break out of the mundane, and get 118 | students engaged in their learning. 119 | 120 | 121 | #### Conversations with data 122 | 123 | The creators of Jupyter describe it as a set of open-source tools for 124 | interactive and exploratory computing, and a platform for creating computational 125 | narratives. Jupyter allows us, as educators, to narrate a "conversation between 126 | the student and data". Consider this example, using the data of life expectancy 127 | of many countries over the years: 128 | 129 | > I use a short bit of code to make a graph showing the time evolution, in what 130 | > is called a "spaghetti plot" (see figure). Looking at this messy graphic, I 131 | > point out how most of the lines show growth over time: life expectancy is 132 | > improving all over the world. But a couple of lines show a marked dip in a 133 | > given year. I can ask students: which country had that dip? What happened 134 | > there? Why? With a bit more coding, we identify that Cambodia had a shocking 135 | > life expectancy of about 30 years in 1977, and Rwanda had even worse life 136 | > expectancy in 1992. We then have the opportunity to discuss why these 137 | > countries experienced a mortality crisis. The data brings to life a meaningful 138 | > discussion, with many possible paths involving history, politics, economics, 139 | > and health. -- Lorena Barba 140 | 141 | ![From: [http://go.gwu.edu/engcomp2lesson4](http://go.gwu.edu/engcomp2lesson4)](images/engcomp2lesson4-life-expectancy.png "Life expectancy in the years 1952-2007, across 142 countries") 142 | 143 | Jupyter notebooks are essential tools of connection---tools that engage 144 | learners in transitions in their thinking. The opportunity of intermingling 145 | computation into a narrative, creating a conversation with data is a powerful 146 | and effective form of communication. With Jupyter, you now have a new form of 147 | content to create and share with learners: _computable content_. In a world 148 | where every subject matter can have a data-supported treatment, where 149 | computational devices are omnipresent and pervasive, the union of natural 150 | language and computation creates compelling communication and learning 151 | opportunities. 152 | 153 | 154 | ### Participation 155 | 156 | Engaging students in your courses requires their participation and interaction 157 | with you, their peers, and/or the content [@moore1989three]. How, when, and 158 | why you use student participation in yours will, of course, depend on your 159 | goals, the specific objectives for teaching the content within your course, your 160 | students, and other factors. Using notebooks, however, encourages participation 161 | and gives you more tools for promoting participation. Notebooks can connect 162 | students to authentic external audiences as well. Students can, for example, 163 | consume notebooks from other classes, and publish notebooks where others can 164 | read them. 165 | 166 | 167 | #### Real world experience -- bringing concepts to life 168 | 169 | Notebooks are living documents, meaning they can be edited to respond to 170 | questions or input from students and used a conversation piece during a lecture 171 | or presentation. 172 | 173 | 174 | > Our group uses Jupyter notebooks as "apps" to demonstrate concepts in 175 | > geophysics. These notebook-apps connect numerical simulations to widgets and 176 | > relevant plots. In the classroom, we ask students to help define input 177 | > parameters based on an application or case study that they are interested 178 | > in. Prior to displaying the results, we ask students to build a mental image 179 | > of their expectations. If the resultant image matches their expectations, then 180 | > we have reinforced a concept, and if not, it is an opportunity to learn. We as 181 | > instructors can interactively engage with students' questions by updating the 182 | > inputs to the simulation in order to explore concepts with them. Students have 183 | > access to the same notebooks through free web-platforms like Binder, so simply 184 | > by following a link, they can take the steering wheel and engage with the 185 | > concepts on their own. Notebooks bring the concepts to life and serve as a 186 | > conversation piece for the interaction between learners and educators. -- 187 | > Lindsey Heagy 188 | 189 | ![Dr. Douglas Oldenburg (left) engaging with a student during a short course on geophysical electromagnetics (https://geosci.xyz). Photo credit: Seogi Kang](images/oldenburg-geosci.jpg "Photo credit: Seogi Kang") 190 | 191 | #### Real world experience -- Ticket to leave 192 | 193 | Another example of generating participation in the classroom with Jupyter 194 | notebooks is the Activity magic, available as an extension. It creates what has 195 | been called a "ticket to leave" (or "exit ticket") via the notebook. The idea of 196 | a "ticket to leave" is an excellent way to end a class or lab. Briefly, it is 197 | just a survey that you give the students (see figure). Often, these surveys are 198 | given via a Personal Response System (also known as "clickers" or PRS) or cell 199 | phones. There are a few uses of such surveys: 200 | 201 | 1. Give the instructor some feedback on the students' understanding, as a whole 202 | 1. Provide time and opportunity for students to review and synthesize today's 203 | materials 204 | 1. Allow the students to apply their recent knowledge to a novel problem 205 | 1. An additional instance to learn the materials 206 | 207 | ![Example of the Activity magic seen from the students view. A question, with multiple choice answers is shown, with buttons for their input.](images/activity-magic-student.png "Example of the Activity magic seen from the students view.") 208 | 209 | These questions do not typically require much time to answer, but are meant to 210 | capture the essence of the conversation of the class. After a minute or so to 211 | contemplate the question, the students select their answer (by clicking one of 212 | the buttons), and instructor shows the gestalt results (see figure). 213 | 214 | ![The Activity magic, from the the instructor's perspective. The barchart is shown on the projector once all of the students have had a chance to respond.](images/activity-magic-instructor.png "The Activity magic, from the the instructor's perspective.") 215 | 216 | Good "exit ticket" questions can be domain specific questions, but can also be 217 | metacognitive questions (about one's learning style, for example), or high-level 218 | organizational questions (e.g., "what was the goal of today's discussion?"). We 219 | recommend leaving enough time at the end of class (perhaps 10 minutes) to have a 220 | full and complete wrap-up discussion. After the discussion, you may wish to 221 | adjust the following class meeting if you feel that not enough students had the 222 | insight you were aiming for. For more information on "tickets to leave" see 223 | [https://www.brown.edu/sheridan/teaching-learning-resources/teaching-resources/course-design/classroom-assessment/entrance-and-exit/sample](https://www.brown.edu/sheridan/teaching-learning-resources/teaching-resources/course-design/classroom-assessment/entrance-and-exit/sample). 224 | For more on the Jupyter Notebook extension, see 225 | [using](https://github.com/Calysto/metakernel/blob/master/metakernel/magics/README.md#activity) 226 | and [installing](https://github.com/Calysto/metakernel#use-metakernel-magics-in-ipython) 227 | Calysto Activity magic. 228 | 229 | 230 | 231 | ### Increasing understanding 232 | 233 | Within any course you will typically try to achieve a diverse set of objectives. 234 | Benjamin Bloom (https://en.wikipedia.org/wiki/Bloom%27s_taxonomy) provided a 235 | framework for the detailed objectives we want to achieve, ranging from basic 236 | knowledge (such as, terminology, specific facts, trends and sequences, 237 | classifications and categories, etc.) all the way to ability to evaluate and 238 | create (such as, abstract relationships, judgments but based criteria, original 239 | works). Achieving the former (i.e., basic knowledge and comprehension) is far 240 | easier to achieve than understanding (i.e., evaluation and creation); yet, most 241 | often we, as educators, are striving for increasing the complex understanding of 242 | our students on the topics we are teaching. The good news is that notebooks 243 | offer a valuable tool for teaching toward understanding -- moving students, for 244 | example, from passively viewing course content to exploring, analyzing, 245 | synthesizing, and evaluating the content in active ways. 246 | 247 | 248 | #### Real world experience -- Guiding learners at their own pace 249 | 250 | The fundamental theory behind Computational Fluid Dynamics (CFD) used in 251 | Aerospace Engineering is based on understanding the Navier-Stokes equations. 252 | "CFD Python" is a collection of Jupyter notebooks based on a practical module 253 | that Lorena Barba began using in class in her Computational Fluid Dynamics (CFD) course at 254 | Boston University in 2009. The 5-week module develops worked examples that build 255 | on each other to incrementally guide the learner to create a program to solve 256 | the Navier–Stokes equations of fluid dynamics, in 12 steps. 257 | 258 | 259 | > In 2013, I was invited to teach a 2 day mini-course in the Latin-American 260 | > School in High-Performance Computing, in Argentina. The Jupyter notebooks 261 | > platform allowed me to create a guided narrative to support learners with 262 | > different background experience and knowledge. For that event, we wrote 263 | > notebooks based on the CFD course module, to use as instructional scaffolding 264 | > in the minicourse. Twenty students worked through the notebooks as self-paced 265 | > lessons, while I went from desk to desk asking and answering questions. About 266 | > four of the students completed all 12 steps in the 2 days, a bulk of them 267 | > achieved up to about Step 8, and a few of them lagged behind in Steps 4 or 5 268 | > by the end of the course. For those who completed the full module, they had 269 | > achieved in 2 days what my regular students in the classroom normally took 5 270 | > weeks to do. Seeing that was an eye-opening moment: both the power of worked 271 | > examples in code, and the ability to allow learners to follow their own pace 272 | > made a remarkable difference in these learners. -- Lorena Barba 273 | 274 | Based on the experience developing the "CFD Python" learning module [@barbacfd], 275 | this basic design pattern was adopted for creating lessons using computable 276 | content: 277 | 278 | 1. Break it down into small steps 279 | 1. Chunk small steps into bigger steps 280 | 1. Add narrative and connect 281 | 1. Link out to documentation 282 | 1. Interleave easy exercises 283 | 1. Spice with challenge questions/tasks 284 | 1. Publish openly online 285 | 286 | This was particularly helpful for student understanding. 287 | 288 | 289 | ### Increasing student's performance 290 | 291 | The goal of learning is often actualized through the performance of students. 292 | This is routinely most visible by what we attempt to assess during and at the 293 | end of instruction. Using notebooks we can create a variety of a performance 294 | opportunities for students, thereby giving them more opportunities for practice 295 | and feedback, as well as more opportunities for us, as instructors, to 296 | assess their ability to perform. 297 | 298 | 299 | #### Real world experience -- The worked-example effect 300 | 301 | The worked-example effect is the best known and most widely studied of the 302 | cognitive load effects [@sweller2006worked]. It refers to providing full 303 | guidance on how to solve a problem, resulting in better student performance than 304 | problem-solving conditions with no guidance. For complex tasks, inexperienced or 305 | beginner learners benefit the most from the worked-examples procedure. One study 306 | [@chen2015worked] concludes that: "worked example effect occurs for complex, 307 | high-element interactivity materials that impose a heavy working memory load" 308 | and "when dealing with complex material that learners may have difficulty 309 | understanding, high levels of guidance are likely to result in enhanced 310 | performance over lower levels of guidance." This research-based guidance seems 311 | especially relevant for teaching novice programmers to use computation in the 312 | context of their subject matter (science, engineering, or other). 313 | 314 | 315 | ### Increasing students' preparation for their career 316 | 317 | In preparing students to apply what they have learned, striving to align what 318 | happens in the course with what they will experience in their career is 319 | important. From using parallel software to mirroring workflows, we want our 320 | students to experience and be prepared for the workplace. Recognizing, of 321 | course, that workplaces are not static and the skills required for a career are 322 | always emerging, using notebooks provides a flexible platform to build skills 323 | and build portfolios of what students can do. 324 | 325 | 326 | #### Real world experience -- Publishing a data narrative as a demonstration of industry ability 327 | 328 | For Data Science careers, a publicly shared narrative about a data analytics 329 | project goes a long way at demonstrating the student's potential at an 330 | interview. Elizabeth Wicks has her students develop a Jupyter notebook that 331 | tells the story of a data munging and analysis project done in the class. The 332 | students then publish this notebook to their Github profile pages. Being that 333 | Jupyter is one of the most popular ways in industry to communicate data science 334 | results, the students have a very valuable key to a potential career. 335 | 336 | TODO: Add quote from Elizabeth 337 | 338 | 339 | ## Student benefits 340 | 341 | Creating opportunities for students to develop as learners stretch beyond the 342 | boundaries of any specific course where you may use notebooks. By enriching 343 | their learning experience in your course, you will help them develop valuable 344 | skill-sets and mind-sets that they will take with them into other courses and 345 | into their career. 346 | 347 | 348 | ### Computational thinking 349 | 350 | Jupyter notebooks support a wide range of learning goals. Its interactivity 351 | enables building intuitive understanding of domain knowledge, such as the 352 | understanding of a mechanical response of a system while varying parameters or 353 | understanding how an algorithm behaves. Notebooks can also help teach effective 354 | communication skills, combining prose with graphics into a strong narrative. 355 | Finally, notebooks can support teaching or strengthening programming skills, by 356 | combining code with text descriptions and visualizations. Even if a notebook is 357 | designed to be consumed passively, the exposure to code helps show students how 358 | to do something—and that they can do it themselves. This also helps demystify 359 | coding for students who do not view themselves as traditional "computer science" 360 | types. 361 | 362 | Using notebooks, you can create rich learning experiences that link together the 363 | core foundations of computational thinking: 364 | 365 | * _Decomposition_: Breaking down data, processes, or problems into smaller, manageable parts 366 | * _Pattern Recognition_: Observing patterns, trends, and regularities in data 367 | * _Abstraction_: Identifying the general principles that generate these patterns 368 | * _Algorithm Design_: Developing the step by step instructions for solving 369 | this and similar problems 370 | 371 | ### Open-source 372 | 373 | Integrating notebooks into classes also exposes students to a large and growing 374 | ecosystem of open-source tools. This supports their education, but also provides 375 | experience in the same environment of tools used in industries in high demand 376 | for trained employees, such as data science and machine learning. The 377 | open-source nature of these tools also ensures that course content remains 378 | accessible and affordable to all students—including those outside the 379 | traditional university environment. 380 | 381 | Unlike proprietary notebook technologies such as Mathematica, or specific 382 | programming languages/environments such as Matlab or C++, the barriers to entry 383 | for students learning with Jupyter notebooks can be extremely low. At a minimum, 384 | during a lecture, students can simply watch/read an interactive demo using a 385 | notebook, to replace slides or lecture notes. On their own, using a cloud 386 | service such as Binder or JupyterHub, students can open any modern web browser 387 | to some address and interact with a notebook (an example of this technology can 388 | be found at ), without 389 | needing any installation or configuration. In the most complicated case, 390 | students can install Anaconda and follow simple instructions to install the 391 | Jupyter Notebook, which works and looks the same on all platforms—and is free 392 | and open source. 393 | 394 | 395 | ### Active learning 396 | 397 | Thanks to their interactivity, notebooks enable a spectrum of active learning 398 | methods, which have been shown to increase performance in science, engineering, 399 | and mathematics [@freeman2014active]. To start, students can consume notebook 400 | content by reading and running notebooks, then move to editing or completing 401 | notebooks as assignments. This allows students to focus on the content and 402 | concepts, rather than just note-taking. 403 | 404 | At the top of Bloom's Taxonomy is pure creation, where students can, for 405 | example, author complete computational essays. In both cases, notebooks support 406 | courses where students have a wide range of experience and ability: students who 407 | need help can rely on the scaffolding of prose explanations and existing code, 408 | while also providing room to stretch and explore for more-experienced students. 409 | The additional annotation and prose that accompanies code also helps support 410 | non-traditional learners and students from underrepresented groups who may have 411 | less initial experience/comfort with programming. 412 | 413 | Instilling the habits of active learning, through the use of notebooks, will 414 | also provide benefits beyond the boundaries of your course. Interactivity drives 415 | engagement, interest, and exploration of concepts. Engaged students in your 416 | course are more likely to be engaged learners in other courses and beyond. 417 | 418 | 419 | ## Instructor benefits 420 | 421 | Notebooks can be adopted at a variety of levels and formats, offering 422 | flexibility based on the needs of a course and comfort/interest level of the 423 | instructor: in-class demos, interactive labs, auxiliary material (e.g., book 424 | replacements, lecture note supplements), assignments, or full course content in 425 | a flipped learning environment. Notebooks offer a route to active learning 426 | methods for instructors without experience of them, but do not force a 427 | particular teaching style. 428 | 429 | At a minimum, notebooks can be used to make publishable and interactive lecture 430 | notes that blend narrative text, images, videos with image and results to 431 | present the concepts. Furthermore, these course materials can be developed 432 | gradually, starting with a low-effort draft to a more-polished, publishable 433 | document that can be easily extended over time—and adopted by others. The growth 434 | of open-source communities around software tools and educational resources 435 | creates more opportunities for the re-use and adaptation of existing resources. 436 | 437 | While many notebook authors do use Python, the Jupyter Notebook supports many 438 | languages, so students (and instructors) are not tied to one specific language. 439 | Indeed, the name Jupyter comes from three languages: Julia, Python, and R. 440 | Furthermore, these (free) tools have minimal barriers to entry—using a cloud 441 | infrastructure means students and instructors do not have to install anything, 442 | while in the "worst" case installations require a few command-line excursions, 443 | but these are free, openly available, and cross-platform. 444 | 445 | 446 | ## Conclusions 447 | 448 | We hope that this chapter has illustrated that teaching with Jupyter notebooks 449 | can be valuable for you and your student. We have shown notebooks to be a tool that 450 | can increase student engagement, participation, understanding, performance, and 451 | preparation for their careers. These are substantial accomplishments that can be 452 | achieved in a variety of disciplines and content areas. Using several real world 453 | examples, we attempted to illustrate the numerous ways teachers are using 454 | notebooks. Hopefully these, when combined with the chapters that follow, will 455 | guide you in 1) supporting your students' learning, 2) giving you confidence 456 | that you can use notebooks, 3) help you understand the necessary logistics, and 457 | 4) help give you clear expectations of what can be accomplished with Jupyter 458 | notebooks. 459 | -------------------------------------------------------------------------------- /apa.csl: -------------------------------------------------------------------------------- 1 | 2 | 776 | -------------------------------------------------------------------------------- /05-jupyter-ecosystem.md: -------------------------------------------------------------------------------- 1 | # Jupyter Notebook ecosystem {#jupyter} 2 | 3 | ## Language support: kernels 4 | 5 | The Jupyter system supports over 100 programming languages (called 6 | "kernels" in the Jupyter ecosystem) including Python, Java, R, Julia, 7 | Matlab, Octave, Scheme, Processing, Scala, and many more. Out of the 8 | box, Jupyter will only run the IPython kernel, but additional kernels 9 | may be installed. Language support continues to be added 10 | by the open source community and the best source for an up-to-date list is the wiki page maintained by the project: 11 | [https://github.com/jupyter/jupyter/wiki/Jupyter-kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). 12 | These projects 13 | are developed and maintained by the open source community and exist in 14 | various levels of support. Some kernels may be supported 15 | by a vast number of active (and even paid) developers, while others 16 | may be a single person's pet project. When trying out a new kernel, we 17 | suggest exploring a kernel's community of users and documentation to 18 | see if it has an appropriate level of support for your (and your 19 | students') use. 20 | 21 | Jupyter's kernel flexibility allows instructors to pick the right 22 | language for a particular context. For example instructors may use 23 | Python to teach programming, while switching to R to teach statistics, 24 | and then perhaps Scala to teach big-data processing. Regardless of the 25 | language chosen, the Jupyter interface remains the same. Thus, some 26 | cognitive load can be lessened when using multiple languages within or 27 | across courses (e.g., the user interface stays the same between 28 | the student's Digital Humanities and Biology courses). 29 | Students often appreciate consistent use of the same language within a course, however. 30 | 31 | ## Using Jupyter notebooks 32 | 33 | When using Jupyter notebooks on the data projector or large screen 34 | monitor in the classroom, we recommend giving the students specific 35 | instructions on the meaning of the user interface of the notebook. It 36 | is not exactly intuitive. 37 | 38 | The first and most salient component of the notebook is the 39 | *cell*. Indeed, the entire contents of a notebook is composed of 40 | only cells. These cells can take one of two forms: text or code. We 41 | will descibe the authoring of a notebook in the following section; 42 | however, here we identify some of the subtle, yet important components 43 | of a code cell. 44 | 45 | Code cells are composed of three areas: the **input** area, the 46 | **display** area, and the **output** area. The input area is identified by 47 | the `In []:` prompt to the left of the cell. Between the brackets of 48 | the `In` prompt can be one of three items: a number, an asterisk, or a 49 | blank. A number indicates that this cell has been executed and the 50 | value of the number indicates the order of execution. For example, 51 | normally, after you execute the first cell after opening a notebook, 52 | its prompt will read `In [1]:`. 53 | 54 | ```{block2, type='rmdnote'} 55 | Pro Tip 56 | 57 | When teaching with notebooks, you often will want to refer to a cell 58 | my name. You could refer to a cell by its input prompt 59 | number. However, keep in mind that this number will change if you 60 | excecute the cell again, or that students may have different numbers 61 | if they, too, are executing their own copy of the notebook. A better 62 | way of referring to a cell may be to refer to the text right above the 63 | cell as that won't change while you execute cells. For referring to 64 | lines of code, see the following section on Tips and Tricks. 65 | ``` 66 | 67 | Before executing a cell, the input prompt number area will be 68 | blank. Therefore, you can tell at a glance that that cell has not been 69 | executed yet. It may also be the case that if an input prompt does 70 | have a number in it, then the cell has been run in the past. However, 71 | the cell may not have been run during this session, and thus the 72 | output may be showing old results. We recommend running from the menu: 73 | `Cell`, `All outputs`, `Clear` at the beginning of a 74 | presentation. That initializes all cell inputs to the blank state. 75 | 76 | During the execution of a cell, the input prompt will contain an 77 | asterisk. If it seems that too much time has passed and you still see 78 | `In [*]:` your code may be in an infinite loop, or you have lost 79 | communication with the kernel. You may have to interrupt or restart 80 | the kernel. This is discussed below. 81 | 82 | Finally, it is important to keep separate the display and output areas 83 | below the input cell. The difference between these two areas is subtle 84 | and confusing, but is very important in some instances. The display 85 | area is reserved for any item that code has produced for viewing. That 86 | includes simple text (i.e., `print("hello, world")`) or figures from a 87 | plot. The output area is reserved for items that the cell "returns." 88 | This is why in many notebooks you may see a variable assignment 89 | followed immediately by the variable, like this: 90 | 91 | ```python 92 | x = 2434 + 33476 93 | x 94 | ``` 95 | 96 | In this example, you wouldn't actually see the value computed unless 97 | you print it to the display area, or return the value. Here, we return 98 | it as the last value of the cell. 99 | 100 | ```{block2, type='rmdimportant'} 101 | Keep in mind that the bottom portion of the notebook on the screen or 102 | monitor may not be visible to students in the back of the room. Make 103 | sure that the font size is large enough, and that you don't go too fast 104 | when demonstrating code that students don't have access to. We also 105 | recommend that you hide the Jupyter toolbar and header to get more 106 | room for the actual notebook (select `Toggle Header` and `Toggle View` 107 | under the Jupyter `View` menu). 108 | ``` 109 | 110 | ## Authoring Jupyter notebooks 111 | 112 | 113 | Before embarking on writing notebooks for your course, we recommend 114 | that you look around on the internet for related courses. 115 | A similar course for which an instructor has already generated 116 | notebooks could exist for you to use or adapt for your course. 117 | Notebook authors often are happy to collaborate on open source 118 | educational resources or have their resources be used by other 119 | instructors. The following sections focus on Python 120 | simply because it is currently the language with the largest Jupyter 121 | feature support. 122 | 123 | 124 | ### Accessing documentation in the notebook {#accessing-documentation-in-the-notebook} 125 | 126 | One of the best features of quality libraries is their documentation, 127 | which students and other users will likely consult regularly. From a 128 | notebook cell, the TAB key autocompletes (or gives completion tips) 129 | and SHIFT-TAB brings up full documentation. Similarly, using a 130 | question-mark after a method or function will bring up the 131 | documentation after the cell is run, as shown in Figure 5.1. 132 | 133 | 134 | ![A question mark used after a method or function brings up the documentation after executing the cell.](images/chapter50.png "getting help") 135 | 136 | Using this feature in class during live coding or 137 | while explaining how code works helps make students comfortable 138 | of working effectively with libraries. 139 | 140 | 141 | ### Widgets {#widgets} 142 | 143 | Widgets provide the opportunity for learners and instructors to 144 | interact with code outputs, such as charts and tables. 145 | Widgets are "mini" 146 | Graphical User Interfaces (GUI) that give the notebook user access to 147 | slide bars, toggle buttons, and text-boxes. They can be used in 148 | conjunction with code, allowing a change of mindset from programming 149 | as a primary goal to exploring a model or computation as the primary 150 | goal. Alternatively, the code can be hidden and the widgets used to 151 | create a notebook "app" that might connect input parameters with a 152 | simulation and a plot. 153 | 154 | Currently, only a small subset of kernels have widget 155 | functionality. The reference implementation of widgets 156 | are the Jupyter-Python widgets 157 | ([https://ipywidgets.rtfd.io](https://ipywidgets.rtfd.io)). It 158 | includes widget components to generate and display sliders, progress 159 | bars, text boxes, check boxes, toggle buttons, etc. Many popular 160 | visualization tools, such as Matplotlib, Plotly, leaflet.js, three.js, 161 | have Jupyter-Python widget implementations. The documentation contains 162 | an up-to-date list of all of the widgets and their 163 | variations. The `interact` method allows you to 164 | wrap a function, which might be a simple computation or a complex 165 | simulation that produces a plot, and provides widgets for each of the 166 | inputs to the function. Figure 5.2 shows a simple example of a sinusoid 167 | plot whose frequency is controlled by a slide-bar. Another kernel that 168 | has some widget functionality is C++ 169 | ([https://github.com/QUantStack/xwidgets](https://github.com/QUantStack/xwidgets)). 170 | 171 | 172 | 173 | ![Here, a slider allows the user to interactively change the variable k in our function as we plot it.](images/notebook-matplotlib-interact.png "interactive sliders") 174 | 175 | In addition to the IPywidgets library, the ipyleaflet library 176 | (https://ipyleaflet.rtfd.io) displays an interactive map in a notebook. 177 | 178 | #### Example {-} 179 | 180 | 181 | ``` 182 | from ipyleaflet import Map 183 | Map(center=[34.6252978589571, -77.34580993652344], zoom=10) 184 | ``` 185 | 186 | 187 | ![Interactive map widget with `ipyleafletalt_text`.](images/chapter52.png "interactive map") 188 | 189 | 190 | For the ambitions reader, there are resources available for you to 191 | write your your own custom widgets. The widget cookie cutter project 192 | ([https://ipywidgets.rtfd.io](https://ipywidgets.rtfd.io)) is a good 193 | place to start. 194 | 195 | 196 | 197 | 198 | ### Magics {#magics} 199 | 200 | Magics are meta-commands that only function within Jupyter and allow a 201 | user to access language/kernel-specific features. For instance, the 202 | IPython kernel provides a number of magics that can be useful while 203 | developing Jupyter notebooks using Python as the primary 204 | language. These are 205 | [documented](https://ipython.readthedocs.io/en/stable/interactive/magics.html) 206 | and we will only call out a few of these here. Many other magics are 207 | available for different kernels but they are specific to Jupyter so 208 | may not be usable in a stand-alone script in that language outside of 209 | Jupyter. In some instances, you may want to use magics sparingly to 210 | avoid obfuscating these meta-commands with the actual commands in the 211 | language you are teaching. Magics always begin with either a single 212 | `%` for single-line commands or with `%%` for applying a command to an 213 | entire cell. Some magics can be used with single or double `%`, but 214 | some cannot. 215 | 216 | #### Examples {-} 217 | 218 | * Matplotlib is a common choice for visualization. In Jupyter, the 219 | magic `%matplotlib` allows the resulting figures to 220 | be displayed in the notebook: `%matplotlib inline` produces 221 | static images embedded in the notebook, and `%matplotlib 222 | notebook` produces interactive images (with zooming, panning, etc.). 223 | 224 | * The `%run` magic allows running external scripts (and other 225 | notebooks), captures output and displays it in the notebook, 226 | e.g., `%run my_script.py`. The `%run` magic is one answer to "how 227 | do I import one notebook into another?" 228 | 229 | * The `%time` magic times the execution of the Python expression following it, e.g., `%time sum(range(1000))`. 230 | 231 | * The `%timeit` magic is similar to `%time`, but it 232 | runs the expression multiple times and reports the average 233 | execution time. 234 | 235 | * The `%reset` magic deletes all user-defined variables along with input and 236 | output. Magics often have "flags," following the Unix command 237 | pattern. For example, `%reset -s` is a soft reset and only removes 238 | user-defined variables. These commands can be useful to avoid problems 239 | with out-of-order execution problems. 240 | 241 | * The `%debug` magic is used after code has stopped due to an 242 | exception (i.e., "the program has crashed"). Enter the `%debug` 243 | magic immediately after the crash, and you will be placed into the 244 | environment that caused the problem. From there you can explore 245 | variables and find the cause of the problem. 246 | 247 | 248 | A good example of a magic operating on the entire contents of cell is 249 | the `%%HTML` magic, forcing the cell to be interpreted as HTML 250 | and rendered appropriately. You can also use magics to call other 251 | languages while running the IPython kernel. For example, you can run 252 | R code from within an IPython notebook by using the `%%R` magic. 253 | 254 | ```{block2, type='rmdnote'} 255 | Pro Tip 256 | 257 | In the IPython kernel you can also use the `%shell` magic. This is 258 | often abbreviated as `!` and can run and return results from the 259 | shell/terminal. In IPython, you can also mix magics with regular 260 | Python code. For example, `files = ! ls` will use the `ls` (list 261 | files) command in the terminal, return the list, and set the 262 | Python variable `files` to that list. 263 | ``` 264 | 265 | ### Notebooks under version control {#notebooks-under-version-control} 266 | 267 | Keeping notebooks under version control is a great way to not only 268 | keep track of changes to your content, but also for 269 | sharing it. In a course where multiple people are contributing 270 | to the development of notebooks for the course, using version control 271 | in conjunction with a platform like GitHub, allows authorship to be 272 | tracked and provides communication tools for reviewing new 273 | contributions or outlining requested development for a new assignment, 274 | activity, etc. Another advantage of using version control is that 275 | some services will provide rendered views of notebooks 276 | that you have made public. GitHub shows a rendered 277 | version of the notebook, rather than the ASCII text that a notebook is 278 | comprised of. Some pitfalls with LaTeX rendering may occur, 279 | as platforms do not always render the notebooks the same as they would 280 | appear in an active Jupyter interface. 281 | 282 | We should mention a few caveats to keeping notebooks under version control. 283 | The code output, including images, is stored 284 | in the repository, unless you clear the output 285 | before committing changes. This can make reviewing changes difficult, 286 | as changes in output will be detected even when nothing has actually 287 | changed content-wise. The tracked notebooks also can become large if 288 | output is tracked. Even when clearing the output, reviewing 289 | changes can be awkward due to the format of the notebook (notebooks 290 | are plain-text files and the file format is represented as 291 | [JSON](https://www.json.org/)). 292 | The community is actively developing tools to make it easier to use version control with Jupyter notebooks; one such tool is `nbdime` (see box). 293 | 294 | ```{block2, type='rmdnote'} 295 | nbdime nbdime.readthedocs.io/ 296 | 297 | nbdime includes a set of tools for reviewing the changes ("diffs") and 298 | merging changes in Jupyter notebooks. You can compare versions of a 299 | notebook using the terminal, view the changes richly rendered on a 300 | browser, and merge in various ways. Because nbdime understands the 301 | structure of notebook documents, it can make smart "diffing and 302 | merging" decisions. 303 | ``` 304 | 305 | Another option to improve your version-control experience is to export 306 | a Jupyter notebook to a markdown document, for example using the [jupytext](https://github.com/mwouts/jupytext) tool. 307 | Then you can review diffs in the usual way for plain-text files. 308 | 309 | 310 | 311 | ### Testing notebooks {#testing-notebooks} 312 | 313 | Before distributing notebooks, and in particular if you are working 314 | with multiple contributors to the course material, testing the 315 | notebooks before they are distributed to students or used in a live 316 | demo can help mitigate unexpected bugs. At a minimum, you can test 317 | that the notebook executes cleanly from top to bottom by restarting 318 | the kernel and running all cells from top to bottom. This can be done 319 | from the menu (Restart + Run all). 320 | 321 | Though it requires a bit more setup, tests can be run automatically 322 | using a continuous integration service, such as TravisCI 323 | ([https://travis-ci.org](https://travis-ci.org)). This will require 324 | executing the entire notebook via the command line, for example 325 | `jupyter nbconvert --ExecutePreprocessor.enabled=True --to=html 326 | my_notebook.ipynb` will execute the notebook (same as pressing 327 | "Restart + Run All") and then convert it to HTML. These services can 328 | be connected to GitHub so that any time that the notebooks are 329 | changed, the tests are run automatically. Simplifying this process is 330 | an area that is under development in the open source community. The 331 | package 332 | [https://github.com/opengeophysics/testipynb](https://github.com/opengeophysics/testipynb) 333 | provides an easy way to test notebooks. 334 | 335 | 336 | ### Essential Python libraries {#essential-python-libraries} 337 | 338 | The purpose of this section is to introduce some of the most widely 339 | used packages within the Python ecosystem. As mentioned before, over 100 kernels enable different programming languages in Jupyter. 340 | But Python is a common choice in many disciplines, due to its 341 | large open-source community which develops and maintains an ecosystem of over 150,000 software packages. 342 | 343 | The core Python library 344 | ([https://docs.python.org](https://docs.python.org/3/)) contains basic data 345 | types such as lists and dictionaries, as well as core functionality 346 | such as arithmetic operators and simple file parsers. Most tasks can 347 | be achieved with core Python. They are often made easier, however, with 348 | higher-level libraries. This particularly applies for 349 | scientific computing with Python. 350 | Among the vast number of packages in the Python ecosystem, NumPy, 351 | Scipy, Matplotlib and Pandas are among the most commonly used. 352 | A good resource for getting familiar with these libraries 353 | is the **Scipy Lecture Notes** [https://scipy-lectures.org/](https://scipy-lectures.org/). 354 | 355 | * Numpy 356 | ([http://www.numpy.org/](http://www.numpy.org/)) is a fundamental 357 | library for numerical and scientific computing with Python. It 358 | contains data structures for numerical arrays, tools for linear 359 | algebra, random number capabilities, and much more. 360 | * SciPy 361 | ([https://docs.scipy.org/](https://docs.scipy.rg/)) offers a 362 | varied set of functions for scientific computing, such 363 | as optimization, interpolation, statistics and signal processing. It 364 | also includes fundamental constants from many disciplines such as the 365 | speed of light as well as data structures for sparse 366 | matrices. 367 | * Matplotlib 368 | ([https://matplotlib.org/](https://matplotlib.org/)) is the core 369 | plotting library for Python and can be used inline in the notebook 370 | with the `%matplotlib notebook` or `%matplotlib inline` cell 371 | magics. 372 | * Pandas 373 | ([https://pandas.pydata.org/](https://pandas.pydata.org/)) provides 374 | resources for data analysis and a flexible data structures for labeled tabular data. 375 | 376 | 377 | ### Advanced topic: extensions {#advanced-topic-extensions} 378 | 379 | There are many community contributed extensions that add functionality 380 | to Jupyter notebooks. Extensions vary from displaying an automated 381 | table of contents for a notebook, or prettify code, or hiding/showing 382 | solution cells. Here is the link for how to install and enable 383 | extensions: 384 | [https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html) 385 | 386 | Here is a list of a collection of extensions that are bundled 387 | together: 388 | [https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions.html](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions.html) 389 | 390 | Creating custom extensions is a way to extend or customize Jupyter to 391 | add a capability that is not currently available with current 392 | extensions or out of the box. These extensions may be targeted for a 393 | specific kernel. Here are instructions for how to create and install 394 | custom extensions: 395 | [https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html](https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html) 396 | 397 | Figure X shows shows how Google Collaboratory, one of many tools to 398 | interact with Jupyter notebooks, leverages the power of Jupyter 399 | extensions for custom interaction and presentation. 400 | 401 | 402 | ![Google Collaboratory uses Jupyter extensions to customize Jupyter for their users. The run/play icon to the left of the code cell is created using extensions. This is not present in the standard Jupyter software. TensorFlow is a library for creating Machine Learning experiments in Python.](images/chapter53.png "Tensorflow example") 403 | 404 | The set of extensions for Jupyter is constantly evolving. Educators 405 | are exploring new and interesting methods of using notebooks in 406 | pedagogy. While the list of current extensions is far too long to 407 | list, you can interactively experience some of the most useful 408 | extensions through this live 409 | [Binder notebook](https://hub.mybinder.org/user/psychemedia-showntell-eii7j2nh/notebooks/index_computing.ipynb) 410 | (Binder is described in detail in the following chapter). 411 | This live notebook demonstrates the following: 412 | 413 | * Turning on line numbers in code cells (makes it easier to refer to a line of code) 414 | * Code folding extension (hide code blocks to help focus attention) 415 | * Locked and frozen cells extension (prevent changes to cells) 416 | * An extension for a better user interface for error messages 417 | * A "turtle" extension (draws in a canvas in the notebook) 418 | * Block-based programming extension 419 | 420 | The block-based programming extension (called Jigsaw) allows users to 421 | program using drag-and-drop blocks of code that can be integrated with 422 | other cells in a Jupyter Notebook (see figure). The advantages (and 423 | disadvantages) of blocked-based languages are active research topics 424 | in computer education research (see, for example, Mark Guzdial's 425 | excellent [Computing Education Research Blog](https://computinged.wordpress.com/), 426 | specifically [those posts on block-based languages](https://computinged.wordpress.com/tag/blocks-based-language/)). 427 | 428 | ![Example of incorporating Jigsaw, a block-based extension, in a Jupyter Notebook. The extension allows the user to assemble code blocks that can then be translated into Python or Java, and executed.](images/jigsaw.png "block-based programming") 429 | 430 | ## Tips and tricks 431 | 432 | 433 | ### Reminders 434 | 435 | If you are using a single notebook as a standalone exercise in a 436 | traditional class (i.e., this is the only computational component of 437 | your class), then it is helpful to have a few cells at the top of that 438 | notebook that reviews how to navigate through the notebook and how to 439 | insert cells, etc. 440 | 441 | 442 | ### Feedback 443 | 444 | How do we get feedback from students in an interactive session to see 445 | if students have completed an exercise? 446 | 447 | A low tech solution is to give students sticky notes of different 448 | colors, one meaning "finished" and one meaning "need help", that they 449 | can stick on the back of their computers. The instructor can then 450 | quickly look up to take a survey of the state of the class and decide 451 | how to proceed. 452 | 453 | Projecting Slack or a similar chat group on a screen and having 454 | student copy-paste solutions (provided they are short functions) is a 455 | nice way to let everyone in the class see one another's solutions. A 456 | positive aspect of having multiple student solutions projected is that 457 | it can show the variety of ways to solve a problem. This gives an 458 | opportunity to talk about the readability of solutions and their 459 | efficiency. A downside is that in a large class, the sheer volume of 460 | posts can make it overwhelming. Instead polling can be used to 461 | aggregate student answers and provide some form of feedback to the 462 | instructor. Nbgrader or travis-CI can also be options here, requiring 463 | students to submit completed code where it is assessed 464 | automatically. These will however require more setup and can take some 465 | time to complete. 466 | 467 | 468 | ### Explaining each cell 469 | 470 | Consider moving the comments for a code block into a markdown cell 471 | either directly above or below the code cell. Comments in a markdown 472 | cell often read much better and give you more flexibility in 473 | discussing or describing the code. However, short comments in a block 474 | of code can still be useful. 475 | 476 | 477 | ### How to structure code cells 478 | 479 | How much code should you put in a cell? You will develop your own 480 | style of writing noteooks with experience. Typically, you will want to 481 | keep the number of lines low so that it is easy to follow, and you can 482 | have useful comments above the cell. However, we recommend putting 483 | code that "goes together as a meaningful unit" into a single cell. For 484 | example, if you have lines of code that are highly dependent on each 485 | other, then you might want to put them together. As an example, 486 | consider two lines of code: one that opens a file, and the second that 487 | reads the data from the file. It is probably a good idea to put those 488 | into the same cell so that they are always executed 489 | together. Otherwise, the student may encounter errors if they execute 490 | cells independently a second time (e.g., there are no more data). 491 | 492 | Specifically, messing up the dependencies between cells is where most 493 | of the confusion using notebooks comes from with new users. For 494 | example, if you change a variable's name (without restarting the 495 | notebook), then the following code cells may continue to use the old 496 | variable's name (and value). Later, when running the notebook again, 497 | the notebook may fail in unexpected ways because the old variable no 498 | longer exists. This is sometimes referred to as "the hidden state 499 | problem." This is an open research problem, and researchers are 500 | exploring various possible solutions. For example, trying searching 501 | the internet for "jupyter dependency graph" or "jupyter dataflow 502 | notebook." 503 | 504 | ```{block2, type='rmdnote'} 505 | Pro Tip 506 | 507 | You can easily split a cell into two parts at the cursor using the 508 | keystroke `CONTROL` + `SHIFT` + `-`. You can also merge multiple cells 509 | with `SHIFT` + `m`. Both of these are also available from the menu 510 | under `Edit`. 511 | ``` 512 | 513 | On the other hand, it is often a useful idea to separate lines of code 514 | where you want to provide the student a place to interactively add 515 | cells, and examine the state at that particular point in the 516 | process. Asking probing questions in a Socratic method is a very 517 | useful technique for engaging the reader and encouraging them to 518 | become more than a reader. Students do not naturally know to insert 519 | cells and explore items in a notebook. You will need to explicitly 520 | teach this skill. In fact, teaching students how to effectively weave 521 | code into their *own* notebook stories is an important component of 522 | teaching with notebooks. 523 | 524 | ### Custom styling 525 | 526 | New notebook creators often try to centrally manage the formatting of 527 | headings, equations, and other textual items. For example, rather than 528 | using a standard markdown heading, a creator may over-design the 529 | headings by using HTML styles. This may create two problems: 530 | 531 | 532 | 1. The rendering of the notebook markdown may change and your 533 | formatted HTML header may not maintain the same look over time. 534 | 535 | 1. Headers created using markdown can be used by notebook tools, 536 | such as automatically creating a Table of Contents. 537 | 538 | Our recommendation is to resist the desire to customize the styling 539 | and simply use the default representations. If you want to do 540 | customization (for example if you want to color certain cells) you can 541 | use CSS. 542 | 543 | 544 | ### Length of notebooks 545 | 546 | Notebook authors sometimes make the notebooks very long with many 547 | topics and sections. Notebook sections and cells are currently not 548 | easily reused in a copy/paste sense for mixing intra-notebook 549 | content. Until this functionality is available, we recommend that 550 | authors make short, self-contained notebooks around short topics. This 551 | allows other notebooks authors to mix and match notebooks to create 552 | curriculum. 553 | 554 | 555 | 556 | 557 | ## Gotchas 558 | 559 | ### Programming language $\neq$ Jupyter 560 | 561 | Teaching a class entirely with Jupyter can give the sense to students 562 | that this is the way all computational exploration is done. In 563 | particular, students can be confused into thinking that programming 564 | requires the notebook, instead of understanding that a notebook is 565 | just one way to interact with a particular language. This point should 566 | be made clear periodically. A good way to reinforce this is to show 567 | how to take a function that has been developed and debugged in a 568 | notebook and cut-paste it into a script (such as a file ending in .py 569 | for Python) and then import it into the notebook to regain that 570 | functionality. Also, the Integrated Development Environment (IDE), 571 | Spyder, has a plugin 572 | ([https://github.com/spyder-ide/spyder-notebook](https://github.com/spyder-ide/spyder-notebook)) 573 | that allows notebooks to be displayed alongside Python scripts and a 574 | python terminal which can be useful for showing this dichotomy. 575 | 576 | 577 | ![Jupyter notebook displayed in a window pane inside Spyder.](images/chapter54.png "spyder rendering") 578 | 579 | 580 | ### Restart, restart, restart... 581 | 582 | Often, students may need to stop a computation, and this can be 583 | accomplished by pressing the "Interrupt" button in the 584 | toolbar. However, students should also be made aware of how to restart 585 | the kernel in a notebook, and what this means. There are several 586 | instances when students might need to do this. Sometimes students 587 | write code that can go into an infinite loop. The visual cues that 588 | notebooks give in this case are subtle, and students may not realize 589 | this and don't understand why the notebook is non-responsive. In 590 | live-coding situations, it can be useful to demonstrate this to 591 | students and show them how to restart the kernel and carry on. 592 | 593 | A second instance of where restarting a kernel might be needed is due 594 | to how the notebook stores the state of the computation. We like to 595 | think that, since the notebook is laid out in a linear fashion, that 596 | the state will always reflect what would happen if the notebook was 597 | run from the start up to that point. However, it is common to work in 598 | a notebook out of order, for instance if students ask a question about 599 | some previous example. If the variable has been changed in subsequent 600 | cells, then its value might not reflect what you expect when you rerun 601 | a cell earlier in the notebook. Restarting the kernel is sometimes the 602 | only solution. 603 | 604 | 605 | ### Notebook hygiene {#notebook-hygiene} 606 | 607 | Many gotchas can be mitigated by developing notebooks that will be 608 | robust to incremental and non-linear execution. The main principle is 609 | to minimize side-effects of executing a cell and manifests itself 610 | somewhat differently in different languages; our suggestions here will 611 | be relevant to Python and may need to be adapted for other 612 | languages. Notebooks should generally be able to execute sequentially, 613 | such as via "restart kernel and run all cells". (An exception is when 614 | a notebook is intentionally incomplete for the purpose of live coding 615 | or student exercises, see nbgrader or the exercise estnations for more 616 | elegant ways to handle this.) Variable mutation is the most common way 617 | in which a notebook may malfunction when executing cells in a 618 | non-linear way (e.g., in response to student questions or when 619 | comparing and contrasting different methodologies). Sometimes this 620 | mutation is incidental, through dummy variables that were not meant to 621 | have significance outside the scope of the cell in which they are 622 | used. Their scope can be limited by placing them in a function, even 623 | if that function is only called once. Redefinition of functions can 624 | often be avoided by parameterizing the desired functionality as would 625 | typically be done if designing a library (though this may be a 626 | distracting software design for novice programmers). Function 627 | definitions should have little or no dependency on variables from 628 | their enclosing scope. When modifying cells for demos and formative 629 | assessments during class, it is useful to either copy the cell or 630 | modify/execute such that a conforming implementation remains present 631 | when moving on to other cells where it may be used. Additionally, you 632 | can minimize these issues by grouping code in a single cell that 633 | should always be executed sequentially, because code within a cell 634 | will always be sequential. 635 | --------------------------------------------------------------------------------