Region of interest; sf polygon. Must be in the WGS 84 (epsg:4326) coordinate reference system.

One of the following:

• "VNP46A1": Daily (raw)

• "VNP46A2": Daily (corrected)

• "VNP46A3": Monthly

• "VNP46A4": Annual

Date of raster data. Entering one date will produce a SpatRaster object. Entering multiple dates will produce a SpatRaster object with multiple bands; one band per date.

• For product_ids "VNP46A1" and "VNP46A2", a date (eg, "2021-10-03").

• For product_id "VNP46A3", a date or year-month (e.g., "2021-10-01", where the day will be ignored, or "2021-10").

• For product_id "VNP46A4", year or date (e.g., "2021-10-01", where the month and day will be ignored, or 2021).

NASA bearer token. For instructions on how to create a token, see here.

Function used to aggregate nighttime lights data to polygons; this values is passed to the fun argument in exactextractr::exact_extract (Default: mean).

Whether to add a variable indicating the number of nighttime light pixels used to compute nighttime lights statistics (eg, number of pixels used to compute average of nighttime lights). When TRUE, it adds three values: n_non_na_pixels (the number of non-NA pixels used for computing nighttime light statistics); n_pixels (the total number of pixels); and prop_non_na_pixels the proportion of the two. (Default: TRUE).

Variable to used to create raster (default: NULL). If NULL, uses the following default variables:

• For product_id ⁠:VNP46A1"⁠, uses DNB_At_Sensor_Radiance_500m.

• For product_id "VNP46A2", uses Gap_Filled_DNB_BRDF-Corrected_NTL.

• For product_ids "VNP46A3" and "VNP46A4", uses NearNadir_Composite_Snow_Free. To see all variable choices, set variable = "" (this will create an error message that lists all valid variables). For additional information on variable choices, see here; for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9.

Quality flag values to use to set values to NA. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the quality_flag_rm vector. Note that quality_flag_rm does not apply for VNP46A1. (Default: NULL).

For VNP46A2 (daily data):

• 0: High-quality, Persistent nighttime lights

• 1: High-quality, Ephemeral nighttime Lights

• 2: Poor-quality, Outlier, potential cloud contamination, or other issues

For VNP46A3 and VNP46A4 (monthly and annual data):

• 0: Good-quality, The number of observations used for the composite is larger than 3

• 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

• 2: Gap filled NTL based on historical data

Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. If TRUE, skips cases where not all tiles are available. (Default: TRUE).

When data for more than one date is downloaded, whether to interpolate NA values in rasters using the terra::approximate function. Additional arguments for the terra::approximate function can also be passed into bm_extract (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE).

Where to produce output; either memory or file. If memory, functions returns a dataframe in R. If file, function exports a .csv file and returns NULL.

(If output_location_type = file). The directory where data should be exported (default: NULL, so the working directory will be used)

(If output_location_type = file). Prefix to add to the file to be saved. The file will be saved as the following: ⁠[file_prefix][product_id]_t[date].csv⁠

(If output_location_type = file). Whether the function should first check wither the file already exists, and to skip downloading or extracting data if the data for that date if the file already exists (default: TRUE).

Whether to return NULL instead of a dataframe. When output_location_type = 'file', the function will export data to the file_dir directory. When file_return_null = FALSE, the function will also return a dataframe of the queried data—so the data is available in R memory. Setting file_return_null = TRUE, data will be saved to file_dir but no data will be returned by the function to R memory (default: FALSE).

Black Marble data are originally downloaded as h5 files. If h5_dir = NULL, the function downloads to a temporary directory then deletes the directory. If h5_dir is set to a path, h5 files are saved to that directory and not deleted. The function will then check if the needed h5 file already exists in the directory; if it exists, the function will not re-download the h5 file.

Suppress output that show downloading progress and other messages. (Default: FALSE).

Additional arguments for terra::approximate, if interpol_na = TRUE

Region of interest; sf polygon. Must be in the WGS 84 (epsg:4326) coordinate reference system.

One of the following:

• "VNP46A1": Daily (raw)

• "VNP46A2": Daily (corrected)

• "VNP46A3": Monthly

• "VNP46A4": Annual

Date of raster data. Entering one date will produce a SpatRaster object. Entering multiple dates will produce a SpatRaster object with multiple bands; one band per date.

• For product_ids "VNP46A1" and "VNP46A2", a date (eg, "2021-10-03").

• For product_id "VNP46A3", a date or year-month (e.g., "2021-10-01", where the day will be ignored, or "2021-10").

• For product_id "VNP46A4", year or date (e.g., "2021-10-01", where the month and day will be ignored, or 2021).

NASA bearer token. For instructions on how to create a token, see here.

Variable to used to create raster (default: NULL). If NULL, uses the following default variables:

• For product_id ⁠:VNP46A1"⁠, uses DNB_At_Sensor_Radiance_500m.

• For product_id "VNP46A2", uses Gap_Filled_DNB_BRDF-Corrected_NTL.

• For product_ids "VNP46A3" and "VNP46A4", uses NearNadir_Composite_Snow_Free. To see all variable choices, set variable = "" (this will create an error message that lists all valid variables). For additional information on variable choices, see here; for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9.

Quality flag values to use to set values to NA. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the quality_flag_rm vector. Note that quality_flag_rm does not apply for VNP46A1. (Default: NULL).

For VNP46A2 (daily data):

• 0: High-quality, Persistent nighttime lights

• 1: High-quality, Ephemeral nighttime Lights

• 2: Poor-quality, Outlier, potential cloud contamination, or other issues

For VNP46A3 and VNP46A4 (monthly and annual data):

• 0: Good-quality, The number of observations used for the composite is larger than 3

• 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

• 2: Gap filled NTL based on historical data

Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. If TRUE, skips cases where not all tiles are available. (Default: TRUE).

When data for more than one date is downloaded, whether to interpolate NA values using the terra::approximate function. Additional arguments for the terra::approximate function can also be passed into bm_raster (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE).

Where to produce output; either memory or file. If memory, functions returns a raster in R. If file, function exports a .tif file and returns NULL. For output_location_type = file:

The directory where data should be exported (default: NULL, so the working directory will be used)

Prefix to add to the file to be saved. The file will be saved as the following: ⁠[file_prefix][product_id]_t[date].tif⁠

Whether the function should first check wither the file already exists, and to skip downloading or extracting data if the data for that date if the file already exists (default: TRUE).

Whether to return NULL instead of a SpatRaster. When output_location_type = 'file', the function will export data to the file_dir directory. When file_return_null = FALSE, the function will also return a SpatRaster of the queried data—so the data is available in R memory. Setting file_return_null = TRUE, data will be saved to file_dir but no data will be returned by the function to R memory (default: FALSE).

Black Marble data are originally downloaded as h5 files. If h5_dir = NULL, the function downloads to a temporary directory then deletes the directory. If h5_dir is set to a path, h5 files are saved to that directory and not deleted. The function will then check if the needed h5 file already exists in the directory; if it exists, the function will not re-download the h5 file.

Suppress output that show downloading progress and other messages. (Default: FALSE).

Additional arguments for terra::approximate, if interpol_na = TRUE

character. NASA Earthdata username

character. NASA Earthdata password