{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "## Validate HED in a BIDS dataset.\n",
    "\n",
    "Validating HED annotations as you develop them makes the annotation process much easier and faster to debug. This notebook validates HED in a BIDS dataset.\n",
    "\n",
    "The tool creates a `BidsDataset` object, which represents the information from a BIDS dataset that is relevant to HED, including the `dataset_description.json`, all `events.tsv` files, and all `events.json` sidecar files.\n",
    "\n",
    "The `validate` method of `BidsDataset` first validates all of the `events.json` sidecars and then assembles the relevant sidecars for each `events.tsv` file and validates it. The validation uses the HED schemas specified in the `HEDVersion` field of the dataset's `dataset_description.json` file.\n",
    "\n",
    "The script does the following steps:\n",
    "\n",
    "1. Set the dataset location (`dataset_path`) to the absolute path of the root of your BIDS dataset.\n",
    "2. Indicates whether to check for warnings during validation (`check_for_warnings`).\n",
    "3. Create a `BidsDataset` for the dataset.\n",
    "4. Validate the dataset and output the issues.\n",
    "\n",
    "**Note:** This validation pertains to event files and HED annotation only. It does not do a full BIDS validation.\n",
    "\n",
    "\n",
    "For validation of a single `events.json` file during annotation development, users often find the [**online sidecar tools**](https://hedtools.ucsd.edu/hed/sidecar) convenient, but the online tool does not provide complete dataset-level validation."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "from hed.errors import get_printable_issue_string\n",
    "from hed.tools import BidsDataset\n",
    "from hed import _version as vr\n",
    "\n",
    "print(f\"Using HEDTOOLS version: {str(vr.get_versions())}\")\n",
    "\n",
    "## Set the dataset location and the check_for_warnings flag\n",
    "check_for_warnings = True\n",
    "dataset_dir = \"../../../datasets/eeg_ds004105s_hed\"\n",
    "# outfile = 'temp.txt'\n",
    "outfile = \"\"\n",
    "\n",
    "## Validate the dataset\n",
    "bids = BidsDataset(dataset_dir)\n",
    "issue_list = bids.validate(check_for_warnings=check_for_warnings)\n",
    "if issue_list:\n",
    "    issue_str = get_printable_issue_string(issue_list, \"HED validation errors: \", skip_filename=False)\n",
    "else:\n",
    "    issue_str = \"No HED validation errors\"\n",
    "# print(issue_str)\n",
    "print(f\"Number of issues: {len(issue_list)}\")\n",
    "if outfile and issue_list:\n",
    "    with open(outfile, \"w\") as fp:\n",
    "        fp.write(issue_str)\n",
    "else:\n",
    "    print(f\"{issue_str}\")"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2025-03-13T21:43:10.913063Z",
     "start_time": "2025-03-13T21:43:02.839791Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using HEDTOOLS version: {'date': '2025-03-11T13:51:39-0500', 'dirty': True, 'error': None, 'full-revisionid': '66de2a50dc86db45aa722556493569adae4ac5ea', 'version': '0.5.0+186.g66de2a50.dirty'}\n",
      "Number of issues: 0\n",
      "No HED validation errors\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
}