readers#

Low-level data-access functions for admin units and entities. Imported by internal modules (io/, geo/). Also re-exported from api.py.

Functions#

get_admin([admin_id, level, recipe, geom, columns, ...])

Get admin units of any administrative level

get_admin_ids(admin_level[, admin_id, admin_recipe])

Get list of administrative unit IDs

get_entities(recipe[, admin_id, geom, layer, ...])

Load and combine processed Parquet tables for entities.

get_dataset(recipe[, admin_id, partition_id, geom])

Load a processed dataset by recipe.

Module Contents#

openplaces.io.readers.get_admin(admin_id=None, level=None, recipe=None, geom=False, columns=None, all_columns=False, silent=True)#

Get admin units of any administrative level

Parameters:

  • admin_id (str, list, or openplaces.core.schema.AdminId) – Identifier(s) of admin units to return. Can include higher-level Admin IDs to select many lower levels

  • level (int) – Admin level for which to return units. If none, use level of admin_id (deepest if a list is passed).

  • recipe (str) – Use this recipe to import geometries and additional attributes.

  • geom (bool or 'simplified') – If False or None, return DataFrame without geometries. If True, return GeoDataFrame with geometries.

  • columns (list of str or None) – If a list of strings, will be used to select columns.

  • all_columns (bool) – If True, returns not only the most important columns

  • silent (True) – Silence warnings

  • geom – If False, return a DataFrame without geometries. If True, return a GeoDataFrame with full geometries. If 'simplified', return a GeoDataFrame with simplified geometries from the _geo_simplified companion file written by AdminHarmonizer.

openplaces.io.readers.get_admin_ids(admin_level, admin_id=None, admin_recipe=None)#

Get list of administrative unit IDs

openplaces.io.readers.get_entities(recipe, admin_id=None, geom=False, layer=None, partition_id=None, columns: collections.abc.Sequence[str] | None = None, missing='raise')#

Load and combine processed Parquet tables for entities.

Parent administrative IDs are expanded to the recipe’s save level. Recipes aggregated to a single file read their _all output by default.

Parameters:

  • recipe (str or dict) – Recipe that defines the entity.

  • admin_id (str, AdminId, or sequence) – Administrative unit(s) to load. Defaults to the recipe admin ID.

  • geom (bool) – If True, include geometries and return a GeoDataFrame.

  • layer (str, optional) – Secondary layer defined in additional_layers.

  • partition_id (str, optional) – Explicit partition value to read.

  • columns (sequence of str, optional) – Columns to read.

  • missing ({'raise', 'warn', 'ignore'}) – How to handle missing output files.

openplaces.io.readers.get_dataset(recipe, admin_id=None, partition_id=None, geom=False)#

Load a processed dataset by recipe.

Handles both raster and tabular dataset recipes. For raster datasets (Cloud Optimized GeoTIFFs written by fetch_rasters_by_admin), returns the path to the .tif file so the caller controls resource management (e.g. with rasterio or xarray). For tabular datasets, returns a DataFrame or GeoDataFrame exactly as get_entities does.

Parameters:

  • recipe (str or dict) – Recipe that defines the dataset. Can be a loaded recipe (dict) or a string recipe ID.

  • admin_id (str or AdminId, optional) – Administrative unit for which to load the data. If None, uses the admin_id from the recipe.

  • partition_id (str, optional) – Partition value to locate a specific partition file, e.g. ‘2020’ for a year-partitioned recipe. Pass None (default) for recipes without partitioning.

  • geom (bool) – If True, include geometries and return a GeoDataFrame. Ignored for raster datasets.

Returns:

  • Path – Path to the .tif file, for raster datasets.

  • pandas.DataFrame or geopandas.GeoDataFrame – Loaded tabular data, for non-raster datasets.

Raises:

ValueError – If the recipe does not have a ‘dataset’ key. Use get_entities for entity recipes.