assessDL

Description

Assess semantic segmentation model using all samples in a torch DataLoader.

Usage

assessDL(
  dl,
  model,
  multiclass = TRUE,
  batchSize,
  size,
  nCls,
  cCodes,
  cNames,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  usedDS = FALSE,
  useCUDA = FALSE,
  decimals = 4
)

Arguments

Details

This function generates a set of summary assessment metrics based on all samples within a torch data loader. Results are returned as a list object. For multiclass assessment, the class names ($Classes), count of samples per class in the reference data ($referenceCounts), count of samples per class in the predictions ($predictionCounts), confusion matrix ($confusionMatrix), aggregated assessment metrics ($aggMetrics) (OA = overall accuracy, macroF1 = macro-averaged class aggregated F1-score, macroPA = macro-averaged class aggregated producer's accuracy or recall, and macroUA = macro-averaged class aggregated user's accuracy or precision), class-level user's accuracies or precisions ($userAccuracies), class-level producer's accuracies or recalls ($producerAccuracies), and class-level F1-scores ($F1Scores). For a binary case, the $Classes, $referenceCounts, $predictionCounts, and $confusionMatrix objects are also returned; however, the $aggMets object is replaced with $Mets, which stores the following metrics: overall accuracy, recall, precision, specificity, negative predictive value (NPV), and F1-score. For binary cases, the second class is assumed to be the positive case.

Value

List object containing the resulting metrics and ancillary information.

Examples

## Not run: 
metricsOut <- assessDL(dl=testDL,
                       model=model,
                       batchSize=15,
                       size=256,
                       nCls=2,
                       mode="binary",
                       cCodes=c(1,2),
                       cNames=c("Not Mine", "Mine"),
                       usedDS=FALSE,
                       useCUDA=TRUE,
                       decimals=4)

## End(Not run)

assessPnts

Description

Assess semantic segmentation model using point locations

Usage

assessPnts(
  reference,
  predicted,
  multiclass = TRUE,
  mappings = levels(as.factor(reference)),
  decimals = 4
)

Arguments

Details

This function generates a set of summary assessment metrics when provided reference and predicted classes. Results are returned as a list object. For multiclass assessment, the class names ($Classes), count of samples per class in the reference data ($referenceCounts), count of samples per class in the predictions ($predictionCounts), confusion matrix ($confusionMatrix), aggregated assessment metrics ($aggMetrics) (OA = overall accuracy, macroF1 = macro-averaged class aggregated F1-score, macroPA = macro-averaged class aggregated producer's accuracy or recall, and macroUA = macro-averaged class aggregated user's accuracy or precision), class-level user's accuracies or precisions ($userAccuracies), class-level producer's accuracies or recalls ($producerAccuracies), and class-level F1-scores ($F1Scores). For a binary case, the $Classes, $referenceCounts, $predictionCounts, and $confusionMatrix objects are also returned; however, the $aggMets object is replaced with $Mets, which stores the following metrics: overall accuracy, recall, precision, specificity, negative predictive value (NPV), and F1-score. For binary cases, the second class is assumed to be the positive case.

Value

List object containing the resulting metrics and ancillary information.

Examples

#Multiclass example

#Generate example data as data frame of class predictions
inDF <- data.frame(ref = sample(c("Class A", "Class B", "Class C"), 1000, replace=TRUE),
pred = sample(c("Class A", "Class B", "Class C"), 1000, replace=TRUE))

#Calculate metrics
metsOut <- assessPnts(reference=inDF$ref,
                     predicted=inDF$pred,
                     multiclass=TRUE,
                     mappings = c("Class A", "Class B", "Class C"),
                     decimals=4)

print(metsOut)

#Binary example

#Generate example data as data frame of class predictions
inDF <- data.frame(ref = sample(c("Background", "Positive"), 1000, replace=TRUE),
                  pred = sample(c("Background", "Positive"), 1000, replace=TRUE))

#Calculate metrics
metsOut <- assessPnts(reference=inDF$ref,
                     predicted=inDF$pred,
                     multiclass=FALSE,
                     mappings = c("Background", "Positive"),
                     decimals=4)

print(metsOut)

assessRaster

Description

Assess semantic segmentation model using categorical raster grids (wall-to-wall reference data and predictions)

Usage

assessRaster(
  reference,
  predicted,
  multiclass = TRUE,
  mappings = levels(as.factor(reference)),
  decimals = 4
)

Arguments

Details

This function generates a set of summary assessment metrics when provided reference and predicted classes. Results are returned as a list object. For multiclass assessment, the class names ($Classes), count of samples per class in the reference data ($referenceCounts), count of samples per class in the predictions ($predictionCounts), confusion matrix ($confusionMatrix), aggregated assessment metrics ($aggMetrics) (OA = overall accuracy, macroF1 = macro-averaged class aggregated F1-score, macroPA = macro-averaged class aggregated producer's accuracy or recall, and macroUA = macro-averaged class aggregated user's accuracy or precision), class-level user's accuracies or precisions ($userAccuracies), class-level producer's accuracies or recalls ($producerAccuracies), and class-level F1-scores ($F1Scores). For a binary case, the $Classes, $referenceCounts, $predictionCounts, and $confusionMatrix objects are also returned; however, the $aggMets object is replaced with $Mets, which stores the following metrics: overall accuracy, recall, precision, specificity, negative predictive value (NPV), and F1-score. For binary cases, the second class is assumed to be the positive case.

Value

List object containing the resulting metrics and ancillary information.

Examples

if(requireNamespace("terra", quietly = TRUE)){
require(torch)
require(terra)
#Multiclass example

#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))

#Calculate metrics
metsOut <- assessRaster(reference=ref,
                        predicted=pred,
                        multiclass=TRUE,
                        mappings=c("Class A", "Class B", "Class C"),
                        decimals=4)

print(metsOut)

#Binary example

#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(0, 1), 625, replace=TRUE), nrow=25, ncol=25))
pred <- terra::rast(matrix(sample(c(0, 1), 625, replace=TRUE), nrow=25, ncol=25))

#Calculate metrics
metsOut <- assessRaster(reference=ref,
                        predicted=pred,
                        multiclass=FALSE,
                        mappings=c("Background", "Positive"),
                        decimals=4)

print(metsOut)
}

callback_save_model_state_dict

Description

Save the model state dictionary to disk at the end of each epoch as a .pt file. For use within luz training loop.

Usage

callback_save_model_state_dict(save_dir = ".", prefix = "model_epoch")

Arguments

Value

No R object is returned. The state dictionary is saved to disk as a .pt file.

checkDymamicChips

Description

Generate a dataframe of summary infformation for each chip defined using makeDynamicChipsSF().

Usage

checkDynamicChips(
  chipsSF,
  chipSize = 512,
  cellSize = 1,
  doJitter = FALSE,
  jitterSD = 15,
  useSeed = TRUE,
  seed = 42
)

Arguments

Details

Generate set of summary information about each chip defined by makeDynamicChipsSF() including all the information in the sf object generated by makeDynamicChipsSF() and the number of columns of cells in the predictor variable raster and mask ("cCntImg" and "cCntMsk"), number of rows of cells in the predictor variable raster and mask ("rCntImg" and "rCntMsk"), number of input predictor variables ("bCntImg"), and count of NA pixels in the predictor variable raster and mask ("naCntImg" and "naCntMsk"). This function is used primarily to check the chips prior to attempting to use them in a training or validation process.

Value

Dataframe of summary information about image chips.

countParams

Description

Count the number of trainable parameters in a model.

Usage

countParams(model, test_data)

Arguments

Details

Count the number of trainable parameters in an instantiated model subclassed from nn_module().

Value

Counts of model parameters.

Examples

require(torch)
model <- defineUNet(inChn = 4,
                    nCls = 3,
                    actFunc = "lrelu",
                    useAttn = TRUE,
                    useSE = TRUE,
                    useRes = TRUE,
                    useASPP = TRUE,
                    useDS = FALSE,
                    enChn = c(16,32,64,128),
                    dcChn = c(128,64,32,16),
                    btnChn = 256,
                    dilRates=c(6,12,18),
                    dilChn=c(256,256,256,256),
                    negative_slope = 0.01,
                    seRatio=8)
 t1 <- torch::torch_rand(c(12,4,128,128))
 params <- countParams(model, t1)
 

defineDynamicSegDataSet

Description

Instantiate a subclass of torch::dataset() for geospatial semantic segmentation using dynamically generated chips

Usage

defineDynmamicSegDataSet(
  chipsSF,
  chipSize = 512,
  cellSize = 2,
  doJitter = TRUE,
  jitterSD = 15,
  useSeed = TRUE,
  seed = 42,
  normalize = FALSE,
  rescaleFactor = 1,
  mskRescale = 1,
  mskAdd = 0,
  bands = c(1, 2, 3),
  bMns = 1,
  bSDs = 1,
  doAugs = FALSE,
  maxAugs = 0,
  probVFlip = 0,
  probHFlip = 0,
  probRotate = 0,
  probBrightness = 0,
  probContrast = 0,
  probGamma = 0,
  probHue = 0,
  probSaturation = 0,
  brightFactor = c(0.8, 1.2),
  contrastFactor = c(0.8, 1.2),
  gammaFactor = c(0.8, 1.2, 1),
  hueFactor = c(-0.2, 0.2),
  saturationFactor = c(0.8, 1.2)
)

Arguments

Details

This function instantiates a subclass of torch::dataset() that dynmaically generates chips using tghe output from makeDynamicChips.R Can also define random augmentations to combat overfitting. Note that horizontal and vertical flips will affect the alignment of the image and associated mask chips. As a result, the same augmentation will be applied to both the image and the mask. Changes in brightness, contrast, gamma, hue, and saturation will not be applied to the masks since alignment is not impacted by these transformations. Predictor variables are generated with three dimensions (channel/variable, width, height) regardless of the number of channels/variables. Masks are generated as three dimensional tensors (class index, width, height).

Value

A dataset object that can be provided to torch::dataloader().

defineMobileUNet

Description

Define a UNet architecture for geospatial semantic segmentation with a MobileNet-v2 backbone.

Usage

defineMobileUNet(
  inChn = 3,
  nCls = 3,
  pretrainedEncoder = TRUE,
  freezeEncoder = TRUE,
  avgImNetWeights = FALSE,
  actFunc = "relu",
  useAttn = FALSE,
  useDS = FALSE,
  dcChn = c(256, 128, 64, 32, 16),
  negative_slope = 0.01
)

Arguments

Details

Define a UNet architecture with a MobileNet-v2 backbone or encoder. This UNet implementation was inspired by a blog post by Sigrid Keydana available here. This architecture has 6 blocks in the encoder (including the bottleneck) and 5 blocks in the decoder. The user is able to implement deep supervision (useDS = TRUE) and attention gates along the skip connections (useAttn = TRUE). If ImageNet weights are used and more then three predictor variables are provided, ImageNet weights in the layer of the encoder block are averaged. If three channels or predictor variables are provided, the user can specify to user the ImageNet weights or average them.

Value

ModileUNet model instance as torch nn_module

Examples

require(torch)
model <- defineMobileUNet(inChn = 4,
                          nCls = 7,
                          pretrainedEncoder = TRUE,
                          freezeEncoder = FALSE,
                          avgImNetWeights = TRUE,
                          actFunc = "relu",
                          useAttn = TRUE,
                          useDS = TRUE,
                          dcChn = c(256,128,64,32,16),
                          negative_slope = 0.01)
t1 <- torch::torch_rand(c(12,4,128,128))
p1 <- model(t1)

defineSegDataSet

Description

Instantiate a subclass of torch::dataset() for geospatial semantic segmentation

Usage

defineSegDataSet(
  chpDF,
  folder,
  normalize = FALSE,
  rescaleFactor = 1,
  mskRescale = 1,
  mskAdd = 0,
  bands = c(1, 2, 3),
  bMns = 1,
  bSDs = 1,
  doAugs = FALSE,
  maxAugs = 0,
  probVFlip = 0,
  probHFlip = 0,
  probRotation = 0,
  probBrightness = 0,
  probContrast = 0,
  probGamma = 0,
  probHue = 0,
  probSaturation = 0,
  brightFactor = c(0.8, 1.2),
  contrastFactor = c(0.8, 1.2),
  gammaFactor = c(0.8, 1.2, 1),
  hueFactor = c(-0.2, 0.2),
  saturationFactor = c(0.8, 1.2)
)

Arguments

Details

This function instantiates a subclass of torch::dataset() that loads data generated using the makeChips() or makeChipsMultiClass() function. Can also define random augmentations to combat overfitting. Note that horizontal and vertical flips will affect the alignment of the image and associated mask chips. As a result, the same augmentation will be applied to both the image and the mask. Changes in brightness, contrast, gamma, hue, and saturation will not be applied to the masks since alignment is not impacted by these transformations. Predictor variables are generated with three dimensions (channel/variable, width, height) regardless of the number of channels/variables. Masks are generated as three dimensional tensors (class index, width, height).

Value

A dataset object that can be provided to torch::dataloader().

Examples

## Not run: 
#Define training dataset and augmentations
trainDS <- defineSegDataSet(
  chpDF=trainDF,
  folder="PATH TO CHIPS FOLDER",
  normalize = FALSE,
  rescaleFactor = 255,
  mskRescale= 255,
  bands = c(1,2,3),
  mskAdd=1,
  doAugs = TRUE,
  maxAugs = 1,
  probVFlip = .5,
  probHFlip = .5,
  probBrightness = 0,
  probContrast = 0,
  probGamma = 0,
  probHue = 0,
  probRotation = 0,
  probSaturation = 0,
  brightFactor = c(.9,1.1),
  contrastFactor = c(.9,1.1),
  gammaFactor = c(.9, 1.1, 1),
  hueFactor = c(-.1, .1),
  saturationFactor = c(.9, 1.1))

## End(Not run)

defineTerrainSeg

Description

CNN-based semantic segmentation architecture of landform extraction or classification from a DTM.

Usage

defineTerrainSeg(
  segModel = "UNet",
  nCls = 2,
  cellSize = 1,
  spatDim = 640,
  tCrop = 64,
  doGP = FALSE,
  innerRadius = 2,
  outerRadius = 10,
  hsRadius = 50,
  smoothRadius = 11,
  actFunc = "lrelu",
  useAttn = FALSE,
  useSE = FALSE,
  useRes = TRUE,
  useASPP = TRUE,
  useDS = FALSE,
  pretrainedEncoder = TRUE,
  freezeEncoder = TRUE,
  avgImNetWeights = FALSE,
  enChn = c(16, 32, 64, 128),
  dcChn = c(128, 64, 32, 16),
  outChn = 64,
  btnChn = 256,
  dilChn = c(256, 256, 256, 256),
  dilRates = c(6, 12, 18),
  negative_slope = 0.01,
  seRatio = 8
)

Arguments

Details

Define a CNN-based semantic segmentation model for landform extraction or classification that includes a module that generates land surface parameters (LSPs) from the input DTM that are then passed to a semantic segmentation model. A UNet, UNet with a MobileNetv2 encoder, UNet3+, or HRNet architecture can be used. Gaussian pyramids can be calculated from the DTM to calculate LSPs at different scales. If Gaussian pyramids are not use, 6 LSPs are passed to the segmentation model. If Gaussian pyramids are used, 31 LSPs are passed to UNet3+. Model assumes a single band DTM of elevation measurements as input.

Value

terrainSeg model consisting of LSP generation of UNet3+ model.

defineUNet

Description

Define a UNet architecture for geospatial semantic segmentation.

Usage

defineUNet(
  inChn = 3,
  nCls = 3,
  actFunc = "relu",
  useAttn = FALSE,
  useSE = FALSE,
  useRes = FALSE,
  useASPP = FALSE,
  useDS = FALSE,
  enChn = c(16, 32, 64, 128),
  dcChn = c(128, 64, 32, 16),
  btnChn = 256,
  dilRates = c(6, 12, 18),
  dilChn = c(256, 256, 256, 256),
  negative_slope = 0.01,
  seRatio = 8
)

Arguments

Details

Define a UNet architecture with 4 blocks in the encoder, a bottleneck block, and 4 blocks in the decoder. UNet can accept a variable number of input channels, and the user can define the number of feature maps produced in each encoder and decoder block and the bottleneck. Users can also choose to (1) replace all ReLU activation functions with leaky ReLU or swish, (2) implement attention gates along the skip connections, (3) implement squeeze and excitation modules within the encoder blocks, (4) add residual connections within all blocks, (5) replace the bottleneck with a modified atrous spatial pyramid pooling (ASPP) module, and/or (6) implement deep supervision using predictions generated at each stage in the decoder.

Value

Unet model instance as torch nn_module

Examples

require(torch)
model <- defineUNet(inChn = 4,
                   nCls = 3,
                   actFunc = "lrelu",
                   useAttn = TRUE,
                   useSE = TRUE,
                   useRes = TRUE,
                   useASPP = TRUE,
                   useDS = TRUE,
                   enChn = c(16,32,64,128),
                   dcChn = c(128,64,32,16),
                   btnChn = 256,
                   dilRates=c(6,12,18),
                   dilChn=c(256,256,256,256),
                   negative_slope = 0.01,
                   seRatio=8)

t1 <- torch::torch_rand(2,4,256,256)
tp <- model(t1)
 

defineUnet3p

Description

Define a UNet3+ architecture for use in luz training loop.

Usage

defineUNet3p(
  inChn = 3,
  nCls = 2,
  enChn = c(16, 32, 64, 128),
  outChn = 64,
  btnChn = 256,
  useASPP = TRUE,
  dilRates = c(6, 12, 18),
  dilChn = c(256, 256, 256, 256),
  negative_slope = 0.01,
  useDS = FALSE
)

Arguments

Details

Define a UNet3+-like architecture for use in luz training loop. User can specify the number of output feature maps from each encoder and decoder block and the bottleneck block. Deep supervision can also be implemented. The default bottleneck block can be replaced with a atrous spatial pyramid pooling module. Leaky ReLU is used throughout. A variable number of input predictor variables and output classes can be defined.

The architecture was inspired by:

Huang, H., Lin, L., Tong, R., Hu, H., Zhang, Q., Iwamoto, Y., Han, X., Chen, Y.W. and Wu, J., 2020, May. Unet 3+: A full-scale connected unet for medical image segmentation. In ICASSP 2020-2020 IEEE international conference on acoustics, speech and signal processing (ICASSP) (pp. 1055-1059). IEEE.

Value

UNet3+ model using nn_module().

Examples

library(torch)
model <- defineUNet3p(inChn=4,
nCls=2,
enChn = c(16,32,64,128),
outChn = 64,
btnChn = 256,
useASPP = TRUE,
dilRates=c(6,12,18),
dilChn=c(256,256,256,256),
negative_slope=0.01,
useDS = FALSE)$to(device="cuda")
t1 <- torch::torch_rand(2,4,512,512)$to(device="cuda")
tp <- model(t1)

defineUnifiedFocalLoss

Description

Define a loss for semantic segmentation using a modified unified focal loss framework as a subclass of torch::nn_module()

Usage

defineUnifiedFocalLoss(
  nCls = 3,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  lambda = 0.5,
  gamma = 0.5,
  delta = 0.6,
  smooth = 1e-08,
  zeroStart = TRUE,
  clsWghtsDist = 1,
  clsWghtsReg = 1,
  useLogCosH = FALSE,
  device = "cuda"
)

Arguments

Details

Implementation of modified version of the unified focal loss after:

Yeung, M., Sala, E., Schönlieb, C.B. and Rundo, L., 2022. Unified focal loss: Generalising Dice and cross entropy-based losses to handle class imbalanced medical image segmentation. Computerized Medical Imaging and Graphics, 95, p.102026.

Modifications include (1) allowing users to define class weights for both the distribution- based and region-based losses, (2) using class weights as opposed to the symmetric and asymmetric methods implemented by the authors, and (3) including an option to apply a logcosh transform to the region-based loss.

This loss has three key hyperparameters that control its implementation. Lambda controls the relative weight of the distribution- and region-based losses. Default is 0.5, or equal weighting between the losses is applied. If lambda = 1, only the distribution- based loss is considered. If lambda = 0, only the region-based loss is considered. Values between 0.5 and 1 put more weight on the distribution-based loss while values between 0 and 0.5 put more weight on the region-based loss.

Gamma controls the application of focal loss and the application of increased weight to difficult-to-predict pixels (for distribution-based losses) or difficult-to-predict classes (region-based losses). Lower gamma values put increased weight on difficult samples or classes. Using a value of 1 equates to not using a focal adjustment.

The delta term controls the relative weight of false positive and false negative errors for each class. The default is 0.6 for each class, which results in placing a higher weight on false negative as opposed to false positive errors relative to that class.

By adjusting the lambda, gamma, delta, and class weight terms, the user can implement a variety of different loss metrics including cross entropy loss, weighted cross entropy loss, focal cross entropy loss, focal weighted cross entropy loss, Dice loss, focal Dice loss, Tversky loss, and focal Tversky loss.

Value

Loss metric for use in training process.

Examples

library(terra)
library(torch)
#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred1 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred2 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred3 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred <- c(pred2, pred2, pred3)

#Convert SpatRaster to array
ref <- terra::as.array(ref)
pred <- terra::as.array(pred)

#Convert arrays to tensors and reshape
ref <- torch::torch_tensor(ref, dtype=torch::torch_long())
pred <- torch::torch_tensor(pred, dtype=torch::torch_float32())
ref <- ref$permute(c(3,1,2))
pred <- pred$permute(c(3,1,2))

#Add mini-batch dimension
ref <- ref$unsqueeze(1)
pred <- pred$unsqueeze(1)

#Duplicate tensors to have a batch of two
ref <- torch::torch_cat(list(ref, ref), dim=1)
pred <- torch::torch_cat(list(pred, pred), dim=1)

#Instantiate loss metric
myDiceLoss <- defineUnifiedFocalLoss(nCls=3,
                                    lambda=0, #Only use region-based loss
                                    gamma= 1,
                                    delta= 0.5, #Equal weights for FP and FN
                                    smooth = 1e-8,
                                    zeroStart=FALSE,
                                    clsWghtsDist=1,
                                    clsWghtsReg=1,
                                    useLogCosH =FALSE,
                                    device='cpu')
#Calculate loss
myDiceLoss(pred, ref)

defineUnifiedFocalLossDS

Description

Define a loss for geospatial semantic segmentation using a modified unified focal loss framework as a subclass of torch::nn_module() when using deep supervision.

Usage

defineUnifiedFocalLossDS(
  nCls = 3,
  cropFactor = 0,
  dsWghts = c(0.6, 0.2, 0.1, 0.1),
  lambda = 0.5,
  gamma = 0.5,
  delta = 0.6,
  smooth = 1e-08,
  zeroStart = TRUE,
  clsWghtsDist = 1,
  clsWghtsReg = 1,
  useLogCosH = FALSE,
  device = "cuda"
)

Arguments

Details

Implementation of modified version of the unified focal loss after:

Yeung, M., Sala, E., Schönlieb, C.B. and Rundo, L., 2022. Unified focal loss: Generalising Dice and cross entropy-based losses to handle class imbalanced medical image segmentation. Computerized Medical Imaging and Graphics, 95, p.102026.

Modifications include (1) allowing users to define class weights for both the distribution- based and region-based losses, (2) using class weights as opposed to the symmetric and asymmetric methods implemented by the authors, and (3) including an option to apply a logcosh transform to the region-based loss.

This loss has three key hyperparameters that control its implementation. Lambda controls the relative weight of the distribution- and region-based losses. Default is 0.5, or equal weighting between the losses is applied. If lambda = 1, only the distribution- based loss is considered. If lambda = 0, only the region-based loss is considered. Values between 0.5 and 1 put more weight on the distribution-based loss while values between 0 and 0.5 put more weight on the region-based loss.

Gamma controls the application of focal loss and the application of increased weight to difficult-to-predict pixels (for distribution-based losses) or difficult-to-predict classes (region-based losses). Lower gamma values put increased weight on difficult samples or classes. Using a value of 1 equates to not using a focal adjustment.

The delta term controls the relative weight of false positive and false negative errors for each class. The default is 0.6 for each class, which results in placing a higher weight on false negative as opposed to false positive errors relative to that class.

By adjusting the lambda, gamma, delta, and class weight terms, the user can implement a variety of different loss metrics including cross entropy loss, weighted cross entropy loss, focal cross entropy loss, focal weighted cross entropy loss, Dice loss, focal Dice loss, Tversky loss, and focal Tversky loss.

Value

Loss metric for use in training process.

describeBatch

Description

Generate summary information for a batch of image chips and masks.

Usage

describeBatch(dataLoader, zeroStart = FALSE)

Arguments

Details

The goal of this function is to provide a check of a mini-batch of image chips and associated masks generated by a DataLoader instance using defineSegDataSet(). Summary information includes the mini-batch size (batchSize); image chip data type (imageDataType); mask data type (maskDataType); the shape of the mini-batch of images or predictor variables as mini-batch size, number of channels, width pixel count, and height pixel count (imageShape); the mask shape (maskShape); image band means (bndMns); image band standard deviations (bndSDs); count of pixels in each class in the mini-batch (maskCnts); and minimum (minIndex) and maximum (maxIndex) class indices present in the mini-batch.

Value

List object summarizing a mini-batch of image chips and masks.

Examples

## Not run: 
trainStats <- describeBatch(trainDL,
tzeroStart=TRUE,
tusedDS=FALSE)

## End(Not run)

describeChips

Description

Generate data frame of band summary statistics and class pixel counts

Usage

describeChips(
  folder,
  extension = ".tif",
  mode = "All",
  subSample = TRUE,
  numChips = 200,
  numChipsBack = 200,
  subSamplePix = TRUE,
  sampsPerChip = 100
)

Arguments

Details

This function generates a set of summary metrics from image chips and associated masks stored in a directory. For each band, the minimum, median, mean, maximum, and standard deviation are returned (along with some other metrics). For mask data, the count of pixels in each class are returned. These summarizations can be useful for data normalization and determining class weightings in loss calculations.

Value

List object containing the summary metrics for each band in the $ImageStats object and the count of pixels by class in the $maskStats object.

Examples

## Not run: 
chpDescript <- describeChips(folder= "PATH TO CHIPS FOLDER",
                             extension = ".tif",
                             mode = "Positive",
                             subSample = TRUE,
                             numChips = 100,
                             numChipsBack = 100,
                             subSamplePix = TRUE,
                             sampsPerChip = 400)

## End(Not run)

luz_metric_f1score

Description

luz_metric function to calculate the macro-averaged, class aggregated F1-score

Usage

luz_metric_f1score(
  nCls = 1,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  smooth = 1,
  mode = "multiclass",
  biThresh = 0.5,
  clsWghts = rep(1, nCls),
  zeroStart = TRUE,
  usedDS = FALSE
)

Arguments

Details

Calculates F1-score based on luz_metric() for use within training and validation loops.

Value

Calculated metric returned as a base-R vector as opposed to tensor.

Examples

library(terra)
library(torch)
#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred1 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred2 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred3 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred <- c(pred2, pred2, pred3)

#Convert SpatRaster to array
ref <- terra::as.array(ref)
pred <- terra::as.array(pred)

#Convert arrays to tensors and reshape
ref <- torch::torch_tensor(ref, dtype=torch::torch_long())
pred <- torch::torch_tensor(pred, dtype=torch::torch_float32())
ref <- ref$permute(c(3,1,2))
pred <- pred$permute(c(3,1,2))

#Add mini-batch dimension
ref <- ref$unsqueeze(1)
pred <- pred$unsqueeze(1)

#Duplicate tensors to have a batch of two
ref <- torch::torch_cat(list(ref, ref), dim=1)
pred <- torch::torch_cat(list(pred, pred), dim=1)

#Calculate Macro-Averaged, Class Aggregated F1-Score
metric<-luz_metric_f1score(nCls=3,
                           smooth=1e-8,
                           mode = "multiclass",
                           zeroStart=FALSE,
                           usedDS=FALSE)
metric<-metric$new()
metric$update(pred,ref)
metric$compute()

luz_metric_overall_accuracy

Description

luz_metric function to calculate overall accuracy ((correct/total)*100)

Usage

luz_metric_overall_accuracy(
  nCls = 1,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  smooth = 1,
  mode = "multiclass",
  biThresh = 0.5,
  zeroStart = TRUE,
  usedDS = FALSE
)

Arguments

Value

Calculated metric returned as a base-R vector as opposed to tensor.

Examples

require(terra)
require(torch)
#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred1 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred2 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred3 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred <- c(pred2, pred2, pred3)

#Convert SpatRaster to array
ref <- terra::as.array(ref)
pred <- terra::as.array(pred)

#Convert arrays to tensors and reshape
ref <- torch::torch_tensor(ref, dtype=torch::torch_long())
pred <- torch::torch_tensor(pred, dtype=torch::torch_float32())
ref <- ref$permute(c(3,1,2))
pred <- pred$permute(c(3,1,2))

#Add mini-batch dimension
ref <- ref$unsqueeze(1)
pred <- pred$unsqueeze(1)

#Duplicate tensors to have a batch of two
ref <- torch::torch_cat(list(ref, ref), dim=1)
pred <- torch::torch_cat(list(pred, pred), dim=1)

#Calculate Overall Accuracy
metric<-luz_metric_overall_accuracy(nCls=3,
                                   smooth=1e-8,
                                    mode = "multiclass",
                                   zeroStart=FALSE,
                                   usedDS=FALSE)
metric<-metric$new()
metric$update(pred,ref)
metric$compute()

luz_metric_precision

Description

luz_metric function to calculate macro-averaged, class aggregated precision

Usage

luz_metric_precision(
  nCls = 3,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  smooth = 1,
  mode = "multiclass",
  biThresh = 0.5,
  zeroStart = TRUE,
  clsWghts = rep(1, nCls),
  usedDS = FALSE
)

Arguments

Details

Calculates precision based on luz_metric() for use within training and validation loops.

Value

Calculated metric returned as a base-R vector as opposed to tensor.

Examples

library(terra)
library(torch)
#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred1 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred2 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred3 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred <- c(pred2, pred2, pred3)

#Convert SpatRaster to array
ref <- terra::as.array(ref)
pred <- terra::as.array(pred)

#Convert arrays to tensors and reshape
ref <- torch::torch_tensor(ref, dtype=torch::torch_long())
pred <- torch::torch_tensor(pred, dtype=torch::torch_float32())
ref <- ref$permute(c(3,1,2))
pred <- pred$permute(c(3,1,2))

#Add mini-batch dimension
ref <- ref$unsqueeze(1)
pred <- pred$unsqueeze(1)

#Duplicate tensors to have a batch of two
ref <- torch::torch_cat(list(ref, ref), dim=1)
pred <- torch::torch_cat(list(pred, pred), dim=1)
#Calculate Macro-Averaged, Class Aggregated Precision
metric<-luz_metric_precision(nCls=3,
                             smooth=1e-8,
                             mode = "multiclass",
                             zeroStart=FALSE,
                             usedDS=FALSE)
metric<-metric$new()
metric$update(pred,ref)
metric$compute()

luz_metric_recall

Description

luz_metric function to calculate macro-averaged, class aggregated recall

Usage

luz_metric_recall(
  nCls = 3,
  cropFactorMsk = 0,
  cropFactorPred = 0,
  smooth = 1,
  mode = "multiclass",
  biThresh = 0.5,
  zeroStart = TRUE,
  clsWghts = rep(1, nCls),
  usedDS = FALSE
)

Arguments

Details

Calculates recall based on luz_metric() for use within training and validation loops.

Value

Calculated metric returned as a base-R vector as opposed to tensor.

Examples

library(terra)
library(torch)
#Generate example data as SpatRasters
ref <- terra::rast(matrix(sample(c(1, 2, 3), 625, replace=TRUE), nrow=25, ncol=25))
pred1 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred2 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred3 <- terra::rast(matrix(sample(c(1:150), 625, replace=TRUE), nrow=25, ncol=25))
pred <- c(pred2, pred2, pred3)

#Convert SpatRaster to array
ref <- terra::as.array(ref)
pred <- terra::as.array(pred)

#Convert arrays to tensors and reshape
ref <- torch::torch_tensor(ref, dtype=torch::torch_long())
pred <- torch::torch_tensor(pred, dtype=torch::torch_float32())
ref <- ref$permute(c(3,1,2))
pred <- pred$permute(c(3,1,2))

#Add mini-batch dimension
ref <- ref$unsqueeze(1)
pred <- pred$unsqueeze(1)

#Duplicate tensors to have a batch of two
ref <- torch::torch_cat(list(ref, ref), dim=1)
pred <- torch::torch_cat(list(pred, pred), dim=1)

#Calculate Macro-Averaged, Class Aggregated Recall
metric<-luz_metric_recall(nCls=3,
                          smooth=1e-8,
                          mode = "multiclass",
                          zeroStart=FALSE,
                          usedDS=FALSE)
metric<-metric$new()
metric$update(pred,ref)
metric$compute()

makeAspect

Description

Calculate aspect or slope orientation or a related metric from a digital terrain model (DTM) using torch

Usage

makeAspect(
  dtm,
  cellSize = 1,
  flatThreshold = 1,
  mode = "aspect",
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

Calculate topographic aspect or slope orientation or a related metric using torch in degree units. Processing on the GPU can be much faster than using base R and non-tensor-based calculations. "aspect" = topographic aspect in degree units where flat slopes are coded to -1; "northness" = cosine of aspect in radians; "eastness" = sine of aspect in radians; "trasp" = topographic radiation aspect index; "sei" = site exposure index.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
aspR <- makeAspect(dtm, cellSize=1,
flatThreshold=1,
mode= "aspect",
writeRaster=TRUE,
outName=paste0(pth, "asp.tif"),
device="cuda")

## End(Not run)

makeChips

Description

Generate image chips from images and associated raster masks

Usage

makeChips(
  image,
  mask,
  n_channels = 3,
  size = 256,
  stride_x = 256,
  stride_y = 256,
  outDir,
  mode = "All",
  useExistingDir = FALSE
)

Arguments

Details

This function generates image and mask chips from an input image and associated raster mask. The chips are written into the defined directory. The number of rows and columns of pixels in each chip are equal to the size argument. If a stride_x and/or stride_y is used that is different from the size argument, resulting chips will either overlap or have gaps between them. In order to not have overlap or gaps, the stride_x and stride_y arguments should be the same as the size argument. Both the image chips and associated masks are written to TIFF format (".tif"). Input data are not limited to three band images. This function is specifically for a binary classification where the positive case is indicated with a cell value of 1 and the background or negative case is indicated with a cell value of 0. If an irregular shaped raster grid is provided, only chips and masks that contain no NA or NoDATA cells will be produced.

Three modes are available. If "All" is used, all image chips are generated even if they do not contain pixels mapped to the positive case. Within the provided directory, image chips will be written to an "images" folder and masks will be written to a "masks" folder. If "Positive" is used, only chips that have at least 1 pixel mapped to the positive class will be produced. Background- only chips will not be generated. Within the provided directory, image chips will be written to an "images" folder and masks will be written to a "masks" folder. Lastly, if the "Divided" method is used, separate "positive" and "background" folders will be created with "images" and "masks" subfolders. Any chip that has at least 1 pixel mapped to the positive class will be written to the "positive" folder while any chip having only background pixels will be written to the "background" folder.

Value

Image and mask files written to disk in TIFF format. No R object is returned.

Examples

## Not run: 
makeChips(image = "INPUT IMAGE FILE NAME AND PATH",
          mask = "INPUT RASTER MASK FILE NAME AND PATH",
          n_channels = 3,
          size = 256,
          stride_x = 256,
          stride_y = 256,
          outDir = "OUTPUT DIRECTY IN WHICH TO SAVE CHIPS",
          mode = "Positive",
          useExistingDir=FALSE)

## End(Not run)

makeChipsDF

Description

Create data frame and CSV file listing image chips and associated masks

Usage

makeChipsDF(
  folder,
  outCSV,
  extension = ".tif",
  mode = "All",
  shuffle = FALSE,
  saveCSV = FALSE
)

Arguments

Details

This function creates a data frame and, optionally, a CSV file that lists all of the image chips and associated masks in a directory. Three columns are produced. The chpN column provides the name of the chip, the chpPth column provides the path to the chip, and the chpMsk column provides the path to the associated mask. All paths are relative to the input folder as opposed to the full file path so that the results can still be used if the data are copied to a new location on disk or to a new computer.

Value

Data frame with three columns (chpN, chpPth, and mskPth) and, optionally, a CSV file written to disk. If mode = "Divided", a division column is added to differentiate "positive" and "background" samples.

Examples

## Not run: 
chpDF <- makeChipsDF(folder = "PATHT TO CHIPS FOLDER",
                      outCSV = "OUTPUT CSV FILE AND PATH",
                      extension = ".tif",
                      mode="Positive",
                      shuffle=TRUE,
                      saveCSV=TRUE)

## End(Not run)

makeChipsMultiClass

Description

Generate image chips from images and associated raster masks for multiclass classification

Usage

makeChipsMultiClass(
  image,
  mask,
  n_channels = 3,
  size = 256,
  stride_x = 256,
  stride_y = 256,
  outDir,
  useExistingDir = FALSE
)

Arguments

Details

This function generates image and mask chips from an input image and associated raster mask. The chips will be written into the defined directory. The number of rows and columns of pixels per chip are equal to the size argument. If a stride_x and/or stride_y is used that is different from the size argument, resulting chips will either overlap or have gaps between them. In order to not have overlap or gaps, the stride_x and stride_y arguments should be the same as the size argument. Both the image chips and associated masks are written to TIFF format (".tif"). Input data are not limited to three band images. This function is specifically for a multiclass classification. For a binary classification or when only two classes are differentiated, use the makeChips() function. If an irregular shaped raster grid is provided, only chips and masks that contain no NA or NoDATA cells will be produced.

Within the provided directory, image chips will be written to an "images" folder and masks will be written to a "masks" folder.

Value

Image and mask files written to disk in TIFF format. No R object is returned.

Examples

## Not run: 
makeChipsMultiClass(image = "INPUT IMAGE NAME AND PATH",
                    mask = "INPUT RASTER MASK NAME AND PATH",
                    n_channels = 3,
                    size = 512,
                    stride_x = 512,
                    stride_y = 512,
                    outDir = "DIRECTORY IN WHICH TO SAVE CHIPS",
                    useExistingDir=FALSE)

## End(Not run)

makeCrv

Description

Calculate surface curvatures from input digital terrain model (DTM) using torch

Usage

makeCrv(
  dtm,
  cellSize = 1,
  mode = "mean",
  smoothRadius = 7,
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

Calculate surface curvatures from input digital terrain model (DTM) using torch. "mean" = mean curvature or average of profile and planform curvature; "profile" = curvature in the direction of maximum slope; "planform" = curvature in the direction perpendicular to the direction of maximum slope. Radii are specified using cell counts as opposed to map distance. Gaussian smoothing using a circular window of a user-defined radius is applied prior to calculating curvatures to minimize the impact of local noise/variability.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
crvPro7 <- makeCrv(dtm,
cellSize=1,
mode="profile",
smoothRadius=7,
writeRaster=TRUE,
outName=paste0(pth, "crvPro7.tif"),
device="cuda")

## End(Not run)

makeDynamicChipsSF

Description

Generate a vector point sf object of chip center locations for use with defineDynamicSegDataSet().

Usage

makeDynamicChipsSF(
  featPth,
  featName,
  extentPth,
  extentName,
  extentCrop = 50,
  imgPth,
  imgName,
  doBackground = FALSE,
  backgroundCnt,
  backgroundDist,
  useSeed = FALSE,
  seed,
  doShuffle = FALSE
)

Arguments

Details

Requires an input vector object of feature examples, a boundary extent, and the path and name of the associated raster predictor variables. Note that the raster predictor variable must cover the full spatial extent defined by the extent object. If not, a smaller extent should be defined for which predictor variables are available.

The input vector features must contain a "code" column of numeric class codes and a "class" column of text class names. If the data are not spatial contiguous, we recommend reserving code 0 for the background class.

The extent can be cropped to avoid generating chips without a full set of cells available. We recommend cropping by a factor larger than 50% the width/height of the desired chip size.

The tool returns a sf dataframe with class name ("class"), class numeric code ("code"), path to the image or predictor variables ("imgPth"), name of the image or predictor variables ("imgName"), the path to the input features ("featPth"), the file name of the input features ("featName"), the file path to the extent ("extentPth"), the file name for the extent ("extentName"), and the point feature geometry ("geometry").

Value

sf dataframe object of center locations for chip creation with associated information as attributes.

makeAspect

Description

Calculate a hillshde from a digital terrain model (DTM) using torch

Usage

makeHillshade(
  dtm,
  cellSize = 1,
  sunAzimuth = 315,
  sunAltitude = 45,
  doMD = FALSE,
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

Calculate a hillshade from a digital terrain model (DTM) using torch. User can specify a illuminating position using an aspect and altitude. A multidirectiontal hillshade is calculated by averaging hillshades with different sun positions ((north X 2Xnorthwest X west X southeast)/5.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
hsR <- makeHillshade(dtm,
cellSize=1,
sunAzimuth=315,
sunAltitude=45,
doMD = FALSE,
writeRaster=TRUE,
outName=paste0(pth, "hs.tif"), device="cuda")

## End(Not run)

makeMasks

Description

Make raster mask from input vector data

Usage

makeMasks(
  image,
  features,
  crop = FALSE,
  extent,
  field,
  background = 0,
  outImage,
  outMask,
  mode = "Both"
)

Arguments

Details

This function creates a raster mask from input vector data. The cell value is indicated by the field parameter. A unique numeric code should be provided for each class. In the case of a binary classification, 0 should indicate background and 1 should indicate positive. For a multiclass problem, values should be sequential from 0 to n-1, where n is the number of classes, or 1 to n. We recommend using 1 to n. If no cropping is applied, the generated raster mask will have the same spatial extent, number of rows of pixels, number of columns of pixels, cell size, and coordinate reference system as the input image.

Value

Single-band raster mask written to disk in TIFF format and, optionally, a copy of the image written to disk. Cropping may be applied as specified. No R objects are returned.

Examples

## Not run: 
makeMasks(image = "INPUT IMAGE FILE AND PATH",
          features = "INPUT VECTOR FEATURES FILE AND PATH",
          crop = TRUE,
          extent = "INPUT VECTOR BOUNDARY and PATH",
          field = "ATTRIBUTE COLUMN NAME",
          background = 0,
          outImage = "OUTPUT IMAGE NAME AND PATH",
          outMask = "OUTPUT MASK NAME AND PATH",
          mode = "Both")

## End(Not run)

makeSlope

Description

Calculate slope from a digital terrain model (DTM) using torch

Usage

makeSlope(dtm, cellSize = 1, writeRaster = FALSE, outName, device = "cpu")

Arguments

Details

Calculate topographic slope using torch in degree units. Processing on the GPU can be much faster than using base R and non-tensor-based calculations.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
slpR <- makeSlope(dtm, cellSize=1, writeRaster=TRUE, outName=paste0(pth, "slp.tif"), device="cuda")

## End(Not run)

makeTPI

Description

Calculate a topographic position index (TPI) from a digital terrain model (DTM) using torch

Usage

makeTPI(
  dtm,
  cellSize = 1,
  innerRadius = 2,
  outerRadius = 10,
  mode = "circle",
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

Calculate a topographic position index (TPI) from a digital terrain model (DTM) using torch. TPI is calculated as the center cell elevation minus the mean elevation in a local moving window. Large, positive values indicate local topographic high points while large, negative values indicate topographic low points. Near zero values indicate flat areas. Larger windows can characterize the hillslope position of a cell while smaller windows can capture local topographic variability. Radii are specified using cell counts as opposed to map distance.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
tpiA3_11 <- makeTPI(dtm,cellSize=1,
innerRadius=3,
outerRadius=11,
mode="circle",
writeRaster=TRUE,
outName=paste0(pth, "tpiA3_11.tif"),
device="cuda")

## End(Not run)

makeTRI

Description

Calculate a topographic roughness index (TRI) from a digital terrain model (DTM) using torch

Usage

makeTRI(
  dtm,
  cellSize = 1,
  roughRadius = 7,
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

Calculate a topographic roughness index (TPI) from a digital terrain model (DTM) using torch. Us calculated as the square root of the standard deviation of slope in a local moving window. Output can be noisy. Radii are specified using cell counts as opposed to map distance.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
tri11 <- makeTRI(dtm,
cellSize=1,
roughRadius=11,
writeRaster=TRUE,
outName=paste0(pth, "tri11f.tif"),
device="cuda")

## End(Not run)

makeTerrainVisTerra

Description

Make three band terrain stack from input digital terrain model using terra

Usage

makeTerrainVisTerra(
  dtm,
  cellSize,
  innerRadius = 2,
  outerRadius = 10,
  hsRadius = 50,
  writeRaster = FALSE,
  outName
)

Arguments

Details

This function creates a three-band raster stack from an input digital terrain model (DTM) of bare earth surface elevations using terra. This implementation is slower than the torch-based implementation, especially when the torh-based implementation uses GPU-based computation.

The first band is a topographic position index (TPI) calculated using a moving window with a 50 m circular radius. The second band is the square root of slope calculated in degrees. The third band is a TPI calculated using an annulus moving window with an inner radius of 2 and outer radius of 5 meters. The TPI values are clamped to a range of -10 to 10 then linearly rescaled from 0 and 1. The square root of slope is clamped to a ange of 0 to 10 then linearly rescaled from 0 to 1. Values are provided in floating point.

The stack is described in the following publication and was originally proposed by William Odom of the United States Geological Survey (USGS):

Maxwell, A.E., W.E. Odom, C.M. Shobe, D.H. Doctor, M.S. Bester, and T. Ore, 2023. Exploring the influence of input feature space on CNN-based geomorphic feature extraction from digital terrain data, Earth and Space Science, 10: e2023EA002845. https://doi.org/10.1029/2023EA002845.

Value

Three-band raster grid written to disk in TIFF format and spatRaster object.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
tVisT <- makeTerrainVisTerra(dtm,
cellSize=1,
innerRadius=2,
outerRadius=5,
hsRadius=50,
writeRaster=TRUE,
outName=paste0(pth, "tVisTerra.tif"))

## End(Not run)

makeTerrainVisTerra

Description

Make three band terrain stack from input digital terrain model using torch

Usage

makeTerrainVisTorch(
  dtm,
  cellSize = 1,
  innerRadius = 2,
  outerRadius = 10,
  hsRadius = 50,
  writeRaster = FALSE,
  outName,
  device = "cpu"
)

Arguments

Details

This function creates a three-band raster stack from an input digital terrain model (DTM) of bare earth surface elevations using torch. This implementation is faster than the terra-based implementation, especially when using GPU-based computation.

The first band is a topographic position index (TPI) calculated using a moving window with a 50 m circular radius. The second band is the square root of slope calculated in degrees. The third band is a TPI calculated using an annulus moving window with an inner radius of 2 and outer radius of 5 meters. The TPI values are clamped to a range of -10 to 10 then linearly rescaled from 0 and 1. The square root of slope is clamped to a ange of 0 to 10 then linearly rescaled from 0 to 1. Values are provided in floating point.

The stack is described in the following publication and was originally proposed by William Odom of the United States Geological Survey (USGS):

Maxwell, A.E., W.E. Odom, C.M. Shobe, D.H. Doctor, M.S. Bester, and T. Ore, 2023. Exploring the influence of input feature space on CNN-based geomorphic feature extraction from digital terrain data, Earth and Space Science, 10: e2023EA002845. https://doi.org/10.1029/2023EA002845.

Value

Three-band raster grid written to disk in TIFF format and spatRaster object.

Examples

## Not run: 
pth <- "OUTPUT PATH"
dtm <- rast(paste0(pth, "dtm.tif"))
tVis <- makeTerrainVisTorch(dtm,
cellSize=1,
innerRadius=2,
outerRadius=5,
hsRadius=50,
writeRaster=TRUE,
outName=paste0(pth, "tVisTorch.tif"),
device="cuda")

## End(Not run)

predictSpatial

Description

Apply a trained semantic segmentation model to predict back to geospatial raster data

Usage

predictSpatial(
  imgIn,
  model,
  predOut,
  mode = "multiclass",
  predType = "class",
  biThresh = 0.5,
  doPad = FALSE,
  predPad = 0,
  useCUDA = FALSE,
  nCls,
  chpSize,
  stride_x,
  stride_y,
  crop,
  nChn = 3,
  normalize = FALSE,
  bMns,
  bSDs,
  rescaleFactor = 1,
  usedDS = FALSE
)

Arguments

Details

This function generates a pixel-by-pixel prediction using input data and a trained semantic segmentation model. Can return either hard classifications, logits, or rescaled logits with a sigmoid or softmax activation applied. Note that this package treats all problems as multiclass problems and does not differentiate between binary and multiclass classification. As a result, in our workflow the multiclass mode should be used. Result is written to disk and provided as a spatRaster object. If you are experiencing memory issues, you may need to break larger raster extents into smaller tiles for processing.

Value

A spatRast object and a raster grid saved to disk of predicted class indices (predType = "class"), logits (predType = "logit"), or rescaled logits (predType = "prob").

Examples

## Not run: 
#Predict classification
predCls <- predictSpatial(imgIn="INPUT IMAGE NAME AND PATH",
                          model=model,
                          predOut="OUTPUT RASTER NAME AND PATH",
                          mode="multiclass",
                          predType="class",
                          useCUDA=TRUE,
                          nCls=2,
                          chpSize=256,
                          stride_x=128,
                          stride_y=128,
                          crop=50,
                          nChn=3,
                          normalize=FALSE,
                          rescaleFactor=255,
                          usedDS=FALSE)

## End(Not run)

saveDynamicChips

Description

Save chips meant to be generated dynamically to disk.

Usage

saveDynamicChips(
  chipsSF,
  chipSize = 512,
  cellSize = 1,
  outDir,
  mode = "All",
  useExistingDir = FALSE,
  doJitter = FALSE,
  jitterSD = 15,
  useSeed = TRUE,
  seed = 42
)

Arguments

Details

Save chips defined by defineDynamicChips() to disk. It is not required to save dynamically generated chips to disk. This is primarily a utility function.

Value

chips and masks written to disk. No R object is returned.

viewBatch

Description

Generate image grid of mini-batch of image chips and associated masks created by a DataLoader.

Usage

viewBatch(
  dataLoader,
  nCols = 3,
  r = 1,
  g = 2,
  b = 3,
  cCodes,
  cNames,
  cColors,
  padding = 10
)

Arguments

Details

The goal of this function is to provide a visual check of a mini-batch of image chips and associated masks generated from a DataLoader.

Value

Image grids of example chips and masks loaded from a mini-batch produced by the DataLoader.

Examples

## Not run: 
viewBatch(dataLoader=trainDL,
          nCols = 5,
          r = 1,
          g = 2,
          b = 3,
          cCodes=c(1,2),
          cNames=c("Background", "Mine"),
          cColors=c("gray", "darksalmon"))

## End(Not run)

viewBatchPreds

Description

Generate image grid of mini-batch of image chips, masks, and predictions for all samples in a DataLoader mini-batch.

Usage

viewBatchPreds(
  dataLoader,
  model,
  mode = "multiclass",
  nCols = 4,
  padding = 10,
  r = 1,
  g = 2,
  b = 3,
  cCodes,
  cNames,
  cColors,
  useCUDA = TRUE,
  probs = FALSE,
  usedDS = FALSE
)

Arguments

Details

The goal of this function is to provide a visual check of predictions for a mini-batch of data.

Value

Image grids of example chips, reference masks, and predictions loaded from a mini-batch provided by the DataLoader.

Examples

## Not run: 
viewBatchPreds(dataLoader=testDL,
               model=model,
               mode="multiclass",
               nCols =5,
               r = 1,
               g = 2,
               b = 3,
               cCodes=c(1,2),
               cNames=c("Not Mine", "Mine"),
               cColors=c("gray", "darksalmon"),
               useCUDA=TRUE,
               probs=FALSE,
               usedDS=FALSE)

## End(Not run)

viewChips

Description

Plot a grid of image and/or mask chips

Usage

viewChips(
  chpDF,
  folder,
  nSamps = 16,
  mode = "both",
  justPositive = FALSE,
  cCnt = 4,
  rCnt = 4,
  r = 1,
  g = 2,
  b = 3,
  rescale = FALSE,
  rescaleVal = 1,
  cCodes,
  cNames,
  cColors,
  useSeed = FALSE,
  seed = 42
)

Arguments

Details

This function generates a plot of image chips and/or image masks. It serves as a means to visualize chips generated with the makeChips() or makeChipsMultiClass() function. It can be used as a check to make sure chips were generated as expected.

Value

Plot of image chip grid (if mode = "image"); plot of mask chip grid (if mode ="mask"); plot of image and mask chip grids (if model = "both").

Examples

## Not run: 
viewChips(chpDF=chpDF,
          folder= "FOLDER CONTAINING CHIPS",
          nSamps = 16,
          mode = "both",
          justPositive = FALSE,
          cCnt = 4,
          rCnt = 4,
          r = 1,
          g = 2,
          b = 3,
          rescale = FALSE,
          rescaleVal = 1,
          cCodes=c(0,1,2,3,4),
          cNames=c("Background",
                   "Building",
                   "Woodland",
                   "Water",
                   "Road"),
          cColor=c("gray",
                   "darksalmon",
                    "forestgreen",
                    "lightblue",
                    "black"),
          useSeed = FALSE,
          seed = 42)

## End(Not run)