MODIS (version 1.2.11)

MODISoptions: Set or Retrieve Permanent MODIS Package Options

Description

Set or retrieve MODIS package options (per user or system-wide). If save = TRUE (default), changes will persist through sessions and updates.

Usage

MODISoptions(
  localArcPath,
  outDirPath,
  pixelSize,
  outProj,
  resamplingType,
  dataFormat,
  gdalPath,
  MODISserverOrder,
  dlmethod,
  stubbornness,
  wait,
  quiet,
  cellchunk,
  systemwide = FALSE,
  save = TRUE,
  checkTools = TRUE,
  checkWriteDrivers = TRUE,
  ask = TRUE,
  check_earthdata_login = TRUE
)

Value

An invisible list of MODIS options. In addition, the most relevant of these options are printed to the console. Use utils::capture.output() to prevent this behavior.

Arguments

localArcPath

character, defaults to file.path(tempdir(), "MODIS_ARC"). Target folder for downloaded MODIS HDF files.

outDirPath

character, defaults to file.path(tempdir(), "MODIS_ARC/PROCESSED"). Target folder for results of runGdal() and runMrt().

pixelSize

Output pixel size (in target reference system units) passed to runGdal() and runMrt(), defaults to "asIn".

outProj

Target reference system passed to runGdal() and runMrt(). runGdal() requires a valid CRS. As for runMrt(), please consult the MRT manual. Since the two processing methods do not have common methods, it is suggested to stick with the default settings (see Details).

resamplingType

Defaults to "NN" (Nearest Neighbor). MRT and GDAL both support c('NN', 'CC', 'BIL'). GDAL additionally supports all resampling methods listed under https://gdal.org/programs/gdalwarp.html.

dataFormat

character, defaults to "GTiff". See sf::st_drivers(what = "raster") for available options.

gdalPath

character. Path to GDAL binary executable, used to relate writable sf::st_drivers("raster") to file extensions in case of non-standard formats.

MODISserverOrder

character. Possible options are "LPDAAC" (default), "LAADS" (see 'dlmethod' and Details). If only one server is selected, all efforts to download data from the second server are inhibited.

dlmethod

character, defaults to "auto". See 'method' in utils::download.file() for available options. If installed, you can also leverage "aria2" for multi-source download. Note that in any case, either curl or wget must be installed and made available through the system's PATH environment variable to validate Earthdata Login credentials.

stubbornness

numeric. The number of retries after the target server has refused a connection. Higher values increase the chance of getting the file, but also lead to hanging functions if the server is down.

wait

numeric waiting time (in seconds) inserted after each internal online download call via utils::download.file() or curl::curl(). Reduces the chance of connection errors that may occur after many requests.

quiet

logical passed e.g. to utils::download.file() and sf::gdal_utils().

cellchunk

Default 1, i.e. use raster default. Comparable with 'chunksize' in raster::rasterOptions(), but as no effect was found in adapting chunksize, MODIS applies its own variant. On a reasonable working station, 'cellchunk' can easily be increased to 5e5.

systemwide

A logical determining whether changes made to MODISoptions() are to be applied system-wide or per user (default), see Details.

save

logical. If TRUE (default), settings are permanent.

checkTools

logical, defaults to TRUE. Check if external tools (i.e., GDAL and MRT) are installed and reachable through R.

checkWriteDrivers

logical. If TRUE (default), find write drivers supported by sf GDAL installation.

ask

logical. If TRUE (default) and permanent settings file does not exist (see Details), the user is asked whether to create it.

check_earthdata_login

logical. If TRUE (default), look for Earthdata Login credentials in ~/.netrc and try to download a small sample .hdf file.

Author

Matteo Mattiuzzi, Steven Mosher and Florian Detsch

Details

These settings are easy to change and take effect immediately! However, please mind that the CRAN Repository Policy does not permit automated write access to the user's file system exempt for tempdir(). Therefore, changes made to MODISoptions() remain temporary for the current session unless write access is explicitly granted by the user in interactive mode, in which case a permanent settings file is created in file.path("~/.MODIS_Opts.R") (per user) or file.path(R.home(component = "etc"), '.MODIS_Opts.R') (system-wide, write access provided).

Due to similar reasons, 'localArcPath' and 'outDirPath' default to tempdir() and should be changed immediately after loading the package in order to make downloaded files permanently available. You may also specify a shared network drive if you have a central MODIS data server.

If you change default values, consider that your settings have to be valid for any MODIS product, layer and area!

Please note that in order to download MODIS files from any available server, you are required to

• register for an Earthdata Login profile at https://urs.earthdata.nasa.gov/users/new,

• fill out mandatory fields therein, and

• create a .netrc file in your home directory containing the Earthdata server address and your login credentials. An automated solution for the creation of such a file is provided through EarthdataLogin().

Examples

if (FALSE) {
## get options
MODISoptions()

## set options
lap = "/another/path/to/MODIS_ARC" # 'localArcPath'
odp = file.path(lap, "PROCESSED")  # 'outDirPath'

MODISoptions(localArcPath = lap, outDirPath = odp)
}