getting_started_ExpMode.ipynb

{
 "metadata": {
  "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.6.8"
  },
  "orig_nbformat": 4,
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3.6.8 64-bit ('3.6.8': pyenv)"
  },
  "interpreter": {
   "hash": "9789cbeb2318af48dcddd1580358646604a4fcad901c01d62d526b58f32318a2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2,
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# Using PyTrack in Experiment Design"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Directory and data setup\n",
    "\n",
    "Before running the framework, lets setup the folder so PyTrack can read and save all the generated figures in one central location and things are organised.\n",
    "\n",
    "Create a directory structure like the one shown below. It is essential for the listed directories to be present for the proper functioning of PyTrack.\n",
    "\n",
    "**NOTE:** The sample data has a folder called NTU_Experiment which is already organised in the following manner. It can be used as reference.\n",
    "\n",
    "```\n",
    "[Experiment-Name]\n",
    "|\n",
    "└── Data/\n",
    "│   │   subject_001.[asc/txt/tsv/...]\n",
    "│   │   subject_002.[asc/txt/tsv/...]\n",
    "|   |__ ......\n",
    "│\n",
    "└── Stimulus/\n",
    "│   │   stim_1.[jpg/jpeg]\n",
    "│   │   stim_2.[jpg/jpeg]\n",
    "|   |__ ......\n",
    "|\n",
    "└── [Experiment-Name].json\n",
    "\n",
    "```\n",
    "*[Experiment-Name]* stands for the name of your experiment. The rest of the\n",
    "steps will use *NTU_Experiment* as the *[Experiment-Name]* folder.\n",
    "\n",
    "This is what a sample Experiment directory can look like:\n",
    "\n",
    "![Dir_struct](Dir_structure.png)"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Experiment JSON file setup\n",
    "\n",
    "This file should contain the essential details of your experiment. It contains specifications regarding your experiment such as the stimuli you wish to analyse or the participants/subjects you wish to include. Mentioned below is the json file structure. The content below can be copied and pasted in a file called *NTU_Experiment*.json\n",
    "\n",
    "   * \"*Experiment_name*\" should be the same name as the json file without the extension and \"*Path*\" should be the absolute path to your experiment directory without the final \"/\" at the end.\n",
    "   * The subjects should be added under the \"*Subjects*\" field. You may specify one or more groups of division for your subjects (recommended for between group statistical analysis). **There must be atleast 1 group**.\n",
    "   * The stimuli names should be added under the \"*Stimuli*\" field and again you may specify one or more types (recommended for between/within stimulus type statistical analysis). **There must be atleast 1 type**.\n",
    "   * The \"*Control_Questions*\" field is optional. In case you have some stimuli that should be used to standardise/normalise features extracted from all stimuli, specify the names here. **These stimuli must be present under the \"*Stimuli*\" field under one of the types**.\n",
    "   * **The field marked \"*Columns_of_interest*\" should not be altered**.\n",
    "   * Under \"*Analysis_Params*\", just change the values of \"Sampling_Freq\", \"Display_height\" and \"Display_width\" to match the values of your experiment.\n",
    "\n",
    "   **Note**: If you wish to analyse only a subset of your stimuli or subjects, specify only the ones of interest in the json file. The analysis and visualization will be done only for the ones mentioned in the json file.\n",
    "\n",
    "**NOTE:** A sample json file is present in the NTU_Experiment folder in the sample data. You can just edit it to make your work simpler.\n",
    "\n",
    "```json\n",
    "{\n",
    "   \"Experiment_name\":\"NTU_Experiment\",\n",
    "   \"Path\":\"abcd/efgh/NTU_Experiment\",\n",
    "   \"Subjects\":{\n",
    "      \"group1\":[\n",
    "         \"Subject_01\",\n",
    "         \"Subject_02\"\n",
    "      ],\n",
    "      \"group2\":[\n",
    "         \"Subject_03\",\n",
    "         \"Subject_04\"\n",
    "      ]\n",
    "   },\n",
    "   \"Stimuli\":{\n",
    "      \"Type_1\":[\n",
    "         \"Stim_1\",\n",
    "         \"Stim_2\"\n",
    "      ],\n",
    "      \"Type_2\":[\n",
    "         \"Stim_3\",\n",
    "         \"Stim_4\"\n",
    "      ],\n",
    "   },\n",
    "   \"Control_Questions\":[\n",
    "         \"Stim_1\"\n",
    "    ],\n",
    "   \"Columns_of_interest\":{\n",
    "      \"EyeTracker\":[\n",
    "         \"GazeLeftx\",\n",
    "         \"GazeLefty\",\n",
    "         \"GazeRightx\",\n",
    "         \"GazeRighty\",\n",
    "         \"PupilLeft\",\n",
    "         \"PupilRight\",\n",
    "         \"FixationSeq\",\n",
    "         \"GazeAOI\"\n",
    "      ],\n",
    "      \"Extra\":[\n",
    "         \"EventSource\"\n",
    "      ]\n",
    "   },\n",
    "   \"Analysis_Params\":{\n",
    "      \"EyeTracker\":{\n",
    "        \"Sampling_Freq\": 1000,\n",
    "        \"Display_width\": 1920,\n",
    "        \"Display_height\": 1280\n",
    "      }\n",
    "   }\n",
    "}\n",
    "\n",
    "```"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Step1 : Convert eyetracker files to PyTrack compatible format"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "import os\n",
    "from PyTrack.formatBridge import generateCompatibleFormat\n",
    "\n",
    "# For windows the path will look like \n",
    "#    a. exp_path=\"complete\\\\path\\\\to\\\\NTU_Experiment\"\n",
    "# or b. exp_path=r\"complete\\path\\to\\NTU_Experiment\"\n",
    "generateCompatibleFormat(exp_path=os.path.abspath(\"PyTrack_Sample_Data/NTU_Experiment\"),\n",
    "                        device=\"eyelink\",\n",
    "                        stim_list_mode='NA',\n",
    "                        start='start_trial',\n",
    "                        stop='stop_trial',\n",
    "                        eye='B')"
   ],
   "outputs": [],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Step2 : Create an Experiment object \n",
    "\n",
    "Remember to open the NTU_Experiment.json file and change the \"Path\" to the complete path to the NTU_Experiment folder on your machine.\n",
    "\n",
    "eg.\n",
    "```\n",
    "{\n",
    "    \"Experiment_name\": \"NTU_Experiment\",\n",
    "    \"Path\": \"/home/abcd/Documents/PyTrack_Sample_Data/NTU_Experiment\",\n",
    "    ...\n",
    "}\n",
    "```"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "from PyTrack.Experiment import Experiment\n",
    "\n",
    "# Creating an object of the Experiment class\n",
    "exp = Experiment(json_file=os.path.abspath(\"PyTrack_Sample_Data/NTU_Experiment/NTU_Experiment.json\"), \n",
    "    reading_method='CSV')"
   ],
   "outputs": [],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Step3 : Extract features and run statstical tests"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Extract features and save them in CSV files without performing any tests."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "# Instantiate the meta_matrix_dict of an Experiment to find and extract all features from the raw data\n",
    "exp.metaMatrixInitialisation()\n",
    "\n",
    "# Does not run any statistical test. Just saves all the data as csv files.\n",
    "exp.analyse(parameter_list={\"all\"},\n",
    "            statistical_test=\"None\",\n",
    "            file_creation=True)"
   ],
   "outputs": [],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Extract features and perform a basic ANOVA test for each feature. Features and\n",
    "outputs of the test will be written to CSV files"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "# Calling the function for the statistical analysis of the data\n",
    "exp.analyse(parameter_list={\"all\"},\n",
    "            between_factor_list=[\"Subject_type\"],\n",
    "            within_factor_list=[\"Stimuli_type\"],\n",
    "            statistical_test=\"anova\",\n",
    "            file_creation=True)"
   ],
   "outputs": [],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Step4 : Visualisation"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "# This function call will open up a GUI which you can use to navigate the entire visualization process\n",
    "exp.visualizeData()"
   ],
   "outputs": [],
   "metadata": {}
  }
 ]
}