Tutorial [NUMBER]: Tutorial’s name

Week [WEEK_NUMBER], Day [DAY_NUMBER]: [DAY_TOPIC]

By Sciencematch Academy # update to the correct academy

Content creators: Names & Surnames

Content reviewers: Names & Surnames

Production editors: Names & Surnames

Acknowledgments: [ACKNOWLEDGMENT_INFORMATION]

---

Use a line (—) separator from title block to objectives.

Tutorial Objectives

Estimated timing of tutorial: [insert estimated duration of whole tutorial in minutes]

In this tutorial, you will learn what a tutorial notebook should look like.

You should briefly introduce your content here in a few sentences.

Then have a few specific objectives for this tutorial, ideally SMART goals.

An example of the expected structure to follow:

Tutorial Learning Objectives

• Learning objective 1

• Learning objective 2

• …

Tutorial Slides “link_id”s will be added in below by the curriculum or production team. You do not need to do anything but leave the block of code below here.

---

Setup

In this section, we have (please keep the order):

1. Gadget (optional): install and import feedback gadget - not relevant for cliamtematch

2. Import cell (required): imports all libraries you use in the tutorial

3. Hidden Figure settings cell (optional): sets up the plotting style (copy exactly).

4. Hidden Plotting functions cell (optional): should contain all functions used to create plots throughout the tutorial (so students don’t waste time looking at boilerplate matplotlib but can here if they wish to). Please use only matplotlib for plotting for consistency.

5. Hidden Data retrieval (optional): set up the data retrieval needed for the tutorial.

6. Hidden Helper functions cell (optional): This should contain functions that students have previously used or that are very simple. Any helper functions that are being used for the first time and are important should be placed directly above the relevant text or exercise (see Section 1.1 for an example).

7. set random seed (with/out pytorch) and set GPU/CPU (optional): several cells that set the seed for repeatability and set the GPU for computations

Please see comments in the code for instructions on what you need to change, if anything

Install and import feedback gadget

Show code cell source Hide code cell source

# @title Install and import feedback gadget

# note this is not relevant for climatematch at the moment

!pip3 install vibecheck datatops --quiet

from vibecheck import DatatopsContentReviewContainer
def content_review(notebook_section: str):
    return DatatopsContentReviewContainer(
        "",  # No text prompt - leave this as is
        notebook_section,
        {
            "url": "https://pmyvdlilci.execute-api.us-east-1.amazonaws.com/klab",
            "name": "sciencematch_sm", # change the name of the course : neuromatch_dl, climatematch_ct, etc
            "user_key": "y1x3mpx5",
        },
    ).render()

# Define the feedback prefix: Replace 'weeknumber' and 'daynumber' with appropriate values, underscore followed by T(stands for tutorial) and the number of the tutorial
# e.g., W1D1_T1
feedback_prefix = "W*weeknumber*D*daynumber*_T*tutorialNumber*"

# Imports

# Import only the libraries/objects that you use in this tutorial.

# If any external library has to be installed contact the tech and curriculum chairs so it can be add to the base enviroment

import numpy as np
import matplotlib.pyplot as plt
import logging
import ipywidgets as widgets  # interactive display
import io
import requests

Figure settings

Show code cell source Hide code cell source

# @title Figure settings

logging.getLogger('matplotlib.font_manager').disabled = True

%matplotlib inline
%config InlineBackend.figure_format = 'retina' # perfrom high definition rendering for images and plots
plt.style.use("https://raw.githubusercontent.com/NeuromatchAcademy/course-content/main/nma.mplstyle") # update this to match your course

Plotting functions

Show code cell source Hide code cell source

# @title Plotting functions

# add your plotting functions here. below is an example for a basic plotting funciton

logging.getLogger('matplotlib.font_manager').disabled = True

# You may have functions that plot results that aren't
# particularly interesting. You can add these here to hide them.

# example:
def plotting_z(z):
  """This function multiplies every element in an array by a provided value

  Args:
    z (ndarray): neural activity over time, shape (T, ) where T is number of timesteps

   """

  fig, ax = plt.subplots()

  ax.plot(z)
  ax.set(
      xlabel='Time (s)',
      ylabel='Z',
      title='Neural activity over time'
      )

Data retrieval

This cell downloads the example dataset that we will use in this tutorial.

Show code cell source Hide code cell source

#@title Data retrieval

#@markdown This cell downloads the example dataset that we will use in this tutorial.


## Uncomment the code below to test your function


# Only need to put in the OSF url below, or other cloud based retrievals here

#r = requests.get('<YOUR_URL_HERE>') #E.g., ('https://osf.io/sy5xt/download')
#if r.status_code != 200:
  #print('Failed to download data')
#else:
  #data = np.load(io.BytesIO(r.content), allow_pickle=True)['data']

Helper functions

Show code cell source Hide code cell source

# @title Helper functions

# If any helper functions you want to hide for clarity (that has been seen before
# or is simple/uniformative), add here
# If helper code depends on libraries that aren't used elsewhere,
# import those libaries here, rather than in the main import cell

Set random seed

Executing set_seed(seed=seed) you are setting the seed

Show code cell source Hide code cell source

# @title Set random seed

# @markdown Executing `set_seed(seed=seed)` you are setting the seed

# E.g., for DL its critical to set the random seed so that students can have a
# baseline to compare their results to expected results.
# Read more here: https://pytorch.org/docs/stable/notes/randomness.html

# Call `set_seed` function in the exercises to ensure reproducibility.
import random
import numpy as np

def set_seed(seed=None):
  if seed is None:
    seed = np.random.choice(2 ** 32)
  random.seed(seed)
  np.random.seed(seed)
  print(f'Random seed {seed} has been set.')


set_seed(seed=2023)  # change 2023 with any number you like

Random seed 2023 has been set.

Set random seed, when using pytorch

Executing set_seed(seed=seed) you are setting the seed

Show code cell source Hide code cell source

# @title Set random seed, when using `pytorch`

# @markdown Executing `set_seed(seed=seed)` you are setting the seed

# for DL its critical to set the random seed so that students can have a
# baseline to compare their results to expected results.
# Read more here: https://pytorch.org/docs/stable/notes/randomness.html

# Call `set_seed` function in the exercises to ensure reproducibility.
import random
import torch
import numpy as np

def set_seed(seed=None, seed_torch=True):
  if seed is None:
    seed = np.random.choice(2 ** 32)
  random.seed(seed)
  np.random.seed(seed)
  if seed_torch:
    torch.manual_seed(seed)
    torch.cuda.manual_seed_all(seed)
    torch.cuda.manual_seed(seed)
    torch.backends.cudnn.benchmark = False
    torch.backends.cudnn.deterministic = True

  print(f'Random seed {seed} has been set.')


# In case that `DataLoader` is used
def seed_worker(worker_id):
  worker_seed = torch.initial_seed() % 2**32
  np.random.seed(worker_seed)
  random.seed(worker_seed)


set_seed(seed=2021, seed_torch=False)  # change 2021 with any number you like

Random seed 2021 has been set.

Set device (GPU or CPU). Execute set_device()

Show code cell source Hide code cell source

# @title Set device (GPU or CPU). Execute `set_device()`
# especially if torch modules used.

# inform the user if the notebook uses GPU or CPU.

def set_device():
  device = "cuda" if torch.cuda.is_available() else "cpu"
  if device != "cuda":
    print("GPU is not enabled in this notebook. \n"
          "If you want to enable it, in the menu under `Runtime` -> \n"
          "`Hardware accelerator.` and select `GPU` from the dropdown menu")
  else:
    print("GPU is enabled in this notebook. \n"
          "If you want to disable it, in the menu under `Runtime` -> \n"
          "`Hardware accelerator.` and select `None` from the dropdown menu")

  return device

---

Section 1: Example of tutorial structure

The above section header should be a description of what the section covers. It should be a level 1 header.

The curriculum or production team will supply the “video_id” variable for youtube, billibilli, and OSF needed in the code below to render the videos when the notebook is executed. You do not need to do anything but change the video title name, please leave this code block here.

Video 1: Video 1 Name # put in the title of your video

• one concept per video

• many small videos preferable to 1 large video

• Keep distance between idea and interaction small

Do not:

• Speak in mathematical notation instead of: as we increase alpha, Say : as we increase the learning rate.

Add text that is meant to suppliment the videos and reiterate the key information.

Below students can rate your content with the feedback gadget:

Submit your feedback

Show code cell source Hide code cell source

# @title Submit your feedback
content_review(f"{feedback_prefix}_Video_1_Name")

Section 1.1: Different types of activities in the tutorial (subsection header)

You can have students complete coding exercises, play with interactive demos, or have group discussions. This should be a level 2 header.

Coding Exercise 1.1: Helpful exercise name (e.g., fitting a linear regression model)

This exercise fits in this subsection so is a level 3 header. We name it after the section it is in.

Very briefly summarize the exercise here. The first exercise should not be too difficult, to serve as a warm-up for students. Outputs of the code cell will ideally be a plot (so students can easily check against the correct one). In limited cases, the output may be printing numbers, text, etc. In that case you need to write the solution output manually after the exercise (E.g.: “You should see [4, 5, 6] when running the cell above”).

Warn them when they will use a helper function. For example: In this exercise, you will also invoke multiply_array which multiplies an array by a scalar (a silly example).

Note: In case of randomness and to ensure reproducibility, do not forget to use a random seed before the exercise or within the function.

The following block of code shows how you can first define functions used in the exercises that you want hidden but do not want to put in the Helper functions section defined above. This keeps the notebooks cleaner by hiding functions, but still keeps relevant functions close to where students will encounter them. Make sure to use the markdown tag at the beginning of the cell, and keep the title of the function in the markdown text so students can still search for it in the notebooks.

Execute this cell to enable the array multiplication function: multiply_array

Show code cell source Hide code cell source

# @markdown *Execute this cell to enable the array multiplication function: `multiply_array`*


def multiply_array(x, c, seed):
  """Multiply every element in an array by a provided value

  Args:
    x (ndarray): An array of shape (N,)
    c (scalar): multiplicative factor
    seed (integer): random seed

  Returns:
    ndarray: output of the multiplication
  """
  np.random.seed(seed)
  y = x * c + 4*np.random.randn()

  return y

Below is an example of a student exercise. Within each student exercise, there should be a NotImplementedError call that stops the notebook from executing fully so that students will pause and complete the exercise. Once they have completed the exercise, they may remove this function so that the cell will execute.

def generic_function(x, seed):
  """Google style doc string. Brief summary of what function does here

  Args:
    x (ndarray): An array of shape (N,) that contains blah blah
    seed (integer): random seed for reproducibility

  Returns:
    ndarray: The output is blah blah
  """
  #################################################
  ## TODO for students: details of what they should do ##
  # Fill remove the following line of code one you have completed the exercise:
  raise NotImplementedError("Student exercise: say what they should have done")
  #################################################

  # Have a comment for every line of code they need to write, and when possible have
  # variables written with ellipses where they should fill in or ellipses where they should
  # fill in inputs to functions
  y = multiply_array(..., 5, seed)

  # Another comment because they need to add another line of code
  z = ...

  return z


x = np.array([4, 5, 6])

# We usually define the plotting function in the hidden Helper Functions
# so students don't have to see a bunch of boilerplate matplotlib code

## Uncomment the code below to test your function

# z = generic_function(x, seed=2021)
# plotting_z(z)

---

Please note, there must be a corresponding ‘solution’ code cell to all student exercises. These solutions are useful to the teaching assistants in our course as well as for those using the material asynchornously.

Editor guideline for exercise solution formatting:

1. Must include # to_remove solution in the first line of solution code cell

2. Do not include the fenced (#####) block that raises a NotImplementedError

3. Include valid code replacing all ellipses (...)

4. Code that uses or depends on the completed function/lines is uncommented

5. All other comments and code should be identical

---

An example of a solution cell to the exercise posed above:

Click for solution

Submit your feedback

Show code cell source Hide code cell source

# @title Submit your feedback
content_review(f"{feedback_prefix}_name_of_Exercise")

---

Interactive Demo 1.1: Name of demo

Here, we will demonstrate how to create a widget if you would like to use a widget to demonstrate something. Make sure the use a @markdown as the first line in the cell to hide the contents by default, because the code to make the widget is often pretty ugly and not important for the students to see.

If the widget makes use of a function that must be completed as part of an exercise, you may want to re-implement the correct version of the function inside the widget cell, so that it is useful for a student who got completely stuck.

Make sure you execute this cell to enable the widget!

Show code cell source Hide code cell source

# @markdown Make sure you execute this cell to enable the widget!

x = np.arange(-10, 11, 0.1)


def gaussian(x, mu, sigma):
  px = np.exp(-1 / 2 / sigma**2 * (mu - x) ** 2)
  px = px / px.sum()
  return px


@widgets.interact
def plot_gaussian(mean=(-10, 10, .5), std=(.5, 10, .5)):
  plt.plot(x, gaussian(x, mean, std))

There shoud be discussion questions posed about the interactive demo (and coding exercises possibly).

Interactive Demo 1.1 Discussion

1. Discussion question 1

2. Discussion question 2

You must include an explanation for each discussion question using the following cell as a guide:

Click for solution

Click for solution

---

Section 2: Notation Standards

Estimated timing to here from start of tutorial: ?

For notation standards, please refer to the course specific day lead instructions here: https://docs.neuromatch.io/p/npByLKa5tvx9kY/Course-Specific-Day-Lead-and-Project-Lead-Instructions

---

Section 3: Name of Section 3

Estimated timing to here from start of tutorial: ?

An additional example section

Separate with lines and add more content here! Depending on how the videos were created, you may or may not have a separate video for each section

Coding Exercise 3: Name

This exercise is in this section (not in a subsection) so has a level 2 header.

---

Think: Name of discussion topic

In addition to code exercises and interactive demos, you can have “discussion exercises” where students discuss open-ended questions. Each should roughly replace a code exercise so take about 10 minutes.

E.g.: What do you think contributes to a good learning experience? Take 2 minutes to think in silence, then discuss as a group (~10 minutes).

You can then include an airtable form through which students can write down their thoughts. This helps us to see how students are thinking (as we can read the responses). You should also still include the explanation cell with the answer or some discussion to aid students.

# airtable
# relevant_variable_name: text

Editor guideline: note that to notify us where you’d like an airtable input form, use this special syntax. The first line is “#

• First line is # airtable

• Relevant variable name on the second line should be something related to the question you’re asking (an identifier). For example it could be “learning_experience_contribs” in this example. It should be a valid Python variable (no spaces, don’t start with numbers).

• You can have different types of inputs: text, numerical, or multiple choice.

If you want a text answer, use # relevant_variable_name: text If you want a numerical answer, use # relevant_variable_name: number If you want a multiple choice answer, use # relevant_variable_name: [option1, option2, option3] where you fill out what the options are.

Click for solution

Submit your feedback

Show code cell source Hide code cell source

# @title Submit your feedback
content_review(f"{feedback_prefix}_Name_of_Discussion_Topic")

---

Summary

Estimated timing of tutorial: [minutes] [provide the estimated time for the completing of the entire tutorail]

Have a summary of what they learned with specific points.

1. Specific point A

2. Specific point B

Bonus: Name of Bonus section

Add extra text that you want students to have for reference later but that will make reading times too long during tutorials. You can have multiple Bonus sections if you’d like, just number them as Bonus 1: Name, Bonus 2: Name, etc.

This can also serve as more advanced content for advanced students or those taking the course asyncrhonously.

You should not have bonus content interleaved into the tutorial.