CleanSLCClasses {HYPEtools}

Clean Soil-Landuse classes (SLCs) from small fractions

Description

CleanSLCClasses attempts to clean small SLC fractions within each SUBID (sub-catchment) from an imported GeoData file using user-provided area thresholds. Cleaning can be performed along class similarity rules or along SLC area alone.

Usage

CleanSLCClasses(
  gd,
  gcl,
  m1.file = NULL,
  m1.class = "s",
  m1.clean = rep(TRUE, 2),
  m1.precedence = rep(TRUE, 2),
  m2.frac = NULL,
  m2.abs = NULL,
  signif.digits = 3,
  verbose = TRUE,
  progbar = TRUE
)

Arguments

gd

Data frame containing columns with SUBIDs, SUBID areas in m^2, and SLC fractions, typically a 'GeoData.txt' file imported with ReadGeoData.

gcl

Data frame containing columns with SLCs and corresponding land use and soil class IDs, typically a 'GeoClass.txt' file imported with ReadGeoClass.

m1.file

Character string, path and file name of the soil or land use class transfer table, a tab-separated text file. Format see details. A value of NULL (default) prevents method 1 cleaning.

m1.class

Character string, either "soil" or "landuse", can be abbreviated. Gives the type of transfer class table for method 1 cleaning. See Details.

m1.clean

A logical vector of length 2 which indicates if cleaning should be performed for area fraction thresholds (position 1) and/or absolute area thresholds (position 2).

m1.precedence

A logical vector of length 2 which indicates if areas below cleaning threshold should be moved to similar areas according to precedence in the transfer table given in m1.file (TRUE) or to the largest area of available transfer classes (FALSE). Area fraction thresholds (position 1) and absolute area thresholds (position 2).

m2.frac

Numeric, area fraction threshold for method 2 cleaning, i.e. moving of small SLC areas to largest SLC in each SUBID without considering similarity between classes. Either a single value or a vector of the same length as the number of SLC classes in gd, giving area fraction thresholds for each SLC separately, with a value 0 for SLCs to omit from cleaning. A value of NULL (default) prevents method 2 area fraction cleaning.

m2.abs

Numeric, see m2.frac. Threshold(s) for absolute areas in m^{2}.

signif.digits

Integer, number of significant digits to round cleaned SLCs to. See also signif. Set to NULL to prevent rounding.

verbose

Logical, print some information during runtime.

progbar

Logical, display a progress bar while calculating SLC class fractions. Adds overhead to calculation time but useful when subid is NULL or contains many SUBIDs.

Details

CleanSLCClasses performs a clean-up of small SLC fractions in an imported GeoData file. Small SLCs are eliminated either by moving their area to similar classes according to rules which are passed to the function in a text file (Method 1), or by simply moving their area to the largest SLC in the SUBID (Method 2). Moving rules for the first method can be based on either soil classes or land use classes but these cannot be combined in one function call. Run the function two times to combine soil and land use based clean-up. Method 1 and 2, however, can be combined in one function call, in which case the rule-based classification will be executed first. Clean-up precedence in method 1: if clean-ups based on area fractions and absolute areas are combined (m1.clean = rep(TRUE, 2)), then area fractions will be cleaned first. In order to reverse precedence, call CleanSLCClasses two times with absolute area cleaning activated in first call and area fraction cleaning in second. In both methods, SLCs in each SUBID are cleaned iteratively in numerical order, starting with SLC_1. This implies a greater likelihood of eliminating SLCs with smaller indices.

Method 1

For method one, small SLC fractions are moved to either similar land use classes within the same soil class, or vice versa. Similarities are defined by the user in a tab-separated text file, which is read by CleanSLCClasses during runtime. Soil and land use classes correspond to the classes given in column two and three in the GeoClass file. The file must have the following format:

class.1	thres.frac.1	thres.abs.1	transfer.1	...	transfer.n
class.2	thres.frac.2	thres.abs.2	transfer.1	...	transfer.o
...	...	...	...	...	...
class.m	thres.frac.m	thres.abs.m	transfer.1	...	transfer.p

Column 1 contains the source land use or soil classes subjected to clean-up, columns 2 and 3 contain threshold values for area fractions and absolute areas. The remaining columns contain classes to which areas below threshold will be transferred, in order of precedence. Each class can have one or several transfer classes. CleanSLCClasses will derive SLC classes to clean from the given soil or land use class using the GeoClass table given in argument gcl. No header is allowed. At least one transfer class must exist, but classes can be omitted and will then be ignored by CleanSLCClasses. The order of transfer classes in the transfer file indicates transfer preference. CleanSLCClasses constructs a transfer list for each SLC class in the model set-up and per default uses the order to choose a preferred SLC to transfer to. However, if several SLCs exist for a given soil or land use class, one of them will be chosen without further sorting. If argument m1.precedence is set to FALSE for either area fractions or absolute areas, precedence will be ignored and the largest area available will be chosen to transfer small areas to. Area fraction thresholds are given as fractions of 1, absolute area thresholds as values in m^{2}. If an area below threshold is identified but there are no fitting SLCs available to transfer to, the area will remain unchanged.

Method 2

This method is more rigid than method one and can also be applied as a post-processor after clean-up using method 1 to force a removal of all SLCs below a given threshold from a GeoData file (method 1 cleaning can be be very selective, depending on how many transfer classes are provided in the transfer table). Cleaning thresholds for method 2 area fractions and absolute areas are given in arguments m2.frac and m2.abs. SLC areas below the given thresholds will be moved to the largest SLC in the given SUBID without considering any similarity between classes.

Value

CleanSLCClasses returns the GeoData data frame passed to the function in argument gd with cleaned SLC class columns.

See Also

RescaleSLCClasses for re-scaling of SLC area fraction sums.

Examples

# Import source data
te1 <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
te2 <- ReadGeoClass(filename = system.file("demo_model", "GeoClass.txt", package = "HYPEtools"))
# Clean-up using method 2, 0.5 % area fraction threshold and 100 m^2 absolute area threshold
te3 <- CleanSLCClasses(gd = te1, gcl = te2, m2.frac = 0.005, m2.abs = 100)
# Detailed comparison with function CompareFiles
te4 <- CompareFiles(te1, te3, type = "GeoData")
te4