MODISoptions: Set or Retrieve Permanent MODIS Package Options
In MatMatt/MODIS: Acquisition and Processing of MODIS Products

MODISoptions

R Documentation

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
)

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.

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().

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.

Author(s)

Matteo Mattiuzzi, Steven Mosher and Florian Detsch

Examples

## Not run: 
## get options
MODISoptions()

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

MODISoptions(localArcPath = lap, outDirPath = odp)

## End(Not run)

MatMatt/MODIS documentation built on Feb. 1, 2023, 12:39 a.m.