{
"cells": [
{
"cell_type": "markdown",
"metadata": {
"id": "APIsXs1LfIoI"
},
"source": [
"## Advanced Data Enrichment using CARTO's Data Observatory\n",
"\n",
"This notebook shows how to use CARTOframes to enrich the area of influence of different POIs with data from CARTO's Data Observatory. Please, visit [CARTOframes Guides](https://carto.com/developers/cartoframes/guides/) to learn more about the enrichment functionality.\n",
"\n",
"We will show CARTOframes enrichment functionality with an example in which we will quantify the number of eating places within a 5-minute isochrone for all sports POI's in Madrid downtown.\n",
"\n",
"The notebook is organized as follows:\n",
"1. [Download sports POIs](#section1)\n",
"2. [Calculate isochrones](#section2)\n",
"3. [Enrich isochrones](#section3)\n",
" - [Simple enrichment: Counting the number of POI's within isochrones](#section31)\n",
" - [Enrichment applying filters: Counting the number of eating places](#section32)\n",
" - [Brief analysis](#section33)\n",
"\n",
"**Note** for this notebook we are using the premium [dataset of Pitney Bowes POI's in Spain](https://carto.com/spatial-data-catalog/browser/dataset/pb_points_of_i_94bda91b/)."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "Z7-NfDHvhgRc"
},
"source": [
"### Setup"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Import packages"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 72
},
"id": "tamaCNqjlJ3u",
"outputId": "12fefed4-74bc-4ab2-9f35-9b4493db346c"
},
"outputs": [],
"source": [
"import geopandas as gpd\n",
"import matplotlib.pyplot as plt\n",
"import seaborn as sns\n",
"\n",
"from cartoframes.auth import set_default_credentials\n",
"from cartoframes.data.observatory import *\n",
"from cartoframes.data.services import Isolines\n",
"from cartoframes.viz import *\n",
"\n",
"sns.set_style('whitegrid')\n",
"%matplotlib inline"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Set CARTO default credentials\n",
"\n",
"In order to be able to use the Data Observatory via CARTOframes, you need to set your CARTO account credentials first.\n",
"\n",
"Please, visit the [Authentication guide](https://carto.com/developers/cartoframes/guides/Authentication/) for further detail."
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [],
"source": [
"from cartoframes.auth import set_default_credentials\n",
"\n",
"set_default_credentials('creds.json')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"**Note about credentials**\n",
"\n",
"For security reasons, we recommend storing your credentials in an external file to prevent publishing them by accident when sharing your notebooks. You can get more information in the section _Setting your credentials_ of the [Authentication guide](https://carto.com/developers/cartoframes/guides/Authentication/)."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "dq4_-q83lchv"
},
"source": [
"\n",
"### 1. Download sports POIs\n",
"\n",
"We need to start with the initial DataFrame that we would like to enrich. Normally, this initial DataFrame contains your own data that you later enrich with data from the Data Observatory. In this case, we will download all sports POI's and use it as our initial DataFrame.\n",
"\n",
"We first check that we are subscribed to PB POIs dataset in Spain and download the sports POI's within a bounding box covering Madrid downtown. You can calculate your bounding box of interest using [bboxfinder](http://bboxfinder.com).\n",
"\n",
"For a step by step description on how to discover and download premium datasets, take a look at templates: Data Discovery and Access Premium Data."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 52
},
"id": "nugq6FQJlYFy",
"outputId": "3a5f3fe1-5a5f-4f43-fd1c-866104998b9e"
},
"outputs": [
{
"data": {
"text/html": [
"
\n",
"\n",
"
\n",
" \n",
"
\n",
"
\n",
"
slug
\n",
"
name
\n",
"
description
\n",
"
category_id
\n",
"
country_id
\n",
"
data_source_id
\n",
"
provider_id
\n",
"
geography_name
\n",
"
geography_description
\n",
"
temporal_aggregation
\n",
"
time_coverage
\n",
"
update_frequency
\n",
"
is_public_data
\n",
"
lang
\n",
"
version
\n",
"
category_name
\n",
"
provider_name
\n",
"
geography_id
\n",
"
id
\n",
"
\n",
" \n",
" \n",
"
\n",
"
0
\n",
"
ags_sociodemogr_a7e14220
\n",
"
Sociodemographics - United States of America (...
\n",
"
Census and ACS sociodemographic data estimated...
\n",
"
demographics
\n",
"
usa
\n",
"
sociodemographics
\n",
"
ags
\n",
"
Census Block Group - United States of America
\n",
"
None
\n",
"
yearly
\n",
"
None
\n",
"
yearly
\n",
"
False
\n",
"
eng
\n",
"
2020
\n",
"
Demographics
\n",
"
Applied Geographic Solutions
\n",
"
carto-do.ags.geography_usa_blockgroup_2015
\n",
"
carto-do.ags.demographics_sociodemographics_us...
\n",
"
\n",
"
\n",
"
1
\n",
"
ags_retailpoten_aaf25a8c
\n",
"
Retail Potential - United States of America (C...
\n",
"
The retail potential database consists of aver...
\n",
"
demographics
\n",
"
usa
\n",
"
retailpotential
\n",
"
ags
\n",
"
Census Block Group - United States of America ...
\n",
"
Shoreline clipped TIGER/Line boundaries. More ...
\n",
"
yearly
\n",
"
[2018-01-01, 2019-01-01)
\n",
"
yearly
\n",
"
False
\n",
"
eng
\n",
"
2019
\n",
"
Demographics
\n",
"
Applied Geographic Solutions
\n",
"
carto-do-public-data.carto.geography_usa_block...
\n",
"
carto-do.ags.demographics_retailpotential_usa_...
\n",
"
\n",
"
\n",
"
2
\n",
"
pb_consumer_po_62cddc04
\n",
"
Points Of Interest - Consumer - United States ...
\n",
"
Consumer Point of interest database per catego...
\n",
"
points_of_interest
\n",
"
usa
\n",
"
consumer_points_of_interest
\n",
"
pitney_bowes
\n",
"
Latitude/Longitude - United States of America
\n",
"
Location of Points of Interest
\n",
"
monthly
\n",
"
None
\n",
"
monthly
\n",
"
False
\n",
"
eng
\n",
"
v1
\n",
"
Points of Interest
\n",
"
Pitney Bowes
\n",
"
carto-do.pitney_bowes.geography_usa_latlon_v1
\n",
"
carto-do.pitney_bowes.pointsofinterest_consume...
\n",
"
\n",
"
\n",
"
3
\n",
"
ags_sociodemogr_f510a947
\n",
"
Sociodemographics - United States of America (...
\n",
"
Census and ACS sociodemographic data estimated...
\n",
"
demographics
\n",
"
usa
\n",
"
sociodemographics
\n",
"
ags
\n",
"
Census Block Group - United States of America ...
\n",
"
Shoreline clipped TIGER/Line boundaries. More ...
\n",
"
yearly
\n",
"
[2019-01-01, 2020-01-01)
\n",
"
yearly
\n",
"
False
\n",
"
eng
\n",
"
2019
\n",
"
Demographics
\n",
"
Applied Geographic Solutions
\n",
"
carto-do-public-data.carto.geography_usa_block...
\n",
"
carto-do.ags.demographics_sociodemographics_us...
\n",
"
\n",
"
\n",
"
4
\n",
"
ags_consumer_sp_dbabddfb
\n",
"
Consumer Spending - United States of America (...
\n",
"
The Consumer Expenditure database consists of ...
\n",
"
demographics
\n",
"
usa
\n",
"
consumer_spending
\n",
"
ags
\n",
"
Census Block Group - United States of America
\n",
"
None
\n",
"
yearly
\n",
"
None
\n",
"
yearly
\n",
"
False
\n",
"
eng
\n",
"
2020
\n",
"
Demographics
\n",
"
Applied Geographic Solutions
\n",
"
carto-do.ags.geography_usa_blockgroup_2015
\n",
"
carto-do.ags.demographics_consumerspending_usa...
\n",
"
\n",
"
\n",
"
5
\n",
"
spa_geosocial_s_d5dc42ae
\n",
"
Geosocial Segments - United States of America ...
\n",
"
By analysing feeds from Twitter, Instagram, Me...
\n",
"
behavioral
\n",
"
usa
\n",
"
geosocial_segments
\n",
"
spatial_ai
\n",
"
Census Block Group - United States of America ...
\n",
"
Shoreline clipped TIGER/Line boundaries. More ...
\n",
"
quarterly
\n",
"
[2020-01-01, 2020-04-01)
\n",
"
quarterly
\n",
"
False
\n",
"
eng
\n",
"
v1
\n",
"
Behavioral
\n",
"
Spatial.ai
\n",
"
carto-do-public-data.carto.geography_usa_block...
\n",
"
carto-do.spatial_ai.behavioral_geosocialsegmen...
\n",
"
\n",
"
\n",
"
6
\n",
"
mc_geographic__7980c5c3
\n",
"
Geographic Insights - United States of America...
\n",
"
Geographic Insights validate, evaluate and ben...
\n",
"
financial
\n",
"
usa
\n",
"
geographic_insights
\n",
"
mastercard
\n",
"
Census Block Group - United States of America ...
\n",
"
Shoreline clipped TIGER/Line boundaries. More ...
\n",
"
monthly
\n",
"
[2019-01-01, 2020-01-01)
\n",
"
monthly
\n",
"
False
\n",
"
eng
\n",
"
v1
\n",
"
Financial
\n",
"
Mastercard
\n",
"
carto-do-public-data.carto.geography_usa_block...
\n",
"
carto-do.mastercard.financial_geographicinsigh...
\n",
"
\n",
"
\n",
"
7
\n",
"
pb_points_of_i_94bda91b
\n",
"
Points Of Interest - Spain (Latitude/Longitude)
\n",
"
Point of interest database per categories
\n",
"
points_of_interest
\n",
"
esp
\n",
"
points_of_interest
\n",
"
pitney_bowes
\n",
"
Latitude/Longitude - Spain
\n",
"
Location of Points of Interest
\n",
"
monthly
\n",
"
None
\n",
"
monthly
\n",
"
False
\n",
"
eng
\n",
"
v1
\n",
"
Points of Interest
\n",
"
Pitney Bowes
\n",
"
carto-do.pitney_bowes.geography_esp_latlon_v1
\n",
"
carto-do.pitney_bowes.pointsofinterest_pointso...
\n",
"
\n",
" \n",
"
\n",
"
"
],
"text/plain": [
" slug \\\n",
"0 ags_sociodemogr_a7e14220 \n",
"1 ags_retailpoten_aaf25a8c \n",
"2 pb_consumer_po_62cddc04 \n",
"3 ags_sociodemogr_f510a947 \n",
"4 ags_consumer_sp_dbabddfb \n",
"5 spa_geosocial_s_d5dc42ae \n",
"6 mc_geographic__7980c5c3 \n",
"7 pb_points_of_i_94bda91b \n",
"\n",
" name \\\n",
"0 Sociodemographics - United States of America (... \n",
"1 Retail Potential - United States of America (C... \n",
"2 Points Of Interest - Consumer - United States ... \n",
"3 Sociodemographics - United States of America (... \n",
"4 Consumer Spending - United States of America (... \n",
"5 Geosocial Segments - United States of America ... \n",
"6 Geographic Insights - United States of America... \n",
"7 Points Of Interest - Spain (Latitude/Longitude) \n",
"\n",
" description category_id \\\n",
"0 Census and ACS sociodemographic data estimated... demographics \n",
"1 The retail potential database consists of aver... demographics \n",
"2 Consumer Point of interest database per catego... points_of_interest \n",
"3 Census and ACS sociodemographic data estimated... demographics \n",
"4 The Consumer Expenditure database consists of ... demographics \n",
"5 By analysing feeds from Twitter, Instagram, Me... behavioral \n",
"6 Geographic Insights validate, evaluate and ben... financial \n",
"7 Point of interest database per categories points_of_interest \n",
"\n",
" country_id data_source_id provider_id \\\n",
"0 usa sociodemographics ags \n",
"1 usa retailpotential ags \n",
"2 usa consumer_points_of_interest pitney_bowes \n",
"3 usa sociodemographics ags \n",
"4 usa consumer_spending ags \n",
"5 usa geosocial_segments spatial_ai \n",
"6 usa geographic_insights mastercard \n",
"7 esp points_of_interest pitney_bowes \n",
"\n",
" geography_name \\\n",
"0 Census Block Group - United States of America \n",
"1 Census Block Group - United States of America ... \n",
"2 Latitude/Longitude - United States of America \n",
"3 Census Block Group - United States of America ... \n",
"4 Census Block Group - United States of America \n",
"5 Census Block Group - United States of America ... \n",
"6 Census Block Group - United States of America ... \n",
"7 Latitude/Longitude - Spain \n",
"\n",
" geography_description temporal_aggregation \\\n",
"0 None yearly \n",
"1 Shoreline clipped TIGER/Line boundaries. More ... yearly \n",
"2 Location of Points of Interest monthly \n",
"3 Shoreline clipped TIGER/Line boundaries. More ... yearly \n",
"4 None yearly \n",
"5 Shoreline clipped TIGER/Line boundaries. More ... quarterly \n",
"6 Shoreline clipped TIGER/Line boundaries. More ... monthly \n",
"7 Location of Points of Interest monthly \n",
"\n",
" time_coverage update_frequency is_public_data lang version \\\n",
"0 None yearly False eng 2020 \n",
"1 [2018-01-01, 2019-01-01) yearly False eng 2019 \n",
"2 None monthly False eng v1 \n",
"3 [2019-01-01, 2020-01-01) yearly False eng 2019 \n",
"4 None yearly False eng 2020 \n",
"5 [2020-01-01, 2020-04-01) quarterly False eng v1 \n",
"6 [2019-01-01, 2020-01-01) monthly False eng v1 \n",
"7 None monthly False eng v1 \n",
"\n",
" category_name provider_name \\\n",
"0 Demographics Applied Geographic Solutions \n",
"1 Demographics Applied Geographic Solutions \n",
"2 Points of Interest Pitney Bowes \n",
"3 Demographics Applied Geographic Solutions \n",
"4 Demographics Applied Geographic Solutions \n",
"5 Behavioral Spatial.ai \n",
"6 Financial Mastercard \n",
"7 Points of Interest Pitney Bowes \n",
"\n",
" geography_id \\\n",
"0 carto-do.ags.geography_usa_blockgroup_2015 \n",
"1 carto-do-public-data.carto.geography_usa_block... \n",
"2 carto-do.pitney_bowes.geography_usa_latlon_v1 \n",
"3 carto-do-public-data.carto.geography_usa_block... \n",
"4 carto-do.ags.geography_usa_blockgroup_2015 \n",
"5 carto-do-public-data.carto.geography_usa_block... \n",
"6 carto-do-public-data.carto.geography_usa_block... \n",
"7 carto-do.pitney_bowes.geography_esp_latlon_v1 \n",
"\n",
" id \n",
"0 carto-do.ags.demographics_sociodemographics_us... \n",
"1 carto-do.ags.demographics_retailpotential_usa_... \n",
"2 carto-do.pitney_bowes.pointsofinterest_consume... \n",
"3 carto-do.ags.demographics_sociodemographics_us... \n",
"4 carto-do.ags.demographics_consumerspending_usa... \n",
"5 carto-do.spatial_ai.behavioral_geosocialsegmen... \n",
"6 carto-do.mastercard.financial_geographicinsigh... \n",
"7 carto-do.pitney_bowes.pointsofinterest_pointso... "
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Catalog().subscriptions().datasets.to_dataframe()"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"id": "NB78cM-AmVn7"
},
"outputs": [],
"source": [
"pois_ds = Dataset.get('pb_points_of_i_94bda91b')"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
" NAME geoid \\\n",
"0 ACQUAPLAYA SPA 2204263540#-3.7095628#40.4226394 \n",
"1 ALAMBIQUE TIENDA Y ESCUELA DE COCINA 2157202351#-3.7109121#40.4198204 \n",
"2 ALCÁZAR NIGHT 2137823204#-3.69905#40.4178 \n",
"3 ALICIA PRODUCE 2181768913#-3.7112#40.42404 \n",
"4 ALMA PILATES 2197072938#-3.7033635#40.4141477 \n",
"\n",
" do_date BRANDNAME PB_ID TRADE_NAME FRANCHISE_NAME ISO3 \\\n",
"0 2020-04-01 NaN 2204263540 NaN NaN ESP \n",
"1 2019-12-01 NaN 2157202351 NaN NaN ESP \n",
"2 2019-12-01 NaN 2137823204 NaN NaN ESP \n",
"3 2020-02-01 NaN 2181768913 NaN NaN ESP \n",
"4 2020-04-01 NaN 2197072938 NaN NaN ESP \n",
"\n",
" AREANAME4 AREANAME3 ... GLOBAL_ULTIMATE_STREET_ADDRESS \\\n",
"0 NaN MADRID ... NaN \n",
"1 NaN MADRID ... NaN \n",
"2 NaN MADRID ... NaN \n",
"3 NaN MADRID ... NaN \n",
"4 NaN MADRID ... NaN \n",
"\n",
" GLOBAL_ULTIMATE_AREANAME3 GLOBAL_ULTIMATE_AREANAME1 \\\n",
"0 NaN NaN \n",
"1 NaN NaN \n",
"2 NaN NaN \n",
"3 NaN NaN \n",
"4 NaN NaN \n",
"\n",
" GLOBAL_ULTIMATE_COUNTRY GLOBAL_ULTIMATE_POSTCODE FAMILY_MEMBERS \\\n",
"0 NaN NaN NaN \n",
"1 NaN NaN NaN \n",
"2 NaN NaN NaN \n",
"3 NaN NaN NaN \n",
"4 NaN NaN NaN \n",
"\n",
" HIERARCHY_CODE TICKER_SYMBOL EXCHANGE_NAME geom \n",
"0 NaN NaN NaN POINT (-3.70956 40.42264) \n",
"1 NaN NaN NaN POINT (-3.71091 40.41982) \n",
"2 NaN NaN NaN POINT (-3.69905 40.41780) \n",
"3 NaN NaN NaN POINT (-3.71120 40.42404) \n",
"4 NaN NaN NaN POINT (-3.70336 40.41415) \n",
"\n",
"[5 rows x 74 columns]"
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sql_query = \"\"\"\n",
" SELECT * except(do_label) FROM $dataset$ \n",
" WHERE TRADE_DIVISION = 'DIVISION M. - SPORTS' \n",
" AND ST_IntersectsBox(geom, -3.716398,40.407437,-3.690477,40.425277)\n",
"\"\"\"\n",
"\n",
"pois_df = pois_ds.to_dataframe(sql_query=sql_query)\n",
"\n",
"# To keep only the latest version of POI's\n",
"pois_df = pois_df.sort_values(['NAME', 'do_date']).groupby('NAME').first().reset_index()\n",
"\n",
"pois_df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "P-au_zH5r2BY"
},
"source": [
"\n",
"### 2. Calculate isochrones\n",
"\n",
"For this analysis, we are interested in knowing the number of eating places reachable within 5 minutes for every sport POI. We'll now proceed to calculate 5-minute isochrones for every POI, which represent the area reachable within 5 minutes.\n",
"\n",
"You can read more regarding isochrones on [CARTOframes Guides](https://carto.com/developers/cartoframes/guides/)."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 34
},
"id": "8UHM-TzmnmJL",
"outputId": "bee85084-45b2-41df-e0b5-41c2fcbdb7aa"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Success! Isolines created correctly\n"
]
}
],
"source": [
"iso_service = Isolines()\n",
"isochrones_gdf, isochrones_metadata = iso_service.isochrones(pois_df, [300], mode='walk', geom_col='geom')"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 197
},
"id": "PwpFB32KaWPo",
"outputId": "870b06e0-e555-464a-9d25-59aff9a9c3b6"
},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
" NAME geoid \\\n",
"0 ACQUAPLAYA SPA 2204263540#-3.7095628#40.4226394 \n",
"1 ALAMBIQUE TIENDA Y ESCUELA DE COCINA 2157202351#-3.7109121#40.4198204 \n",
"2 ALCÁZAR NIGHT 2137823204#-3.69905#40.4178 \n",
"3 ALICIA PRODUCE 2181768913#-3.7112#40.42404 \n",
"4 ALMA PILATES 2197072938#-3.7033635#40.4141477 \n",
"\n",
" do_date BRANDNAME PB_ID TRADE_NAME FRANCHISE_NAME ISO3 \\\n",
"0 2020-04-01 NaN 2204263540 NaN NaN ESP \n",
"1 2019-12-01 NaN 2157202351 NaN NaN ESP \n",
"2 2019-12-01 NaN 2137823204 NaN NaN ESP \n",
"3 2020-02-01 NaN 2181768913 NaN NaN ESP \n",
"4 2020-04-01 NaN 2197072938 NaN NaN ESP \n",
"\n",
" AREANAME4 AREANAME3 ... GLOBAL_ULTIMATE_AREANAME3 \\\n",
"0 NaN MADRID ... NaN \n",
"1 NaN MADRID ... NaN \n",
"2 NaN MADRID ... NaN \n",
"3 NaN MADRID ... NaN \n",
"4 NaN MADRID ... NaN \n",
"\n",
" GLOBAL_ULTIMATE_AREANAME1 GLOBAL_ULTIMATE_COUNTRY GLOBAL_ULTIMATE_POSTCODE \\\n",
"0 NaN NaN NaN \n",
"1 NaN NaN NaN \n",
"2 NaN NaN NaN \n",
"3 NaN NaN NaN \n",
"4 NaN NaN NaN \n",
"\n",
" FAMILY_MEMBERS HIERARCHY_CODE TICKER_SYMBOL EXCHANGE_NAME \\\n",
"0 NaN NaN NaN NaN \n",
"1 NaN NaN NaN NaN \n",
"2 NaN NaN NaN NaN \n",
"3 NaN NaN NaN NaN \n",
"4 NaN NaN NaN NaN \n",
"\n",
" geom \\\n",
"0 POINT (-3.70956 40.42264) \n",
"1 POINT (-3.71091 40.41982) \n",
"2 POINT (-3.69905 40.41780) \n",
"3 POINT (-3.71120 40.42404) \n",
"4 POINT (-3.70336 40.41415) \n",
"\n",
" isochrone \n",
"0 MULTIPOLYGON (((-3.71192 40.42488, -3.71149 40... \n",
"1 MULTIPOLYGON (((-3.71346 40.42093, -3.71321 40... \n",
"2 MULTIPOLYGON (((-3.70248 40.41750, -3.70222 40... \n",
"3 MULTIPOLYGON (((-3.71346 40.42437, -3.71338 40... \n",
"4 MULTIPOLYGON (((-3.70660 40.41544, -3.70634 40... \n",
"\n",
"[5 rows x 75 columns]"
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pois_df['isochrone'] = isochrones_gdf.sort_values('source_id')['the_geom'].values\n",
"pois_df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Visualize isochrones"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 674
},
"id": "syg5-YSopMDE",
"outputId": "2c86f83f-78c6-4cae-a57e-029d8c2a24fb"
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Map([Layer(pois_df, geom_col='geom'),\n",
" Layer(pois_df, geom_col='isochrone', style=basic_style(opacity=0.1))])"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "I41LlwWLsPjc"
},
"source": [
"\n",
"### 3. Enrich isochrones"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "AMj-EbULsU9U"
},
"source": [
"We will now proceed to enrich our DataFrame. \n",
"\n",
"For enriching datasets, we use the Enrichment class. Please, visit [CARTOframes Guides](https://carto.com/developers/cartoframes/guides/) to learn more."
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"id": "CC_KNhQeIDhk"
},
"outputs": [],
"source": [
"enrichment = Enrichment()"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "VNpTVV1fsrcB"
},
"source": [
"\n",
"#### 3.1 Simple enrichment: Counting the number of POI's within isochrones\n",
"\n",
"We will start by simply counting the number of POI's within each isochrone. This will allow us to measure how busy the area around each sport POI is.\n",
"\n",
"In order to do this, we will use the Enrichment function `enrich_polygons()` for which we can select any variable, because we are only interested in counting POIs. That is why we selected the variable `CLASS_517d6003` that we will use later. Remember you can access the dataset variables doing `pois_ds.variables.to_dataframe()`.\n",
"\n",
"**Note** that we need to specify the name of the geometry column (`geom_col`) because we are working with a DataFrame instead of a GeoDataFrame."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {
"id": "Fz16KW7AIDvt"
},
"outputs": [
{
"data": {
"text/html": [
"
\n",
"\n",
"
\n",
" \n",
"
\n",
"
\n",
"
NAME
\n",
"
geoid
\n",
"
do_date
\n",
"
BRANDNAME
\n",
"
PB_ID
\n",
"
TRADE_NAME
\n",
"
FRANCHISE_NAME
\n",
"
ISO3
\n",
"
AREANAME4
\n",
"
AREANAME3
\n",
"
...
\n",
"
GLOBAL_ULTIMATE_AREANAME1
\n",
"
GLOBAL_ULTIMATE_COUNTRY
\n",
"
GLOBAL_ULTIMATE_POSTCODE
\n",
"
FAMILY_MEMBERS
\n",
"
HIERARCHY_CODE
\n",
"
TICKER_SYMBOL
\n",
"
EXCHANGE_NAME
\n",
"
geom
\n",
"
isochrone
\n",
"
n_pois
\n",
"
\n",
" \n",
" \n",
"
\n",
"
0
\n",
"
ACQUAPLAYA SPA
\n",
"
2204263540#-3.7095628#40.4226394
\n",
"
2020-04-01
\n",
"
NaN
\n",
"
2204263540
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.70956 40.42264)
\n",
"
MULTIPOLYGON (((-3.71192 40.42488, -3.71149 40...
\n",
"
31977
\n",
"
\n",
"
\n",
"
1
\n",
"
ALAMBIQUE TIENDA Y ESCUELA DE COCINA
\n",
"
2157202351#-3.7109121#40.4198204
\n",
"
2019-12-01
\n",
"
NaN
\n",
"
2157202351
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.71091 40.41982)
\n",
"
MULTIPOLYGON (((-3.71346 40.42093, -3.71321 40...
\n",
"
10131
\n",
"
\n",
"
\n",
"
2
\n",
"
ALCÁZAR NIGHT
\n",
"
2137823204#-3.69905#40.4178
\n",
"
2019-12-01
\n",
"
NaN
\n",
"
2137823204
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.69905 40.41780)
\n",
"
MULTIPOLYGON (((-3.70248 40.41750, -3.70222 40...
\n",
"
19947
\n",
"
\n",
"
\n",
"
3
\n",
"
ALICIA PRODUCE
\n",
"
2181768913#-3.7112#40.42404
\n",
"
2020-02-01
\n",
"
NaN
\n",
"
2181768913
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.71120 40.42404)
\n",
"
MULTIPOLYGON (((-3.71346 40.42437, -3.71338 40...
\n",
"
24480
\n",
"
\n",
"
\n",
"
4
\n",
"
ALMA PILATES
\n",
"
2197072938#-3.7033635#40.4141477
\n",
"
2020-04-01
\n",
"
NaN
\n",
"
2197072938
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.70336 40.41415)
\n",
"
MULTIPOLYGON (((-3.70660 40.41544, -3.70634 40...
\n",
"
30348
\n",
"
\n",
" \n",
"
\n",
"
5 rows × 76 columns
\n",
"
"
],
"text/plain": [
" NAME geoid \\\n",
"0 ACQUAPLAYA SPA 2204263540#-3.7095628#40.4226394 \n",
"1 ALAMBIQUE TIENDA Y ESCUELA DE COCINA 2157202351#-3.7109121#40.4198204 \n",
"2 ALCÁZAR NIGHT 2137823204#-3.69905#40.4178 \n",
"3 ALICIA PRODUCE 2181768913#-3.7112#40.42404 \n",
"4 ALMA PILATES 2197072938#-3.7033635#40.4141477 \n",
"\n",
" do_date BRANDNAME PB_ID TRADE_NAME FRANCHISE_NAME ISO3 \\\n",
"0 2020-04-01 NaN 2204263540 NaN NaN ESP \n",
"1 2019-12-01 NaN 2157202351 NaN NaN ESP \n",
"2 2019-12-01 NaN 2137823204 NaN NaN ESP \n",
"3 2020-02-01 NaN 2181768913 NaN NaN ESP \n",
"4 2020-04-01 NaN 2197072938 NaN NaN ESP \n",
"\n",
" AREANAME4 AREANAME3 ... GLOBAL_ULTIMATE_AREANAME1 GLOBAL_ULTIMATE_COUNTRY \\\n",
"0 NaN MADRID ... NaN NaN \n",
"1 NaN MADRID ... NaN NaN \n",
"2 NaN MADRID ... NaN NaN \n",
"3 NaN MADRID ... NaN NaN \n",
"4 NaN MADRID ... NaN NaN \n",
"\n",
" GLOBAL_ULTIMATE_POSTCODE FAMILY_MEMBERS HIERARCHY_CODE TICKER_SYMBOL \\\n",
"0 NaN NaN NaN NaN \n",
"1 NaN NaN NaN NaN \n",
"2 NaN NaN NaN NaN \n",
"3 NaN NaN NaN NaN \n",
"4 NaN NaN NaN NaN \n",
"\n",
" EXCHANGE_NAME geom \\\n",
"0 NaN POINT (-3.70956 40.42264) \n",
"1 NaN POINT (-3.71091 40.41982) \n",
"2 NaN POINT (-3.69905 40.41780) \n",
"3 NaN POINT (-3.71120 40.42404) \n",
"4 NaN POINT (-3.70336 40.41415) \n",
"\n",
" isochrone n_pois \n",
"0 MULTIPOLYGON (((-3.71192 40.42488, -3.71149 40... 31977 \n",
"1 MULTIPOLYGON (((-3.71346 40.42093, -3.71321 40... 10131 \n",
"2 MULTIPOLYGON (((-3.70248 40.41750, -3.70222 40... 19947 \n",
"3 MULTIPOLYGON (((-3.71346 40.42437, -3.71338 40... 24480 \n",
"4 MULTIPOLYGON (((-3.70660 40.41544, -3.70634 40... 30348 \n",
"\n",
"[5 rows x 76 columns]"
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Here we can use any variable because we're only interested in counts\n",
"pois_df = enrichment.enrich_polygons(\n",
" pois_df,\n",
" variables=['CLASS_517d6003'],\n",
" aggregation='COUNT',\n",
" geom_col='isochrone'\n",
")\n",
"\n",
"# We rename the column name to give it a more descriptive name\n",
"pois_df.rename(columns={'CLASS_y':'n_pois'}, inplace=True)\n",
"pois_df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Visualize enrichment"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 674
},
"id": "Oy0hEIIrtPVx",
"outputId": "48ec1d10-e24a-4872-c40c-bdc91ca3bd95"
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Map(Layer(pois_df, geom_col='geom', \n",
" style=size_continuous_style('n_pois'),\n",
" legends=size_continuous_legend('# POIs'),\n",
" popup_hover=[popup_element('NAME', 'Name'), \n",
" popup_element('n_pois', 'Number of POIs')]))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "ekX7WOwasv4R"
},
"source": [
"\n",
"#### 3.2 Enrichment applying filters: Counting the number of eating places\n",
"\n",
"Now, we are interested in getting the number of eating places within a 5-minute isochrone for every sport POI. This requires using a filter to indicate that only eating places should be counted. Filters are added in a dictionary-like format, where the key is the filtering variable and the value is the filtering value.\n",
"\n",
"If you are interested in knowing how to identify the variable to use as filter, check out this notebook on how to access and download premium data."
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 467
},
"id": "bNvZkW90Djr-",
"outputId": "01aa5879-0700-41ab-b05b-a222aea6d44b"
},
"outputs": [
{
"data": {
"text/html": [
"
\n",
"\n",
"
\n",
" \n",
"
\n",
"
\n",
"
NAME
\n",
"
geoid
\n",
"
do_date
\n",
"
BRANDNAME
\n",
"
PB_ID
\n",
"
TRADE_NAME
\n",
"
FRANCHISE_NAME
\n",
"
ISO3
\n",
"
AREANAME4
\n",
"
AREANAME3
\n",
"
...
\n",
"
GLOBAL_ULTIMATE_COUNTRY
\n",
"
GLOBAL_ULTIMATE_POSTCODE
\n",
"
FAMILY_MEMBERS
\n",
"
HIERARCHY_CODE
\n",
"
TICKER_SYMBOL
\n",
"
EXCHANGE_NAME
\n",
"
geom
\n",
"
isochrone
\n",
"
n_pois
\n",
"
n_pois_eating
\n",
"
\n",
" \n",
" \n",
"
\n",
"
0
\n",
"
ACQUAPLAYA SPA
\n",
"
2204263540#-3.7095628#40.4226394
\n",
"
2020-04-01
\n",
"
NaN
\n",
"
2204263540
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.70956 40.42264)
\n",
"
MULTIPOLYGON (((-3.71192 40.42488, -3.71149 40...
\n",
"
31977
\n",
"
2052
\n",
"
\n",
"
\n",
"
1
\n",
"
ALAMBIQUE TIENDA Y ESCUELA DE COCINA
\n",
"
2157202351#-3.7109121#40.4198204
\n",
"
2019-12-01
\n",
"
NaN
\n",
"
2157202351
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.71091 40.41982)
\n",
"
MULTIPOLYGON (((-3.71346 40.42093, -3.71321 40...
\n",
"
10131
\n",
"
1009
\n",
"
\n",
"
\n",
"
2
\n",
"
ALCÁZAR NIGHT
\n",
"
2137823204#-3.69905#40.4178
\n",
"
2019-12-01
\n",
"
NaN
\n",
"
2137823204
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.69905 40.41780)
\n",
"
MULTIPOLYGON (((-3.70248 40.41750, -3.70222 40...
\n",
"
19947
\n",
"
1534
\n",
"
\n",
"
\n",
"
3
\n",
"
ALICIA PRODUCE
\n",
"
2181768913#-3.7112#40.42404
\n",
"
2020-02-01
\n",
"
NaN
\n",
"
2181768913
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.71120 40.42404)
\n",
"
MULTIPOLYGON (((-3.71346 40.42437, -3.71338 40...
\n",
"
24480
\n",
"
2125
\n",
"
\n",
"
\n",
"
4
\n",
"
ALMA PILATES
\n",
"
2197072938#-3.7033635#40.4141477
\n",
"
2020-04-01
\n",
"
NaN
\n",
"
2197072938
\n",
"
NaN
\n",
"
NaN
\n",
"
ESP
\n",
"
NaN
\n",
"
MADRID
\n",
"
...
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
NaN
\n",
"
POINT (-3.70336 40.41415)
\n",
"
MULTIPOLYGON (((-3.70660 40.41544, -3.70634 40...
\n",
"
30348
\n",
"
2744
\n",
"
\n",
" \n",
"
\n",
"
5 rows × 77 columns
\n",
"
"
],
"text/plain": [
" NAME geoid \\\n",
"0 ACQUAPLAYA SPA 2204263540#-3.7095628#40.4226394 \n",
"1 ALAMBIQUE TIENDA Y ESCUELA DE COCINA 2157202351#-3.7109121#40.4198204 \n",
"2 ALCÁZAR NIGHT 2137823204#-3.69905#40.4178 \n",
"3 ALICIA PRODUCE 2181768913#-3.7112#40.42404 \n",
"4 ALMA PILATES 2197072938#-3.7033635#40.4141477 \n",
"\n",
" do_date BRANDNAME PB_ID TRADE_NAME FRANCHISE_NAME ISO3 \\\n",
"0 2020-04-01 NaN 2204263540 NaN NaN ESP \n",
"1 2019-12-01 NaN 2157202351 NaN NaN ESP \n",
"2 2019-12-01 NaN 2137823204 NaN NaN ESP \n",
"3 2020-02-01 NaN 2181768913 NaN NaN ESP \n",
"4 2020-04-01 NaN 2197072938 NaN NaN ESP \n",
"\n",
" AREANAME4 AREANAME3 ... GLOBAL_ULTIMATE_COUNTRY GLOBAL_ULTIMATE_POSTCODE \\\n",
"0 NaN MADRID ... NaN NaN \n",
"1 NaN MADRID ... NaN NaN \n",
"2 NaN MADRID ... NaN NaN \n",
"3 NaN MADRID ... NaN NaN \n",
"4 NaN MADRID ... NaN NaN \n",
"\n",
" FAMILY_MEMBERS HIERARCHY_CODE TICKER_SYMBOL EXCHANGE_NAME \\\n",
"0 NaN NaN NaN NaN \n",
"1 NaN NaN NaN NaN \n",
"2 NaN NaN NaN NaN \n",
"3 NaN NaN NaN NaN \n",
"4 NaN NaN NaN NaN \n",
"\n",
" geom \\\n",
"0 POINT (-3.70956 40.42264) \n",
"1 POINT (-3.71091 40.41982) \n",
"2 POINT (-3.69905 40.41780) \n",
"3 POINT (-3.71120 40.42404) \n",
"4 POINT (-3.70336 40.41415) \n",
"\n",
" isochrone n_pois n_pois_eating \n",
"0 MULTIPOLYGON (((-3.71192 40.42488, -3.71149 40... 31977 2052 \n",
"1 MULTIPOLYGON (((-3.71346 40.42093, -3.71321 40... 10131 1009 \n",
"2 MULTIPOLYGON (((-3.70248 40.41750, -3.70222 40... 19947 1534 \n",
"3 MULTIPOLYGON (((-3.71346 40.42437, -3.71338 40... 24480 2125 \n",
"4 MULTIPOLYGON (((-3.70660 40.41544, -3.70634 40... 30348 2744 \n",
"\n",
"[5 rows x 77 columns]"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pois_df = enrichment.enrich_polygons(\n",
" pois_df,\n",
" variables=['CLASS_517d6003'],\n",
" aggregation='COUNT',\n",
" geom_col='iso_10walk',\n",
" filters={Variable.get('CLASS_517d6003').id:\"= 'EATING PLACES/RESTAURANTS'\"}\n",
")\n",
"\n",
"# We rename the column name to give it a more descriptive name\n",
"pois_df.rename(columns={'CLASS':'n_pois_eating'}, inplace=True)\n",
"pois_df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Visualize enrichment"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 674
},
"id": "G5CbIzbftdw7",
"outputId": "e5dcf939-2500-4a19-9cb3-bd6281cdda3e"
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Map(Layer(pois_df, geom_col='geom', \n",
" style=size_continuous_style('n_pois_eating'), \n",
" legends=size_continuous_legend('# Eating POIs'),\n",
" popup_hover=[popup_element('NAME', 'Name'), \n",
" popup_element('n_pois_eating', 'Number of eating places')]))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "LrRqlkPptLQG"
},
"source": [
"\n",
"#### 3.3 Brief analysis\n",
"\n",
"Let's now take a look at how the total number of POI's and eating places around sport POI's correlate."
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 592
},
"id": "xxNM-_K4KKUe",
"outputId": "09bb4b63-666e-43f3-8f29-7bdfdb0f0988"
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Layout([Map(Layer(pois_df, geom_col='geom', \n",
" style=size_continuous_style('n_pois'),\n",
" legends=size_continuous_legend('# POIs'),\n",
" popup_hover=[popup_element('NAME', 'Name'), \n",
" popup_element('n_pois', 'Number of POIs')])),\n",
" Map(Layer(pois_df, geom_col='geom', \n",
" style=size_continuous_style('n_pois_eating'), \n",
" legends=size_continuous_legend('# Eating POIs'),\n",
" popup_hover=[popup_element('NAME', 'Name'), \n",
" popup_element('n_pois_eating', 'Number of eating places')]))],\n",
" map_height=550)"
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 352
},
"id": "ZOM93X3eGcmE",
"outputId": "ef1550b8-02ac-4768-bdc0-4d0cbf6f6f99"
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 17,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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\n",
"text/plain": [
"