Land Use Allocation module - GLOBIO4/GlobioModelPublic GitHub Wiki
Introduction
Land-use is an important input parameter of GLOBIO. At this moment a global high-resolution discrete land-use map is not available. This is why a module is developed which is capable of downscaling (or spatially allocating) low-resolution land-use data (regional totals or 'claims') to a global high-resolution discrete land-use map that is compatible with the GLOBIO 4 model environment.
The allocation routine is able to work with user-defined land-use classes and corresponding regional totals, i.e. 'claims', expressed in surface area per region per land-use class. The regional totals of each land-use class is spatially allocated based on an overall 'suitability layer' for that class. This layer is derived from a set of environmental characteristics that influence the likelihood that the land-use class of concern will be located in that grid cell. Relevant environmental covariates may include land-cover, proximity of roads, elevation, slope, and soil type.
The Discrete Land-use Allocation module is implemented as a pre-processing module of GLOBIO 4 and can be run in the GLOBIO 4 framework.
Land-use types
The Land-use Allocation module is developed to be highly flexible regarding to the input it needs. During the development process the following land-use types were used.
Code Type
------ ----------------------
1 Urban
2 Crop
3 Pasture
4 Forestry
5 Secondary vegetation
6 Undefined
Which land-use types to use can be specified in the configuration file of the module.
Input datasets
The Land-use Allocation module uses the following input datasets.
Type Description
--------------------------------- -----------------------------------------------------------
Regions Raster with regions.
Land-cover Raster with land-cover.
Land-use Raster with land-use.
Not-allocatable areas Raster with areas which can not be allocated.
Reduce factor of protected area Raster with the factor with which the suitability will
be reduced in protected areas.
Suitabilities Rasters with suitability for the land-use types to allocate.
Land-use claims File with the claim areas in km2 per region of the
land-use types to allocate.
Land-use claims lookup File with the translation of the land-use class in the
claim file to the land-use types.
Cell Areas Raster with the cell area in km2.
The rasters with the reduce factor of protected areas and the cell areas and the land-use claims lookup file are optional. When no cell areas raster is specified the cell areas will be calculated in the module.
In more detail the input datasets should meet the following requirements.
Type Data type and range
--------------------------------- ---------------------------------------------------------------
Regions Integer, 0 to 255
Land-cover Integer, 0 to 255
Land-use Integer, 0 to 255
Not-allocatable areas Integer, 0 = allocatable, 1 = not-allocatable
Reduce factor of protected area Floating point, 0.0 (highly protected) to 1.0 (not protected)
Suitabilities Floating point, 0.0 (not suitable) to 1.0 (highly suitable)
Cell Areas Floating point, > 0.0
The land-use claims file should be a CSV file with at least the following fields.
Type Description
---------- ------------------------
Region Region code.
Land-use Land-use code or name.
Area Claim area in km2.
Example:
IMGREGCD;AggLUClass;totalArea
1;Agriculture;528817,282901763
1;Forestry;873406,031250004
1;Grazing;140171,296874976
1;Natural Bare/Ice/Other;547819,535087822
1;Natural Forest;3971636,54983329
1;Natural Shrub/Grassland;3418831,63914383
1;Urban;6351,6719083299
2;Agriculture;1814997,31385521
2;Forestry;2051521,13279041
2;Grazing;1896179,9374999
2;Natural Bare/Ice/Other;118216,104434085
2;Natural Forest;1414061,74554685
...
When a land-use claims lookup file is specified it should be a CSV file with at least the following fields.
Type Description
---------------- ---------------------------------------------------
Land-use class The land-use class used in the claim file.
Land-use type The land-use type used in the configuration file.
Example:
LANDUSECLASS;LANDUSETYPE
Urban;urban
Agriculture;crop
Grazing;pasture
Forestry;forestry
Output datasets
The Land-use Allocation module will calculate the following output datasets.
Type Description
----------------------------------------- ---------------------------------------------------------------
Allocated land-use Raster with allocated land-use.
Areas per region Summarized cell areas per region.
Areas per region per land-cover Summarized cell areas per region per land-cover type.
Areas per region per allocated land-use Summarized cell areas per region per allocated land-use type.
Calculating the various summarized cell areas is optional.
Calculations
Calculation: GLOBIO_CalcDiscreteLanduseAllocation.py
Description
Calculates the discrete land-use allocation.
Data needs
p.m.
Outputs
p.m.
Module folder description
Directory - Calculations
The directory \Calculations contains the following files of the Land Use Allocation module:
- GLOBIO_CalcDiscreteLanduseAllocation.py
- Calculates the discrete land-use allocation.
Directory - Config
The directory \Config contains the following files of the Land Use Allocation module:
- LanduseAllocation.glo
- Defines the land-use allocation module.
Directory - LandAllocation
The directory \LandAllocation contains additional Python modules used for the Land Use Allocation module. The following Python modules are present:
- ClaimFile.py
- A class for reading land-use claim files.
- LanduseType.py
- A class for storing land-use type information.
Directory - Scripts
The directory \Scripts contains the following files of the Land Use Allocation module:
- Run_LanduseAllocation_eu.glo
- Calculates the discrete land-use allocation for Europe.
- Run_LanduseAllocation_wrld.glo
- Calculates the global discrete land-use allocation.
Running the module
After installing GLOBIO 4 (see the Installation Guide) the Land-use Allocation module can be run like any other GLOBIO 4 module using the command globio4.
Definition of the module
The Land-use Allocation module is defined in the configuration file LanduseAllocation.glo located in the Config directory. Unlike the GLOBIO 4 modules, by default this file in not already included.
Including the module in your script
To use the Land-use Allocation module in your run configuration script you must include the module by adding the following line at the beginning of your script:
INCLUDE LanduseAllocation.glo
Setting module parameters
The Land-use Allocation module is defined as follows:
CalcDiscreteLanduseAllocation(
IN EXTENT Extent,
IN CELLSIZE CellSize,
IN STRING LanduseCodes,
IN STRING LanduseNames,
IN STRING LandusePriorityCodes,
IN RASTER Landcover,
IN RASTER Regions,
IN STRING RegionFilter,
IN STRING RegionExcludeFilter,
IN RASTER Landuse,
IN STRING LanduseReplaceCodes,
IN STRING LanduseReplaceWithCode,
IN STRING LanduseUndefinedCode,
IN RASTER NotAllocatableAreas,
IN RASTER PAReduceFactor,
IN STRING SuitRasterCodes,
IN RASTERLIST SuitRasterNames,
IN FILE ClaimFileName,
IN STRING ClaimLanduseFieldName,
IN STRING ClaimRegionFieldName,
IN STRING ClaimAreaFieldName,
IN FILE ClaimLookup,
IN STRING ClaimAreaMultiplierLanduseCodes,
IN STRING ClaimAreaMultipliers,
IN RASTER CellAreas,
IN BOOLEAN AddNoiseFlag,
OUT FILE OutRegionAreasFileName,
OUT FILE OutRegionLandcoverAreasFileName,
OUT FILE OutRegionLanduseAreasFileName,
OUT RASTER OutAllocatedLanduse)
With the following parameters:
Name Description
------------------------------- ----------------------------------------------------------------------
Extent The regional extent, e.g. world.
CellSize The cellsize, e.g. 30sec.
LanduseCodes The user-defined land-use codes, e.g. 1|2|3|4|5|6.
LanduseNames The user-defined corresponding land-use names,
e.g. urban|crop|pasture|forestry|secondary vegetation|undefined.
The number of names should be equal to the number of codes.
LandusePriorityCodes The sequence in which the land-use codes are allocated, e.g. 1|2|3|4.
Not all user-defined land-use codes need to be allocated.
Landcover Name of raster with land-cover.
Regions Name of raster with regions.
RegionFilter Selection of region codes which are processed, e.g. 11|12.
Use NONE for all regions.
RegionExcludeFilter Selection of region codes which are not processed, e.g. 7|16|17.
Use NONE for no regions.
Landuse Name of raster with land-use.
LanduseReplaceCodes The land-use codes of areas which are not allocated and which will
be replaced with the LanduseReplaceWithCode at the end of the
allocation process, e.g. 1|2|3|4.
LanduseReplaceWithCode The code of the user-defined land-use codes which will be used to
fill not-allocated areas at the end of the allocation process, e.g. 5.
LanduseUndefinedCode The code of the user-defined land-use codes which will be used
to fill areas which could not be allocated, e.g. 6.
NotAllocatableAreas Name of raster with not-allocatable areas (0 = allocatable,
1 = not-allocatable).
PAReduceFactor Name of raster with the factors which will be used to reduce the
suitability in protected areas (0.0 = high protection, 1.0 = no
protection).
Use NONE for no raster with protected areas.
SuitRasterCodes The corresponding land-use codes for the SuitRasterNames, e.g. 1|2|3|4.
SuitRasterNames The names of the suitability rasters for the land-use types.
The suitability varies from 0.0 (not suitable) to 1.0 (highly suitable).
ClaimFileName The name of the csv file with land-use claims (km2) per region
per land-use type.
ClaimLanduseFieldName The name of the field with the land-use type in the claim file.
ClaimRegionFieldName The name of the field with the regioncode in the claim file.
ClaimAreaFieldName The name of the field with the claim area in the claim file.
ClaimLookup The lookup file to translate land-use classes in land-use names.
Use NONE if no translation is needed.
ClaimAreaMultiplierLanduseCodes The corresponding land-use codes for the ClaimAreaMultipliers, e.g. 1|2|3|4.
ClaimAreaMultipliers A list of factors which will be multiplied with the corresponding
land-use claim area, e.g. 2.0|4.0|1.0|0.5.
CellAreas Name of raster with cell areas (km2).
AddNoiseFlag Flag which can be used to add semi-random noise to the suitability
rasters, e.g. TRUE.
OutRegionAreasFileName Name of the file for summarized cell areas per region.
Use NONE if no cell areas need to be calculated.
OutRegionLandcoverAreasFileName Name of the file for summarized cell areas per region per land-cover type.
Use NONE if no cell areas need to be calculated.
OutRegionLanduseAreasFileName Name of the file for summarized cell areas per region per land-use type.
Use NONE if no cell areas need to be calculated.
OutAllocatedLanduse Name of raster with the new allocated land-use.
Starting a run within Windows
In Windows open a command window and go to the directory where GLOBIO 4 is installed (for example C:\Python27\Globio4). Type the following command:
cd \Python27\Globio4\Scripts
Create your own configuration script or edit the existing configuration file Run_LanduseAllocation.glo in the directory Scripts. Modify the paths and other settings to meet your needs. To run the script type the following command.
globio4 Run_LanduseAllocation.glo
After the script is finished the results can be found in the output directory specified in the script.
Calculation rules
The Land-use Allocation module uses the following calculation rules (in pseudo-code) to create a map with allocated land-use types.
Read the suitability maps for the land-use types to allocate.
Read the file with land-use claims (km2).
Optional: translate the land-use classes of the claims to land-use types.
Read de map with not-allocatable areas.
Optional: Read the map with the reduce-factors for protected areas.
Read the map with regions and create a list of region codes. Apply the region filter or
the excluded region list. Remove region codes for which there are no land-use claims.
Read or create a map with raster cell areas in km2.
Create an empty map for the allocated land-use output (0 = is empty/not yet allocated).
Read the sequence of land-use types in which they are allocated.
For all land-use types in this list do:
Read the suitability map for this land-use type.
Optional: Multiply the suitability with the reduce factor for protected areas.
Optional: Add semi-random noise to the suitability map. The minimum difference
between all successive suitability values is calculated. For each cell this
value is multiplied by a random value between 0.0 and 0.9 which is generated with
a fixed seed. This semi-random value is added to suitability value of that cell.
For all regions do:
Select all cells within the region.
Select in here all cells which are allocatable (i.e. not not-allocatable).
Select in here all cells which are not allocated yet by a previous processed
land-use type.
Sort the remaining cells on suitability from high to low values.
Get the cell areas of the sorted cells.
For these cells calculate the cumulated area.
From this list get the index of the first cell with the cumulated area which is
greater or equal to the claim area of the current processed land-use type and
region.
Assign to these cells in the map of allocated land-use the currently processed
land-use type.
Select all empty cells which are allocatable but lie outside the processed regions. Assign
the user-defined 'undefined' land-use type to these cells.
For all processed land-use types do:
Select in the allocated land-use map all cells which have in the input land-use map
the current land-use type.
Select in here all cells which are not allocated yet. Assign to these cells the
user-defined 'replace' land-use type e.g. 'secondary vegetation'.
Read the land-cover map.
Select all cells which are not allocated yet. Assign to these cells the code from the
land-cover type.
Save the allocated land-use map.
Optional: Calculate areas.
Test results
Input data
During the development of the Land-use Allocation module various test runs are made. For these runs the following input data is used:
Name Dataset Source
------------------ -------------------------------------------------------------------- -----
Land-cover ESACCI-LC-L4-LCCS-Map-300m-P5Y-2010-v1.6.1.tif ESA
http://maps.elie.ucl.ac.be/CCI/viewer/
Region IMAGEregions.gdb\\ImageRegions27_5min PBL
Livestock glbctd1t0503m FAO
http://www.fao.org/ag/AGAinfo/resources/en/glw/GLW_dens.html
Traveltime acc_50k JRC
http://forobs.jrc.ec.europa.eu/products/gam/download.php
Protected areas WDPA_Jan2017_Public.gdb\\WDPA_poly_Jan2017 WDPA
http://www.wdpa.org/
Land-use claims ssp2_2050_claims_and_restclaims.xlsx PBL
Many of these datasets are pre-processed before they are used as input. In most cases the pre-processing included resampling and resize the original dataset and converting to a tif raster.
Suitability
Some of the input data is used to calculate suitability rasters to be used in the Land-use Allocation module. These rasters indicate the suitability of regions for specific land-use types. The suitability varies from 0.0 (not suitable) to 1.0 (highly suitable).
Suitability rasters are calculated for every allocated land-use type. During the development of the module the following suitability rasters are calculated.
Urban
The following calculation rules (in pseudo-code) are used to calculate the suitability raster.
Reclass the land-cover to an urban land-use type.
Select all areas outside these urban areas and calculate for each cell
the shortest euclidean distance to the nearest urban area.
Invert the euclidean distance values (new_dist = max_dist -- org_dist).
Calculate for all cells inside the urban areas the shortest euclidean
distance to the nearest urban area border.
Summarize the euclidean distance for each cell.
Calculate the suitability, i.e. normalize the euclidean distance to
values between 0.0 and 1.0.
Crop
The following calculation rules are used to calculate the suitability raster.
Reclass the land-cover to a crop land-use type.
Select all areas outside these crop areas and calculate for each cell
the shortest euclidean distance to the nearest crop area.
Invert the euclidean distance values (new_dist = max_dist -- org_dist).
Calculate for all cells inside the crop areas the shortest euclidean
distance to the nearest crop area border.
Summarize the euclidean distance for each cell.
Calculate the suitability, i.e. normalize the euclidean distance to
values between 0.0 and 1.0.
Pasture
The following calculation rules are used to calculate the suitability raster.
Select specific land-cover types and assign a suitability value to these areas.
Use the livestock map and normalize the number of animals per km2 to a
suitability value between 0.0 and 1.0.
Calculate the total suitability by multiplying both suitability values.
Forestry
For the suitability map of forestry a map was provided by PBL with minimum distances between roads and rivers, and forest taking in account a biome specific elevation limit.
The following calculation rules are used to calculate the suitability raster.
Normalize the minimum distances to values between 0.0 and 1.0.
Invert the values (1.0 -- value) to suitability values between 0.0 and 1.0.
For calculating the suitabilty rasters, scripts are available in the directory Suitability. These scripts are using the ESRI ArcPy library so a license of ArcGIS is required. For forestry a separate script is used.
Example configuration script
Next listing shows an example configuration script for a global run at 10 arcsecond resolution.
#-------------------------------------------------------------------------------
# RUN_LANDUSEALLOCATION_10SEC.GLO
#-------------------------------------------------------------------------------
# Include landuse allocation module.
INCLUDE LanduseAllocation.glo
#-------------------------------------------------------------------------------
BEGIN_RUN Calculations()
# Set output directory.
Outdir = G:\Data\Globio4LA\data\out\v405\10sec_wrld\landalloc_20170303
# Save temporary data?
SaveTmpData = False
# Set region and resolution.
Extent = wrld
CellSize = 10sec
# Set output raster.
RASTER OutAllocatedLanduse = $OutDir;\landuse_alloc.tif
# Set input directory versions.
STRING LcRefVersion = 20170116
STRING RegionRefVersion = 20170116
STRING PARefVersion = 20170118
STRING SuitRefVersion = 20170116
STRING ClaimRefVersion = 20161214
# Set input directories.
DIR LcDir = G:\Data\Globio4LA\data\referentie\v405\30sec_wrld\in_$LcRefVersion;
DIR RegionDir = G:\Data\Globio4LA\data\referentie\v405\30sec_wrld\in_$RegionRefVersion;
DIR ClaimDir = G:\Data\Globio4LA\data\referentie\v405\lookup\in_$ClaimRefVersion;
DIR SuitDir = G:\Data\Globio4LA\data\referentie\v405\30sec_wrld\suit_$SuitRefVersion;
DIR LuDirDir = $SuitDir;
DIR NotAllocDir = $SuitDir;
DIR PaDirDir = $RegionDir;
# Set other input parameters.
STRING LanduseCodes = 1|2|3|4|5|6
STRING LanduseNames = urban|crop|pasture|forestry|secondary vegetation|undefined
STRING LandusePriorityCodes = 1|2|3|4
RASTER Landcover = $LcDir;\esa_lc_2010.tif
RASTER Regions = $RegionDir;\imgregions27.tif
STRING RegionFilter = NONE
STRING RegionExcudeFilter = NONE
RASTER Landuse = $LuDirDir;\landcover_landuse.tif
STRING LanduseReplaceCodes = 1|2|3|4
STRING LanduseReplaceWithCode = 5
STRING LanduseUndefinedCode = 6
RASTER NotAllocatableAreas = $NotAllocDir;\not_allocatable_areas.tif
RASTER PAReduceFactor = $PaDirDir;\pa_reduce_factor.tif
STRING SuitRasterCodes = 1|2|3|4
RASTERLIST SuitRasterNames = $SuitDir;\suit_urban.tif|$SuitDir;\suit_crop.tif|$SuitDir;\suit_pasture.tif|$SuitDir;\suit_forestry.tif
FILE ClaimFileName = $ClaimDir;\Claims_2050.csv
STRING ClaimLanduseFieldName = AggLUClass
STRING ClaimRegionFieldName = IMGREGCD
STRING ClaimAreaFieldName = totalArea
FILE ClaimLookup = $ClaimDir;\LanduseClassToLanduseType.csv
STRING ClaimAreaMultiplierLanduseCodes = NONE
STRING ClaimAreaMultipliers = NONE
RASTER CellAreas = NONE
BOOLEAN AddNoiseFlag = True
# Set output files/raster.
FILE OutRegionAreasFileName = $OutDir;\regio_areas.csv
FILE OutRegionLandcoverAreasFileName = $OutDir;\regio_landcover_areas.csv
FILE OutRegionLanduseAreasFileName = $OutDir;\regio_landuse_areas.csv
RASTER TerrestrialMSA = $OutDir;\landuse_alloc.tif
#-------------------------------------------------------------------------------
# Start running.
#-------------------------------------------------------------------------------
RUN_MODULE CalcDiscreteLanduseAllocation(
$Extent,$CellSize,
$LanduseCodes,$LanduseNames,
$LandusePriorityCodes,
$Landcover,
$Regions,
$RegionFilter,$RegionExcudeFilter,
$Landuse,
$LanduseReplaceCodes,
$LanduseReplaceWithCode,$LanduseUndefinedCode,
$NotAllocatableAreas,
$PAReduceFactor,
$SuitRasterCodes,$SuitRasterNames,
$ClaimFileName,$ClaimLanduseFieldName,
$ClaimRegionFieldName,$ClaimAreaFieldName,
$ClaimLookup,
$ClaimAreaMultiplierLanduseCodes,
$ClaimAreaMultipliers,
$CellAreas,
$AddNoiseFlag,
$OutRegionAreasFileName,
$OutRegionLandcoverAreasFileName,
$OutRegionLanduseAreasFileName,
$OutAllocatedLanduse)
END_RUN
#-------------------------------------------------------------------------------
#-------------------------------------------------------------------------------
RUN Calculations()
Performance and memory usage
Test runs are done on different computers and for different regions and resolutions. The following table gives an overview of the execution times of some runs and the RAM memory used.
Resolution Region Duration Config 1) Memory Used Environment 2)
---------- ------- ---------- ---------- ------------- --------------
10 sec world 02:35:06 no noise 146 GB Linux
10 sec world 02:57:23 noise 201 GB Linux
30 sec world 00:08:43 no noise 24 GB Linux
30 sec world 00:10:24 noise 28 GB Linux
30 sec eu 00:00:49 no noise 4 GB Linux
30 sec eu 00:01:25 noise 11 GB Linux
30 sec world 00:23:11 no noise 14 GB Windows
30 sec eu 00:02:11 no noise 0.7 GB Windows
1) no noise = no semi-random noise is used; noise = semi-random noise is used.
2) Linux = a Linux server with an Intel Xeno processor and 256 GB RAM;
Windows = a Windows 7 VMWare Virtual Machine on a host with an Intel i7 processor and 24 GB RAM.