{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# Tutorial 3: Multi-Year Comparisons\n",
                "\n",
                "cendat makes it easy to compare data across multiple years.\n",
                "\n",
                "**Goal:** Find Colorado incorporated places with very low poverty rates across recent years."
            ]
        },
        {
            "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",
                "\n",
                "# Request multiple years at once\n",
                "cdh.list_products(years=[2020, 2021, 2022, 2023], patterns=r\"acs/acs5\\)\")\n",
                "cdh.set_products()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 2: Select Data"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "cdh.set_groups([\"B17001\"])\n",
                "cdh.set_geos([\"160\"])  # Places"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 3: Get Data"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# Filter to Colorado (state = 08)\n",
                "response = cdh.get_data(\n",
                "    include_names=True,\n",
                "    within={\"state\": \"08\"}\n",
                ")"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Step 4: Complex Filtering with Tabulate\n",
                "\n",
                "The `where` parameter supports multiple conditions:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "response.tabulate(\n",
                "    \"NAME\",\n",
                "    \"B17001_002E\",  # Below poverty\n",
                "    \"B17001_001E\",  # Total\n",
                "    where=[\n",
                "        \"B17001_001E > 1_000\",                    # Population > 1,000\n",
                "        \"B17001_002E / B17001_001E < 0.01\",       # Poverty rate < 1%\n",
                "        \"'CDP' not in NAME\",                      # Exclude CDPs\n",
                "    ],\n",
                "    weight_var=\"B17001_001E\",\n",
                "    strat_by=\"vintage\"  # Separate results by year\n",
                ")"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "> **Tip - Condition Syntax**\n",
                ">\n",
                "> The `where` parameter supports:\n",
                "> - Simple comparisons: `\"AGEP > 17\"`\n",
                "> - Division expressions: `\"B17001_002E / B17001_001E < 0.01\"`\n",
                "> - String containment: `\"'CDP' not in NAME\"`"
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "Python 3",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "name": "python",
            "version": "3.11.0"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 4
}