diff --git a/.gitignore b/.gitignore index 52fce67d..0d8b07be 100755 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ .vscode .idea _build -_toc.yml \ No newline at end of file +_toc.yml +tutorials/.DS_Store diff --git a/tutorials/W1D2_Template/W1D2_Tutorial1.ipynb b/tutorials/W1D2_Template/W1D2_Tutorial1.ipynb index 69b75df6..0f604aa4 100644 --- a/tutorials/W1D2_Template/W1D2_Tutorial1.ipynb +++ b/tutorials/W1D2_Template/W1D2_Tutorial1.ipynb @@ -21,7 +21,7 @@ "\n", "**Week [WEEK_NUMBER], Day [DAY_NUMBER]: [DAY_TOPIC]**\n", "\n", - "**By Neuromatch Academy** #or Climatematch\n", + "**By Sciencematch Academy** # update to the correct academy\n", "\n", "__Content creators:__ Names & Surnames\n", "\n", @@ -52,7 +52,23 @@ "\n", "\n", "\n", - "You should briefly introduce your content here in a few sentences. Then have a few specific objectives for this tutorial, ideally [SMART goals](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5944406/#:~:text=1%20The%20mnemonic%20SMART%E2%80%94Specific,a%20well%2Dwritten%20learning%20objective.&text=Verbs%20such%20as%20understand%2C%20know,measurable%20and%20should%20be%20avoided.) \n" + "You should briefly introduce your content here in a few sentences. \n", + "\n", + "Then have a few specific objectives for this tutorial, ideally [SMART goals](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5944406/#:~:text=1%20The%20mnemonic%20SMART%E2%80%94Specific,a%20well%2Dwritten%20learning%20objective.&text=Verbs%20such%20as%20understand%2C%20know,measurable%20and%20should%20be%20avoided.). \n", + "\n", + "An example of the expected structure to follow:\n", + "\n", + "**Tutorial Learning Objectives**\n", + "* Learning objective 1\n", + "* Learning objective 2\n", + "* ...\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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." ] }, { @@ -97,14 +113,17 @@ "execution": {} }, "source": [ - "In this section, we have:\n", + "In this section, we have (please keep the order):\n", "\n", - "1. **Gadget**: Install and import feedback gadget.\n", - "2. **Import cell**: imports all libraries you use in the tutorial.\n", - "3. **Hidden Figure settings cell**: sets up the plotting style (copy exactly).\n", - "4. **Hidden Plotting functions cell**: should contains 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.\n", - "5. **Hidden Data retrieval**: set up the data retrieval needed for the tutorial.\n", - "6. **Hidden Helper functions cell**: 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)." + "1. **Gadget (optional)**: install and import feedback gadget - not relevant for cliamtematch\n", + "2. **Import cell (required)**: imports all libraries you use in the tutorial\n", + "3. **Hidden Figure settings cell (optional)**: sets up the plotting style (copy exactly).\n", + "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.\n", + "5. **Hidden Data retrieval (optional)**: set up the data retrieval needed for the tutorial.\n", + "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).\n", + "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 \n", + "\n", + "**Please see comments in the code for instructions on what you need to change, if anything**" ] }, { @@ -118,22 +137,24 @@ "source": [ "# @title Install and import feedback gadget\n", "\n", + "# note this is not relevant for climatematch at the moment\n", + "\n", "!pip3 install vibecheck datatops --quiet\n", "\n", "from vibecheck import DatatopsContentReviewContainer\n", "def content_review(notebook_section: str):\n", " return DatatopsContentReviewContainer(\n", - " \"\", # No text prompt\n", + " \"\", # No text prompt - leave this as is\n", " notebook_section,\n", " {\n", " \"url\": \"https://pmyvdlilci.execute-api.us-east-1.amazonaws.com/klab\",\n", - " \"name\": \"neuromatch_cn\", #change the name of the course\n", + " \"name\": \"sciencematch_sm\", # change the name of the course : neuromatch_dl, climatematch_ct, etc\n", " \"user_key\": \"y1x3mpx5\",\n", " },\n", " ).render()\n", "\n", - "#3. Feedback prefix: Replace 'weeknumber' and 'daynumber' with appropriate values, underscore followed by T(stands for tutorial) and the number of the tutorial\n", - "#e.g., W1D1_T1\n", + "# Define the feedback prefix: Replace 'weeknumber' and 'daynumber' with appropriate values, underscore followed by T(stands for tutorial) and the number of the tutorial\n", + "# e.g., W1D1_T1\n", "feedback_prefix = \"W*weeknumber*D*daynumber*_T*tutorialNumber*\"" ] }, @@ -149,11 +170,15 @@ "\n", "# Import only the libraries/objects that you use in this tutorial.\n", "\n", - "# If any external library has to be installed, !pip install library --quiet\n", - "# follow this order: numpy>matplotlib.\n", + "# If any external library has to be installed contact the tech and curriculum chairs so it can be add to the base enviroment\n", "\n", "import numpy as np\n", - "import matplotlib.pyplot as plt" + "import matplotlib.pyplot as plt\n", + "import logging\n", + "import ipywidgets as widgets # interactive display\n", + "import io\n", + "import requests\n", + "\n" ] }, { @@ -165,15 +190,13 @@ }, "outputs": [], "source": [ - "# @title Figure Settings\n", + "# @title Figure settings\n", "\n", - "import logging\n", "logging.getLogger('matplotlib.font_manager').disabled = True\n", "\n", - "import ipywidgets as widgets # interactive display\n", "%matplotlib inline\n", - "%config InlineBackend.figure_format = 'retina'\n", - "plt.style.use(\"https://raw.githubusercontent.com/NeuromatchAcademy/course-content/main/nma.mplstyle\")" + "%config InlineBackend.figure_format = 'retina' # perfrom high definition rendering for images and plots\n", + "plt.style.use(\"https://raw.githubusercontent.com/NeuromatchAcademy/course-content/main/nma.mplstyle\") # update this to match your course " ] }, { @@ -187,12 +210,30 @@ "source": [ "# @title Plotting functions\n", "\n", - "#def plot_isis(single_neuron_isis):\n", - " #plt.hist(single_neuron_isis, bins=50, histtype=\"stepfilled\")\n", - " #plt.axvline(single_neuron_isis.mean(), color=\"orange\", label=\"Mean ISI\")\n", - " #plt.xlabel(\"ISI duration (s)\")\n", - " #plt.ylabel(\"Number of spikes\")\n", - " #plt.legend()" + "# add your plotting functions here. below is an example for a basic plotting funciton\n", + "\n", + "logging.getLogger('matplotlib.font_manager').disabled = True\n", + "\n", + "# You may have functions that plot results that aren't\n", + "# particularly interesting. You can add these here to hide them.\n", + "\n", + "# example: \n", + "def plotting_z(z):\n", + " \"\"\"This function multiplies every element in an array by a provided value\n", + "\n", + " Args:\n", + " z (ndarray): neural activity over time, shape (T, ) where T is number of timesteps\n", + "\n", + " \"\"\"\n", + "\n", + " fig, ax = plt.subplots()\n", + "\n", + " ax.plot(z)\n", + " ax.set(\n", + " xlabel='Time (s)',\n", + " ylabel='Z',\n", + " title='Neural activity over time'\n", + " )" ] }, { @@ -211,8 +252,9 @@ "\n", "## Uncomment the code below to test your function\n", "\n", - "import io\n", - "import requests\n", + "\n", + "# Only need to put in the OSF url below, or other cloud based retrievals here\n", + "\n", "#r = requests.get('') #E.g., ('https://osf.io/sy5xt/download')\n", "#if r.status_code != 200:\n", " #print('Failed to download data')\n", @@ -220,40 +262,6 @@ " #data = np.load(io.BytesIO(r.content), allow_pickle=True)['data']" ] }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "cellView": "form", - "execution": {} - }, - "outputs": [], - "source": [ - "# @title Plotting functions\n", - "import logging\n", - "logging.getLogger('matplotlib.font_manager').disabled = True\n", - "\n", - "# You may have functions that plot results that aren't\n", - "# particularly interesting. You can add these here to hide them.\n", - "\n", - "def plotting_z(z):\n", - " \"\"\"This function multiplies every element in an array by a provided value\n", - "\n", - " Args:\n", - " z (ndarray): neural activity over time, shape (T, ) where T is number of timesteps\n", - "\n", - " \"\"\"\n", - "\n", - " fig, ax = plt.subplots()\n", - "\n", - " ax.plot(z)\n", - " ax.set(\n", - " xlabel='Time (s)',\n", - " ylabel='Z',\n", - " title='Neural activity over time'\n", - " )" - ] - }, { "cell_type": "code", "execution_count": null, @@ -387,17 +395,10 @@ "---\n", "\n", "# Section 1: Example of tutorial structure\n", - "The above section header should be a description of what the section covers\n", - " " - ] - }, - { - "cell_type": "markdown", - "metadata": { - "execution": {} - }, - "source": [ - "How to upload videos:" + "\n", + "The above section header should be a description of what the section covers. It should be a level 1 header.\n", + " \n", + "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." ] }, { @@ -409,7 +410,11 @@ }, "outputs": [], "source": [ - "# @title Video 1: Video 1 Name\n", + "# @title Video 1: Video 1 Name # put in the title of your video\n", + "# note the libraries are imported here on purpose\n", + "\n", + "###@@@ for konstanine. a question, why isn't this above in the list of cells? \n", + "\n", "from ipywidgets import widgets\n", "from IPython.display import YouTubeVideo\n", "from IPython.display import IFrame\n", @@ -446,7 +451,7 @@ " tab_contents.append(out)\n", " return tab_contents\n", "\n", - "\n", + "# curriculum or production team will provide these ids\n", "video_ids = [('Youtube', ''), ('Bilibili', ''), ('Osf', '')]\n", "tab_contents = display_videos(video_ids, W=854, H=480)\n", "tabs = widgets.Tab()\n", @@ -475,7 +480,9 @@ " \n", " \n", " \n", - "Add text that is meant to suppliment the videos and reiterate the key information. " + "Add text that is meant to suppliment the videos and reiterate the key information. \n", + "\n", + "Below students can rate your content with the feedback gadget:" ] }, { @@ -499,7 +506,7 @@ "source": [ "## Section 1.1: Different types of activities in the tutorial (subsection header)\n", "\n", - "You can have students complete coding exercises, play with interactive demos, or have group discussions." + "You can have students complete coding exercises, play with interactive demos, or have group discussions. This should be a level 2 header." ] }, { @@ -515,7 +522,9 @@ "\n", "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).\n", "\n", - "**Note**: In case of randomness and to ensure reproducibility, do not forget to use a random seed before the exercise or within the function.\n" + "**Note**: In case of randomness and to ensure reproducibility, do not forget to use a random seed before the exercise or within the function.\n", + "\n", + "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." ] }, { @@ -552,11 +561,9 @@ }, { "cell_type": "markdown", - "metadata": { - "execution": {} - }, + "metadata": {}, "source": [ - "**Editor guideline:** the above structure allows us to make the notebooks cleaner by hiding functions but still keep relevant functions close to where students will encounter them. Make sure to have the function in the markdown text so it's searchable." + "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." ] }, { @@ -582,7 +589,7 @@ " \"\"\"\n", " #################################################\n", " ## TODO for students: details of what they should do ##\n", - " # Fill out function and remove\n", + " # Fill remove the following line of code one you have completed the exercise:\n", " raise NotImplementedError(\"Student exercise: say what they should have done\")\n", " #################################################\n", "\n", @@ -601,11 +608,11 @@ "\n", "# We usually define the plotting function in the hidden Helper Functions\n", "# so students don't have to see a bunch of boilerplate matplotlib code\n", + "\n", "## Uncomment the code below to test your function\n", "\n", "# z = generic_function(x, seed=2021)\n", - "# with plt.xkcd():\n", - "# plotting_z(z)" + "# plotting_z(z)" ] }, { @@ -616,16 +623,19 @@ "source": [ "---\n", "\n", + "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.\n", + "\n", "***Editor guideline for exercise solution formatting:***\n", "\n", - "1. the presence of `# to_remove solution` in the first line of solution block\n", - "2. The absence of the fenced (`#####`) block that raises a `NotImplementedError`\n", - "3. Valid code replacing all ellipses (`...`)\n", + "1. Must include `# to_remove solution` in the first line of solution code cell\n", + "2. Do not include the fenced (`#####`) block that raises a `NotImplementedError`\n", + "3. Include valid code replacing all ellipses (`...`)\n", "4. Code that uses or depends on the completed function/lines is uncommented\n", - "5. Plotting code is indented under a `with plt.xkcd():` context manager.\n", "6. **All other comments and code should be identical**\n", " \n", - "---" + "---\n", + "\n", + "An example of a solution cell to the exercise posed above:" ] }, { @@ -663,11 +673,11 @@ "\n", "# We usually define the plotting function in the hidden Helper Functions\n", "# so students don't have to see a bunch of boilerplate matplotlib code\n", + "\n", "## Uncomment the code below to test your function\n", "\n", "# z = generic_function(x, seed=2021)\n", - "# with plt.xkcd():\n", - "# plotting_z(z)" + "# plotting_z(z)" ] }, { @@ -693,11 +703,9 @@ "\n", "## Interactive Demo 1.1: Name of demo\n", "\n", - "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 @title cell and hide the contents by default, because the code to make the widget is often pretty ugly and not important for the students to see.\n", - "\n", - "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.\n", + "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.\n", "\n", - "There should be specific questions asked about the demo (e.g. what happens when you do this?)" + "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." ] }, { @@ -725,6 +733,30 @@ " plt.plot(x, gaussian(x, mean, std))" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "There shoud be discussion questions posed about the interactive demo (and coding exercises possibly). " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Interactive Demo 1.1 Discussion\n", + "\n", + "1. Discussion question 1\n", + "2. Discussion question 2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You must include an explanation for each discussion question using the following cell as a guide:" + ] + }, { "cell_type": "code", "execution_count": null, @@ -740,6 +772,10 @@ "\n", "You can write a paragraph or two of nice didactic text\n", "within a single comment.\n", + "\n", + "From the example above:\n", + "1. Answer to discussion question 1.\n", + "2. Answer to discussion question 2.\n", "\"\"\";" ] }, @@ -749,13 +785,7 @@ "execution": {} }, "source": [ - "**Editor guideline**: note that the form header for the cell above is **to_remove explanation**, not **to_remove solution.**\n", - "\n", - "maybe some more text about what exercises showed (if helpful). The Gaussian is:\n", - "\n", - "- bumpy in the middle\n", - "- symmetric\n", - "- almighty" + "**Editor guideline**: note that the form header for the cell above is **to_remove explanation**, not **to_remove solution.** This line is required, as is the triple quite block." ] }, { @@ -770,7 +800,7 @@ "\n", "Estimated timing to here from start of tutorial: ? \n", "\n", - "Add notation standards if useful. E.g., for DL: https://www.deeplearningbook.org/contents/notation.html" + "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" ] }, { @@ -906,6 +936,8 @@ "\n", "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.\n", "\n", + "This can also serve as more advanced content for advanced students or those taking the course asyncrhonously.\n", + "\n", "You should not have bonus content interleaved into the tutorial." ] }