Add schematic figure engine and shapefile loading utilities

- Implemented `schematic_figure.py` to provide a generic nested three-panel figure engine with layers for raster, polygon, and point data, along with a convenience wrapper for creating schematic figures.
- Introduced `shapefile_functions.py` for loading admin shapefiles, including functions to load global admin boundaries and rasterize admin codes into a pixel grid.
- Added detailed docstrings for public API and internal functions to enhance code readability and usability.

Author: bcreiner

README.md

@@ -1,69 +1,133 @@
 # IDD Spatial Analysis
 
-[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![Poetry](https://img.shields.io/badge/poetry-managed-blue.svg)](https://python-poetry.org/)
 
-Repository for IDD geospatial analysis tools and utilities in Python.
+Geospatial analysis tools for IDD research, focusing on clinic proximity analysis and population coverage estimation.
 
-## 🚀 Quick Start
+## 🚀 Features
 
-### Local Installation
+- **Clinic Proximity Analysis**: Calculate population within X km of each clinic
+- **Coverage Analysis**: Estimate population with access to at least Y clinics within X km
+- **Administrative Summaries**: Aggregate results by admin boundaries (Admin 0, 1, 2)
+- **Raster Operations**: Work with 100m resolution population rasters in equal area projections
 
-#### Option 1: Using Conda (Recommended)
+## 📦 Environment Setup
+
+This project uses conda for environment management with Python 3.13 and all necessary geospatial libraries.
+
+### Create and Activate Environment
 
 ```bash
-# Clone the repository
+# Clone the repository (if not already cloned)
 git clone https://github.com/ihmeuw/idd-spatial-analysis.git
 cd idd-spatial-analysis
 
-# Create and activate the conda environment
+# Create the conda environment
 conda env create -f environment.yml
-conda activate idd-spatial-analysis
-```
-
-#### Option 2: Using Poetry
 
-```bash
-# Clone the repository
-git clone https://github.com/ihmeuw/idd-spatial-analysis.git
-cd idd-spatial-analysis
+# Activate the environment
+conda activate idd-spatial-analysis
 
-# Install dependencies with poetry
+# Install the package in development mode
 poetry install
-poetry shell
+
+# Create Jupyter kernel (for notebooks)
+python -m ipykernel install --user --name=idd-spatial-analysis --display-name="Python 3.13 (idd-spatial-analysis)"
 ```
 
-#### Option 3: Install as a Python package (from GitHub)
+## 💡 Usage
 
-You can install and use `idd_spatial_analysis` in other projects/environments:
+### Basic Example
 
-```bash
-pip install git+https://github.com/ihmeuw/idd-spatial-analysis.git
+```python
+from idd_spatial_analysis.clinic_proximity import (
+    load_clinic_data,
+    population_within_distance,
+    population_coverage_multiple_clinics
+)
+
+# Load clinic GPS coordinates
+clinics = load_clinic_data("path/to/clinics.csv")
+
+# Calculate population within 5 km of each clinic
+results = population_within_distance(
+    clinics_gdf=clinics,
+    population_raster_path="path/to/population_100m.tif",
+    distance_km=5.0
+)
+
+# Calculate population with access to at least 1 clinic within 5 km
+coverage = population_coverage_multiple_clinics(
+    clinics_gdf=clinics,
+    population_raster_path="path/to/population_100m.tif",
+    distance_km=5.0,
+    min_clinics=1
+)
+
+print(f"Coverage: {coverage['coverage_percentage']:.2f}%")
 ```
 
-Then, in your Python code:
+### Data Requirements
 
-```python
-from idd_spatial_analysis import spatial_utils
+1. **Clinic Data**: GPS coordinates in CSV, shapefile, or GeoJSON format
+   - Expected columns: `longitude`/`latitude` or `lon`/`lat` or `x`/`y`
+   
+2. **Population Raster**: High-resolution population data
+   - Format: GeoTIFF
+   - Projection: Equal area projection (e.g., Mollweide, Albers Equal Area)
+   - Resolution: 100m (or as available)
+   
+3. **Administrative Boundaries**: Shapefiles for Admin 0, 1, and 2 levels
+   - Format: Shapefile, GeoJSON, or other vector format
+   - Must have a name field for labeling
 
-# Your geospatial analysis code here
-```
+### Example Notebook
 
-## 📦 Package Structure
+See [notebooks/example_usage.ipynb](notebooks/example_usage.ipynb) for a complete working example.
+
+## � Project Structure
 
 ```
 idd-spatial-analysis/
 ├── src/
 │   └── idd_spatial_analysis/    # Main package
 │       ├── __init__.py
-│       └── spatial_utils.py     # Core spatial utilities
+│       ├── spatial_utils.py     # Core spatial utilities
+│       └── clinic_proximity.py  # Clinic proximity analysis functions
 ├── notebooks/                   # Example notebooks
+│   └── example_usage.ipynb      # Complete usage example
 ├── tests/                       # Unit tests
+│   ├── __init__.py
+│   └── test_spatial_utils.py
 ├── pyproject.toml              # Poetry configuration
-├── environment.yml             # Conda environment
+├── environment.yml             # Conda environment (Python 3.13)
 └── README.md
 ```
 
+## 🔑 Key Functions
+
+### `load_clinic_data(filepath, crs="EPSG:4326")`
+Load clinic GPS coordinates from various file formats.
+
+### `population_within_distance(...)`
+Calculate population within specified distance of each individual clinic.
+
+**Returns**: DataFrame with clinic IDs and population counts.
+
+### `population_coverage_multiple_clinics(...)`
+Calculate population with access to at least `min_clinics` within `distance_km`.
+
+**Returns**:
+- Total population
+- Population with access
+- Coverage percentage
+- Coverage raster (number of clinics within distance per pixel)
+- Admin-level summaries (if boundaries provided)
+
+### `export_coverage_raster(...)`
+Export coverage raster to GeoTIFF file.
+
 ## 🛠️ Development
 
 ### Running Tests

environment.yml

@@ -3,7 +3,7 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python=3.10
+  - python=3.13
   - geopandas>=0.14.0
   - rasterio>=1.3.0
   - xarray>=2023.0.0
@@ -13,6 +13,8 @@ dependencies:
   - numpy>=1.24.0
   - matplotlib>=3.7.0
   - cartopy>=0.22.0
+  - scipy>=1.10.0
+  - rtree>=1.0.0
   - dask
   - netcdf4
   - zarr