Merge branch 'docs' into develop

Author: GaelleChapuis

examples/loading_data/loading_trials_data.ipynb

@@ -45,7 +45,45 @@
   {
    "cell_type": "markdown",
    "source": [
-    "## Loading a session's trials"
+    "## Loading a single session's trials\n",
+    "\n",
+    "If you want to load the trials data for a single session, we recommend you use the `SessionLoader`:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "'''\n",
+    "RECOMMENDED\n",
+    "'''\n",
+    "from brainbox.io.one import SessionLoader\n",
+    "from one.api import ONE\n",
+    "one = ONE()\n",
+    "eid = '4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a'\n",
+    "sl = SessionLoader(eid=eid, one=one)\n",
+    "sl.load_trials()\n",
+    "\n",
+    "# The datasets are attributes of the sl.trials, for example probabilityLeft :\n",
+    "probabilityLeft = sl.trials['probabilityLeft']\n",
+    "# Find all of them using:\n",
+    "sl.trials.keys()"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "For completeness, we present below how to load the trials object using the `one.load_object` method, however we recommend you use the code above and use the `SessionLoader` instead."
    ],
    "metadata": {
     "collapsed": false
@@ -56,6 +94,9 @@
    "execution_count": null,
    "outputs": [],
    "source": [
+    "'''\n",
+    "ALTERNATIVE - NOT RECOMMENDED\n",
+    "'''\n",
     "from one.api import ONE\n",
     "one = ONE()\n",
     "eid = '4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a'\n",
@@ -73,9 +114,10 @@
    "id": "0514237a",
    "metadata": {},
    "source": [
-    "## Loading a subject's trials\n",
-    "This loads all trials data for a given subject (all session trials concatenated) into a DataFrame.\n",
-    "The subjectTraining table contains the training statuses."
+    "## Loading all the sessions' trials for a single subject at once\n",
+    "If you want to study several sessions for a single subject, we recommend you use the `one.load_aggregate` method rather than downloading each trials data individually per session.\n",
+    "This methods loads all the trials data `subjectTrials` for a given subject into a single DataFrame (i.e. all session trials are concatenated).\n",
+    "You can use the same method to load the `subjectTraining` table, which contains the training statuses."
    ]
   },
   {