{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# This cell is added by sphinx-gallery\n# It can be customized to whatever you like\n%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# National-Level Census Data Analysis\n\nThis example demonstrates how to retrieve and analyze national-level census data\nusing the newly added level='C' functionality. This is particularly useful for\nestablishing national baselines when comparing regional data.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Setting up pycancensus\n\nFirst, import the necessary libraries and configure the API key.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import pycancensus as pc\nimport pandas as pd\nimport os\n\n# Set your API key\napi_key = os.environ.get('CANCENSUS_API_KEY')\nif api_key:\n    pc.set_api_key(api_key)\n    print(\"API key configured\")\nelse:\n    print(\"No API key - examples will show code structure\")\n    print(\"Get your API key at: https://censusmapper.ca/users/sign_up\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Retrieving National-Level Data\n\nThe level='C' parameter allows you to retrieve Canada-wide census data,\nwhich is useful for establishing national baselines.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(\"\\nRetrieving national-level census data:\")\ntry:\n    # Get national data for 2021 Census\n    national_data = pc.get_census(\n        dataset='CA21',\n        level='C',\n        regions={'C': '01'},  # Canada\n        vectors=[\n            'v_CA21_1',   # Total population\n            'v_CA21_2',   # Male population\n            'v_CA21_3',   # Female population\n        ],\n        labels='short',\n        use_cache=False\n    )\n\n    print(f\"\\nNational Census Data (CA21):\")\n    print(national_data)\n\n    # Display key statistics\n    total_pop = national_data['v_CA21_1'].iloc[0]\n    male_pop = national_data['v_CA21_2'].iloc[0]\n    female_pop = national_data['v_CA21_3'].iloc[0]\n\n    print(f\"\\nNational Statistics:\")\n    print(f\"Total Population: {total_pop:,}\")\n    print(f\"Male: {male_pop:,} ({male_pop/total_pop*100:.1f}%)\")\n    print(f\"Female: {female_pop:,} ({female_pop/total_pop*100:.1f}%)\")\n\nexcept Exception as e:\n    print(f\"Error retrieving national data: {e}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Comparing Regional vs National Data\n\nA common analysis pattern is to compare regional demographics against\nnational baselines. This example compares Toronto's demographics with\nnational averages.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(\"\\nComparing regional vs national demographics:\")\ntry:\n    # Get national income data\n    national_income = pc.get_census(\n        dataset='CA21',\n        level='C',\n        regions={'C': '01'},\n        vectors=[\n            'v_CA21_923',  # Total household income groups\n            'v_CA21_939',  # $100,000 and over\n        ],\n        labels='short',\n        use_cache=False\n    )\n\n    # Get Toronto CMA income data\n    toronto_income = pc.get_census(\n        dataset='CA21',\n        level='CMA',\n        regions={'CMA': '535'},  # Toronto CMA\n        vectors=[\n            'v_CA21_923',  # Total household income groups\n            'v_CA21_939',  # $100,000 and over\n        ],\n        labels='short',\n        use_cache=False\n    )\n\n    # Calculate proportions\n    nat_total = national_income['v_CA21_923'].iloc[0]\n    nat_high_income = national_income['v_CA21_939'].iloc[0]\n    nat_prop = nat_high_income / nat_total * 100\n\n    tor_total = toronto_income['v_CA21_923'].iloc[0]\n    tor_high_income = toronto_income['v_CA21_939'].iloc[0]\n    tor_prop = tor_high_income / tor_total * 100\n\n    print(f\"\\nHousehold Income Comparison ($100k+):\")\n    print(f\"National: {nat_high_income:,} / {nat_total:,} = {nat_prop:.1f}%\")\n    print(f\"Toronto:  {tor_high_income:,} / {tor_total:,} = {tor_prop:.1f}%\")\n    print(f\"Difference: {tor_prop - nat_prop:+.1f} percentage points\")\n\n    if tor_prop > nat_prop:\n        print(f\"\\nToronto has a higher proportion of high-income households\")\n    else:\n        print(f\"\\nToronto has a lower proportion of high-income households\")\n\nexcept Exception as e:\n    print(f\"Error in comparison analysis: {e}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Multi-Year National Comparison\n\nNational-level data is also useful for analyzing trends over time\nacross different Census years.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(\"\\nComparing national data across Census years:\")\ntry:\n    # Get 2021 data\n    national_2021 = pc.get_census(\n        dataset='CA21',\n        level='C',\n        regions={'C': '01'},\n        vectors=['v_CA21_1'],  # Total population\n        labels='short',\n        use_cache=False\n    )\n\n    # Get 2016 data\n    national_2016 = pc.get_census(\n        dataset='CA16',\n        level='C',\n        regions={'C': '01'},\n        vectors=['v_CA16_1'],  # Total population\n        labels='short',\n        use_cache=False\n    )\n\n    pop_2021 = national_2021['v_CA21_1'].iloc[0]\n    pop_2016 = national_2016['v_CA16_1'].iloc[0]\n    growth = pop_2021 - pop_2016\n    growth_pct = (pop_2021 / pop_2016 - 1) * 100\n\n    print(f\"\\nNational Population Growth (2016-2021):\")\n    print(f\"2016: {pop_2016:,}\")\n    print(f\"2021: {pop_2021:,}\")\n    print(f\"Growth: {growth:,} ({growth_pct:.2f}%)\")\n\nexcept Exception as e:\n    print(f\"Error in multi-year comparison: {e}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Summary\n\nThis example demonstrated:\n\n1. Retrieving national-level data using level='C'\n2. Comparing regional demographics against national baselines\n3. Analyzing national trends across Census years\n\nNational-level data is essential for contextualizing regional analyses\nand understanding how local areas compare to the country as a whole.\n\n"
      ]
    }
  ],
  "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.9.22"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}