MODIS (version 1.1.7)

MODISoptions: Set or Retrieve Permanent MODIS Package Options

Description

Set or retrieve persistant MODIS package options (per user or systemwide). Changes here 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
)

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 pocessing methods do not have common methods, it is suggested to stick with the default settings (see Details).

resamplingType

Defaults to "NN" (Nearest Neightbour). MRT and GDAL both support c('NN', 'CC', 'BIL'). In addition, GDAL supports cubicspline and lanczos and, from GDAL >= 1.10.0 onwards, also mode and average.

dataFormat

character, defaults to "GTiff". One of getOption("MODIS_gdalOutDriver") (column 'name').

gdalPath

character. Path to gdal bin directory and more relevant for Windows users. Use MODIS:::checkTools("GDAL") to try to detect it automatically.

MODISserverOrder

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

dlmethod

character, defaults to auto. See 'method' in download.file. On Unix (also Mac?), it is suggested to use "wget" or, if installed, "aria2" (supports multi source download). In order to download MODIS files from LP DAAC and NSIDC, please note that either wget (default) or curl must be installed and made available through the PATH environmental variable.

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 download.file or curl. Reduces the chance of connection errors that frequently occur after many requests.

quiet

logical passed eg to download.file which is called from inside getHdf.

cellchunk

Default 1 (=use raster default), comparable with chunksize in rasterOptions. But as no effect was found in adapting chunksize, MODIS applies its own variant: minrows <- max(floor(cellchunk/ncol(x)),1) blockSize(x,minrows=minrows). On a reasonable working station you can easily increase cellchunk to 500000.

systemwide

A logical determining whether changes made to MODISoptions are to be applied system or user-wide (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 local GDAL installation.

ask

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

Value

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

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 temporally limited to the current R 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") (user-wide) or file.path(R.home(component = "etc"), '.MODIS_Opts.R') (system-wide, write access provided).

Due to similar reasons, 'localArcPath' and 'outDirPath' default to R's 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!

It is not recommended to use

• a coordinate reference system that is not applicable globally as default for 'outProj',

• or a fixed 'pixelSize' for different products,

• or a 'resamplingType' that is not "NN".

On Windows, you have to set 'gdalPath' to the location of GDAL executables (i.e., the '.../GDAL../bin' directory). On Unix-alikes, this should not be required unless you want to specify a non-default GDAL installation.

On an unixoid OS, it is suggested to use dlmethod = 'wget' because it is a reliable tool and, after the change of the 'LP DAAC' datapool from FTP to HTTP (May 2013), dlmethod = 'auto' seems not to work properly. On Windows, on the other hand, dlmethod = 'auto' seems to work fine.

Please note that in order to download MODIS files from LP DAAC and NSIDC, you are required to register for an Earthdata Login Profile (https://urs.earthdata.nasa.gov/users/new) and create a read-only .netrc file in your home directory containing the Earthdata server address as well as your login credentials. An automated solution for the creation of a workable .netrc file is provided through EarthdataLogin.

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)
# }
# NOT RUN {
# }