Add examples

examples/brain_lateralization/configs/default_cfg.py

@@ -0,0 +1,49 @@
+"""
+Default configurations
+"""
+
+from yacs.config import CfgNode as CN
+
+# -----------------------------------------------------------------------------
+# Config definition
+# -----------------------------------------------------------------------------
+
+_C = CN()
+
+# -----------------------------------------------------------------------------
+# Dataset
+# -----------------------------------------------------------------------------
+_C.DATASET = CN()
+_C.DATASET.DATASET = "HCP"
+_C.DATASET.DOWNLOAD = True
+_C.DATASET.ROOT = "data"
+_C.DATASET.ATLAS = "BNA"
+_C.DATASET.FEATURE = "correlation"
+_C.DATASET.TEST_RATIO = 0.0
+_C.DATASET.TYPE = "functional"
+_C.DATASET.SESSIONS = [None]
+_C.DATASET.RUN = "Fisherz"
+_C.DATASET.CONNECTION = "intra"
+_C.DATASET.NUM_REPEAT = 1
+_C.DATASET.MIX_GROUP = False
+_C.DATASET.REST1_ONLY = False  # only use rest1 data for training, HCP dataset only
+# ---------------------------------------------------------------------------- #
+# Solver
+# ---------------------------------------------------------------------------- #
+_C.SOLVER = CN()
+_C.SOLVER.SEED = 2023
+_C.SOLVER.L2_HPARAM = 0.1  # hyperparameter for the l2 regularization
+_C.SOLVER.LR = 0.04  # Initial learning rate
+_C.SOLVER.OPTIMIZER = "lbfgs"
+_C.SOLVER.MAX_ITER = 100
+_C.SOLVER.LAMBDA_ = [0.0, 1.0, 2.0, 5.0, 8.0, 10.0]
+
+# ---------------------------------------------------------------------------- #
+# Misc options
+# ---------------------------------------------------------------------------- #
+_C.OUTPUT = CN()
+_C.OUTPUT.ROOT = "output"
+
+
+def get_cfg_defaults():
+    return _C.clone()

examples/brain_lateralization/configs/demo-gsp.yaml

@@ -0,0 +1,13 @@
+DATASET:
+  DATASET: "GSP"
+  ROOT: "data"
+  MIX_GROUP: False
+  TEST_RATIO: 0.2
+SOLVER:
+  LAMBDA_: [0.0, 2.0, 5.0, 10]
+  LR: 1.0
+  SEED: 2023
+  OPTIMIZER: "lbfgs"
+  MAX_ITER: 100
+OUTPUT:
+  ROOT: "output"

examples/brain_lateralization/configs/demo-hcp.yaml

@@ -0,0 +1,13 @@
+DATASET:
+  DATASET: "HCP"
+  ROOT: "data"
+  MIX_GROUP: False
+  TEST_RATIO: 0.2
+SOLVER:
+  LAMBDA_: [0.0, 2.0, 5.0, 10]
+  LR: 1.0
+  SEED: 2023
+  OPTIMIZER: "lbfgs"
+  MAX_ITER: 100
+OUTPUT:
+  ROOT: "output"

examples/brain_lateralization/configs/test.yaml

@@ -0,0 +1,7 @@
+DATASET:
+  ROOT: "data"
+  NUM_REPEAT: 5
+SOLVER:
+  SEED: 2022
+OUTPUT:
+  ROOT: 'output'

examples/brain_lateralization/tutorial.ipynb

@@ -0,0 +1,158 @@
+{
+  "nbformat": 4,
+  "nbformat_minor": 2,
+  "metadata": {},
+  "cells": [
+    {
+      "metadata": {},
+      "source": [
+        "# Group-Specific Discriminant Analysis for sex-specific lateralization Running Demo\n",
+        "\n",
+        "[Open in Colab](https://colab.research.google.com/github/pykale/kale-linear/blob/main/examples/brain_lateralization/gsda_demo.ipynb)  (click `Runtime`\u2006\u2192\u2006`Run all (Ctrl+F9)`)"
+      ],
+      "cell_type": "markdown"
+    },
+    {
+      "metadata": {},
+      "source": [
+        "## Setup\n",
+        "\n",
+        "The first few blocks of code are necessary to set up the notebook execution environment. This checks if the notebook is running on Google Colab and installs required packages."
+      ],
+      "cell_type": "markdown"
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Setup environment and fetch code from GitHub\n",
+        "\n",
+        "if 'google.colab' in str(get_ipython()):\n",
+        "    print('Running on CoLab')\n",
+        "    !pip install yacs\n",
+        "    !git clone https://github.com/pykale/kale-linear\n",
+        "    %cd kale-linear/examples/brain_lateralization\n",
+        "else:\n",
+        "    print('Not running on CoLab')\n",
+        "     "
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Import required modules\n",
+        "import os\n",
+        "from configs.default_cfg import get_cfg_defaults\n",
+        "from utils.experiment import run_experiment\n",
+        "\n",
+        "from utils.io_ import load_result, reformat_results\n",
+        "from utils import plot"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "### Configurations\n",
+        "\n",
+        "The customized configuration used in this demo is stored in `configs/demo-cp.yaml`, this file overwrites defaults in `default_cfg.py` where a value is specified. Change the configuration file path to `cfg_path = \"configs/demo-gsp.yaml\"` for running the demo with GSP data."
+      ],
+      "cell_type": "markdown"
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Setup configs using .yaml file\n",
+        "cfg_path = \"configs/demo-hcp.yaml\" # Path to `.yaml` config file\n",
+        "\n",
+        "cfg = get_cfg_defaults()\n",
+        "cfg.merge_from_file(cfg_path)\n",
+        "cfg.freeze()\n",
+        "print(cfg)"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "## Group-specific model training\n",
+        "\n",
+        "It could take a while (15 to 25 mins) to run the experiments. "
+      ],
+      "cell_type": "markdown"
+    },
+    {
+      "metadata": {},
+      "source": [
+        "_ = [run_experiment(cfg, lambda_) for lambda_ in cfg.SOLVER.LAMBDA_]"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "## Classification result visualization"
+      ],
+      "cell_type": "markdown"
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Load results and reformat as a dataframe\n",
+        "\n",
+        "dataset = cfg.DATASET.DATASET\n",
+        "model_root_dir = cfg.OUTPUT.ROOT\n",
+        "lambdas = cfg.SOLVER.LAMBDA_\n",
+        "seed_start = cfg.SOLVER.SEED\n",
+        "test_size = cfg.DATASET.TEST_RATIO\n",
+        "\n",
+        "res_df = load_result(dataset=dataset, root_dir=model_root_dir, \n",
+        "                         lambdas=lambdas, seed_start=seed_start, test_size=test_size)\n",
+        "\n",
+        "res_df[\"GSI_train_session\"] = 2 * (res_df[\"acc_tgt_train_session\"] * \n",
+        "                                       (res_df[\"acc_tgt_train_session\"] - \n",
+        "                                        res_df[\"acc_nt_train_session\"]))\n",
+        "res_df[\"GSI_test_session\"] = 2 * (res_df[\"acc_tgt_test_session\"] * \n",
+        "                                      (res_df[\"acc_tgt_test_session\"] - \n",
+        "                                       res_df[\"acc_nt_test_session\"]))\n",
+        "\n",
+        "res_df_train_session = reformat_results(res_df, [\"acc_tgt_train_session\", \"acc_nt_train_session\"])\n",
+        "res_df_test_session = reformat_results(res_df, [\"acc_tgt_test_session\", \"acc_nt_test_session\"])"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Plot accuracy\n",
+        "\n",
+        "if not os.path.exists(\"figures\"):\n",
+        "    os.mkdir(\"figures\")\n",
+        "plot.plot_accuracy(res_df_train_session)"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {},
+      "source": [
+        "#@title Plot Group Specificity Index (GSI)\n",
+        "plot.plot_gsi(res_df, x=\"lambda\", y=\"GSI_train_session\", hue=\"target_group\")"
+      ],
+      "cell_type": "code",
+      "outputs": [],
+      "execution_count": null
+    }
+  ]
+}