extra info about visual azimuth

Author: mayofaulkner

brainbox/examples/docs_wheel_screen_stimulus.ipynb

@@ -13,15 +13,14 @@
    "id": "cd4144b5",
    "metadata": {},
    "source": [
-    "In the IBL task a visual stimulus (Gabor patch) appears on the left (-35°) or right (+35°) of a screen and the mouse must use a wheel to bring the stimulus to the centre of the screen (0°). If the mouse moves the wheel in the correct direction, the trial is deemed correct and the mouse receives a reward, if however, the mouse moves the wheel in the wrong direction and the stimulus goes off the screen, this is an error trial and the mouse receives a white noise error tone. \n",
+    "In the IBL task a visual stimulus (Gabor patch of size 7°<sup>2</sup>) appears on the left (-35°) or right (+35°) of a screen and the mouse must use a wheel to bring the stimulus to the centre of the screen (0°). If the mouse moves the wheel in the correct direction, the trial is deemed correct and the mouse receives a reward. If however, the mouse moves the wheel 35° in the wrong direction and the stimulus goes off the screen, this is an error trial and the mouse receives a white noise error tone. The screen was positioned 8 cm in front of the animal and centralized relative to the position of eyes to cover ~102 visual degree azimuth. In the case that the mouse moves the stimulus 35° in the wrong direction, the stimulus, therefore is visible for 20° and the rest is off the screen.\n",
     "\n",
-    "For some analysis it may be useful to know the position of the visual stimulus on the screen during a trial. While there is no direct read out of the location of the stimulus on the screen, as the stimulus is coupled to the wheel, we can infer the position using the wheel position. \n",
+    "For some analyses it may be useful to know the position of the visual stimulus on the screen during a trial. While there is no direct read out of the location of the stimulus on the screen, as the stimulus is coupled to the wheel, we can infer the position using the wheel position. \n",
     "\n",
-    "Below we walk you through an example of how to compute the continuous screen position for a given trial.\n",
+    "Below we walk you through an example of how to compute the continuous stimulus position on the screen for a given trial.\n",
     "\n",
-    "For this anaylsis we need access to information about the wheel radius and the wheel gain (visual degrees moved on screen per mm of wheel movement).\n",
-    "* Wheel radius = 3.1 cm\n",
-    "* Wheel gain = 4 (deg / mm)"
+    "For this anaylsis we need access to information about the wheel radius (3.1 cm) and the wheel gain (visual degrees moved on screen per mm of wheel movement). The wheel gain changes throughout the training period (see our [behavior paper](https://doi.org/10.7554/eLife.63711\n",
+    ") for more information) but for the majority of sessions is set at 4°/mm."
    ]
   },
   {
@@ -221,7 +220,7 @@
    "source": [
     "# Find the index of the wheel timestamps when the stimulus was presented (stimOn_times)\n",
     "idx_stim = np.searchsorted(wh_times, trials['stimOn_times'][tr_idx])\n",
-    "# Normalise the wh_pos to the position at stimOn\n",
+    "# Zero the wh_pos to the position at stimOn\n",
     "wh_pos = wh_pos - wh_pos[idx_stim]"
    ]
   },
@@ -254,7 +253,7 @@
    "outputs": [],
    "source": [
     "GAIN_MM_TO_SC_DEG = 4\n",
-    "screen_pos = wh_pos * GAIN_MM_TO_SC_DEG"
+    "stim_pos = wh_pos * GAIN_MM_TO_SC_DEG"
    ]
   },
   {
@@ -270,7 +269,7 @@
    "id": "e0189229",
    "metadata": {},
    "source": [
-    "The screen_pos values that we have above have been computed over the whole trial interval, from trial start to trial end. The stimlus on the screen however is can only move with the wheel between the time at which the stimlus is presented (stimOn_times) and the time at which a choice is made (response_times). After a response is made the visual stimulus then remains in a fixed position until the it disappears from the screen (stimOff_times)"
+    "The stim_pos values that we have above have been computed over the whole trial interval, from trial start to trial end. The stimlus on the screen however is can only move with the wheel between the time at which the stimlus is presented (stimOn_times) and the time at which a choice is made (response_times). After a response is made the visual stimulus then remains in a fixed position until the it disappears from the screen (stimOff_times)"
    ]
   },
   {
@@ -293,19 +292,19 @@
     "idx_off = np.searchsorted(wh_times, trials['response_times'][tr_idx])\n",
     "\n",
     "# Before stimOn no stimulus on screen, so set to nan\n",
-    "screen_pos[0:idx_stim - 1] = np.nan\n",
+    "stim_pos[0:idx_stim - 1] = np.nan\n",
     "# Stimulus is in a fixed position between response time and stimOff time\n",
-    "screen_pos[idx_res:idx_off - 1] = screen_pos[idx_res]\n",
+    "stim_pos[idx_res:idx_off - 1] = stim_pos[idx_res]\n",
     "# After stimOff no stimulus on screen, so set to nan\n",
-    "screen_pos[idx_off:] = np.nan"
+    "stim_pos[idx_off:] = np.nan"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "781fe47f",
    "metadata": {},
    "source": [
-    "The screen_pos values are given relative to stimOn times but the stimulus appears at either -35° or 35° depending on the stimlus side. We therefore need to apply this offset to our screen position"
+    "The stim_pos values are given relative to stimOn times but the stimulus appears at either -35° or 35° depending on the stimlus side. We therefore need to apply this offset to our stimulus position. We also need to account for the convention that increasing wheel position indicates a counter-clockwise movement and therefore a left-ward (-ve) movement of the stimulus in visual azimuth."
    ]
   },
   {
@@ -328,12 +327,12 @@
     "    # The stimulus appeared on the right\n",
     "    # Values for the screen position will be >0\n",
     "    offset = ONSET_OFFSET  # The stimulus starts at +35 and goes to --> 0\n",
-    "    screen_pos = -1 * screen_pos + offset\n",
+    "    stim_pos = -1 * stim_pos + offset\n",
     "else:\n",
     "    # The stimulus appeared on the left\n",
     "    # Values for the screen position will be <0\n",
     "    offset = -1 * ONSET_OFFSET # The stimulus starts at -35 and goes to --> 0\n",
-    "    screen_pos = -1 * screen_pos + offset"
+    "    stim_pos = -1 * stim_pos + offset"
    ]
   },
   {
@@ -378,8 +377,8 @@
     "axs[0].set_ylabel('Wheel displacement (mm)')\n",
     "\n",
     "\n",
-    "# On bottom axis plot the screen position\n",
-    "axs[1].plot(wh_times, screen_pos, 'k')\n",
+    "# On bottom axis plot the stimulus position\n",
+    "axs[1].plot(wh_times, stim_pos, 'k')\n",
     "axs[1].vlines([trials['stimOn_times'][tr_idx], trials['response_times'][tr_idx]],\n",
     "              0, 1, transform=axs[1].get_xaxis_transform(), colors='k', linestyles='dashed')\n",
     "axs[1].set_xlim(trials['intervals'][tr_idx])\n",
@@ -392,7 +391,7 @@
     "\n",
     "axs[1].set_ylim([-90, 90])\n",
     "axs[1].set_xlim(trials['stimOn_times'][tr_idx] - 0.1, trials['response_times'][tr_idx] + 0.1)\n",
-    "axs[1].set_ylabel('Screen position (°)')\n",
+    "axs[1].set_ylabel('Visual azimuth angle (°)')\n",
     "axs[1].set_xlabel('Time in session (s)')\n",
     "fig.suptitle(f\"ContrastLeft: {trials['contrastLeft'][tr_idx]}, ContrastRight: {trials['contrastRight'][tr_idx]},\"\n",
     "                 f\"FeedbackType {trials['feedbackType'][tr_idx]}\")\n",