### Setup Environment and Dependencies

Source: https://context7.com/edwardoughton/backcast/llms.txt

Commands to initialize the conda environment and list required external data sources.

```bash
# Create conda environment from specification
conda env create -f backcast.yml

# Activate environment
conda activate backcast

# Required external data sources:
# 1. OpenCellID cell tower database (cell_towers_2022-12-24.csv)
# 2. GADM administrative boundaries (gadm36_levels_shp/)
# 3. WorldPop settlement layer (ppp_2020_1km_Aggregated.tif)
# 4. OpenStreetMap road network (gis_osm_roads_free_1.shp)
# 5. Mobile Coverage Explorer GeoTIFFs (MCE_2G, MCE_3G, MCE_4G)
# 6. Country metadata (countries.csv, mobile_codes.csv)
# 7. Investment data (cash_to_spend.csv, revenue_estimation.xlsx)
```

--------------------------------

### start_year

Source: https://context7.com/edwardoughton/backcast/llms.txt

Returns deployment period start and end years for a radio technology.

```APIDOC
## start_year

### Description
Returns the deployment window (start and end years) for a given radio technology.

### Parameters
#### Request Body
- **radio** (string) - Required - Technology name (e.g., 'gsm', 'umts', 'lte')

### Response
- **years** (tuple) - (start_year, end_year)
```

--------------------------------

### Get Spending Proportion by Year

Source: https://context7.com/edwardoughton/backcast/llms.txt

Returns the spending allocation percentage between technologies based on the year, used to model transition periods between different technology eras.

```python
from scripts.process import spending_proportion

# Single technology era (GSM only)
pct_2000 = spending_proportion(2000)  # Returns 100

# Dual technology era (GSM + UMTS overlap)
pct_2010 = spending_proportion(2010)  # Returns 50

# Later single technology era (LTE focus)
pct_2019 = spending_proportion(2019)  # Returns 100
```

--------------------------------

### Get Radio Technology Deployment Years

Source: https://context7.com/edwardoughton/backcast/llms.txt

Returns the start and end years for the deployment period of a specified radio technology (GSM, UMTS, LTE).

```python
from scripts.process import start_year

# Get deployment windows for each technology
gsm_start, gsm_end = start_year('gsm')    # Returns (1996, 2014)
umts_start, umts_end = start_year('umts')  # Returns (2008, 2018)
дает_start, lte_end = start_year('lte')     # Returns (2013, 2022)

print(f"GSM deployment: {gsm_start}-{gsm_end}")
print(f"UMTS deployment: {umts_start}-{umts_end}")
print(f"LTE deployment: {lte_start}-{lte_end}")
```

--------------------------------

### Run Full Preprocessing Pipeline

Source: https://context7.com/edwardoughton/backcast/llms.txt

Orchestrates the complete preprocessing pipeline for a country, including boundary processing, site data extraction, and coverage data generation. Requires country configuration with ISO3 code and regional administrative level.

```python
from scripts.preprocess import run_preprocessing

# Define country configuration
country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Run full preprocessing pipeline
# This will:
# 1. Create national sites CSV from cell tower data
# 2. Process country boundary shapes
# 3. Process regional administrative boundaries
# 4. Create national and regional site shapefiles
# 5. Export cell counts by region
# 6. Process regional coverage rasters
run_preprocessing(country)

# Output files created:
# - data/processed/MEX/sites/MEX.csv
# - data/processed/MEX/national_outline.shp
# - data/processed/MEX/regions/regions_1_MEX.shp
# - data/processed/MEX/regions/regions_2_MEX.shp
# - data/processed/MEX/sites/cells_by_region.csv
```

--------------------------------

### Generate Tile Backcast Algorithm

Source: https://context7.com/edwardoughton/backcast/llms.txt

Core backcast algorithm simulating year-by-year infrastructure deployment based on investment attractiveness. Uses parameters like cost per site, population per site, market share, and an attractiveness formula (pop_km2 + (motorway_km * 10000)).

```python
from scripts.process import generate_tile_backcast

country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Parameters:
# - cost_per_site: $150,000 USD
# - pop_per_site: 5,000 users per cell site
# - market_share: 25%

# Deployment periods:
# - GSM: 1996-2014
# - UMTS: 2008-2018
# - LTE: 2013-2022

# Attractiveness formula: pop_km2 + (motorway_km * 10000)

generate_tile_backcast(country)

# Output files per radio technology:
# - results/MEX/by_radio/gsm.csv
# - results/MEX/by_radio/umts.csv
# - results/MEX/by_radio/lte.csv
# - results/MEX/by_radio/gsm_tiles.shp
# - results/MEX/by_radio/umts_tiles.shp
# - results/MEX/by_radio/lte_tiles.shp

# CSV columns: id_lower, year, radio, population, users, attractiveness, cells_to_build
```

--------------------------------

### Plot Deployment Schedule Maps

Source: https://context7.com/edwardoughton/backcast/llms.txt

Generates visualization maps for the deployment schedule of each radio technology. Creates choropleth maps showing deployment years using the viridis_r colormap with 2-year bins.

```python
from scripts.process import plot_map

country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Creates choropleth maps showing deployment years
# Uses viridis_r colormap with 2-year bins
plot_map(country)

# Output files:
# - vis/figures/2G_deployment_schedule.png
# - vis/figures/3G_deployment_schedule.png
```

--------------------------------

### generate_tile_backcast

Source: https://context7.com/edwardoughton/backcast/llms.txt

Core backcast algorithm that simulates year-by-year infrastructure deployment.

```APIDOC
## generate_tile_backcast

### Description
Simulates year-by-year infrastructure deployment based on investment attractiveness (pop_km2 + motorway_km * 10000).

### Parameters
#### Request Body
- **country** (object) - Required - Dictionary containing 'iso3' and 'gid_region'

### Response
- **output** (files) - Results saved to results/{iso3}/by_radio/ for gsm, umts, and lte
```

--------------------------------

### Visualize Investment Attractiveness

Source: https://context7.com/edwardoughton/backcast/llms.txt

Visualizes the investment attractiveness metric using the inferno_r colormap.

```python
from scripts.vis import plot_regions_by_investment_attractiveness

iso3 = 'MEX'

# Shows attractiveness score distribution
# Uses inferno_r colormap
plot_regions_by_investment_attractiveness(iso3)

# Output: vis/figures/investment_attractiveness.png
```

--------------------------------

### run_preprocessing

Source: https://context7.com/edwardoughton/backcast/llms.txt

Orchestrates the complete preprocessing pipeline for a country, generating national and regional boundaries, processing cell tower sites, and extracting coverage data.

```APIDOC
## run_preprocessing

### Description
Orchestrates the complete preprocessing pipeline for a country, generating national and regional boundaries, processing cell tower sites, and extracting coverage data.

### Parameters
#### Request Body
- **country** (dict) - Required - Configuration object containing 'iso3' (string) and 'gid_region' (int).
```

--------------------------------

### Execute Full Backcast Analysis Pipeline

Source: https://context7.com/edwardoughton/backcast/llms.txt

Runs the complete end-to-end workflow including grid generation, preprocessing, population modeling, backcast processing, and visualization.

```python
# Step 1: Generate grid and process road network
from scripts.grid import (
    generate_grid,
    export_specific_road_network,
    segment_lower_into_upper_grid,
    cut_roads_with_upper_grid,
    segment_roads_to_lower,
    export_road_network_metrics
)

iso3 = 'MEX'
side_length_upper = 100000  # 100km upper grid
side_length_lower = 10000   # 10km lower grid

export_specific_road_network(iso3)
generate_grid(iso3, side_length_lower)
generate_grid(iso3, side_length_upper)
segment_lower_into_upper_grid(iso3, side_length_lower, side_length_upper)
cut_roads_with_upper_grid(iso3, side_length_upper)
segment_roads_to_lower(iso3, side_length_lower, side_length_upper)
export_road_network_metrics(iso3, side_length_lower)

# Step 2: Preprocess country data
from scripts.preprocess import run_preprocessing

country = {'iso3': 'MEX', 'gid_region': 2}
run_preprocessing(country)

# Step 3: Process population data
from scripts.pop import (
    process_settlement_layer,
    generate_population,
    generate_tile_population
)

country = {'iso3': 'MEX', 'regional_level': 2}
process_settlement_layer(country)
generate_population(country)
generate_tile_population(country)

# Step 4: Run backcast analysis
from scripts.process import (
    load_data,
    generate_tile_backcast,
    aggregate_results,
    plot_map
)

country = {'iso3': 'MEX', 'gid_region': 2}
load_data(country)
generate_tile_backcast(country)
aggregate_results(country)
plot_map(country)

# Step 5: Generate visualizations
from scripts.vis import (
    plot_coverage,
    plot_regions_by_geotype,
    plot_road_network,
    plot_regions_by_investment_attractiveness
)

plot_coverage('MEX')
plot_regions_by_geotype('MEX')
plot_road_network('MEX')
plot_regions_by_investment_attractiveness('MEX')
```

--------------------------------

### plot_map

Source: https://context7.com/edwardoughton/backcast/llms.txt

Generates deployment schedule visualization maps for each radio technology.

```APIDOC
## plot_map

### Description
Creates choropleth maps showing deployment years using viridis_r colormap.

### Parameters
#### Request Body
- **country** (object) - Required - Dictionary containing 'iso3' and 'gid_region'

### Response
- **output** (files) - Saved to vis/figures/ as PNG files
```

--------------------------------

### Visualize Population Density by Geotype

Source: https://context7.com/edwardoughton/backcast/llms.txt

Creates a population density map binned by grid tile density.

```python
from scripts.vis import plot_regions_by_geotype

iso3 = 'MEX'

# Bins: <10, 10-50, 50-100, 100-250, 250-500, 500-750,
#       750-1000, 1000-2000, 2000-5000, >5000 km²
plot_regions_by_geotype(iso3)

# Output: vis/figures/population_density_km2.png
```

--------------------------------

### Visualize Mobile Coverage Layers

Source: https://context7.com/edwardoughton/backcast/llms.txt

Generates a 2x2 subplot visualizing 2G, 3G, and 4G coverage layers from Mobile Coverage Explorer data.

```python
from scripts.vis import plot_coverage

iso3 = 'MEX'

# Creates 2x2 subplot showing coverage by generation
# Processes coverage shapefiles from GeoTIFF rasters
plot_coverage(iso3)

# Output: vis/figures/coverage.png
```

--------------------------------

### Generate Spatial Grid

Source: https://context7.com/edwardoughton/backcast/llms.txt

Creates a spatial grid clipped to a country's boundary. Specify the ISO3 code and desired cell side length in meters (using EPSG:3857).

```python
from scripts.grid import generate_grid

iso3 = 'MEX'
side_length = 10000  # 10km x 10km grid cells in meters (EPSG:3857)

# Generates grid clipped to country boundary
grid = generate_grid(iso3, side_length)

# Output: data/processed/MEX/grid/grid_10000_10000_km.shp
# Attributes: GID_id (centroid coordinates), area_km2

# GID_id format: "{lon}_{lat}" e.g., "-99.5_19.25"
```

--------------------------------

### process_settlement_layer

Source: https://context7.com/edwardoughton/backcast/llms.txt

Clips the WorldPop settlement raster layer to country boundaries for population analysis.

```APIDOC
## process_settlement_layer

### Description
Clips the WorldPop settlement raster layer to country boundaries for population analysis.

### Parameters
#### Request Body
- **country** (dict) - Required - Configuration object containing 'iso3' (string) and 'regional_level' (int).
```

--------------------------------

### Process Settlement Layer

Source: https://context7.com/edwardoughton/backcast/llms.txt

Clips the WorldPop settlement raster layer to country boundaries for population analysis. Sets the nodata value to 255 and outputs the clipped raster file.

```python
from scripts.pop import process_settlement_layer

country = {
    'iso3': 'MEX',
    'regional_level': 2,
}

# Clips ppp_2020_1km_Aggregated.tif to national boundary
# Sets nodata value to 255
process_settlement_layer(country)

# Output: data/processed/MEX/population/settlements.tif
```

--------------------------------

### Load Comprehensive Analysis Data

Source: https://context7.com/edwardoughton/backcast/llms.txt

Merges population tile data with road network metrics to create the comprehensive analysis dataset. Joins population data with road length information for a specified country and region.

```python
from scripts.process import load_data

country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Joins population_tiles.shp with road_lengths_by_region.csv
data = load_data(country)

# Output: data/processed/MEX/all_data.shp
# Combined attributes: iso3, id_upper, id_lower, population, area_km2,
#                      pop_km2, motorway, primary, secondary, tertiary, trunk, total
```

--------------------------------

### generate_grid

Source: https://context7.com/edwardoughton/backcast/llms.txt

Creates a spatial grid of a specified cell size covering a country boundary.

```APIDOC
## generate_grid

### Description
Creates a spatial grid of specified cell size covering the country boundary.

### Parameters
#### Request Body
- **iso3** (string) - Required - ISO 3-letter country code
- **side_length** (integer) - Required - Grid cell size in meters

### Response
- **grid** (object) - Spatial grid object saved to data/processed/{iso3}/grid/grid_{side_length}_{side_length}_km.shp
```

--------------------------------

### load_data

Source: https://context7.com/edwardoughton/backcast/llms.txt

Merges population tile data with road network metrics to create the comprehensive analysis dataset.

```APIDOC
## load_data

### Description
Joins population_tiles.shp with road_lengths_by_region.csv to create a comprehensive analysis dataset.

### Parameters
#### Request Body
- **country** (object) - Required - Dictionary containing 'iso3' and 'gid_region'

### Response
- **data** (object) - Combined dataset saved to data/processed/{iso3}/all_data.shp
```

--------------------------------

### Aggregate Backcast Results

Source: https://context7.com/edwardoughton/backcast/llms.txt

Combines results from all radio technologies (GSM, UMTS, LTE) into a single output CSV file. Merges individual technology deployment records.

```python
from scripts.process import aggregate_results

country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Merges gsm.csv, umts.csv, lte.csv
aggregate_results(country)

# Output: results/MEX/results.csv
# Contains all deployment records across all technologies
```

--------------------------------

### export_road_network_metrics

Source: https://context7.com/edwardoughton/backcast/llms.txt

Calculates road length metrics per grid tile for investment attractiveness modeling.

```APIDOC
## export_road_network_metrics

### Description
Aggregates road lengths by type for each tile to support investment modeling.

### Parameters
#### Request Body
- **country** (object) - Required - Dictionary containing 'iso3' and 'gid_region'
- **side_length_lower** (integer) - Required - Grid cell size in meters

### Response
- **output** (file) - Saved to data/processed/{iso3}/infrastructure/road_lengths_by_region.csv
```

--------------------------------

### spending_proportion

Source: https://context7.com/edwardoughton/backcast/llms.txt

Returns the spending allocation percentage between technologies based on year.

```APIDOC
## spending_proportion

### Description
Returns the spending allocation percentage for a given year to model transition periods.

### Parameters
#### Request Body
- **year** (integer) - Required - The year to query

### Response
- **percentage** (integer) - Spending allocation percentage
```

--------------------------------

### Export Road Network Metrics

Source: https://context7.com/edwardoughton/backcast/llms.txt

Calculates road length metrics per grid tile for investment attractiveness modeling. Aggregates road lengths by type for each tile within a specified region and grid size.

```python
from scripts.grid import export_road_network_metrics

country = {'iso3': 'MEX', 'gid_region': 2}
side_length_lower = 10000

# Aggregates road lengths by type for each tile
export_road_network_metrics(country, side_length_lower)

# Output: data/processed/MEX/infrastructure/road_lengths_by_region.csv
# Columns: iso3, id_lower, motorway, primary, secondary, tertiary, trunk, total

# Sample output:
# iso3,id_lower,motorway,primary,secondary,tertiary,trunk,total
# MEX,-99.5_19.25,12.5,8.3,15.2,22.1,5.0,63.1
```

--------------------------------

### aggregate_results

Source: https://context7.com/edwardoughton/backcast/llms.txt

Combines results from all radio technologies into a single output file.

```APIDOC
## aggregate_results

### Description
Merges individual radio technology deployment records into a single results file.

### Parameters
#### Request Body
- **country** (object) - Required - Dictionary containing 'iso3' and 'gid_region'

### Response
- **output** (file) - Saved to results/{iso3}/results.csv
```

--------------------------------

### Create National Sites CSV

Source: https://context7.com/edwardoughton/backcast/llms.txt

Extracts cell tower data for a specific country from the global OpenCellID dataset, filtering by Mobile Country Code (MCC). Outputs a CSV file containing radio, mcc, net, area, cell, unit, lon, and lat.

```python
from scripts.preprocess import create_national_sites_csv

country = {
    'iso3': 'MEX',
    'gid_region': 2,
}

# Creates MEX.csv in data/processed/MEX/sites/
# Columns: radio, mcc, net, area, cell, lon, lat
create_national_sites_csv(country)

# Sample output (data/processed/MEX/sites/MEX.csv):
# radio,mcc,net,area,cell,lon,lat
# LTE,334,20,1234,56789,-99.1234,19.4321
# UMTS,334,20,1234,56790,-99.1235,19.4322
# GSM,334,20,1234,56791,-99.1236,19.4323
```

--------------------------------

### generate_tile_population

Source: https://context7.com/edwardoughton/backcast/llms.txt

Generates population estimates at the grid tile level for detailed spatial analysis.

```APIDOC
## generate_tile_population

### Description
Generates population estimates at the grid tile level for detailed spatial analysis.

### Parameters
#### Request Body
- **country** (dict) - Required - Configuration object containing 'iso3' (string) and 'regional_level' (int).
```

--------------------------------

### process_country_shapes

Source: https://context7.com/edwardoughton/backcast/llms.txt

Creates a simplified national boundary shapefile from GADM administrative data, with small island removal for cleaner geometries.

```APIDOC
## process_country_shapes

### Description
Creates a simplified national boundary shapefile from GADM administrative data, with small island removal for cleaner geometries.

### Parameters
#### Request Body
- **iso3** (string) - Required - The ISO3 country code.
```

--------------------------------

### generate_population

Source: https://context7.com/edwardoughton/backcast/llms.txt

Calculates population statistics for each administrative region using zonal statistics on settlement raster data.

```APIDOC
## generate_population

### Description
Calculates population statistics for each administrative region using zonal statistics on settlement raster data.

### Parameters
#### Request Body
- **country** (dict) - Required - Configuration object containing 'iso3' (string) and 'regional_level' (int).
```

--------------------------------

### Generate Tile Population

Source: https://context7.com/edwardoughton/backcast/llms.txt

Generates population estimates at the grid tile level for detailed spatial analysis. This function creates a shapefile containing per-tile population statistics.

```python
from scripts.pop import generate_tile_population

country = {
    'iso3': 'MEX',
    'regional_level': 2,
}

# Creates population shapefile with per-tile statistics
generate_tile_population(country)
```

--------------------------------

### create_national_sites_csv

Source: https://context7.com/edwardoughton/backcast/llms.txt

Extracts cell tower data for a specific country from the global OpenCellID dataset, filtering by Mobile Country Code (MCC).

```APIDOC
## create_national_sites_csv

### Description
Extracts cell tower data for a specific country from the global OpenCellID dataset, filtering by Mobile Country Code (MCC).

### Parameters
#### Request Body
- **country** (dict) - Required - Configuration object containing 'iso3' (string) and 'gid_region' (int).
```

--------------------------------

### Generate Population Statistics per Region

Source: https://context7.com/edwardoughton/backcast/llms.txt

Calculates population statistics for each administrative region using zonal statistics on settlement raster data. Extracts population sum, area in km2, and population density per km2 for each region.

```python
from scripts.pop import generate_population

country = {
    'iso3': 'MEX',
    'regional_level': 2,
}

# Extracts population sum per region from settlements.tif
generate_population(country)

# Output: data/processed/MEX/population/population.csv
# Columns: GID_0, GID_id, GID_level, population, area_km2, population_km2

# Sample output:
GID_0,GID_id,GID_level,population,area_km2,population_km2
MEX,MEX.1.1_1,GID_2,1500000,2500,600.0
MEX,MEX.1.2_1,GID_2,500000,3200,156.25
```

--------------------------------

### process_regions

Source: https://context7.com/edwardoughton/backcast/llms.txt

Processes subnational administrative boundaries at specified regional levels (GID_1 or GID_2).

```APIDOC
## process_regions

### Description
Processes subnational administrative boundaries at specified regional levels (GID_1 or GID_2).

### Parameters
#### Request Body
- **iso3** (string) - Required - The ISO3 country code.
- **level** (int) - Required - The administrative level to process.
```

--------------------------------

### Process Regions

Source: https://context7.com/edwardoughton/backcast/llms.txt

Processes subnational administrative boundaries at specified regional levels (GID_1 or GID_2). Creates simplified region shapefiles with a tolerance of 0.005 degrees. Outputs shapefiles for state and municipality levels.

```python
from scripts.preprocess import process_regions

iso3 = 'MEX'
level = 2  # Process both GID_1 and GID_2 levels

# Creates region shapefiles with simplified geometries
# Tolerance: 0.005 degrees
process_regions(iso3, level)

# Output files:
# - data/processed/MEX/regions/regions_1_MEX.shp (state level)
# - data/processed/MEX/regions/regions_2_MEX.shp (municipality level)
```

--------------------------------

### Process Country Shapes

Source: https://context7.com/edwardoughton/backcast/llms.txt

Creates a simplified national boundary shapefile from GADM administrative data. It removes small island geometries using a specified tolerance and area thresholds. Outputs a national outline shapefile.

```python
from scripts.preprocess import process_country_shapes

iso3 = 'MEX'

# Reads gadm36_0.shp and creates simplified national_outline.shp
# Tolerance: 0.01 degrees
# Removes small multipolygon shapes based on area thresholds
process_country_shapes(iso3)

# Output: data/processed/MEX/national_outline.shp
# Contains merged country info from countries.csv
```

--------------------------------

### Export Specific Road Network

Source: https://context7.com/edwardoughton/backcast/llms.txt

Extracts and filters major road network segments from OpenStreetMap data for a given country. Filters by functional class including motorway, primary, secondary, tertiary, and trunk.

```python
from scripts.grid import export_specific_road_network

iso3 = 'MEX'

# Filters roads by functional class:
# motorway, primary, secondary, tertiary, trunk
export_specific_road_network(iso3)

# Output: data/processed/MEX/infrastructure/road_network_processed.shp
# Attributes: osm_id, fclass, maxspeed
```

--------------------------------

### export_specific_road_network

Source: https://context7.com/edwardoughton/backcast/llms.txt

Extracts and filters major road network segments from OpenStreetMap data.

```APIDOC
## export_specific_road_network

### Description
Extracts and filters major road network segments (motorway, primary, secondary, tertiary, trunk) from OpenStreetMap data.

### Parameters
#### Request Body
- **iso3** (string) - Required - ISO 3-letter country code

### Response
- **output** (file) - Saved to data/processed/{iso3}/infrastructure/road_network_processed.shp
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.