heiplanet_data.population module

heiplanet_data.population

Population-derived quantities on regular latitude-longitude grids.

This module turns population counts per grid cell (e.g. ISIMIP total-population) into population density:

• grid-cell area in km^2 computed from the grid coordinates, assuming a spherical Earth as CDO's gridarea operator does (calculate_grid_cell_area),
• grid-cell area loaded from a precomputed NetCDF file (load_grid_cell_area),
• population density as count divided by cell area (calculate_population_density).

Functions:

• calculate_grid_cell_area –

  Calculate the area of each grid cell of a regular lat-lon grid in km^2.

• calculate_population_density –

  Add population density (persons per km^2) for population count variables.

• load_grid_cell_area –

  Load grid-cell areas in km^2 from a NetCDF file and match them to a dataset.

Attributes:

• DENSITY_SUFFIX –
• EARTH_RADIUS_KM –

DENSITY_SUFFIX module-attribute

DENSITY_SUFFIX = '-density'

EARTH_RADIUS_KM module-attribute

EARTH_RADIUS_KM = 6371.0

calculate_grid_cell_area

calculate_grid_cell_area(dataset, lat_name='latitude', lon_name='longitude', radius_km=EARTH_RADIUS_KM)

Calculate the area of each grid cell of a regular lat-lon grid in km^2.

Coordinates are taken as cell centers. The area of a cell between latitudes phi1 and phi2 and with longitude width dlambda (radians) is R^2 * dlambda * (sin(phi2) - sin(phi1)). Cell edges are clipped to +-90 degrees.

Parameters:

• dataset (Dataset) –

  Dataset providing the grid coordinates.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• radius_km (float, default: EARTH_RADIUS_KM ) –

  Earth radius in km. Default is 6371.0 (as in CDO).

Returns:

• DataArray –

  xr.DataArray: Cell area in km^2 with dimensions (lat_name, lon_name).

calculate_population_density

calculate_population_density(dataset, var_names, area)

Add population density (persons per km^2) for population count variables.

For each count variable <name> a new variable <name>-density = count / cell area is added; the counts are kept. Cells without data (e.g. ocean) stay NaN.

Parameters:

• dataset (Dataset) –

  Dataset with population counts per grid cell.

• var_names (list[str]) –

  Names of the population count variables.

• area (DataArray) –

  Cell area in km^2 on the dataset's grid, e.g. from calculate_grid_cell_area.

Returns:

• Dataset –

  xr.Dataset: Dataset with the added density variables.

load_grid_cell_area

load_grid_cell_area(area_file, dataset, lat_name='latitude', lon_name='longitude', var_name='cell_area')

Load grid-cell areas in km^2 from a NetCDF file and match them to a dataset.

The file may use lat/lon or the dataset's coordinate names. Its grid must match the dataset's grid; areas in m2 are converted to km2.

Parameters:

• area_file (Path | str) –

  Path to the NetCDF file with cell areas.

• dataset (Dataset) –

  Dataset whose grid the areas must match.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate in the dataset. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate in the dataset. Default is "longitude".

• var_name (str, default: 'cell_area' ) –

  Name of the area variable in the file. Default is "cell_area".

Returns:

• DataArray –

  xr.DataArray: Cell area in km^2 on the dataset's coordinates.