getCtryNlData: Returns nightlight statistics for the given ctryCode and...
In chrisvwn/Rnightlights: Satellite Nightlight Data Extraction

Description Usage Arguments Details Value Examples

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:

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,
  extensions,
  multiTileStrategy = pkgOptions("multiTileStrategy"),
  multiTileMergeFun = pkgOptions("multiTileMergeFun"),
  removeGasFlaresMethod = pkgOptions(paste0("removeGasFlaresMethod_", nlTypes)),
  useSavedStats = FALSE,
  source = "local",
  ...
)

`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 config short names of rasters being processed
`extensions`	character the extensions of rasters being processed
`multiTileStrategy`	character How to handle multiple tiles per nlPeriod
`multiTileMergeFun`	character The function to use to merge tiles
`removeGasFlaresMethod`	character The method to use to perform gas flare removal or NULL to disable
`useSavedStats`	logical Whether to load saved stats and search them for nlStats
`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

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.

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

#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

## End(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
    
## End(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
    
## End(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)
    
## End(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)
   
## End(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)
    
## End(Not run)