src/jupyter_notebooks/bids/sidecar_to_spreadsheet.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "## Convert an existing JSON sidecar to spreadsheet format.\n",
    "\n",
    "This notebook creates a 4-column spreadsheet (Pandas dataframe) corresponding to the HED content of a JSON sidecar.\n",
    "This is useful for quickly reviewing and editing HED annotations.\n",
    "\n",
    "You can easily merge the edited information back into the spreadsheet. \n",
    "\n",
    "| Variable | Purpose |\n",
    "| -------- | ------- |\n",
    "| `json_path` | Path of the JSON sidecar file to be converted to 4-column spreadsheet. |\n",
    "| `spreadsheet_path` | Path to save the resulting 4-column tsv file. |\n",
    "\n",
    "To use this notebook, you will need to provide the path to the JSON sidecar and a path to save the spreadsheet if you want to save it. If you don't wish to save the spreadsheet, assign `spreadsheet_filename` to be None.\n"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "import os\n",
    "import json\n",
    "from io import StringIO\n",
    "from hed.tools import hed_to_df\n",
    "\n",
    "json_path =  os.path.realpath('../../../datasets/eeg_ds003645s_hed/task-FacePerception_events.json')\n",
    "spreadsheet_filename = ''\n",
    "with open(json_path) as fp:\n",
    "    example_sidecar = json.load(fp)\n",
    "example_spreadsheet = hed_to_df(example_sidecar)\n",
    "if spreadsheet_filename:\n",
    "    print(f\"Saving the spreadsheet to {os.path.basename(spreadsheet_filename)}\")\n",
    "    example_spreadsheet.to_csv(spreadsheet_filename, sep='\\t', index=False,)\n",
    "else:\n",
    "    output = StringIO()\n",
    "    example_spreadsheet.to_csv(output, sep='\\t', index=False,)\n",
    "    print(f\"{output.getvalue()}\")"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% Create a spreadsheet corresponding to a JSON sidecar and save it.\n"
    },
    "ExecuteTime": {
     "end_time": "2024-09-26T11:19:51.584884Z",
     "start_time": "2024-09-26T11:19:50.106320Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "column_name\tcolumn_value\tdescription\tHED\r\n",
      "event_type\tshow_face\tDisplay a face to mark end of pre-stimulus and start of blink-inhibition.\tSensory-event, Experimental-stimulus, (Def/Face-image, Onset), (Def/Blink-inhibition-task,Onset),(Def/Cross-only, Offset)\r\n",
      "event_type\tshow_face_initial\tDisplay a face at the beginning of the recording.\tSensory-event, Experimental-stimulus, (Def/Face-image, Onset), (Def/Blink-inhibition-task,Onset), (Def/Fixation-task, Onset)\r\n",
      "event_type\tshow_circle\tDisplay a white circle to mark end of the stimulus and blink inhibition.\tSensory-event, (Intended-effect, Cue), (Def/Circle-only, Onset), (Def/Face-image, Offset), (Def/Blink-inhibition-task, Offset), (Def/Fixation-task, Offset)\r\n",
      "event_type\tshow_cross\tDisplay only a white cross to mark start of trial and fixation.\tSensory-event, (Intended-effect, Cue), (Def/Cross-only, Onset), (Def/Fixation-task, Onset),  (Def/Circle-only, Offset)\r\n",
      "event_type\tleft_press\tExperiment participant presses a key with left index finger.\tAgent-action, Participant-response, Def/Press-left-finger\r\n",
      "event_type\tright_press\tExperiment participant presses a key with right index finger.\tAgent-action, Participant-response, Def/Press-right-finger\r\n",
      "event_type\tsetup_left_sym\tSetup for experiment with pressing key with left index finger means a face with above average symmetry.\tExperiment-structure, (Def/Left-sym-cond, Onset), (Def/Initialize-recording, Onset)\r\n",
      "event_type\tsetup_right_sym\tSetup for experiment with pressing key with right index finger means a face with above average symmetry.\tExperiment-structure, (Def/Right-sym-cond, Onset), (Def/Initialize-recording, Onset)\r\n",
      "event_type\tdouble_press\tExperiment participant presses both keys .\tAgent-action, Indeterminate-action, (Press, Keyboard-key)\r\n",
      "face_type\tfamous_face\tA face that should be recognized by the participants.\tDef/Famous-face-cond\r\n",
      "face_type\tunfamiliar_face\tA face that should not be recognized by the participants.\tDef/Unfamiliar-face-cond\r\n",
      "face_type\tscrambled_face\tA scrambled face image generated by taking face 2D FFT.\tDef/Scrambled-face-cond\r\n",
      "rep_status\tfirst_show\tFactor level indicating the first display of this face.\tDef/First-show-cond\r\n",
      "rep_status\timmediate_repeat\tFactor level indicating this face was the same as previous one.\tDef/Immediate-repeat-cond\r\n",
      "rep_status\tdelayed_repeat\tFactor level indicating face was seen 5 to 15 trials ago.\tDef/Delayed-repeat-cond\r\n",
      "rep_lag\tn/a\tHow face images before this one was the image was previously presented.\t(Face, Item-interval/#)\r\n",
      "stim_file\tn/a\tPath of the stimulus file in the stimuli directory.\t(Image, Pathname/#)\r\n",
      "hed_def_sensory\tcross_only_def\tA white fixation cross on a black background in the center of the screen.\t(Definition/Cross-only, (Visual-presentation, (Foreground-view, (White, Cross), (Center-of, Computer-screen)), (Background-view, Black)))\r\n",
      "hed_def_sensory\tface_image_def\tA happy or neutral face in frontal or three-quarters frontal pose with long hair cropped presented as an achromatic foreground image on a black background with a white fixation cross superposed.\t(Definition/Face-image, (Visual-presentation, (Foreground-view, ((Image, Face, Hair), Color/Grayscale), ((White, Cross), (Center-of, Computer-screen))), (Background-view, Black)))\r\n",
      "hed_def_sensory\tcircle_only_def\tA white circle on a black background in the center of the screen.\t(Definition/Circle-only, (Visual-presentation, (Foreground-view, ((White, Circle), (Center-of, Computer-screen))), (Background-view, Black)))\r\n",
      "hed_def_actions\tpress_left_finger_def\tThe participant presses a key with the left index finger to indicate a face symmetry judgment.\t(Definition/Press-left-finger, ((Index-finger, (Left-side-of, Experiment-participant)), (Press, Keyboard-key)))\r\n",
      "hed_def_actions\tpress_right_finger_def\tThe participant presses a key with the right index finger to indicate a face symmetry evaluation.\t(Definition/Press-right-finger, ((Index-finger, (Right-side-of, Experiment-participant)), (Press, Keyboard-key)))\r\n",
      "hed_def_conds\tfamous_face_cond_def\tA face that should be recognized by the participants\t(Definition/Famous-face-cond, (Condition-variable/Face-type, (Image, (Face, Famous))))\r\n",
      "hed_def_conds\tunfamiliar_face_cond_def\tA face that should not be recognized by the participants.\t(Definition/Unfamiliar-face-cond, (Condition-variable/Face-type, (Image, (Face, Unfamiliar))))\r\n",
      "hed_def_conds\tscrambled_face_cond_def\tA scrambled face image generated by taking face 2D FFT.\t(Definition/Scrambled-face-cond, (Condition-variable/Face-type, (Image, (Face, Disordered))))\r\n",
      "hed_def_conds\tfirst_show_cond_def\tFactor level indicating the first display of this face.\t(Definition/First-show-cond, ((Condition-variable/Repetition-type, (Item-count/1, Face), Item-interval/0)))\r\n",
      "hed_def_conds\timmediate_repeat_cond_def\tFactor level indicating this face was the same as previous one.\t(Definition/Immediate-repeat-cond, ((Condition-variable/Repetition-type, (Item-count/2, Face), Item-interval/1)))\r\n",
      "hed_def_conds\tdelayed_repeat_cond_def\tFactor level indicating face was seen 5 to 15 trials ago.\t(Definition/Delayed-repeat-cond, (Condition-variable/Repetition-type, (Item-count/2, Face), (Item-interval, (Greater-than-or-equal-to, Item-interval/5))))\r\n",
      "hed_def_conds\tleft_sym_cond_def\tLeft index finger key press indicates a face with above average symmetry.\t(Definition/Left-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical))))\r\n",
      "hed_def_conds\tright_sym_cond_def\tRight index finger key press indicates a face with above average symmetry.\t(Definition/Right-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical))))\r\n",
      "hed_def_tasks\tface_symmetry_evaluation_task_def\tEvaluate degree of image symmetry and respond with key press evaluation.\t(Definition/Face-symmetry-evaluation-task, (Task, Experiment-participant, (See, Face), (Discriminate, (Face, Symmetrical)), (Press, Keyboard-key)))\r\n",
      "hed_def_tasks\tblink_inhibition_task_def\tDo not blink while the face image is displayed.\t(Definition/Blink-inhibition-task, (Task, Experiment-participant, Inhibit-blinks))\r\n",
      "hed_def_tasks\tfixation_task_def\tFixate on the cross at the screen center.\t(Definition/Fixation-task, (Task, Experiment-participant, (Fixate, Cross)))\r\n",
      "hed_def_setup\tsetup_def\tn/a\t(Definition/Initialize-recording, (Recording))\r\n",
      "\n"
     ]
    }
   ],
   "execution_count": 1
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}