starfm_job: Execute a single self-contained self-contained time-series...
In ImageFusion: Temporal Fusion of Raster Images

Description Usage Arguments Details Value Author(s) References Examples

View source: R/starfm_job.R

A wrapper function for execute_starfm_job_cpp. Intended to execute a single job, that is a number of predictions based on the same input pair(s). It ensures that all of the arguments passed are of the correct type and creates sensible defaults.

starfm_job(
  input_filenames,
  input_resolutions,
  input_dates,
  pred_dates,
  pred_filenames,
  pred_area,
  winsize,
  date1,
  date3,
  n_cores,
  logscale_factor,
  spectral_uncertainty,
  temporal_uncertainty,
  number_classes,
  hightag,
  lowtag,
  MASKIMG_options,
  MASKRANGE_options,
  output_masks,
  use_nodata_value,
  use_strict_filtering,
  double_pair_mode,
  use_temp_diff_for_weights,
  do_copy_on_zero_diff,
  verbose = TRUE
)

`input_filenames`	A string vector containing the filenames of the input images
`input_resolutions`	A string vector containing the resolution-tags (corresponding to the arguments `hightag` and `lowtag`, which are by default "high" and "low") of the input images.
`input_dates`	An integer vector containing the dates of the input images.
`pred_dates`	An integer vector containing the dates for which images should be predicted.
`pred_filenames`	A string vector containing the filenames for the predicted images. Must match `pred_dates` in length and order. Must include an extension relating to one of the drivers supported by GDAL, such as ".tif".
`pred_area`	(Optional) An integer vector containing parameters in image coordinates for a bounding box which specifies the prediction area. The prediction will only be done in this area. (x_min, y_min, width, height). By default will use the entire area of the first input image.
`winsize`	(Optional) Window size of the rectangle around the current pixel. Default is 51.
`date1`	(Optional) Set the date of the first input image pair. By default, will use the pair with the lowest date value.
`date3`	(Optional) Set the date of the second input image pair. By default, will use the pair with the highest date value. Disregarded if using double pair mode.
`n_cores`	(Optional) Set the number of cores to use when using parallelization. Default is 1.
`logscale_factor`	(Optional) When using a positive scale, the logistic weighting formula is used, which reduces the influence of spectral and temporal differences. Default is 0, i. e. logistic formula not used
`spectral_uncertainty`	(Optional) This spectral uncertainty value will influence the spectral difference value. Default is 1 for 8 bit images (INT1U and INT1S), 50 otherwise.
`temporal_uncertainty`	(Optional) This spectral uncertainty value will influence the spectral difference value. Default is 1 for 8 bit images (INT1U and INT1S), 50 otherwise.
`number_classes`	(Optional) The number of classes used for similarity. Note all channels of a pixel are considered for similarity. So this value holds for each channel, e. g. with 3 channels there are n^3 classes. Default: 40.
`hightag`	(Optional) A string which is used in `input_resolutions` to describe the high-resolution images. Default is "high".
`lowtag`	(Optional) A string which is used in `input_resolutions` to describe the low-resolution images. Default is "low".
`MASKIMG_options`	(Optional) A string containing information for a mask image (8-bit, boolean, i. e. consists of 0 and 255). "For all input images the pixel values at the locations where the mask is 0 is replaced by the mean value." Example: `--mask-img=some_image.png`
`MASKRANGE_options`	(Optional) Specify one or more intervals for valid values. Locations with invalid values will be masked out. Ranges should be given in the format `'[<float>,<float>]'`, `'(<float>,<float>)'`, `'[<float>,<float>'` or `'<float>,<float>]'`. There are a couple of options:' "–mask-valid-ranges" Intervals which are marked as valid. Valid ranges can excluded from invalid ranges or vice versa, depending on the order of options. "–mask-invalid-ranges" Intervals which are marked as invalid. Invalid intervals can be excluded from valid ranges or vice versa, depending on the order of options. "–mask-high-res-valid-ranges" This is the same as –mask-valid-ranges, but is applied only for the high resolution images. "–mask-high-res-invalid-ranges" This is the same as –mask-invalid-ranges, but is applied only for the high resolution images. "–mask-low-res-valid-ranges" This is the same as –mask-valid-ranges, but is applied only for the low resolution images. "–mask-low-res-invalid-ranges" This is the same as –mask-invalid-ranges, but is applied only for the low resolution images.
`output_masks`	(Optional) Write mask images to disk? Default is "false".
`use_nodata_value`	(Optional) Use the nodata value as invalid range for masking? Default is "true".
`use_strict_filtering`	(Optional) Use strict filtering, which means that candidate pixels will be accepted only if they have less temporal and spectral difference than the central pixel (like in the paper). Default is "false".
`double_pair_mode`	(Optional) Use two dates `date1` and `date3` for prediction, instead of just `date1` for all predictions? Default is "true" if all the pred dates are in between input pairs, and "false" otherwise. Note: It may be desirable to predict in double-pair mode where possible, as in the following example: `[(7) 10 12 (13) 14]` , where we may wish to predict 10 and 12 in double pair mode, but can only predict 14 in single-pair mode. Do achieve this it is necessary to split the task into different jobs. Default is "true" if all pred_dates are between pair dates and "false" otherwise.
`use_temp_diff_for_weights`	(Optional) Use temporal difference in the candidates weight (like in the paper)? Default is to use temporal weighting in double pair mode, and to not use it in single pair mode.
`do_copy_on_zero_diff`	(Optional) Predict for all pixels, even for pixels with zero temporal or spectral difference (behavior of the reference implementation). Default is "false".
`verbose`	(Optional) Print progress updates to console? Default is "true".

Executes the STARFM algorithm to create a number of synthetic high-resolution images from either two pairs (double pair mode) or one pair (single pair mode) of matching high- and low-resolution images. Assumes that the input images already have matching size. See the original paper for details.

For the weighting (10) states: C = S T D but we use C = (S+1)(T+1)D, according to the reference implementation. With logscale_factor, the weighting formula can be changed to C = ln{(Sb+2)}ln{(Tb+1)D}
In addition to the temporal uncertainty σ_t (see temporal_uncertainty) and the spectral uncertainty σ_s (see spectral_uncertainty) there will be used a combined uncertainty σ_c := √{σ_t^2 + σ_s^2} . This will be used in the candidate weighting: If (S + 1) \, (T + 1) < σ_c , then C = 1 instead of the formula above.
Considering candidate weighting again, there is an option use_tempdiff_for_weights to not use the temporal difference for the weighting (also not for the combined uncertainty check above), i. e. T = 0 then. This is also the default behavior.
The basic assumption of the original paper that with zero spectral or temporal difference the central pixel will be chosen is wrong since there might be multiple pixels with zero difference within one window. Also due to the addition of 1 to the spectral and temporal differences, the weight will not increase so dramatically from a zero difference. However, these assumptions can be enforced with do_copy_on_zero_diff, which is the default behavior.
The paper states that a good candidate should satisfy (15) and (16). This can be set with use_strict_filtering, which is by default used. However the other behavior, that a candidate should fulfill (15) or (16), as in the reference implementation, can be also be selected with that option.
The paper uses max in (15) and (16), which would choose the largest spectral and temporal difference from all input pairs (only one or two are possible). Since this should filter out bad candidates, we believe this is a mistake and should be min instead of max, like it is done in the reference implementation. So this implementation uses min here.

Nothing. Output files are written to disk. The Geoinformation for the output images is adopted from the first input pair images.

Christof Kaufmann (C++)

Johannes Mast (R)

Gao, Feng, et al. "On the blending of the Landsat and MODIS surface reflectance: Predicting daily Landsat surface reflectance." IEEE Transactions on Geoscience and Remote sensing 44.8 (2006): 2207-2218.

# Load required libraries
library(ImageFusion)
library(raster)
# Get filesnames of high resolution images
landsat <- list.files(
  system.file("landsat/filled",
              package = "ImageFusion"),
  ".tif",
  recursive = TRUE,
  full.names = TRUE
)

# Get filesnames of low resolution images
modis <- list.files(
  system.file("modis",
              package = "ImageFusion"),
  ".tif",
  recursive = TRUE,
  full.names = TRUE
)

#Select the first two landsat images 
landsat_sel <- landsat[1:2]
#Select the corresponding modis images
modis_sel <- modis[1:10]
# Create output directory in temporary folder
out_dir <- file.path(tempdir(),"Outputs")
if(!dir.exists(out_dir)) dir.create(out_dir, recursive = TRUE)
#Run the job, fusing two images
starfm_job(input_filenames = c(landsat_sel,modis_sel),
           input_resolutions = c("high","high",
                                 "low","low","low",
                                 "low","low","low",
                                 "low","low","low","low"),
           input_dates = c(68,77,68,69,70,71,72,73,74,75,76,77),
           pred_dates = c(73,77),
           pred_filenames = c(file.path(out_dir,"starfm_73.tif"),
                              file.path(out_dir,"starfm_77.tif"))
)
# remove the output directory
unlink(out_dir,recursive = TRUE)