Deployed be0fe78 with MkDocs version: 1.6.1

Basic Tutorials/(1) First Experiment/(1) First Experiment.ipynb

@@ -0,0 +1,214 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "source": [
+    "\n",
+    "# (1) First Experiment\n",
+    "\n",
+    "Here, we learn how to create a very simple experiment consisting of a single text stimulus. We get familiar with installing the package and loading different functionality. Then we create a stimulus and get used to how to organize stimuli into blocks and the blocks into an experiment."
+   ],
+   "metadata": {
+    "id": "dzL-6EwQwyou"
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Installing SweetBean\n",
+    "\n",
+    "In python, we can make use of packages that are created by the community. To use them, we need to install them first. We use pip, a package manager for python, to install the package.\n",
+    "\n",
+    "<details>\n",
+    "<summary>Optional: Packages and Virtual Environments in Python</summary>\n",
+    "It is best to use virtual environments when using packages in python on your own computer (not in google colab). A virtual environment is an isolated environment for a Python project that contains its own Python interpreter and set of installed packages. Creating a virtual environment allows for a clean separation between projects and their dependencies, which helps avoid conflicts between different versions of the same package required by different projects. Many IDEs (Integrated Development Environments) like PyCharm, Visual Studio Code, or Spyder let you manage these virtual environments via the graphical user interface. If you prefer working in a console, you can create virtual environments using tools such as venv or virtualenv.\n",
+    "</details>"
+   ],
+   "metadata": {
+    "id": "UOqvkQI_HyiJ"
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "hJoIHQvau3QP",
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "outputId": "50b99b60-c986-4c4d-daab-6ebd4c1a142b"
+   },
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "Looking in indexes: https://pypi.org/simple, https://us-python.pkg.dev/colab-wheels/public/simple/\n",
+      "Requirement already satisfied: sweetbean in /usr/local/lib/python3.8/dist-packages (0.0.19)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# installing the package\n",
+    "!pip install sweetbean"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Creating a stimulus\n",
+    "\n",
+    "We now create our first stimulus — a text greeting the participant.\n",
+    "First, we need to import the functionality from SweetBean to create such a stimulus, and then we specify the stimulus.\n",
+    "\n",
+    "There are multiple different stimuli types in SweetBean with varying sets of parameters. Here, we start with a text stimulus with the single feature text.\n",
+    "\n",
+    "<details>\n",
+    "<summary>Optional: Imports in Python</summary>\n",
+    "After importing a feature, it will be available in the rest of the file. Importing has to be done only once. There are multiple ways of importing functionality from packages — all with their own advantages and disadvantages. Here, we use the \"from\" keyword to import only the desired functionality from the SweetBean package, which makes our code more readable and avoids potential naming conflicts. In the subsequent tutorials, we will show other ways of importing.\n",
+    "</details>"
+   ],
+   "metadata": {
+    "id": "LCijBQZDKymT"
+   }
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "# import the functionality from sweetbean to create a text stimulus\n",
+    "from sweetbean.stimulus import Text\n",
+    "\n",
+    "# create an introduction\n",
+    "introduction_stimulus = Text(text='Welcome to our awesome experiment.')"
+   ],
+   "metadata": {
+    "id": "cMVQuZ67LAKf"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Creating a block\n",
+    "\n",
+    "In SweetBean, an experiment consists of blocks, while blocks themselves consist of stimuli.\n",
+    "\n",
+    "For example, the first part of an experiment typically contains informed consent and instructions for the participants. In SweetBean, this can be achieved by assembling a sequence of text stimuli.\n",
+    "\n",
+    "The second block of the experiment could then consist of training trials, the following blocks could be experimental blocks with target trials, and the last block of the experiment could be a debriefing block where we again show text stimuli.\n",
+    "\n",
+    "Here, we have a simple block consisting only of a single text stimulus.\n",
+    "\n",
+    "<details>\n",
+    "<summary>Optional: Why do we use blocks?</summary>\n",
+    "No one prevents you do describe your experiment as a single sequence of stimuli without organizing them into blocks. The block design has two main advantages. First, it helps with designing the experiment and keeping it structured. Second, we will show functionality to loop over blocks in the following tutorials making it possible to define an experimental block and only change specific features of the stimuli.\n",
+    "</deatails>\n",
+    "\n"
+   ],
+   "metadata": {
+    "id": "PfViByiTOxYF"
+   }
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "# import the functionality from sweetbean to create a block\n",
+    "from sweetbean import Block\n",
+    "\n",
+    "# create a list of stimuli for the block\n",
+    "introduction_list = [introduction_stimulus]\n",
+    "\n",
+    "# create the block\n",
+    "introduction_block = Block(introduction_list)"
+   ],
+   "metadata": {
+    "id": "RGEMyP0URnEY"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Creating the experiment\n",
+    "\n",
+    "Now that we have a block, we can create a full experiment from this single block."
+   ],
+   "metadata": {
+    "id": "I2syZ9EfXV71"
+   }
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "# import the functionality from sweetbean to create experiments\n",
+    "from sweetbean import Experiment\n",
+    "\n",
+    "# create a list of blocks\n",
+    "block_list = [introduction_block]\n",
+    "\n",
+    "# create the experiment\n",
+    "experiment = Experiment(block_list)"
+   ],
+   "metadata": {
+    "id": "PPwejgXLXmSI"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Exporting the experiment in html format\n",
+    "\n",
+    "Finally, we create our html file from the experiment.\n",
+    "\n",
+    "\n",
+    "<details>\n",
+    "<summary>Optional: Hosting and storing the data</summary>\n",
+    "There are multiple ways to host the experiment and store the data. For example, you can run the experiment on your own server (if your university provides such a service). But there are also free services where you can host a website like this. For example, Firebase provides the functionality of hosting a website and storing data. <a href=\"https://www.brown.edu/carney/research-project/honeycomb-template-reproducible-psychophysiological-tasks-clinic-laboratory-and\">Honeycomb</a> is a template for reproducible psychophysiological tasks that can be run online and uses Firebase. It is maintained by the <a href=\"https://ccv.brown.edu/\">Center for Computation and Visualization</a> and the <a href=\"https://borton.engin.brown.edu/\">Neuromotion Lab</a> at Brown University. Future iterations of SweetBean will contain functionality to export the experiment to files that can be used in conjunction with Honeycomb.\n",
+    "</details>\n",
+    "\n",
+    "\n",
+    "\n"
+   ],
+   "metadata": {
+    "id": "aMij-3SqYBaz"
+   }
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "# the functionality to create a html is a method of the experiment class. It expects a filename as input and creates the experiment we declared earlier.\n",
+    "experiment.to_html('index.html')"
+   ],
+   "metadata": {
+    "id": "Uw1WYhBIYaIH"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": "If you run this file in google colab, you can locate the newly created file in the \"files\" tab (left side of your screen). This HTML file is ready to be viewed in any web browser of your choice.",
+   "metadata": {
+    "id": "gEaI6T8sZAIr"
+   }
+  }
+ ]
+}