{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Dataset Initialization\n\nOne-time setup before working with the LAION-fMRI dataset.\n\nThis example walks through the steps a new user takes the first\ntime they use the package:\n\n1. Configure the local data directory.\n2. Read the licenses you'll be asked to accept on first download.\n3. Confirm you can reach the bucket and see what it contains.\n\nDownloads themselves are covered by the\n:doc:`quick start <plot_01_quickstart>`.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Initialize the data directory\n\nPick a location with enough disk space. The choice is persisted\nso subsequent sessions pick it up automatically -- you don't need\nto call ``dataset_initialize`` again from the same machine.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import os\n\nfrom laion_fmri.config import dataset_initialize, get_data_dir\n\n# If you already accepted the licenses in another example, the\n# following cells just confirm the configuration -- you won't be\n# re-prompted.\ndata_dir = os.environ.get(\n    \"LAION_FMRI_EXAMPLE_DATA_DIR\",\n    os.path.join(os.getcwd(), \"laion_fmri_quickstart\"),\n)\nos.makedirs(data_dir, exist_ok=True)\ndataset_initialize(data_dir)\nprint(f\"Configured: {get_data_dir()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Inspect the license texts\n\nTwo licenses apply:\n\n* The **dataset license** (CC0 1.0) covers the brain and\n  participant data.\n* The **stimulus license** (closed, research-only) covers the\n  stimulus images.\n\nBelow we print the body of each so you can read the terms in\nadvance. The actual ``Type \"I AGREE\"`` prompt happens in the\nnext cell.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from laion_fmri._constants import (\n    LICENSE_AGREEMENT_BODY,\n    STIMULI_LICENSE_BODY,\n)\n\nprint(LICENSE_AGREEMENT_BODY)\nprint(\"---\")\nprint(STIMULI_LICENSE_BODY)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Accept the licenses\n\nThis is the same prompt-and-write-marker flow that\n:func:`laion_fmri.download.download` triggers internally on its\nfirst call. ``accept_licenses(include_stimuli=True)`` prompts\nyou to type ``I AGREE`` for both the dataset license and the\nstimulus license, then records your acceptance under\n``{data_dir}/.laion_fmri/`` so future ``download(...)`` calls\ndon't ask again.\n\nIf you decline either prompt, the helper raises -- the exception\nis the signal that you opted out and that downstream\n``download(...)`` calls would refuse to run for the\ncorresponding data.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from laion_fmri.download import accept_licenses\n\naccept_licenses(include_stimuli=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Confirm bucket access\n\nThe bucket is public, so discovery works without any\ncredential setup. The functions below query the bucket\ndirectly and tell you what is available in the dataset\nregardless of what you have downloaded -- a quick way to\nconfirm that initialization is complete and the bucket is\nreachable from your network.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from laion_fmri.discovery import describe, get_subjects\n\nprint(f\"Subjects in bucket: {get_subjects()}\")\ndescribe()"
      ]
    }
  ],
  "metadata": {
    "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.12.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}