Skip to content

Latest commit

 

History

History
254 lines (192 loc) · 9.83 KB

FUNCTIONS.md

File metadata and controls

254 lines (192 loc) · 9.83 KB

mobspain - Minimal Spanish Transport Zone Analysis Package

✅ Package Restructure: COMPLETE

The mobspain package has been successfully restructured into a minimal, focused package that supports exactly the analysis demonstrated in the vignette.

🎯 Transformation Summary

  • Before: 25+ functions with complex dependencies (only 4% utilization)
  • After: 1 core function with minimal dependencies (100% utilization)

📦 Current Package Structure

Core Function

  • get_zones() - Downloads Spanish administrative zone geometries with filtering options

Files Included

  • R/zones.R - Core get_zones function
  • R/imports.R - Minimal imports (dplyr, sf, rlang)
  • R/package.R - Package documentation
  • R/data.R - Sample zones dataset
  • vignettes/introduction.Rmd - Comprehensive transport analysis vignette

Files Removed

  • ✅ R/cache.R - Caching functions (not used in vignette)
  • ✅ R/config.R - Configuration functions (not used in vignette)
  • ✅ R/ml.R - Machine learning functions (not used in vignette)
  • ✅ R/mobility.R - Complex mobility analysis functions (not used in vignette)
  • ✅ R/spatial.R - Advanced spatial functions (not used in vignette)
  • ✅ R/transport_analysis.R - Additional analysis functions (not used in vignette)
  • ✅ R/utils.R - Utility functions (not used in vignette)
  • ✅ R/validation.R - Data validation functions (not used in vignette)
  • ✅ R/viz.R - Visualization functions (not used in vignette)
  • ✅ R/zzz.R - Package startup functions (not needed)

🔧 Minimal Dependencies

DESCRIPTION Dependencies

Imports:
    spanishoddata,  # For Spanish zone data
    sf,             # For spatial operations
    dplyr,          # For data manipulation
    rlang           # For non-standard evaluation

Removed Dependencies

  • ggplot2, glue, lubridate, stats, methods, scales, digest, purrr, tidyr

📊 Function Details

get_zones(level, year, zones_filter, region_filter, city_filter)

Purpose: Downloads Spanish administrative zone geometries with comprehensive filtering options.

Parameters:

  • level: "dist" (districts) or "muni" (municipalities)
  • year: Year for zone geometries (default: 2023)
  • zones_filter: Specific zone IDs to filter
  • region_filter: Filter by region/province
  • city_filter: Filter by city names ("Madrid", "Barcelona", etc.)

Returns: SF object with zone geometries

Examples:

# Get all districts
zones <- get_zones(level = "dist")

# Get Madrid zones (as used in vignette)
madrid_zones <- get_zones(level = "dist", city_filter = "Madrid")

# Get specific zones
zones <- get_zones(level = "dist", zones_filter = c("28001", "28002"))

🎨 Design Philosophy

  1. Vignette-Centered: Package contains only what's used in the comprehensive vignette
  2. Minimal Dependencies: Only essential packages for core functionality
  3. Simple API: Single primary function with clear parameters
  4. Complete Analysis: Vignette demonstrates full transport analysis workflow using:
    • Standard R packages (dplyr, sf, ggplot2, tidyr)
    • mobspain's get_zones() for data access
    • Custom analysis code in vignette

📈 Package Efficiency

  • Function Utilization: 100% (1/1 functions used)
  • File Count: Reduced from 13 to 4 R files
  • Dependencies: Reduced from 13 to 4 packages
  • Maintenance: Minimal surface area for bugs and updates
  • Learning Curve: Simple, focused API

📋 Vignette Analysis Coverage

The vignette demonstrates comprehensive transport analysis including:

  • ✅ Zone characteristic analysis
  • ✅ Spatial distribution mapping
  • ✅ Multi-city comparison
  • ✅ Temporal pattern analysis
  • ✅ Flow visualization
  • ✅ Professional minimal design aesthetics

All analysis is performed using standard R packages with mobspain providing only the essential zone data access function.

🎯 Perfect Alignment

The package now perfectly aligns with its stated purpose: providing Spanish administrative zones for transport analysis, with the vignette demonstrating how to perform comprehensive analysis using these zones.

Core Functions

1. analyze_zone_characteristics()

Purpose: Performs spatial analysis of transport zones with size distribution analysis and visualization.

Parameters:

  • zones: SF dataframe with zone geometries
  • size_categories: Named vector of size breakpoints in km² (default: c("Small" = 5, "Medium" = 15, "Large" = Inf))

Returns: List containing:

  • size_distribution: Data frame with zone counts and percentages by category
  • spatial_plot: Spatial map showing zones colored by size category
  • distribution_plot: Bar chart showing zone count distribution

Example:

zones <- get_zones()
analysis <- analyze_zone_characteristics(zones)
print(analysis$size_distribution)
print(analysis$spatial_plot)

2. generate_mobility_data()

Purpose: Creates realistic synthetic mobility data for transport analysis and demonstration with temporal patterns.

Parameters:

  • zones: SF dataframe of zones to generate mobility between
  • days: Number of days to generate data for (default: 7)
  • seed: Random seed for reproducibility (default: 123)
  • base_demand: Base number of trips per OD pair per day (default: 100)

Returns: Data frame with origin, destination, date, hour, weekday, and trip counts including:

  • Peak hour effects (3.5x multiplier during 7-9 AM and 5-7 PM)
  • Weekend adjustments (0.6x multiplier)
  • Random variation factors

Example:

zones <- get_zones()
mobility_data <- generate_mobility_data(zones, days = 3, base_demand = 150)
head(mobility_data)

3. create_multi_city_comparison()

Purpose: Compares transport characteristics across multiple Spanish cities with summary statistics and visualization.

Parameters:

  • cities: Character vector of city names to compare (default: c("Madrid", "Barcelona", "Valencia"))

Returns: List containing:

  • comparison_data: Data frame with zone counts, total area, and mean area by city
  • comparison_plot: Faceted bar chart comparing cities across metrics

Example:

comparison <- create_multi_city_comparison(c("Madrid", "Barcelona", "Sevilla"))
print(comparison$comparison_data)
print(comparison$comparison_plot)

4. create_temporal_analysis()

Purpose: Analyzes mobility patterns over time with hourly and daily patterns, creating comprehensive temporal visualizations.

Parameters:

  • mobility_data: Data frame with mobility data (from generate_mobility_data() or similar)
  • time_window: Character specifying analysis window: "hourly", "daily", or "both" (default: "both")

Returns: List containing:

  • hourly_plot: Line plot showing average trips by hour with peak/off-peak distinction
  • daily_plot: Line plot showing total daily trips with weekend/weekday colors
  • hourly_data: Hourly pattern data with peak period classifications
  • daily_data: Daily pattern data with day type classifications
  • summary_stats: Key statistics including peak hour and peak ratio

Example:

zones <- get_zones()
mobility_data <- generate_mobility_data(zones, days = 7)
temporal_analysis <- create_temporal_analysis(mobility_data)
print(temporal_analysis$hourly_plot)
print(temporal_analysis$summary_stats)

5. create_flow_visualization()

Purpose: Creates flow maps and network analysis for origin-destination mobility patterns with spatial and network-based visualizations.

Parameters:

  • mobility_data: Data frame with mobility data including origin, dest, and n_trips columns
  • zones: SF dataframe with zone geometries
  • flow_threshold: Minimum number of trips to display (default: 50)
  • top_flows: Number of top flows to highlight (default: 10)

Returns: List containing:

  • flow_map: Spatial flow map with lines connecting origin-destination pairs
  • flow_summary: Aggregated flow data above threshold
  • flow_stats: Summary statistics including total flows, volume, and top OD pairs

Example:

zones <- get_zones()
mobility_data <- generate_mobility_data(zones, days = 3)
flow_analysis <- create_flow_visualization(mobility_data, zones, flow_threshold = 100)
print(flow_analysis$flow_map)
print(flow_analysis$flow_stats)

Design Philosophy

User Customization

  • All functions include customizable parameters for different analysis needs
  • Default values provide reasonable starting points for typical Spanish transport analysis
  • Functions are designed to work together in analysis workflows

Professional Visualization

  • Minimal, clean design aesthetic with professional color palettes
  • Consistent theming across all plots
  • Clear titles, subtitles, and legends for publication-ready outputs
  • Thin lines and professional typography

Error Handling

  • Comprehensive input validation for all parameters
  • Clear error messages for common issues
  • Graceful fallbacks for missing data scenarios

Integration

  • Functions work seamlessly with existing get_zones() function
  • Compatible with sf and dplyr workflows
  • Follows tidyverse conventions for data manipulation

Package Integration

These functions replace the comprehensive analysis code from the vignette while maintaining the same analytical capabilities. The package now focuses specifically on the transport analysis scope demonstrated in the vignette, providing users with:

  1. Focused functionality: Only functions needed for transport analysis
  2. Enhanced customization: More options than the original vignette code
  3. Professional outputs: Publication-ready visualizations
  4. Comprehensive documentation: Clear examples and parameter descriptions
  5. Error handling: Robust validation and helpful error messages

The functions can be used individually or combined for comprehensive transport analysis workflows covering spatial characteristics, temporal patterns, multi-city comparisons, and flow analysis.