Commit 2a930442 authored by Cecilia Nievas's avatar Cecilia Nievas
Browse files

Finished docs on creation of data-unit tiles

parent f046c991
Pipeline #40451 passed with stage
in 2 minutes and 2 seconds
......@@ -149,6 +149,12 @@ occupancy cases of the same exposure entity use data units that refer to the exa
geographic areas, which leads to data-unit tiles that refer to the exact same geographic areas
as well, these are still treated as separate data-unit tiles by the `gde-importer`.
As shown in Fig. 2.4, data-unit tiles are an attribute of the [DataUnit](#data-unit) class,
named `data_unit_tiles`. This is a
[pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) object
in which each row corresponds to a data-unit tile (see [here](07_Creation_Data_Unit_Tiles.md))
for further details.
<img src="images/data_unit_tiles.png" width=75%>
Fig. 2.4 Illustrative example of the definition of `data-unit tiles`.
......@@ -18,12 +18,13 @@ parallel, by calling the `define_data_unit_tiles_and_attributes` method of the
## Geometry and Quadkey of Data-Unit Tiles
The first step carried out by the `define_data_unit_tiles_and_attributes` method consists in
identifying the quadkeys and geometries of the zoom level 18 tiles that contain the geometry of
the data unit, for which the [mercantile](https://github.com/mapbox/mercantile) library is
used by the `DataUnitTilesHelper.get_data_unit_tiles` method. These quadtiles are then
intersected with the geometry of the data unit, so that the tiles that are crossed by the
boundary get trimmed accordingly.
The first step carried out by the `DataUnitTilesHelper.define_data_unit_tiles_and_attributes`
method consists in identifying the quadkeys and geometries of the zoom level 18 tiles that
contain the geometry of the data unit, for which the
[mercantile](https://github.com/mapbox/mercantile) library is used by the
`DataUnitTilesHelper.get_data_unit_tiles` method. These quadtiles are then intersected with the
geometry of the data unit, so that the tiles that are crossed by the boundary get trimmed
accordingly.
## Surface Area of Data-Unit Tiles
......@@ -31,18 +32,99 @@ Comparing the areas of the original quadtiles and the data-unit tiles (i.e. the
"trimmed" as per the boundaries of the data unit) allows to define which tiles are fully
contained in the data unit and which are not. This distinction allows to save considerable
computational time by calculating the area of fully-contained tiles using an approximate
formula for the fully-contained tiles and the Albers equal area projection only for the tiles
that are intersected by boundaries.
formula and the Albers equal area projection only for the tiles that are intersected by
boundaries.
For the fully-contained tiles, the area is calculated using the
`SpatialTools.get_area_on_sphere` method, which returns the area of a rectangle on Earth
calculated assuming the Earth is a sphere with default radius 6,371,000 m as per Eq. (1) of
Kelly and Šavrič (2021). When used to calculate the area of zoom level 18 quadtiles, this
approximate function yields area values that differ in less than 1% with respect to those
calculated using the Albers equal area projection.
calculated using the Albers equal area projection, as depicted in Fig. 7.1 below.
<img src="images/areas_sphere_vs_Albers.png" width=75%>
Fig. 7.1 Ratio of surface areas of zoom level 18 tiles calculated using the spherical
approximation to those calculated using the more precise Albers equal area projection, as a
function of longitude and latitude.
The difference in computation time has been benchmarked by computing the time that it takes to
calculate the areas of 2,376 tiles spread across the globe with each approach (spherical
approximation, Albers equal area projection) and using the
[timeit](https://docs.python.org/3/library/timeit.html) Python library. The conclusion from
this small test was that using the Albers equal area approach took 7 to 8 times longer than
with the spherical approximation (in the way they are implemented in `gde-importer` at least).
The surface areas of the data-unit tiles are written to the `size_data_unit_tile_area` column
of the `data_unit_tiles` attribute of the corresponding
[DataUnit](02_Organisation_Geographic_Space.md#data-unit) class.
## Built-Up Area of Data-Unit Tiles
The `DataUnitTilesHelper.retrieve_built_up_area` method is used to retrieve the built-up area
associated with the quadkeys of the data-unit tiles from the
[OBM Tiles database](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmtiles).
This function looks for this information in the database whose credentials are specified by the
user under `database_built_up` in the [configuration file](04_Configuration.md). The
`gde-importer` assumes that this database contains a table named
[obm_built_area_assessments](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmtiles#obm_built_area_assessments-completeness-assessments-information).
The `sourceid` needs to be specified as a nested parameter of `database_built_up`. In the
current version of `obm_built_area_assessments`, `source_id=1` corresponds to the built-up area
retrieved by [obmgapanalysis](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/obmgapanalysis)
from the [Global Human Settlement Layer (GHSL) built-up area layer with multi-temporal
analysis and global coverage](https://git.gfz-potsdam.de/dynamicexposure/datasources/-/tree/master/GHS_BUILT_LDSMT_GLOBE_R2018A),
as explained [here](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/database-obmtiles/-/blob/master/docs/01_obm_built_area_assessments.md).
`DataUnitTilesHelper.retrieve_built_up_area` searches for the quadkey of the data-unit tile and
the `source_id`. If an entry matching these two parameters is not found, the built-up area is
zero, as this is an assumption of the workings of
[obmgapanalysis](https://git.gfz-potsdam.de/dynamicexposure/openbuildingmap/obmgapanalysis)
(tiles for which the built-up area is zero are not stored). If more than one entries are found,
the built-up area is assigned a value of
[numpy.nan](https://numpy.org/doc/stable/reference/constants.html#numpy.nan), as more than one
entry for the same combination of quadkey and `source_id` should not exist.
As the `obm_built_area_assessments` table contains the built-up area associated with a full
tile, `DataUnitTilesHelper.define_data_unit_tiles_and_attributes` multiplies these values by
the ratio of surface area of the data-unit tile to that of the whole tile to obtain the
built-up area associated with the data-unit tile. This is equivalent to assuming that the
built-up area of the zoom level 18 tile is uniformly distributed within it.
The built-up areas of the data-unit tiles are written to the
`size_data_unit_tile_built_up_area` column of the `data_unit_tiles` attribute of the
corresponding [DataUnit](02_Organisation_Geographic_Space.md#data-unit) class.
## Weight of Data-Unit Tiles
Once surface areas and built-up areas have been calculated/retrieved for all data-unit tiles in
the data unit, the ratios of the values of an individual data-unit tile to the summation of
values from all data-unit tiles are calculated. These become the columns
`fraction_data_unit_area` and `fraction_data_unit_built_up_area` of the `data_unit_tiles`
attribute of the corresponding [DataUnit](02_Organisation_Geographic_Space.md#data-unit) class.
Values of `fraction_data_unit_area` are greater than zero (cannot be equal) and smaller than or
equal to one. They can only be one if a data unit is composed of just one data-unit tile.
Values of `fraction_data_unit_built_up_area` are greater than or equal to zero (a tile can have
no built-up area at all), and smaller than or equal to one.
By definition, these columns add up to unity for any particular data unit, except in the case
in whicht he summation of built-up areas from all data-unit tiles in the data unit is equal to
zero. This is feasible, because data units can be any geographic entity and may cover areas
without any detectable built-up area. In this case, all values of
`fraction_data_unit_built_up_area` are equal to [numpy.nan](https://numpy.org/doc/stable/reference/constants.html#numpy.nan).
## Number of Aggregated Buildings in the Data-Unit Tiles
When values of `fraction_data_unit_built_up_area` are not equal to `numpy.nan`, the number of
aggregated buildings assigned to each data-unit tile is calculated as the product between the
total number of buildings (from the aggregated exposure model) in the data unit and
`fraction_data_unit_built_up_area`. If the values of `fraction_data_unit_built_up_area` are
equal to `numpy.nan`, the values of `fraction_data_unit_area` are used instead. This means
that the number of buildings of the data unit is distributed onto the data-unit tiles
proportionally to the estimated built-up area of each of the data-unit tiles, where possible,
and proportionally to the surface area of the data-unit tiles, where not.
The number of buildings assigned to the data-unit tiles are written to the
`aggregated_buildings` column of the `data_unit_tiles` attribute of the corresponding
[DataUnit](02_Organisation_Geographic_Space.md#data-unit) class. By definition, this column
adds up to the total number of buildings (from the aggregated exposure model) in the data unit.
......@@ -11,8 +11,9 @@ Assessment of Global Earthquakes for Response (PAGER) System. In: Proceedings of
10th Canadian Conference on Earthquake Engineering: Reaching Beyond Borders, July 25-29,
Toronto, Canada.
Kelly K, Šavrič B (2021). Area and volume computation of longitude–latitude grids and three-
dimensional meshes. Transactions in GIS 25(1):6–24.
Kelly K, Šavrič B (2021). Area and volume computation of longitude-latitude grids and
three-dimensional meshes. Transactions in GIS 25(1):6–24.
[DOI: 10.1111/tgis.12636](https://doi.org/10.1111/tgis.12636)
Sousa L, Silva V, Bazzurro P (2017). Using open-access data in the development of exposure data
sets of industrial buildings for earthquake risk modeling. Earthquake Spectra 33(1):63-84.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment