Initial commit

.gitignore

@@ -0,0 +1,2 @@
+
+.DS_Store

About_page_info.md

@@ -0,0 +1,21 @@
+# About page for your course
+
+Each course has an About page on the platform, and we need to fill specific information in a template. 
+Please provide the following:
+
+1. Title
+1. Subtitle (optional, but nice to have)
+1. Duration (e.g., 4 h; corresponds to estimated time on task for learners)
+1. Description (<1000 chars)
+1. Short description (<150 chars)
+2. Learning outcomes (these will be displayed as bullet points under the heading “What You will Learn”)
+3. Keywords
+
+
+Instructor details needed:
+
+1. Name
+1. Title
+1. Organization
+1. Short biography
+1. Photo

Course_Development_Guide.md

@@ -0,0 +1,153 @@
+# Course Development Guide
+
+by **Lorena A. Barba**, Vice President of NumFOCUS Academy
+
+## General design
+
+Each course consists of written materials provided as Jupyter notebooks (in this repository), accompanying videos, and student assignments/assessments. 
+The written materials must be on Jupyter notebooks because the course building process pulls content directly from notebooks in a GitHub repository to display a learning sequence in the online course platform.
+All the videos will need to be uploaded to the NumFOCUS YouTube channel, and will be embedded in the course sequences.
+
+NumFOCUS will build an online course with the materials provided by the instructors on our Open edX platform.
+The instructors' content is always open access and free: videos on  YouTube, and notebooks in this GitHub repository (under standard public licenses). 
+To access the learning sequences on the Academy platform, participants need to be registered. 
+
+The materials should include an outline that traces a path through the content, with signposts of where each video and other elements (like exercises) should go.
+
+
+## Infrastructure
+
+NumFOCUS has deployed an ecosystem of tools and platforms to provide online learning experiences. 
+Course instructors will be able to exploit these tools to make their content shine.
+
+### Course platform
+
+We maintain a full-fledged online course platform, using the [Open edX software](https://open.edx.org/about-open-edx/). 
+With your materials (video and Jupyter notebooks), volunteers and NumFOCUS staff will build an online course. 
+It can include quizzes and auto-graded "homework" exercises, to reinforce the partcipants' learning, as described below.
+
+The course platform includes a custom extension for creating course content _from any publicly available Jupyter notebook_, using its URL. 
+Pulling content from Jupyter notebooks allows us to build a learning sequence from the author-provided content, without duplication.
+
+We also have a custom extension that allows writing exercises for the participants that are tested on-the-fly for correctness. 
+This allows creating Jupyter-based student assignments that are auto-graded in the platform.
+
+### JupyterHub/MyBinder
+
+NumFOCUS Academy will maintain a dedicated JupyterHub server that all subscribers will have access to. 
+Learners can launch a JupyterHub session with the notebooks provided by the instructor, so they can interact with the computable content. 
+
+In your outline, you can specify places in the course content where you want learners to find a "Launch Lab" button, which will launch a Jupyter session with your notebooks pre-loaded. 
+You need to provide an environment definition, either in the form on a `requirements.txt` file (for pure Python envionments) or an `environment.yaml` file (for conda environments) at the root of your repository.
+
+
+## Guide to crafting your materials
+
+### Jupyter notebooks
+
+Your course should be written as a set of Jupyter notebooks—about four fully narranted notebooks—walking your reader through the complete path to achieve the learning objectives. 
+
+Each Jupyter notebook is "one lesson" and will correspond to "one section" in the online course. 
+Printed, it should be between 10 and 20 pages in length, equivalent to 17 to 35 minutes reading time. 
+The computational portions should be presented as worked-out examples, broken down into steps, and narrated. 
+
+Because the Jupyter notebooks will be ingested into the content management system of the learning platform, to display learning sequences, it is _very important_ that you break up the notebook in sections and sub-sections. 
+The section headings, marked by `#`, `##` and so on, will be used as delimiters in the learning sequence to display portions of your notebook. 
+That way, the learning sequence can interleave content from the notebooks, videos, self-assessments (e.g., multiple choice quiz), graded Jupyter notebooks, etc.
+
+In other words, your Jupyter notebooks are like the "textbook," while a learning sequence mixes this content with other experiences or activities.
+
+Since the content is pulled dynamically from your notebooks on GitHub, you will be able to continue editing the notebooks after the online course is built.
+As long as you have provided an accurate outline, and you do not make changes to section and sub-section headings, the course building process can go on in parallel to your final edits.
+To be specific: each time a participant visits a section in the course, the Jupyter viewer extension we added to the platform will pull the notebook from its public URL, run `nbconvert`, and display the HTML output.
+
+Building online courses in this way allows us to have the full display richness of Jupyter notebooks: beautiful equations, embedded images in the markdown, syntax-highlighted code, plot outputs, etc. 
+
+**Pro tip**: while you are developing your content as Jupyter notebooks, always _clear output_ before pushing to the repository.
+This will facilitate diff-viewing and keep the repo smaller. 
+Only push the notebooks with output once you feel they are done. 
+If you later fix a typo or make a small edit to markdown cells, push the change without re-running the notebook.
+
+### Videos
+
+The course videos should be short and content-dense.
+(Read the [tweet thread by @gregork](https://twitter.com/gregork/status/1291760045269508096) about online videos.)
+
+They can be recorded as a screencast of you live coding and narrating, a slide-based presentation, a camera capture of yourself explaining or narrating some concept, or a mix of all these. 
+
+NumFOCUS will prepare a streamlined workflow for you to deliver the videos, so they can be uploaded to our YouTube channel.
+
+
+### Slides
+
+If you will have any portions of your presentation using slides, you can include them in the repository. 
+We strongly encourage the use of text-based source for slides.
+
+### Labs and self-assessments
+
+A course should provide several opportunities for learners to self-assess, and we ask instructors to provide these. 
+We request that you share the assessments with us privately (i.e., they should not be included in the public repository).
+
+You can craft simple multiple-choice questions to supplement video or written content. In this case, please provide them to us in this markdown format, so we can embed them in the course:
+
+```
+>>Statement of the question <<
+
+( ) wrong answer
+(x) right answer
+( ) wrong answer
+( ) wrong answer
+
+[Explanation]
+A short explanation to help learner get it right next time.
+[Explanation]
+```
+
+Open edX offers several [core problem types](https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/open-release-ironwood.master/exercises_tools/create_exercises_and_tools.html#core-problem-types), and we can accommodate any of these in your course. 
+Please discuss with us by emailing to: 
+[[email protected]](mailto:[email protected])
+
+### Jupyter auto-graded notebooks
+
+For the course to be most effective, you should include exercises for the learners. 
+These exercises, written as Jupyter notebooks, can be auto-graded in the course platform. 
+For that, you need to write the exercises in a format that allows using `nbgrader` to create an assignment. 
+We have developed an integration in the course platform that allows  running `nbgrader` in a container and checking the learner's assignment, at the click of a button.
+
+Each exercise should be divided into incremental steps, and you provide the solution, and a test, usign the `nbgrader` annotations. 
+See the [`nbgrader` documentation](https://nbgrader.readthedocs.io/en/stable/user_guide/creating_and_grading_assignments.html#autograded-answer-cells) for detailed instructions on how to insert an "Autograded answer" and an "Autograded test."
+
+Here is an example: 
+
+![](images/graded_exercise_sample.png)
+
+In the screenshot above, the solution is in cell 3. After we process the notebook, the code between the marks `### BEGIN SOLUTION` and `### END SOLUTION` will be replaced by a note to the learner to "write your code here." 
+
+The tests in cell 4 will be hidden from the learner, but will be active and used to check the learners code against the correct answer.
+
+Your assignment notebook should include all the needed `import` statements at the top, and you should include `nose` in the `requirements.txt` (as well as all other dependencies, with their versions).
+
+You will need to [install](https://nbgrader.readthedocs.io/en/stable/user_guide/installation.html) the `nbgrader` Jupyter extension. 
+You will only be using the "Create assignment tool," and do not need to follow the later steps to create a student's version of the assignment, as this will be done automatically on the platform.
+
+Open the raw version of your assignment notebook in the environment where you installed `nbgrader`, and you should have the option shown in the screenshot below:
+
+<img src="images/create_assignment.png" width="440" height="250">
+
+Select "Create Assignment." Every notebook cell should now have a selector to pick the cell type, as shown below:
+
+![](images/cell_options.png)
+
+Work down the notebook making a selection for every cell:
+
+- "Read-only" for markdown cells with instructions, and cells with `import` commands that you don't want anyone to mess with.
+- "Autograded answer" for code cells that contain the solutions.
+- "Autograded test" for code cells that contain teh tests.
+
+Save the notebook, and this is the version you should send to us. We will create a _private repository_ for all the assignment notebooks. 
+Don't include them in the public course repository.
+
+**Pro Tip**: Use a rational naming convention for your assignment notebooks with a prefix for your course, and a consecutive number for the assignment.
+
+**We strongly encourage courses to be complemented by autograded exercises.**
+

README.md

@@ -0,0 +1,65 @@
+# course_template
+A template repository for NumFOCUS Academy courses.
+
+We are using GitHub Classroom as a way to collect materials from course developers. 
+After creating an "assignment" with this template repository, the lead course instructor can be sent a link that will allow them to create a repository for their course, under the NF Academy org.
+Having a common folder structure will help us when building courses in the online platform with the contents on GitHub.
+
+> Delete this file (or rename it) and replace it by a README file that targets the contents of the repository, populated with your course materials.
+
+## Instructions
+
+Use the link from [GitHub Classroom](https://classroom.github.com) to create your repository based on this template. 
+Add your content as Jupyter notebooks in the `notebooks` folder, and name them with a numeric prefix:
+
+- `01_title_of_first_lesson.ipynb`
+- `02_title_of_second_lesson.ipynb`
+
+The typical course will be 4 or 5 notebooks, fully narrated (i.e., please include full prose explaining all code and worked examples).
+Use plenty of headings to organize the content, and split Markdown cells at each heading. 
+If a section is longer than what you might read on a single scroll of a laptop display, split the cell (this will help us when building the online course from the notebooks).
+
+Put any data sets used in the worked examples in the `data` folder and add a file index in the README.md file in that folder. 
+(Include any credits for data that you sourced from others.)
+Add in the `images` and `scripts` folders any images embedded in the Markdown cells of your notebooks and any scripts imported or ran within code cells, respectively.
+
+Optionally, you can share any slides in the `slides` folder. We prefer text-based source, but you can also drop PDF files in there (please no binaries like .pptx).
+
+**Important**: Add all code dependencies to the `requirements.txt` or `environment.yaml` file. 
+
+> For more detailed instructions, read the [Course Development Guide](https://github.com/NFAcademy/course_template/blob/main/Course_Development_Guide.md).
+
+## How we build your course
+
+The NumFOCUS Academy uses an instance of the [Open edX](https://open.edx.org/) software platform for online learning. 
+We will build a course learning sequence by pulling content directly from your Jupyter notebooks, which will be displayed as embedded HTML in the course. 
+Sections of a notebook can be displayed in the online course as a "unit" of the learning sequence, interleaved with videos or student assignments (graded or ungraded). 
+
+Open edX allows a variety of [problem types](https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/create_exercises_and_tools.html), such as multiple choice, dropdown choice, numerical input, and even [math expression input](https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/math_expression_input.html#math-expression-input) problems.
+We also have a third-party extension for graded assignments using Jupyter notebooks and [nbgrader](https://nbgrader.readthedocs.io/en/stable/).
+
+### License
+The source materials for NumFOCUS Academy courses are copyright of their authors. 
+We ask that materials be shared under an open-source license of the author's choosing. Our recommendation is: BSD-3 (or MIT) license for code, CC-BY license for text and media, CC0 for data.
+
+
+# General information
+
+## What is NumFOCUS?
+
+[NumFOCUS](http://numfocus.org) is a 501(c)-3 non-profit in the United States. Its mission is to promote open practices in research, data, and scientific computing by serving as a fiscal sponsor for open source projects and organizing community-driven educational programs. NumFOCUS envisions an inclusive scientific and research community that utilizes actively supported open source software to make impactful discoveries for a better world.
+
+## NumFOCUS Academy
+
+The NumFOCUS Academy is an educational initiative begun in 2020, 
+to develop online learning opportunities for our community. 
+It first served as a platform for the online conferences JupyterCon 2020 and PyData Global. 
+
+In 2021, we are developing a catalog of courses to build your skills on the most useful open-source software tools for data science and technical computing.
+
+At NumFOCUS Academy, we aim to create learning opportunities inspired by the open-source ethos. Our courses teach about the NumFOCUS projects, often by the project contributors themselves. 
+No other learning platform has this to offer!
+
+Our instructors are members of the NumFOCUS international community, contribute to our open-source projects, and share their expertise widely. 
+Want to be a part of it? 
+Get in touch by emailing: [[email protected]](mailto:[email protected])

data/README.md

@@ -0,0 +1,7 @@
+# Data
+
+Include in this folder any data files used in the worked-out examples or learner exercises.
+
+Data sources should be credited in this README.
+
+We recommend that data be shared under CC0 public-domain dedication or CC-BY license.

images/README.md

@@ -0,0 +1,6 @@
+# Images
+
+Put *all images* that are embedded in Markdown cells in this folder.
+
+
+**Important**: For any images embedded in Markdown cells, we need you to use HTML tags, and provide at least a width: `<img src="../images/name.jpg" width="600" />`

notebooks/README.md

@@ -0,0 +1,23 @@
+# Jupyter notebooks
+
+The course content should be completely reflected in written materials provided as Jupyter notebooks. Worked out examples should be fully narrated, and no code cell should be left unexplained.
+
+The notebooks are used as source to build learning sequences in the online courses, making use of our Open edX extension for viewing Jupyter notebooks.
+
+## Instructions
+
+1. Use a naming convention where each notebook filename is prepended with a number, reflecting the order of the lessons in the course.
+
+2. List all notebooks in this README.
+
+3. Add any Python package dependencies to the `requirements.txt` file in the parent directory.
+
+4. Add a dockerfile if there are additional package dependencies (e.g. Jupyter extensions).
+
+5. We recommend that all notebooks be shared under a dual license: BSD-3 or MIT license for code, and CC-BY license for text and media.
+
+6. GitHub actions may be added to test that dependencies install and notebooks can execute successfully.
+
+**Important**: Use plenty of headers to organize the notebooks, and split Markdown cells in short portions (no more than a scroll on a laptop display).
+
+**Important**: For any images embedded in Markdown cells, we need you to use HTML tags, and provide at least a width: `<img src="../images/name.jpg" width="600" />`

scripts/README.md

@@ -0,0 +1,3 @@
+# Scripts
+
+Put here any scripts that you import or run in code cells.

slides/README.md

@@ -0,0 +1,7 @@
+# Slides
+
+Slides are optional, but if you use them for your video presentations, and want to share them, you can put them here.
+
+Alternatively, you could deposit your slide desk in PDF format on an archival service like [Figshare](http://figshare.com) or [Zenodo](http://zenodo.org), and you can add a full citation here.
+
+**Please** no binary files like .pptx here.