main.jl (4892B)
1 # ABOUTME: Main user-facing tigerdownload function and geography type registry 2 # ABOUTME: Validates inputs, creates geography instances, and dispatches to download methods 3 4 # -------------------------------------------------------------------------------------------------- 5 const GEOGRAPHY_TYPES = Dict( 6 "state" => State, 7 "county" => County, 8 "zipcode" => ZipCode, 9 "urbanarea" => UrbanArea, 10 "primaryroads" => PrimaryRoads, 11 "cbsa" => CBSA, 12 "csa" => CSA, 13 "metrodivision" => METDIV, 14 "rails" => Rails, 15 16 "cousub" => CountySubdivision, 17 "tract" => Tract, 18 "place" => Place, 19 "consolidatedcity" => ConCity, 20 "primarysecondaryroads" => PrimarySecondaryRoads, 21 22 "areawater" => AreaWater, 23 "linearwater" => LinearWater, 24 "road" => Roads, 25 26 ) 27 # -------------------------------------------------------------------------------------------------- 28 29 30 # -------------------------------------------------------------------------------------------------- 31 """ 32 tigerdownload(type::String, year::Int=2024; 33 state::String="", county::String="", 34 output::String=pwd(), force::Bool=false, 35 verbose::Bool=false) 36 37 Download TIGER/Line shapefiles from the U.S. Census Bureau. 38 39 # Arguments 40 - `type::String`: Geography type. Available options: $(join(keys(GEOGRAPHY_TYPES), ", ")). 41 - `year::Int=2024`: Data year. Census typically provides shapefiles from 2000 onward. 42 43 # Keyword Arguments 44 - `state::String=""`: State identifier (name, abbreviation, or FIPS code). 45 - `county::String=""`: County identifier (name or FIPS code). Requires `state` to be specified. 46 - `output::String=pwd()`: Directory where shapefiles will be saved. 47 - `force::Bool=false`: If `true`, redownload files even if they already exist. 48 - `verbose::Bool=false`: If `true`, display more detailed progress information. 49 50 # Returns 51 - `Vector{String}`: Paths to downloaded files. 52 53 # Examples 54 ```julia 55 # Download state boundaries for the entire USA 56 tigerdownload("state") 57 58 # Download county subdivisions for California 59 tigerdownload("cousub", state="CA") 60 61 # Download census tracts for Los Angeles County, California 62 tigerdownload("tract", state="California", county="Los Angeles") 63 64 # Download with custom output directory and force redownload 65 tigerdownload("county", output="/path/to/data", force=true) 66 ``` 67 68 # Notes 69 - Geography types follow a hierarchy: national-level (state, county), state-level (cousub, place), 70 and county-level (tract, areawater). 71 - For national-level geographies, the `state` and `county` arguments are ignored. 72 - For state-level geographies, the `county` argument is ignored. 73 - For county-level geographies, both `state` and `county` are used when provided. 74 - If no state is specified when downloading state or county-level geographies, all states will be downloaded. 75 - TIGER/Line shapefiles are downloaded as ZIP archives containing multiple files (.shp, .dbf, .prj, etc.). 76 77 # See Also 78 - [Census TIGER/Line Documentation](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html) 79 """ 80 function tigerdownload( 81 type::String, year::Int=2024; 82 state::String="", 83 county::String="", 84 output::String=pwd(), 85 force::Bool=false, 86 verbose::Bool=false) 87 88 type_lower = lowercase(type) 89 if !haskey(GEOGRAPHY_TYPES, type_lower) 90 throw(ArgumentError("Invalid type. Choose from: $(join(keys(GEOGRAPHY_TYPES), ", "))")) 91 end 92 93 # Get the type and create instance 94 geo_type = GEOGRAPHY_TYPES[type_lower] 95 geo = geo_type(year) # No need to pass scope anymore, it's inherent in the type 96 97 # Dispatch based on the type's hierarchy 98 if geo isa NationalGeography 99 if !isempty(state) || !isempty(county) 100 @warn "State/county options ignored for national-level data" 101 end 102 download_shapefile(geo; output_dir=output, force=force) 103 104 elseif geo isa StateGeography 105 if !isempty(county) 106 @warn "County option ignored for state-level data" 107 end 108 if isempty(state) 109 @warn "No state specified - downloading all states" 110 end 111 state_arg = isempty(state) ? nothing : state 112 download_shapefile(geo; state=state_arg, output_dir=output, force=force) 113 114 elseif geo isa CountyGeography 115 if isempty(state) 116 @warn "No state specified - downloading all states" 117 end 118 if !isempty(county) && isempty(state) 119 throw(ArgumentError("--county option requires --state to be specified")) 120 end 121 state_arg = isempty(state) ? nothing : state 122 county_arg = isempty(county) ? nothing : county 123 download_shapefile(geo; state=state_arg, county=county_arg, output_dir=output, 124 force=force, verbose=verbose) 125 end 126 end 127 # --------------------------------------------------------------------------------------------------