pkgOptions: Set or get options for the Rnightlights package

In chrisvwn/Rnightlights: Satellite Nightlight Data Extraction

Description

Set or get options for the Rnightlights package

Usage

pkgOptions(...)

Arguments

...	Option names to retrieve option values or [key]=[value] pairs to set options.

Value

if an option name is supplied as a parameter this returns the value, else a list of all options is returned.

Supported options

The following options are supported

configName_OLS.Y

(character) The regex to uniquely identify the tile file to use out of the downloaded tile .tar. The data are available as annual composited series:

• cf_cvg (Cloud-free coverages): tally the total number of observations that went into each 30 arc second grid cell. This image can be used to identify areas with low numbers of observations where the quality is reduced. In some years there are areas with zero cloud- free observations in certain locations.

• avg_vis (Raw average visible band): contains the average of the visible band digital number values with no further filtering. Data values range from 0-63. Areas with zero cloud-free observations are represented by the value 255.

• stable_lights (Cleaned up avg_vis): contains the lights from cities, towns, and other sites with persistent lighting, including gas flares. Ephemeral events, such as fires have been discarded. Then the background noise was identified and replaced with values of zero. Data values range from 1-63. Areas with zero cloud-free observations are represented by the value 255.

• pct_lights (Percent detection freq): the percentage of observations where light is detected per grid cell.

• avg_lights_x_pct (Avg vis band x percent detection freq): derived from the average visible band digital number(DN) of cloud-free light detections multiplied by the percent frequency of light detection. The inclusion of the percent frequency of detection term normalizes the resulting digital values for variations in the persistence of lighting. For instance, the value for a light only detected half the time is discounted by 50%. Note that this product contains detections from fires and a variable amount of background noise. This is the product used to infer gas flaring volumes from the nighttime lights.

configName_VIIRS.D

(character) The regex to uniquely identify the tile file to use out of the downloaded tile .tgz. The version 1 monthly series is run globally using two different configurations:

• vcmcfg (Stray Light Removed): Excludes any data impacted by stray light.

• vcmslcfg (Stray Light Corrected): includes data impacted by stray light if the radiance values have undergone the stray- light correction procedure.

The "vcmslcfg" version, that includes the stray-light corrected data, will have more data coverage toward the poles, but will be of reduced quality.

It is up to the users to determine which set is best for their applications. The annual versions are only made with the "vcm" version, excluding any data impacted by stray light.

configName_VIIRS.M

(character) The regex to uniquely identify the tile file to use out of the downloaded monthly .tgz tile. Has the same options as configName.VIIRS.D

configName_VIIRS.Y

(character) The regex to uniquely identify the tile file to use out of the downloaded tile .tgz. The annual products can have other values for the config shortname (Field 5). They are:

• vcm-orm (VIIRS Cloud Mask - Outlier Removed): This product contains cloud-free average radiance values that have undergone an outlier removal process to filter out fires and other ephemeral lights.

• vcm-orm-ntl (VIIRS Cloud Mask - Outlier Removed - Nighttime Lights): This product contains the "vcm-orm" average, with background (non-lights) set to zero.

• vcm-ntl (VIIRS Cloud Mask - Nighttime Lights): This product contains the "vcm" average, with background (non-lights) set to zero.

cropMaskMethod

(character) The method to use to clip the nightlight raster tiles to the country boundaries

deleteTiles

(character) whether to delete tiles after processing may be useful where diskspace is a concern

dirNlData

(character) The directory to store the extracted data files in

dirNlRoot

character) The root directory storing the package data

dirNlTiles

(character) The directory in which to store the downloaded VIIRS raster tiles

dirPolygon

(character) The directory to store the downloaded country administration level polygons

dirRasterOutput

(character) The directory in which to store the clipped country rasters

dirRasterWeb

(character) The directory in which to store the rasters resampled for web display

dirZonals

(character) The directory in which to store the zonal statistics country polygon

downloadMethod

(character) The download method to use

downloadTimeout

(character) The timeout for download operations

EOG_CredFile

(character) The filename used to save the user credentials for EOG in the .Rnightlights folder

EOG_ClientID

(character) The client_id required to request for an access token from EOG

EOG_ClientSecret

(character) The client_secret required to request for an access token from EOG

extractMethod

(character) The method to use to extract data from the rasters

gdalCacheMax

(numeric) The maximum memory gdal should use in gdal_rasterize

ntLtsIndexUrlOLS.Y

(character) The url with the OLS tile index

ntLtsIndexUrlVIIRS.D

(character) The url with the VIIRS.D tile index

ntLtsIndexUrlVIIRS.M

(character) The url with the VIIRS.M tile index

ntLtsIndexUrlVIIRS.Y

(character) The url with the VIIRS.Y tile index

ntLtsInfoUrlOLS.Y

(character) The url with the OLS tile info

ntLtsInfoUrlVIIRS.D

(character) The url with the VIIRS.D tile info

ntLtsInfoUrlVIIRS.M

(character) The url with the VIIRS.M tile info

ntLtsInfoUrlVIIRS.Y

(character) The url with the VIIRS.Y tile info

numThreads

(integer) The number of processing threads to use when extractMethod = "raster"

omitCountries

(character) The countries to exclude in processing

removeGasFlaresMethod

(character) The gasflare removal strategy to use. Valid values are:

• OGP (OLS Gas-Flare Polygons): There are gas-flare shapefile polygons provided for OLS. These can be used to crop areas with gas-flares. However, they are old and may not be reliable.

• OTM (OLS Tile Mask): Since OLS tiles are annual composites, it is possible to use them to identify dark areas. However, once again, the OLS data may be out-dated and further processing may be required to align VIIRS and OLS tiles. There may be loss of data.

• VTM (VIIRS Tile Mask): Same as the OLS tile mask but done using the VIIRS.Y annual tiles. Currently only 2 VIIRS.Y annual tiles exist for 2015 and 2016.

stats

(character) The statistics to calculate for country regions. The default are sum and mean. Any other aggregate statistics can be included. Also any aggregate function accessible in the current environment can be added.

tmpDir

(character) Change the temporary directory for processing rasters. Not in use

Examples

#retrieve the current cropMaskMethod
pkgOptions("cropMaskMethod")

#set the cropMaskMethod
pkgOptions(cropMaskMethod="gdal")

#' #set multiple options
pkgOptions(cropMaskMethod="gdal", extractMethod="gdal")

#retrieve all options
pkgOptions()

chrisvwn/Rnightlights documentation built on Sept. 7, 2021, 1:44 a.m.