pcxarray.utils module

pcxarray.utils.create_grid(polygon: Polygon, crs: CRS | str | int = 4326, cell_size: int = 1000, enable_progress_bar: bool = False, clip_to_polygon: bool = True) → GeoDataFrame

Generate a regular grid of square polygons covering a given input polygon.

The grid is aligned to the bounding box of the input polygon and consists of square cells of the specified size. Optionally, only grid cells that intersect the input polygon are retained, and the cells can be clipped to the polygon boundary.

Parameters:

  • polygon (shapely.geometry.Polygon) – The input polygon to cover with a grid.

  • crs (pyproj.CRS, str or int, default=4326) – The coordinate reference system for the output GeoDataFrame.

  • cell_size (int, default=1000) – The size of each grid cell along each side in the units of the CRS.

  • enable_progress_bar (bool, default=False) – Whether to display progress bars during grid creation and filtering.

  • clip_to_polygon (bool, default=True) – If True, grid cells will be clipped to the input polygon boundary.

Returns:

GeoDataFrame containing the grid polygons, optionally clipped to the input polygon.

Return type:

geopandas.GeoDataFrame

pcxarray.utils.load_census_shapefile(level: Literal['state', 'county', 'zcta'] = 'state', verify: bool = True) → GeoDataFrame

Download and load a US Census TIGER shapefile for states, counties, or ZIP Code Tabulation Areas (ZCTA).

The shapefile is downloaded from the US Census Bureau TIGER/Line website, extracted, and loaded as a GeoDataFrame. The function is cached to avoid repeated downloads.

Parameters:

  • level ({'state', 'county', 'zcta'}, default='state') – Which shapefile to download. Options are: - ‘state’: US state boundaries - ‘county’: US county boundaries - ‘zcta’: ZIP Code Tabulation Areas

  • verify (bool, default=True) – Whether to verify the downloaded file’s SSL certificate. Do not set to False in production code.

Returns:

The loaded shapefile as a GeoDataFrame with geometries in WGS84 (EPSG:4326).

Return type:

geopandas.GeoDataFrame

Raises:

  • ValueError – If the level argument is not one of the allowed values.

  • requests.HTTPError – If the download fails due to network or server issues.

  • zipfile.BadZipFile – If the downloaded file is not a valid ZIP archive.

  • AssertionError – If the archive does not contain exactly one .shp file.