Tutorial 5: Projects#
Week 1, Day 1: Instructions
By Neuromatch
Content creators: Konstantine Tsafatinos
Content reviewers: Konstantine Tsafatinos
Production editors: Konstantine Tsafatinos
Acknowledgments: [Climatematch]
Tutorial Objectives#
Estimated timing of tutorial: [15 mins]
In this tutorial, you will learn how to build the projects section and update the repository with your new content.
You will:
learn the projects folder structure
learn what each subdirectory contains, and what to change to add new content
learn how to update the project_materials.yml to reflect the newly created notebooks
It is recommended that you read through all of tutorials 1 through 4 as this tutorial builds upon that knowledge.
Section 1: Folder Structure#
In the projects directory, you will find the following subdirectories and files:
README.md
docs/
past-projects/
project-notebooks/
professional_development/
keynote.ipynb
project_materials.yml
We have included examples from our Computational Tools for Climate Science course. Please feel free to use them as a template and edit them to your needs.
NOTE: You can ignore the professional_development subdirectory in this tutorial as it is explained in the next one; W1D1_Tutorial6.
Section 2: The docs subdirectory#
In the docs subdirectory, you will find the following four files:
continuing_your_project_after_the_course.md
datasets_overview.md
past_project_overview.md
project_guidance.md
Each file describes a different aspect of the projects for the course. Datasets that can be used are described in the datasets_overview.md. Expected structure, schedule, logistics of the projects are described in project_guidance.md. How to continue you project research after the course is described in continuing_your_project_after_the_course.md. Finally, a description of past projects is found in past_project_overview.md. If this is a new course, you can temporarily omit the past project portion by leaving it out of the project_materials.yml file.
Note: The climate team introduced something new last year with the Impact Scholars program. This was hugely successful and highly encourage you to follow their model, or tweak it to fit your needs. Let the neuromatch team know if you have any questions, want to brainstorm, or need support with this program. Impact Scholars allowed their students to participate in their fields of interest, after the course was complete, and this kind of research facilitation is exactly what neuromatch is about. Happy impacting! :)
Section 3: The past-projects subdirectory#
The past-projects subdirectory contains a python notebook for each past project topic. Within each notebook, past projects are showcased by embedding the slides from each projects. You can find an example taken from climatematch in this template. Whatever you decide to name it, make sure you link to that name in the project_materials.yml file and give it a title. See the project_materials.yml file from this template to give you an idea of what the build pipeline expects.
Here is an example, taken from the template on how to add past-projects:
- file: projects/docs/past_projects_overview.md
title: Past projects
sections:
- file: projects/past-projects/example_past_project.ipynb
title: Example Past Project
Section 4: The project-notebook subdirectory#
In this subject, we will describe how to add project topics to your new course. Within the project-notebooks subdirectory, you will create a python notebook file for each project topic. The notebook should then be added to the project materials.yml file with how ever you named it. We have including a project template file name example_project.ipynb in the project-notebooks directory. You can use this template for all your project topics and adapt it as needed.
The following is an example of the project_materials.yml file section for adding projects:
- file: projects/docs/datasets_overview.md
title: Project materials
sections:
- file: projects/project-notebooks/Example_project.ipynb
title: Example Project
Make sure you link to the name of your project file, and give it a title. The title will be used in the table of contents for your course book.
Section 5: The keynote.ipynb file#
The keynote.ipynb file is a notebook that contains an overview of a topic, an embedded video and embedded slides. We have included an example for our climate course as inpiration. Including a keynote speaker is a great way to engage students and excite them about the type of projects they can tackle. We encourage you to find someone who is passionate about the field, and who is a good orator. Happy hunting!
Section 6: The project_materials.yml file#
Finally, we get to the project_materials.yml file. This is where you will need to add all the content we talked about in sections 1 through 5. It is critical that you pay attention to the file names that you are pointing to, and that you follow the structure laid out in the file. Our build scripts expect a specific structure, and if you deviate, you will note build the book correctly. You can find an example of the project_materials.yml file in this template with comments to help guide you through adding content.
Here is what to expect:
- file: projects/README.md
title: Introduction
- file: projects/keynote.ipynb
title: Project Day keynote (W2D2)
- file: projects/docs/project_guidance.md
title: Daily guide for projects
- file: projects/docs/datasets_overview.md
title: Project materials
sections:
- file: projects/project-notebooks/Example_project.ipynb
title: Example Project
# You should add your pojects here using the following:
# - file: point to the file
# title: name the project
- file: projects/docs/continuing_your_project_after_the_course.md
title: Continuing your project after the course
- file: projects/docs/past_projects_overview.md
title: Past projects
sections:
- file: projects/past-projects/example_past_project.ipynb
title: Example Past Project
# You should add your past pojects here using the following:
# - file: point to the file
# title: name the project
Summary#
Congrats! You now know:
the folder structure of the projects directory
what each subdirectory contains and how to update the content
how to include your changes in the book build by updating the project_materials.yml
Happy content creating!