stimuli/stimulus_setup_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Stimuli and session template setup example notebook\n",
    "This notebook provides a minimal example on how to set up the stimuli and upload the sequence of trials to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from upload_to_s3 import upload_stim_to_s3, get_filepaths\n",
    "from experiment_config import experiment_setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set the names for the experiment and the iteration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PROJECT = \"Cognitive_AI_Benchmarking\"\n",
    "DATASET = \"Physion\"\n",
    "TASK = \"OCP\"\n",
    "ITERATION = \"1\"\n",
    "EXPERIMENT = DATASET + \"_\" + TASK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Provide metadata and locations of the stimuli files\n",
    "for a simple data directory with all to-be-uploaded files in one directory,  data_path is in the form /path/to/your/data\n",
    "    \n",
    "For a multi-level directory structure, you will need to use glob ** notation in data_path to index all the relevant files. something like:\n",
    "- `/path/to/your/files/**/*` (this finds all the files in your directory structure)\n",
    "- `/path/to/your/files/**/another_dir/*` (this finds all the files contained in all sub-directories named `another_dir`)\n",
    "- `/path/to/your/files/**/another_dir/*png` (this finds all the pngs contained in all sub-directories named `another_dir`)\n",
    "\n",
    "`bucket`: string, name of bucket to write to. Also specifies the name of the experiment in the input database.\\\n",
    "`pth_to_s3_credentials`: string, path to AWS credentials file\\\n",
    "`data_root`: string, root path for data to upload\\\n",
    "`data_path`: string, path in data_root to be included in upload\\\n",
    "`multilevel`: True for multilevel directory structures, False if all data is stored in one directory\n",
    "`fam_trial_ids`: list of strings, stim_id for familiarization stimuli\\\n",
    "`batch_set_size`: int, # of stimuli to be included in each batch. should be a multiple of overall stimulus set size"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example data used in this example is taken from [Physion](https://github.com/cogtoolslab/physics-benchmarking-neurips2021). Download [Physion_Dominoes](https://physics-benchmarking-neurips2021-dataset.s3.amazonaws.com/Physion_Dominoes.zip) (25 MB), extract it and copy the folder into the `stimuli/` subfolder of the repository."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bucket = (PROJECT + \"_\" + DATASET).replace(\"_\",\"-\").lower() # bucket name on AWS S3 where stimuli where be stored. `_` is not allowed in bucket names\n",
    "pth_to_s3_credentials = None # local path to your aws credentials in JSON format. Pass None to use shared credentials file\n",
    "data_root = '../stimuli/Physion_Dominoes' \n",
    "data_path = '**/*' # this finds all subdirectories in data_root and loads all files in each subdirectory to s3\n",
    "multilevel=True # Dominoes/ contains 2 subdirectories, so the structure is multi-level\n",
    "stim_paths = ['maps/*_map.png', 'mp4s/*_img.mp4'] # list of paths to stimuli to upload to s3—include a pattern to match only for relevant files\n",
    "meta_file = data_root + '/metadata.json' # path to metadata for stimulus set\n",
    "fam_trial_ids = ['pilot_dominoes_0mid_d3chairs_o1plants_tdwroom_0013', \n",
    "                 'pilot_dominoes_1mid_J025R45_boxroom_0020'] # image ids for familiarization trials\n",
    "batch_set_size = 20\n",
    "n_entries = 30 # how many different random orders do we want?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For reproducibility, fix the random seed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "np.random.seed(42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Upload stimuli to S3\n",
    "We need to store the stimuli files in S3. This assumes that a bucket has already been created and the appropriate permissions have been set (the files need to be publicly available, as they are embedded by the web experiment.) \n",
    "\n",
    "Make sure that you have the appropriate credentials to upload to S3. \n",
    "\n",
    "Running this section will upload your stimuli files to the specified S3 bucket.\n",
    "\n",
    "Consider logging into the AWS console to make sure that the right files have been uploaded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# which files would we upload?\n",
    "files = get_filepaths(data_root, stim_paths, multilevel=multilevel)\n",
    "print(\"Got {} paths to files\".format(len(files)))\n",
    "try: print(files[0:5],\"\\n\",\"...\",\"\\n\",files[-5:])\n",
    "except: print(\"Not enough file paths to display\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# upload dataset to aws s3\n",
    "upload_stim_to_s3(bucket, \n",
    "                  pth_to_s3_credentials, \n",
    "                  data_root, \n",
    "                  stim_paths, \n",
    "                  multilevel,\n",
    "                  overwrite=True)\n",
    "   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create and upload session templates to the `input` database\n",
    "This section will create a number of session templates, and upload them to the `input` database. \n",
    "For purposes of documentation (or the use of app.js with `--local_store`) the file is also saved to disk.\n",
    "\n",
    "A session template is an ordered list of stimuli that will be shown to the participant. \n",
    "\n",
    "Make sure that you have appropriate credentials for the `input` database (see the documentation on the CAB config file). If you are not running this one the same machine as the database, you might need to create an ssh tunnel to the database server. (eg. run `ssh -fNL 27017:127.0.0.1:27017 USERNAME@cogtoolslab.org` in your terminal.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# batch dataset and upload to mongodb\n",
    "experiment_setup(PROJECT,\n",
    "                 EXPERIMENT,\n",
    "                 ITERATION,\n",
    "                 meta_file,\n",
    "                 bucket,\n",
    "                 stim_paths,\n",
    "                 fam_trial_ids,\n",
    "                 batch_set_size,\n",
    "                 overwrite=True,\n",
    "                 n_entries = n_entries)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.7 ('curiophysion')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  },
  "vscode": {
   "interpreter": {
    "hash": "7d490802aa9a2e5a123340609c5ae4c60c09c9e951ad0b74d9d85b02a78902d9"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}