{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# Tutorial 4: Working with Geometries\n",
                "\n",
                "cendat can fetch geographic boundaries alongside your data for mapping.\n",
                "\n",
                "**Goal:** Get race data with geometries for US regions."
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Setup"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "import os\n",
                "from cendat import CenDatHelper\n",
                "from dotenv import load_dotenv\n",
                "\n",
                "load_dotenv()\n",
                "cdh = CenDatHelper(key=os.getenv(\"CENSUS_API_KEY\"))\n",
                "cdh.list_products(years=[2011], patterns=r\"acs/acs5\\)\")\n",
                "cdh.set_products()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 2: Select Data and Geography"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "cdh.list_groups(patterns=r\"^race\")"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "cdh.set_groups([\"B02001\"])\n",
                "cdh.describe_groups()"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# 020 = Region\n",
                "cdh.set_geos([\"020\"])"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 3: Get Data with Geometry"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "response = cdh.get_data(\n",
                "    include_names=True,\n",
                "    include_geometry=True  # This fetches boundaries from TIGERweb\n",
                ")"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 4: Convert to GeoDataFrame"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# to_gpd() returns a GeoDataFrame ready for mapping\n",
                "gdf = response.to_gpd(destring=True, join_strategy=\"inner\")\n",
                "print(gdf)"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# Use with matplotlib, folium, or your preferred mapping library\n",
                "gdf.plot(column=\"B02001_001E\", legend=True)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "> **Note - Supported Geographies**\n",
                ">\n",
                "> Geometry fetching currently supports: regions (020), divisions (030), states (040), counties (050), county subdivisions (060), census tracts (140), block groups (150), and places (160)."
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "Python 3",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "name": "python",
            "version": "3.11.0"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 4
}