Skip to contents

idps-Example

Source: vignettes/idps-Example.Rmd
idps-Example.Rmd

Downloading IMERG Data

Firstly, we download IMERG data for 18 December 20181.

library(idps)
# Define the input variables
DATE <- as.Date("2020-12-18")
path <- "/path/to/where/files/should/be/stored"
user <- "username"
password <- "your password"
band <- "precipitation"
lonMin <- 20
lonMax <- 70
latMin <- -5
latMax <- 40
# The data is originally in HDF5 format. This will remove original files
removeHDF5 <- TRUE
# --no verbose option for wget
quiet <- TRUE

IMERG_download_V07(
  path = path,
  user = user,
  password = password,
  dates = DATES,
  band = band,
  lonMin = lonMin,
  lonMax = lonMax,
  latMin = latMin,
  latMax = latMax,
  removeHDF5 = FALSE,
  quiet = TRUE
)

Preprocessing IMERG Data

Second, we preprocess the IMERG file by applying smoothing and removing values below the threshold (0.5 mm/hr). We use 3X3 smoothing. Additionally, we split the file into dry and wet periods, where dry periods are discarded and wet periods form precipitation system files. There are no dry timesteps in the file. Therefore, the function produces one file.

path <- "/path/to/IMERG/files"

netCDF.file <- list.files(
  path = path,
  full.names = T,
  pattern = ".nc$"
)

split_netCDF_files(
  netCDF.file = netCDF.file,
  threshold = 0.5,
  n = 3,
  sub_region = NA,
  window_size = 64, # the size of the largest PIV sub interrogation
  output.path = "/path/to/store/system/files/"
)

Note: Both function use the r package terra to read and process HDF5 and NetCDF files with a compression level of 9. For more information, please check here.

Tracking

Afterwards, we apply the tracking algorithm to the system file. The subwindows size for the PIV multi-pass approach are 64X64, 32X32, 16X16, and 16X16. The objects’ translation speed is truncated using the max_speed parameter. The search radius is set to 4 for the distance-matching approach, while the overlap percentage is set to 10%.

sys.file <- list.files(
  path = "/path/to/store/system/files/",
  full.names = T,
  pattern = ".nc$"
)

tracking_algorithm(
  sys.file = sys.file,
  window_size = c(64, 32, 16, 16),
  max_speed = 27,
  search.radius = 4,
  overlap.percentage = 0.1,
  output.path = "/path/to/store/track/files/"
)

Plotting Tracks

Using plot_tracks, the tracks can be plotted directly from the HDF5 file and saved to PNG. In case of merging or splitting objects, the position on the track is estimated as the area-weighted average of the objects’ centres.

h5.file <- "/path/to/tracks/file.h5"

plot_tracks(
  h5.file,
  tz = "Asia/Riyadh",
  show.singleCells = TRUE,
  map.limits = c(31, 63, 10, 35),
  image.size = c(110, 140),
  output.path = "/path/to/save/image/"
)

Reading Tracks

The idps package includes functions to read and write tracks from HDF5 files. We can read the objects’ information in the tracks using readTracks with the “object_info” option. The sequence of the objects in the tracks can be obtained using “tracks_info”.

# track file
h5.file <- "/path/to/tracks/file.h5"

# read
tracks <- readTracks(h5.file, "track_info")
objects <- readTracks(h5.file, "object_info")

Furthermore, the tracks can filtered either spatially or in terms of precipitation intensity. Either retaining tracks that pass over a specific region using filter_by_areaor that reach a minimum precipitation intensity at least once during their lifetime using filter_pixel.

# filter by area - Arabian Peninsula
AP <- sf::st_read(system.file("geo/AP.gpkg",
  package = "idps"
))
polygon <- sf::st_geometry(AP) |>
  sf::st_coordinates()

polygon <- polygon[, 1:2]

objects_res <- filter_by_area(
  objects,
  polygon
)


# filter by pixel intensity
res_tmp <- filter_by_pixel(
  PC.df = objects_res %>%
    dplyr::select(storms, ObjectID, PC),
  precip.min = 3
)

# final objects data frame
objects_res <- objects_res %>%
  dplyr::filter(storms %in% unique(res_tmp$storms))

# final tracks data frame
tracks_res <- tracks %>%
  dplyr::filter(storms %in% unique(res_tmp$storms))

We can write the filtered to HDF5 file similar to the original one.

# write
writeTracks2HDF5(
  final.df = objects_res,
  extra.df = tracks_res,
  filename = "filtered.h5",
  output.path = "/path/to/filtered/tracks",
  verbose = FALSE
)

Animating Tracks 

# create temp dir
temp.dir <- tempfile()

animate_tracks(h5.file,
  tz = "Asia/Riyadh",
  show.sequence = FALSE,
  map.limits = c(31, 63, 10, 35),
  image.size = c(110, 140),
  temp.dir,
  output.path = "/path/to/filtered/tracks"
)