nightlight_plot: nightlight_plot

In JakobMie/nightlightstats: nightlightstats

nightlight_plot

Description

Plot a shapefile with its nightlights for a given period of time. Note: even though it is possible to produce multiple plots by using multiple inputs for area_names and a timespan for time, you should pay attention to the number of plots that will be produced this way - all plots will be loaded into the global environment as ggplot objects, hence a large number can load many objects into your environment quickly.

Usage

nightlight_plot(
  area_names,
  time,
  light_location,
  shapefile_location = NULL,
  shapefiles = NULL,
  download_shape = ".gpkg",
  gpkg_layer = NULL,
  admlevel = 0,
  saveraster = FALSE,
  colours = c("white", "darkblue", "gray", "black"),
  fixed_scale_low = NULL,
  fixed_scale_high = NULL,
  cut_quality = 0,
  user_projection = NULL,
  user_coordinates = NULL,
  corrected_lights = FALSE,
  harmonized_lights = FALSE
)

Arguments

area_names	May not be empty. String (vector) with the name(s) of your region(s). If you provide a country name, the country shapefile will be downloaded automatically. Shapefiles in your working directory that have the area_names or (in case they exist) their iso3c countrycodes in their filename will be detected automatically. If you provide own shapefiles in the shapefiles argument, put the names in order of the shapefile order. If you only put one name for multiple shapefiles, all shapefiles will be processed with that name.
time	May not be empty. Vector of strings with the start/end dates in the format "2012-04" (monthly data) or "1992" (yearly data). If only one time period is desired, then simply input one date.
light_location	May not be empty. Provide the location of the lightfiles on your drive as a string. Note about the light files: for the DMSP images, some years have 2 versions available. Generally, if possible, a consistent version for your timespan will be chosen. Otherwise the newest version for each year will be selected. If 2 consistent versions are available for your timespan, the newer one will be selected.
shapefile_location	May be empty. Provide the location of the shapefiles on your drive as a string in the case that you want to use shapefiles and not a set of coordinates.
shapefiles	May be empty. You can provide own shapefiles here (input are the filenames) if no automatic download is desired. If there is a shapefile in your working directory that has either the name of the region which you enter in area_names or the iso3c countrycode (if it is a country) in its filename, it will be detected automatically and you do not have to use this argument.
download_shape	Default is ".gpkg", alternative is ".shp". Will only download if no own shapefiles are provided in the shapefiles argument or automatically detected in the shapefile location.
gpkg_layer	May be empty. You might need this argument if the code does not detect the correct layer of a .gpkg file automatically. This can happen if the layers of your .gpkg shapefile do not include an admlevel in their names. In that case, enter the layer here as a string. Note that this only works for one area at a time. To find out which layers are included in your .gpkg shapefile, you can use sf::st_layers().
admlevel	Default is 0. Change this when working with different administrative levels.
saveraster	Default is FALSE. If set to TRUE, an additional RData output with the raw raster nightlight data will be produced for each time period.
colours	Vector of strings. Minimum colour of the colour scale (default is "white"), maximum colour of the colour scale (default is "darkblue"), colour for NAs (default is "gray") and colour of the shapefile (default is "black"). The input inside the vector has to be in this order.
fixed_scale_low	Default is the minimum light value that is calculated (in the case if this is NULL). You can provide a fixed minimum scale value here to keep the colour scale constant across several plots.
fixed_scale_high	Default is the maximum light value that is calculated (in the case if this is NULL). You can provide a fixed maximum scale value here to keep the colour scale constant across several plots.
cut_quality	Default is 0. This will set all light values to NA for which the number of observations that went into the calculation of a pixel is smaller than or equal to cut_quality. Hence, with the default value you will have all pixels set to NA for which 0 observations were made. You can set this to a higher number if you want to drop all pixels below a given number of observations.
user_projection	May be empty. If empty, the standard projection is mercator. For another projection, you can choose from the projections listed here (enter the projection as a string without brackets): https://www.rdocumentation.org/packages/mapproj/versions/1.2.7/topics/mapproject
user_coordinates	May be empty. Inputs are decimal numbers (longlat). Can be specified if you want to plot night lights for a region defined by specific coordinates. Input order is xmin, xmax, ymin, ymax.
corrected_lights	Default is FALSE. If set to TRUE, the radiance-calibrated version of the DMSP data or the straylight-corrected version of the VIIRS data will be used. Note that you have to download these versions first, since they are different images from the standard ones. The data refer to the corrected lights by Bluhm and Krause (2022).
harmonized_lights	Default is FALSE. If set to TRUE, the harmonized DMSP-VIIRS yearly dataset by Li et al. (2020) will be used. Note that you have to download these versions first, since they are different images from the standard ones.

JakobMie/nightlightstats documentation built on April 11, 2025, 11:04 p.m.