Utilities

emiproc.utilities.get_country_mask(
output_grid: Grid | GeoSeries,
resolution: str = '110m',
weight_filepath: PathLike | None = None,
return_fractions: bool = False,
) → ndarray | DataArray

Determine the country-code for each gridcell and return the grid.

Each gridcell gets assigned to code of the country with the most area in the cell.

If for a given grid cell, no country is found (Ocean for example), the country-code ‘-99’ is assigned.

Parameters:

  • output_grid – Contains all necessary information about the output grid. Can be a Grid object or a GeoSeries with a custom geometry.

  • resolution – The resolution for the used shapefile, used as argument for get_natural_earth()

  • return_fractions – In case you want to know the fraction of each country in each grid cell, instead of just the main country, set this to True. If True, this will return a xarray.DataArray with the fraction of each country. If False (default), this will return a numpy array with the main country code.

Returns:

Gridded data with the country identifier of each country (eg. BUR). Array of 3 char strings of the shape of the grid.

emiproc.utilities.get_natural_earth(
resolution: str = '10m',
category: str = 'physical',
name: str = 'coastline',
) → GeoDataFrame

Download the natural earth file and returns it.

For more information about the natural earth data, see the natural earth website.

As this function reads a large dataset, it caches it in case of many uses (ex: testing).

Parameters:

  • resolution – The resolution for the used shapefile. Available resolutions are: ‘10m’, ‘50m’, ‘110m’

  • category – The category of the shapefile. Available categories are: ‘physical’, ‘cultural’, ‘raster’

  • name – The name of the shapefile. Category of the data to download. Many are availables, look at the natural earth website for more info.

Returns:

The shapefile as a GeoDataFrame

emiproc.utilities.get_timezone_mask(output_grid: Grid, **kwargs) → ndarray

Determine the timezone for each gridcell and return the grid.

This function calls get_timezones() to get the timezones shapefile. Any keyword arguments will be passed to that function.

Each gridcell gets assigned to the timezone with the most area in the cell.

If for a given grid cell, no timezone is found, the timezone UTC is assigned, but the dataset should in theory cover the whole world.

Parameters:

output_grid – Grid object on which to calculate the timezones.

Returns:

Gridded data with the timezone of each gridcell as an array of string with the shape of the grid.

emiproc.utilities.get_timezones(
update: bool = False,
version: str | None = None,
simplify_tolerance: float = 100,
) → GeoDataFrame

Load the timezones shapefile.

If the file is not found, it will be downloaded from the github repository timezone-boundary-builder and saved in the files/timezones directory of emiproc.

Parameters:

  • update – Download the latest version of the file.

  • simplify_tolerance – The tolerance for simplifying the timezones shapes. This is used to speed up the calculation and io processes. The unit is meters, as we use a projected crs. See geopandas.GeoSeries.simplify for more information. Set this to 0 or False to disable simplification.

  • version – The version to download. If not given, the latest version will be downloaded. The version correspond to the name of a release (eg: 2023b)

Returns:

The timezones with the shape of each zone.

Emissions Informations

class emiproc.inventories.EmissionInfo

Information about an emission category.

This additional information is used for some models. It concerns only the Inventory.gdfs features.

Parameters:

  • height – The height of the emission source (over the ground). [m]

  • height_over_buildings – If True, the height is taken over buildings.

  • width – The width of the emission source. [m]

  • vertical_extension – The vertical extension (thickness) of the emission source. [m] This implies that the emission starts at height and ends at height + vertical_extension.

  • temperature – The temperature of the emission source. [K]

  • speed – The speed of the emission of the substances. [m/s]

  • comment – A comment about the emission source.

__init__(
height: float = 0.0,
height_over_buildings: bool = True,
width: float = 0.5,
vertical_extension: float = 3.0,
temperature: float = 353.0,
speed: float = 5.0,
comment: str = '',
) → None
classmethod __new__(*args, **kwargs)