{ "cells": [ { "cell_type": "markdown", "source": [ "# Experiment IDs\n", "There are multiple ways to uniquely identify an experiment:\n", "\n", "- eID (str) : An experiment UUID as a string\n", "- np (int64) : An experiment UUID encoded as 2 int64s\n", "- path (Path) : A pathlib ALF path of the form \\/Subjects/\\/\\/\\\n", "- ref (str) : An experiment reference string of the form yyyy-mm-dd_n_subject\n", "- url (str) : An remote http session path of the form \\/Subjects/\\/\\/\\\n", "\n", "Internally Alyx and ONE uses eID strings to identify sessions. For example One.search returns a\n", "list of eID strings. In the ONE cache tables they are represented as a numpy array of 2 int64s\n", "because these are faster to search over. Session paths, URLs and ref strings are more readable." ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 1, "metadata": { "execution": { "iopub.execute_input": "2021-09-07T19:21:20.618438Z", "iopub.status.busy": "2021-09-07T19:21:20.617439Z", "iopub.status.idle": "2021-09-07T19:21:26.888291Z", "shell.execute_reply": "2021-09-07T19:21:26.888647Z" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.185570900Z", "start_time": "2023-08-31T13:00:31.240317Z" } }, "outputs": [], "source": [ "from uuid import UUID\n", "\n", "from one.api import ONE\n", "from one.alf.spec import is_session_path, is_uuid_string, is_uuid\n", "\n", "one = ONE(base_url='https://openalyx.internationalbrainlab.org')" ] }, { "cell_type": "markdown", "source": [ "One.search returns experiment uuid strings" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "execution_count": 2, "outputs": [], "source": [ "eids = one.search(data='channels.brainLocation', date=['2022-08-01', '2022-09-01'])\n", "assert is_uuid_string(eids[0])" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.276636900Z", "start_time": "2023-08-31T13:00:33.201557400Z" } } }, { "cell_type": "markdown", "source": [ "eID strings can be easily converted to other forms" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "execution_count": 3, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Session exists on disk\n" ] } ], "source": [ "session_path = one.eid2path(eids[0]) # returns a pathlib.Path object\n", "assert is_session_path(session_path)\n", "print(f'Session {\"exists\" if session_path.exists() else \"does not exist\"} on disk')\n", "\n", "uuid = UUID(eids[0])\n", "assert is_uuid(uuid)" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.334940500Z", "start_time": "2023-08-31T13:00:33.284784700Z" } } }, { "cell_type": "markdown", "source": [ "These conversion functions can except lists of experiment ids" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "execution_count": 4, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'subject': 'NR_0027', 'date': datetime.date(2022, 8, 23), 'sequence': 1}\n" ] } ], "source": [ "ref_dict = one.eid2ref(eids)\n", "assert len(ref_dict) == len(eids)\n", "print(ref_dict[0])" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.412980900Z", "start_time": "2023-08-31T13:00:33.311614400Z" } } }, { "cell_type": "markdown", "source": [ "ref strings can be sorted lexicographically (by date, number and subject in that order)" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "source": [ "refs = sorted(one.dict2ref(ref_dict))\n", "print(refs)\n", "\n", "# Most ids can be interconverted also\n", "eid = one.path2eid(\n", " one.ref2path(\n", " one.dict2ref(\n", " one.eid2ref(eids[0])\n", " )\n", " )\n", ")\n", "assert eid == eids[0]" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.488753800Z", "start_time": "2023-08-31T13:00:33.374118Z" } }, "execution_count": 5, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "['2022-08-19_1_NR_0027', '2022-08-22_1_NR_0027', '2022-08-23_1_NR_0027']\n" ] } ] }, { "cell_type": "markdown", "source": [ "The `to_eid` method will convert any form to a UUID string or raise a ValueError if invalid:" ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 6, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "['aad23144-0e52-4eac-80c5-c4ee2decb198', 'ae8787b1-4229-4d56-b0c2-566b61a25b77', 'c7bd79c9-c47e-4ea5-aea3-74dda991b48e']\n" ] } ], "source": [ "ids = ['2019-12-10_1_KS023', 'ae8787b1-4229-4d56-b0c2-566b61a25b77', 'CSH_ZAD_029/2020-09-19/001']\n", "print(one.to_eid(ids))" ], "metadata": { "collapsed": false, "ExecuteTime": { "end_time": "2023-08-31T13:00:33.498326200Z", "start_time": "2023-08-31T13:00:33.460256700Z" } } }, { "cell_type": "markdown", "source": [ "One load functions can accept most kinds of experiment identifiers" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "execution_count": 7, "outputs": [], "source": [ "filepath = one.load_dataset(eid, 'channels.brainLocationIds_ccf_2017.npy', download_only=True)\n", "dset = one.load_dataset(session_path, 'channels.brainLocationIds_ccf_2017.npy')\n", "dset = one.load_dataset(filepath, 'channels.brainLocationIds_ccf_2017.npy')\n", "\n", "short_path = '/'.join(session_path.parts[-3:]) # 'subject/date/number'\n", "dset = one.load_dataset(short_path, 'channels.brainLocationIds_ccf_2017.npy')\n", "\n", "url = one.path2url(filepath)\n", "dset = one.load_dataset(url, 'channels.brainLocationIds_ccf_2017.npy')\n", "dset = one.load_dataset(ref_dict[0], 'channels.brainLocationIds_ccf_2017.npy')\n", "dset = one.load_dataset(refs[2], 'channels.brainLocationIds_ccf_2017.npy')" ], "metadata": { "collapsed": false, "ExecuteTime": { "end_time": "2023-08-31T13:00:34.329216900Z", "start_time": "2023-08-31T13:00:33.480427700Z" } } }, { "cell_type": "markdown", "source": [ "Likewise with other load methods..." ], "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } } }, { "cell_type": "code", "source": [ "obj = one.load_object(short_path, 'channels', attribute='brainLocationIds')" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:34.465326200Z", "start_time": "2023-08-31T13:00:34.331212500Z" } }, "execution_count": 8, "outputs": [] }, { "cell_type": "markdown", "source": [ "You can get information about an experiment from its ID using the `get_details` method:" ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 9, "outputs": [ { "data": { "text/plain": "{'subject': 'NR_0027',\n 'lab': 'steinmetzlab',\n 'projects': 'ibl_neuropixel_brainwide_01',\n 'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.6.2',\n 'number': 1,\n 'start_time': '2022-08-23T09:26:09',\n 'url': 'https://openalyx.internationalbrainlab.org/sessions/ae8787b1-4229-4d56-b0c2-566b61a25b77',\n 'local_path': WindowsPath('F:/FlatIron/openalyx.internationalbrainlab.org/steinmetzlab/Subjects/NR_0027/2022-08-23/001'),\n 'date': datetime.date(2022, 8, 23)}" }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "info = one.get_details(eid)\n", "info" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:34.524588100Z", "start_time": "2023-08-31T13:00:34.470311600Z" } } }, { "cell_type": "markdown", "source": [ "In online mode you get retrieve exhaustive session information:" ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 10, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "dict_keys(['subject', 'users', 'location', 'procedures', 'lab', 'projects', 'type', 'task_protocol', 'number', 'start_time', 'end_time', 'narrative', 'parent_session', 'n_correct_trials', 'n_trials', 'url', 'extended_qc', 'qc', 'wateradmin_session_related', 'data_dataset_session_related', 'auto_datetime', 'id', 'json', 'probe_insertion', 'field_of_view', 'notes'])\n" ] } ], "source": [ "assert not one.offline\n", "info = one.get_details(eid, full=True)\n", "print(info.keys())" ], "metadata": { "collapsed": false, "pycharm": { "name": "#%%\n" }, "ExecuteTime": { "end_time": "2023-08-31T13:00:34.549041400Z", "start_time": "2023-08-31T13:00:34.501609600Z" } } } ], "metadata": { "docs_executed": "executed", "kernelspec": { "display_name": "Python 3", "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.8.8" } }, "nbformat": 4, "nbformat_minor": 0 }