Parameterization

A parameter file is mandatory for the Level 2 ImproPhe submodule of FORCE HLPS.

All parameters must be given, even if they are not used. All parameters follow common tag-value notation. Rudimentary checks are performed when using this file.

The following parameter descriptions are a print-out of force-parameter, which can generate an empty parameter file skeleton.

++PARAM_L2IMP_START++

# INPUT/OUTPUT DIRECTORIES
# ------------------------------------------------------------------------
# Lower Level datapool (parent directory of tiled input data)
# Type: full directory path
DIR_LOWER = NULL
# Higher Level datapool (parent directory of tiled output data)
# Type: full directory path
DIR_HIGHER = NULL
# This is the directory where provenance files should be saved.
# Type: full directory path
DIR_PROVENANCE = NULL

# MASKING
# ------------------------------------------------------------------------
# Analysis Mask datapool (parent directory of tiled analysis masks)
# If no analysis mask should be applied, give NULL.
# Type: full directory path
DIR_MASK = NULL
# Basename of analysis masks (e.g. WATER-MASK.tif).
# Masks need to be binary with 0 = off / 1 = on
# Type: Basename of file
BASE_MASK = NULL

# OUTPUT OPTIONS
# ------------------------------------------------------------------------
# Output format, which is either uncompressed flat binary image format aka
# ENVI Standard, GeoTiff, or COG. GeoTiff images are compressed with ZSTD and hori-
# zontal differencing; BigTiff support is enabled; the Tiff is internally tiled
# with 256x256 px blocks.
# Metadata are written to the ENVI header or directly into the Tiff
# to the FORCE domain. If the size of the metadata exceeds the Tiff's limit,
# an external .aux.xml file is additionally generated.
# Note that COG output is only possible when the chunk size matches the tile size.
# Type: Character. Valid values: {ENVI,GTiff,COG,CUSTOM}
OUTPUT_FORMAT = GTiff
# File that contains custom GDAL output options. This is only used if
# OUTPUT_FORMAT = CUSTOM. If OUTPUT_FORMAT = CUSTOM, this file is mandatory.
# The file should be written in tag and value notation. The first two lines
# are mandatory and specify GDAL driver and file extension, e.g. DRIVER = GTiff
# and EXTENSION = tif. The driver name refers to the GDAL short driver names.
# Lines 3ff can hold a variable number of GDAL options (up to 32 are allowed).
# Please note: with opening output options up to the user, it is now possible to
# give invalid or conflicting options that result in the failure of creating files.
# Type: full file path
FILE_OUTPUT_OPTIONS = NULL
# This parameter controls whether the output is written as multi-band image, or
# if the stack will be exploded into single-band files.
# Type: Logical. Valid values: {TRUE,FALSE}
OUTPUT_EXPLODE = FALSE
# This parameter controls whether the output is written in one folder,
# or whether several subfolders per product type will be generated to better
# structure the output.
# Type: Logical. Valid values: {TRUE,FALSE}
OUTPUT_SUBFOLDERS = FALSE
# This parameter controls whether FORCE raises a warning or an error
# if no read or written bytes are detected. The default (FALSE) will
# result in a warning.
# Type: Logical. Valid values: {TRUE,FALSE}
FAIL_IF_EMPTY = FALSE

# PARALLEL PROCESSING
# ------------------------------------------------------------------------
# This module is using a streaming mechanism to speed up processing. There
# are three processing teams (3 Threads) that simultaneously handle Input,
# Processing, and Output. Example: when chunk 2 is being processed, data
# from chunk 3 are already being input and results from chunk 1 are being
# output. Each team can have multiple sub-threads to speed up the work. The
# number of threads to use for each team is given by following parameters.
# Type: Integer. Valid range: [1,...
NTHREAD_READ = 8
NTHREAD_COMPUTE = 22
NTHREAD_WRITE = 4
# Use STREAMING = FALSE to disable streaming. This will perform reading,
# computing and writing after one another in sequential mode.
# Each operation will still be parallelized with above settings.
# Disabling streaming might be necessary for some UDFs that otherwise
# produce threading conflicts with the internally used OpenMP functionality.
# Type: Logical. Valid values: {TRUE,FALSE}
STREAMING = TRUE
# This module will display progress information on screen. By default, the
# progress information overwrites itself to produce a pretty displayal.
# However, this can cause error messages (or printing in UDFs) to be overwritten.
# If disabled (FALSE), the progress information will be simply be appended
# on screen (stdout).
# Type: Logical. Valid values: {TRUE,FALSE}
PRETTY_PROGRESS = TRUE

# PROCESSING EXTENT AND RESOLUTION
# ------------------------------------------------------------------------
# Analysis extent, given in tile numbers (see tile naming)
# Each existing tile falling into this square extent will be processed
# A shapefile of the tiles can be generated with force-tabulate-grid
# Type: Integer list. Valid range: [-999,9999]
X_TILE_RANGE = 0 0
Y_TILE_RANGE = 0 0
# Allow-list of tiles. Can be used to further limit the analysis extent to
# non-square extents. The allow-list is intersected with the analysis extent,
# i.e. only tiles included in both the analysis extent AND the allow-list will
# be processed.
# Optional. If NULL, the complete analysis extent is processed
# Type: full file path
FILE_TILE = NULL
# This parameter is used to define the size of the sub-tile processing units.
# Most efficient is to use a chunk size that coincides with the tile size. Using
# smaller chunks may be necessary if you cannot fit all necessary data into RAM.
# The tilesize must be dividable by the chunk size without remainder.
# Note that setting the chunk size to 0 as was done with the deprecated BLOCK_SIZE
# parameter is not permitted anymore.
# Type: Integer list. Valid range: ]0,TILE_SIZE]
CHUNK_SIZE = 0 0
# Analysis resolution. The tile (and chunk) size must be dividable by this
# resolution without remainder, e.g. 30m resolution with 100km tiles is not possible
# Type: Double. Valid range: ]0,CHUNK_SIZE]
RESOLUTION = 10
# How to reduce spatial resolution for cases when the image resolution is higher
# than the analysis resolution. If FALSE, the resolution is degraded using Nearest
# Neighbor resampling (fast). If TRUE, an approx. Point Spread Function (Gaussian
# lowpass with FWHM = analysis resolution) is used to approximate the acquisition
# of data at lower spatial resolution
# Type: Logical. Valid values: {TRUE,FALSE}
REDUCE_PSF = FALSE
# If you have spatially enhanced some Level 2 ARD using the FORCE Level 2 ImproPhe
# module, this switch specifies whether the data are used at original (FALSE) or
# enhanced spatial resolution (TRUE). If there are no improphe'd products, this
# switch doesn't have any effect
# Type: Logical. Valid values: {TRUE,FALSE}
USE_L2_IMPROPHE = FALSE

# SENSOR ALLOW-LIST
# ------------------------------------------------------------------------
# Sensors to be used in the analysis. Multi-sensor analyses are restricted
# to the overlapping bands. Each sensor needs a sensor definition in the runtime-data
# directory. New sensors can be added by the user. New bandnames can be added, too.
# Type: Character list.
SENSORS = LND08 LND09 SEN2A SEN2B SEN2C
# Target sensor that represents the combination of input sensors.
# A sensor definition for this target sensor needs to exist to make sure that processing
# those outputs will be possible. For example, if you combine Landsat 8 and Sentinel-2,
# the target sensor containing the overlapping bands could be LNDLG. If only using Sentinel-2
# sensors, the target sensor could be SEN2L. Valid values are the same as for SENSORS.
# Type: Character list.
TARGET_SENSOR = LNDLG
# Main product type to be used. Usually, this is a reflectance product like BOA.
# When using composites, you may use BAP. This can be anything, but make sure that
# the string can uniquely identify your product. As an example, do not use LEVEL2.
# Note that the product should contain the bands that are to be expected with the
# sensor used, e.g. 10 bands when sensor is SEN2A.
# Type: Character. Valid values: {BOA,TOA,IMP,BAP,SIG,...}
PRODUCT_TYPE_MAIN = BOA
# Quality product type to be used. This should be a bit flag product like QAI.
# When using composites, you may use INF. This can be anything, but make sure that
# the product should contain quality bit flags as outputted by FORCE L2PS.
# As an exception, it is also possible to give NULL if you don't have any quality masks.
# In this case, FORCE will only be able to filter nodata values, but no other quality
# flags as defined with SCREEN_QAI.
# Type: Character. Valid values: {QAI,INF,NULL,...}
PRODUCT_TYPE_QUALITY = QAI
# Perform a spectral adjustment to Sentinel-2?
# This method can only be used with following sensors: SEN2A, SEN2B, SEN2C, SEN2D,LND04, LND05, LND07,
# LND08, LND09, MOD01, MOD02.
# A material-specific spectral harmonization will be performed, which will convert the
# spectral response of any of these sensors to Sentinel-2A. Non-existent bands will be
# predicted, too.
# Type: Logical. Valid values: {TRUE,FALSE}
SPECTRAL_ADJUST = FALSE

# QAI SCREENING
# ------------------------------------------------------------------------
# This list controls, which QAI flags are masked out before doing the analysis.
# Type: Character list. Valid values: {NODATA,CLOUD_OPAQUE,CLOUD_BUFFER,
#   CLOUD_CIRRUS,CLOUD_SHADOW,SNOW,WATER,AOD_FILL,AOD_HIGH,AOD_INT,SUBZERO,
#   SATURATION,SUN_LOW,ILLUMIN_NONE,ILLUMIN_POOR,ILLUMIN_LOW,SLOPED,WVP_NONE}
SCREEN_QAI = NODATA CLOUD_OPAQUE CLOUD_BUFFER CLOUD_CIRRUS CLOUD_SHADOW SNOW SUBZERO SATURATION
# Threshold for removing outliers. Triplets of observations are used to determine
# the overall noise in the time series by computing linearly interpolating between
# the bracketing observations. The RMSE of the residual between the middle value
# and the interpolation is the overall noise. Any observations, which have a
# residual larger than a multiple of the noise are iteratively filtered out
# (ABOVE_NOISE). Lower/Higher values filter more aggressively/conservatively.
# Likewise, any masked out observation (as determined by the SCREEN_QAI filter)
# can be restored if its residual is lower than a multiple of the noise
# (BELOW_NOISE). Higher/Lower values will restore observations more aggres-
# sively/conservative. Give 0 to both parameters to disable the filtering.
# ABOVE_NOISE = 3, BELOW_NOISE = 1 are parameters that have worked in some settings.
# Type: Float. Valid range: [0,...
ABOVE_NOISE = 0
BELOW_NOISE = 0

# PROCESSING TIMEFRAME
# ------------------------------------------------------------------------
# Time extent for the analysis. All data between these dates will be used in
# the analysis.
# Type: Date list. Format: YYYY-MM-DD
DATE_RANGE = 2010-01-01 2019-12-31
# DOY range for filtering the time extent. Day-of-Years that are outside of
# the given interval will be ignored. Example: DATE_RANGE = 2010-01-01
# 2019-12-31, DOY_RANGE = 91 273 will use all April-September observations from
# 2010-2019. If you want to extend this window over years give DOY min >
# DOY max. Example: DATE_RANGE = 2010-01-01 2019-12-31, DOY_RANGE = 274 90
# will use all October-March observations from 2010-2019.
# Type: Integer list. Valid values: [1,365]
DOY_RANGE = 1 365
# Landat 7 was de-orbited in 2019. Landsat 7 data might be available
# in your data cube even though you might not want to use it anymore.
# This parameters sets the date after which Landsat 7 data should be ignored.
# Type: Date. Format: YYYY-MM-DD
DATE_IGNORE_LANDSAT_7 = 2099-12-31

# ImproPhe PARAMETERS
# ------------------------------------------------------------------------
# This parameter defines the seasonal windows for which the Level 2 ARD
# should be aggregated. This parameter expects a list of DOYs that define
# the window breakpoints. If you specify 5 breakpoints, there will be four
# windows. The windows can extend to the previous/next year (e.g. 270 30
# 91 181 270 would extend into the previous year, 1 30 91 181 270 30 would
# extend into the next year.
# Type: Integer list. Valid values: [1,365]
SEASONAL_WINDOW = 1 91 181 271 365
# This parameter defines the radius of the prediction kernel (in projection
# units, commonly in meters). A larger kernel increases the chance of finding
# a larger number of within-class pixels, but increases prediction time
# Type: Double. Valid values: ]0,CHUNK_SIZE]
KERNEL_SIZE = 2500
# This parameter defines the radius of the kernel used for computing the
# heterogeneity proxies (in projection units, commonly in meters). The
# heterogeneity proxies are derived from a focal standard deviation filter.
# The width of the kernel should reflect the scale difference between the
# coarse and medium resolution data.
# Type: Double. Valid values: ]0,CHUNK_SIZE]
KERNEL_TEXT = 330

# Level 2 ImproPhe PARAMETERS
# ------------------------------------------------------------------------
# This parameter defines the sensors, whose spatial resolution should be
# improved. The SENSORS parameter above defines the sensors that serve as
# target images. For a list of available sensors, see the description for
# the SENSORS parameter. For improving the spatial resolution of Landsat to
# Sentinel-2, it is recommended to use "SENSORS = sen2a sen2b", and
# "SENSORS_LOWRES = LND07 LND08 LND09"
SENSORS_LOWRES = LND07 LND08 LND09

++PARAM_L2IMP_END++