Rnightlights (version 0.2.4)

getCtryNlData: Returns nightlight statistics for the given ctryCode and nlType in the given nPeriods

Description

Returns nightlight data for the given ctryCode and nlStats in the given nlPeriods and of the specified nlType. Note that getCtryNldata only processes one ctryCode at a time. ignoreMissing plays a significant role here. It can take 3 values:

• NULL (default) only return data if found for all nlPeriods and all nlStats provided otherwise return NULL.

• TRUE return any partial data that is found for the provided nlPeriods and nlStats. Ignore any missing data.

• FALSE return all data that is found and call processNlData to download and process any missing nlPeriods and nlStats.

Farther, if nlPeriods is missing, it is assigned values based on the value of ignoreMissing. If ignoreMissing is FALSE, nlPeriods is assigned all existing nlPeriods to date. This is the equivalent of retrieving all nightlight data for the given country and stats. If ignoreMissing is TRUE or NULL then the existing data is returned.

Usage

getCtryNlData(ctryCode = NULL, admLevel, nlTypes, nlPeriods,
  nlStats = pkgOptions("nlStats"), ignoreMissing = FALSE,
  gadmVersion = pkgOptions("gadmVersion"),
  gadmPolyType = pkgOptions("gadmPolyType"), custPolyPath = NULL,
  downloadMethod = pkgOptions("downloadMethod"),
  cropMaskMethod = pkgOptions("cropMaskMethod"),
  extractMethod = pkgOptions("extractMethod"), configNames,
  multiTileStrategy = pkgOptions("multiTileStrategy"),
  multiTileMergeFun = pkgOptions("multiTileMergeFun"),
  removeGasFlares = pkgOptions("removeGasFlares"), source = "local",
  ...)

Arguments

ctryCode

the ISO3 code of the country. Only 1 country can be processed at a time.

admLevel

The country admin level of interest. Only 1 admLevel can be processed at a time.

nlTypes

a vector of nlTypes. The nightlight types to process.

nlPeriods

a vector of nlPeriods. Must be appropriate nlPeriods for the nlType.

nlStats

a vector of nlStats. If not supplied defaults to all nlStats as listed in pkgOptions("nlStats").

ignoreMissing

controls how the function behaves if any data is not found in the data file.

• NULL (default) only return data if found for ALL nlPeriods and ALL stats provided otherwise return NULL

• TRUE return any partial data that is found for the provided nlPeriods and stats. Ignore any missing data

• FALSE return all data that is found and call processNlData to download and process any missing nlPeriods and stats

gadmVersion

The GADM version to use

gadmPolyType

The format of polygons to download from GADM

custPolyPath

Alternative to GADM. A path to a custom shapefile zip

downloadMethod

The method used to download polygons

cropMaskMethod

The method used to crop and mask the satellite raster

extractMethod

The method used to extract data and perform calculations on the satellite raster

configNames

character the types of raster being processed

multiTileStrategy

character How to handle multiple tiles per nlPeriod

multiTileMergeFun

character The function to use to merge tiles

removeGasFlares

logical Whether to perform gas flare removal pre-processing

source

"local" or "remote" Whether to download and process the data locally or to download the pre-processed data from a remote source/repo

...

other arguments

Value

dataframe of data for one country in one nlType in one or multiple nlPeriods

Examples

# NOT RUN {
#NOTE: missing stats implies all stats as given by pkgOptions("nlStats")

#long running examples which also require large downloads
# }
# NOT RUN {
getCtryNlData("KEN", "KEN_adm0", "VIIRS.M", ignoreMissing=NULL)
    #returns either all requested data if it exists i.e. all nlPeriods
    #and all nlStats for KEN otherwise NULL
# }
# NOT RUN {
# }
# NOT RUN {
getCtryNlData("KEN", "KEN_adm0", "OLS.Y", ignoreMissing=TRUE)
    #Returns all requested data if it exists i.e. all nlPeriods and all
    #nlStats for KEN but omits any missing data
    
# }
# NOT RUN {
 
# }
# NOT RUN {
getCtryNlData(ctryCode="KEN", "KEN_adm0", "VIIRS.Y", ignoreMissing=FALSE)
    #Returns all requested data i.e. all nlPeriods and all
    #nlStats for KEN. All missing data will be downloaded and processed
    
# }
# NOT RUN {
 
# }
# NOT RUN {
getCtryNlData("KEN", "KEN_adm0", "VIIRS.M", nlPeriods=c("existingNlPeriod", "missingNlPeriod"),
    nlStats=c("sum", "unknownStat"), ignoreMissing=NULL)
    #Returns NULL due to missingNlPeriod and unknownStat not already existing
    #(ignoreMissing=NULL returns all data if exists or if any is missing returns NULL)
    
# }
# NOT RUN {
# }
# NOT RUN {
getCtryNlData("KEN", "KEN_adm0", "VIIRS.D", nlPeriods=c("existingNlPeriod", "missingNlPeriod"),
    nlStats=c("existingStat", "missingStat"), ignoreMissing=TRUE)
   #Returns existingStat for existingNlPeriods omits missingNlPeriod and missingStat
   #(ignoreMissing=TRUE returns only existing data)
   
# }
# NOT RUN {
 
# }
# NOT RUN {
getCtryNlData("KEN", "KEN_adm0", "VIIRS.M", nlPeriods=c("existingNlPeriod", "missingNlPeriod"),
    nlStats=c("sum", "unknownStat"), ignoreMissing=FALSE)
    #Runs processNlData for missingStat in "missingNlPeriod" and returns
    #"existingStat" and "missingStat" for both "existingNlPeriod" and
    #"missingNlPeriod"
    #(ignoreMissing=FALSE must return all data: forces processing of any missing)
    
# }
# NOT RUN {
 
# }