adding tags

Author: cmatKhan

docs/tutorials/virtual_db_tutorial.ipynb

@@ -33,14 +33,18 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Config saved to: /tmp/tmp60wlr_qk/vdb_config.yaml\n"
+      "Config saved to: /tmp/tmpnx5tjaud/vdb_config.yaml\n"
      ]
     }
    ],
    "source": [
     "config_yaml = \"\"\"\n",
     "repositories:\n",
     "  BrentLab/harbison_2004:\n",
+    "    tags:\n",
+    "      assay: binding\n",
+    "      method: chip-chip\n",
+    "      organism: yeast\n",
     "    dataset:\n",
     "      harbison_2004:\n",
     "        db_name: harbison\n",
@@ -59,6 +63,10 @@
     "          field: regulator_symbol\n",
     "\n",
     "  BrentLab/kemmeren_2014:\n",
+    "    tags:\n",
+    "      assay: perturbation\n",
+    "      method: microarray\n",
+    "      organism: yeast\n",
     "    dataset:\n",
     "      kemmeren_2014:\n",
     "        db_name: kemmeren\n",
@@ -75,8 +83,17 @@
     "          field: regulator_symbol\n",
     "\n",
     "  BrentLab/hackett_2020:\n",
+    "    # Repo-level tags apply to all datasets in this repository\n",
+    "    tags:\n",
+    "      method: test_overwrite\n",
+    "      organism: yeast\n",
     "    dataset:\n",
     "      hackett_2020:\n",
+    "        # Dataset-level tags: 'assay' is new,\n",
+    "        # 'method' overrides the repo-level value\n",
+    "        tags:\n",
+    "          assay: perturbation\n",
+    "          method: overexpression\n",
     "        db_name: hackett\n",
     "        sample_id:\n",
     "          field: sample_id\n",
@@ -126,6 +143,56 @@
     "print(f\"Config saved to: {temp_config}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "ftysbe3fwz4",
+   "metadata": {},
+   "source": [
+    "## Tags\n",
+    "\n",
+    "Tags are arbitrary key/value annotations defined in the configuration. They\n",
+    "follow the same hierarchy as property mappings: repo-level tags apply to all\n",
+    "datasets in that repository, and dataset-level tags override repo-level tags\n",
+    "with the same key.\n",
+    "\n",
+    "Use `config.get_tags(repo_id, config_name)` to retrieve the merged tags for\n",
+    "any dataset."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "d0ulj4mzmf7",
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "NameError",
+     "evalue": "name 'vdb' is not defined",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[31m---------------------------------------------------------------------------\u001b[39m",
+      "\u001b[31mNameError\u001b[39m                                 Traceback (most recent call last)",
+      "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[2]\u001b[39m\u001b[32m, line 3\u001b[39m\n\u001b[32m      1\u001b[39m \u001b[38;5;66;03m# Tags are accessible directly from the VirtualDB instance using the db_name.\u001b[39;00m\n\u001b[32m      2\u001b[39m \u001b[38;5;66;03m# No need to import MetadataConfig or specify repo_id.\u001b[39;00m\n\u001b[32m----> \u001b[39m\u001b[32m3\u001b[39m \u001b[38;5;28mprint\u001b[39m(\u001b[33m\"\u001b[39m\u001b[33mharbison tags:\u001b[39m\u001b[33m\"\u001b[39m, \u001b[43mvdb\u001b[49m.get_tags(\u001b[33m\"\u001b[39m\u001b[33mharbison\u001b[39m\u001b[33m\"\u001b[39m))\n\u001b[32m      4\u001b[39m \u001b[38;5;28mprint\u001b[39m(\u001b[33m\"\u001b[39m\u001b[33mkemmeren tags:\u001b[39m\u001b[33m\"\u001b[39m, vdb.get_tags(\u001b[33m\"\u001b[39m\u001b[33mkemmeren\u001b[39m\u001b[33m\"\u001b[39m))\n\u001b[32m      6\u001b[39m \u001b[38;5;66;03m# Hackett has tags at both levels:\u001b[39;00m\n\u001b[32m      7\u001b[39m \u001b[38;5;66;03m# 'organism' comes from the repo level only,\u001b[39;00m\n\u001b[32m      8\u001b[39m \u001b[38;5;66;03m# 'assay' is added at the dataset level only,\u001b[39;00m\n\u001b[32m      9\u001b[39m \u001b[38;5;66;03m# 'method' is defined at both levels -- the dataset value wins.\u001b[39;00m\n",
+      "\u001b[31mNameError\u001b[39m: name 'vdb' is not defined"
+     ]
+    }
+   ],
+   "source": [
+    "# Tags are accessible directly from the VirtualDB instance using the db_name.\n",
+    "# No need to import MetadataConfig or specify repo_id.\n",
+    "print(\"harbison tags:\", vdb.get_tags(\"harbison\"))\n",
+    "print(\"kemmeren tags:\", vdb.get_tags(\"kemmeren\"))\n",
+    "\n",
+    "# Hackett has tags at both levels:\n",
+    "# 'organism' comes from the repo level only,\n",
+    "# 'assay' is added at the dataset level only,\n",
+    "# 'method' is defined at both levels -- the dataset value wins.\n",
+    "print(\"hackett tags:\", vdb.get_tags(\"hackett\"))\n",
+    "\n",
+    "# Dataset with no tags returns empty dict\n",
+    "print(\"dto tags:\", vdb.get_tags(\"dto\"))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "cell-3",
@@ -140,7 +207,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "cell-4",
    "metadata": {},
    "outputs": [
@@ -187,7 +254,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "cell-6",
    "metadata": {},
    "outputs": [
@@ -236,7 +303,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "pdebujnqb9q",
    "metadata": {},
    "outputs": [
@@ -469,7 +536,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "id": "9deee334",
    "metadata": {},
    "outputs": [
@@ -806,7 +873,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "id": "cell-9",
    "metadata": {},
    "outputs": [
@@ -840,7 +907,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "id": "1a705f1c",
    "metadata": {},
    "outputs": [
@@ -1056,7 +1123,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "id": "cell-17",
    "metadata": {},
    "outputs": [
@@ -1362,7 +1429,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "id": "cell-19",
    "metadata": {},
    "outputs": [
@@ -1786,7 +1853,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": null,
    "id": "cell-21",
    "metadata": {},
    "outputs": [
@@ -2064,7 +2131,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": null,
    "id": "cell-22",
    "metadata": {},
    "outputs": [
@@ -2427,7 +2494,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": null,
    "id": "cell-23",
    "metadata": {},
    "outputs": [
@@ -2691,7 +2758,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
    "id": "f03e942a",
    "metadata": {},
    "outputs": [
@@ -3387,7 +3454,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": null,
    "id": "4d869036",
    "metadata": {},
    "outputs": [
@@ -3603,7 +3670,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": null,
    "id": "89408d2b",
    "metadata": {},
    "outputs": [
@@ -3631,7 +3698,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
    "id": "5a3b802b",
    "metadata": {},
    "outputs": [
@@ -3651,7 +3718,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": null,
    "id": "abed8bc2",
    "metadata": {},
    "outputs": [
@@ -4927,7 +4994,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": null,
    "id": "cell-25",
    "metadata": {},
    "outputs": [
@@ -5017,7 +5084,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": null,
    "id": "cell-26",
    "metadata": {},
    "outputs": [],

docs/virtual_db_configuration.md

@@ -147,6 +147,62 @@ during metadata extraction and query filtering.
 2. **Type consistency**: When source data might be extracted with incorrect type
 3. **Performance**: Helps with query optimization and prevents type mismatches
 
+## Tags
+
+Tags are arbitrary string key/value pairs for annotating datasets. They follow
+the same hierarchy as property mappings: repo-level tags apply to all datasets
+in the repository, dataset-level tags apply only to that dataset, and
+dataset-level tags override repo-level tags with the same key.
+
+```yaml
+repositories:
+  BrentLab/harbison_2004:
+    # Repo-level tags apply to all datasets in this repository
+    tags:
+      assay: binding
+      organism: yeast
+    dataset:
+      harbison_2004:
+        sample_id:
+          field: sample_id
+        # Dataset-level tags override repo-level tags with the same key
+        tags:
+          assay: chip-chip
+
+  BrentLab/kemmeren_2014:
+    tags:
+      assay: perturbation
+      organism: yeast
+    dataset:
+      kemmeren_2014:
+        sample_id:
+          field: sample_id
+```
+
+Access merged tags via `vdb.get_tags(db_name)`, identifying datasets by
+their name as it appears in `vdb.tables()`:
+
+```python
+from tfbpapi.virtual_db import VirtualDB
+
+vdb = VirtualDB("datasets.yaml")
+
+# Returns {"assay": "chip-chip", "organism": "yeast"}
+# (dataset-level assay overrides repo-level)
+vdb.get_tags("harbison")
+
+# Returns {"assay": "perturbation", "organism": "yeast"}
+vdb.get_tags("kemmeren")
+```
+
+The underlying `MetadataConfig` (available as `vdb.config`) exposes the same
+data via `(repo_id, config_name)` pairs for programmatic or developer use:
+
+```python
+# Equivalent to vdb.get_tags("harbison") above
+vdb.config.get_tags("BrentLab/harbison_2004", "harbison_2004")
+```
+
 ## Comparative Datasets
 
 Comparative datasets differ from other dataset types in that they represent