Getting Started Tutorial (with Choropleth Maps)¶
This enhanced tutorial introduces SocialMapper's visualization capabilities, showing how to create professional choropleth maps alongside the standard demographic analysis.
What You'll Learn¶
- How to search for Points of Interest (POIs) from OpenStreetMap
- How to generate travel time isochrones
- How to analyze census demographics within reachable areas
- How to create choropleth maps to visualize demographic patterns
- How to export results in multiple formats
Prerequisites¶
Before starting this tutorial, ensure you have:
-
SocialMapper installed:
-
Census API key (optional but recommended):
!!! tip "Getting a Census API Key" You can obtain a free API key from the U.S. Census Bureau. While optional, having a key prevents rate limiting.
Tutorial Overview¶
This tutorial analyzes access to public libraries in Wake County, NC, demonstrating how residents can reach these important community resources within a 15-minute walk. We'll visualize the demographic characteristics of areas with good library access using choropleth maps.
Step-by-Step Guide¶
Step 1: Import Required Libraries¶
from socialmapper import SocialMapperClient, SocialMapperBuilder
from socialmapper.visualization.pipeline_integration import add_visualization_to_pipeline
The tutorial now uses:
- SocialMapperClient
: Manages the analysis session
- SocialMapperBuilder
: Helps construct analysis configurations
- add_visualization_to_pipeline
: Creates choropleth maps from results
Step 2: Define Search Parameters¶
geocode_area = "Wake County"
state = "North Carolina"
poi_type = "amenity" # OpenStreetMap category
poi_name = "library" # Specific type within category
travel_time = 15 # minutes
Step 3: Select Census Variables¶
census_variables = [
"total_population",
"median_household_income",
"median_age",
"percent_poverty",
"percent_no_vehicle"
]
Variables for Visualization
When creating choropleth maps, choose variables that reveal spatial patterns. Income, poverty, and vehicle access are particularly relevant for understanding library accessibility.
Step 4: Build and Run the Analysis¶
with SocialMapperClient() as client:
# Build configuration with map exports enabled
config = (SocialMapperBuilder()
.with_location(geocode_area, state)
.with_osm_pois(poi_type, poi_name)
.with_travel_time(travel_time)
.with_census_variables(*census_variables)
.with_exports(csv=True, isochrones=True) # Enable both exports
.build()
)
# Run analysis
result = client.run_analysis(config)
Enable Isochrone Export
Set isochrones=True
in .with_exports()
to save the intermediate data needed for creating choropleth maps.
Step 5: Generate Choropleth Maps¶
After the analysis completes, create visualizations:
# Find the generated data files
pipeline_data_dir = Path("output/pipeline_data")
census_data_path = list(pipeline_data_dir.glob("*census*.parquet"))[-1]
poi_data_path = list(pipeline_data_dir.glob("*pois*.parquet"))[-1]
isochrone_data_path = list(pipeline_data_dir.glob("*isochrones*.parquet"))[-1]
# Generate choropleth maps
map_paths = add_visualization_to_pipeline(
census_data_path=census_data_path,
output_dir="output/maps",
poi_data_path=poi_data_path,
isochrone_data_path=isochrone_data_path,
demographic_columns=["total_population", "median_household_income", "percent_poverty"],
create_demographic_maps=True,
map_format="png",
dpi=150
)
Understanding the Output¶
Generated Files¶
The enhanced tutorial creates multiple outputs:
- CSV Data (
output/csv/
): - Detailed demographic data for each library
-
Aggregated statistics
-
Intermediate Data (
output/pipeline_data/
): *_pois.parquet
: Library locations*_isochrones.parquet
: 15-minute walk boundaries-
*_census.parquet
: Census data with geometries -
Choropleth Maps (
output/maps/
): total_population_map.png
: Population density patternsmedian_household_income_map.png
: Income distributionpercent_poverty_map.png
: Poverty concentration
Interpreting Choropleth Maps¶
The choropleth maps reveal spatial patterns in library accessibility:
Population Density Map¶
- Dark blue areas: High population density with library access
- Light blue areas: Lower population density with library access
- Gray areas: Census blocks beyond 15-minute walk
Median Income Map¶
- Dark green areas: Higher income neighborhoods with library access
- Light green areas: Lower income neighborhoods with library access
- Pattern analysis: Are libraries equally accessible across income levels?
Travel Distance Map¶
- Dark red areas: Longer travel distance to nearest library
- Yellow areas: Moderate travel distance
- Pattern analysis: Geographic accessibility varies across the region
Map Features¶
Each choropleth map includes: - Legend: Shows data classification and color scheme - North arrow: Indicates map orientation - Scale bar: Shows distance reference - POI markers: Library locations marked with symbols - Isochrone overlay: 15-minute walk boundaries (if applicable)
Customizing Visualizations¶
Change Color Schemes¶
Modify the visualization configuration:
from socialmapper.visualization import ColorScheme, MapConfig
# Create custom configuration
map_config = MapConfig(
color_scheme=ColorScheme.BLUES, # Use blue gradient
title="Custom Library Access Map",
figsize=(12, 10),
show_legend=True,
show_north_arrow=True,
show_scale_bar=True
)
Select Different Variables¶
Choose variables that reveal different patterns:
demographic_columns = [
"percent_seniors", # Elderly population
"percent_no_vehicle", # Transportation barriers
"percent_college", # Education levels
]
Adjust Classification Methods¶
Control how data is grouped into colors:
from socialmapper.visualization import ClassificationScheme
config = MapConfig(
classification_scheme=ClassificationScheme.QUANTILES, # Equal count bins
n_classes=7, # More granular classification
)
Common Visualization Issues¶
No Maps Generated¶
- Ensure
isochrones=True
is set in.with_exports()
- Check that parquet files exist in
output/pipeline_data/
- Verify census data was successfully fetched
Poor Color Contrast¶
- Try different color schemes (VIRIDIS, PLASMA for continuous data)
- Adjust number of classes (3-7 typically work well)
- Use diverging colors (RDBU) for data with meaningful midpoint
Large File Sizes¶
- Reduce DPI for web display (72-150 dpi)
- Use PNG for photos, SVG for scalable graphics
- Enable geometry simplification for large areas
Complete Example¶
The full enhanced tutorial script is available at:
examples/tutorials/01_getting_started_with_maps.py
Next Steps¶
After completing this tutorial, explore:
- Custom POIs Tutorial: Analyze your own locations
- Multi-Modal Analysis: Compare walk, bike, and drive access
- Address Geocoding: Work with specific addresses
Key Takeaways¶
- Choropleth maps reveal spatial patterns invisible in tabular data
- SocialMapper integrates demographic analysis with professional visualization
- Maps help communicate findings to stakeholders and communities
- Visualization supports equity analysis by highlighting disparities
- The pipeline seamlessly combines data processing with map generation