diff --git a/index.html b/index.html index 7fc0bad..8425bc2 100644 --- a/index.html +++ b/index.html @@ -109,25 +109,25 @@

Bearer Token

Follow the below steps to obtain a bearer token:

    -
  1. Create a NASA Earth Data account account. On the top right, click “Login” then “Earthdata Login”. Then click “register” (blue button).
    2. -
  2. Enter the information in the registration page. You must include the following information; this information is not required to create an account, but the bearer token will not work without this information:
    3. -
+

  • Create a NASA Earth Data account account. On the top right, click “Login” then “Earthdata Login”. Then click “register” (blue button).

    • +
  • +

    Enter the information in the registration page. You must include the following information; this information is not required to create an account, but the bearer token will not work without this information:

    -
      -
    1. Click “Register for EarthData Login” (green button at bottom). Check your email, and click the link in the email to activate the account.
      2. -
    2. Go to the Earth Data Login page and login.
      3. -
    3. On the panel near the top, click “EULAs” then “Accept New EULAs”. Accept:
      4. -
    +
    • +

  • Click “Register for EarthData Login” (green button at bottom). Check your email, and click the link in the email to activate the account.

    • +

  • Go to the Earth Data Login page and login.

    • +
  • +

    On the panel near the top, click “EULAs” then “Accept New EULAs”. Accept:

    -
      -
    1. On the “Profile Home” page, you should see something like below. Information should be filled in for each category, and “Agreed To Meris EULA” and “Agreed To Sentinel-3 EULA” should be True.
      2. + +

    2. On the “Profile Home” page, you should see something like below. Information should be filled in for each category, and “Agreed To Meris EULA” and “Agreed To Sentinel-3 EULA” should be True.

    NASA Profile Home Information

    @@ -144,7 +144,7 @@

    Bearer Token

    Programmatically retrieve token

    -

    After following the above steps, the bearer token can be programmatically retrieved using the get_nasa_token() function and your usename and password.

    +

    After following the above steps, the bearer token can also be programmatically retrieved using the get_nasa_token() function and your usename and password.

     bearer <- get_nasa_token(username = "USERNAME-HERE", 
                          password = "PASSWORD-HERE")
    diff --git a/pkgdown.yml b/pkgdown.yml index a7bb0e5..b550e1e 100644 --- a/pkgdown.yml +++ b/pkgdown.yml @@ -3,4 +3,4 @@ pkgdown: 2.1.1 pkgdown_sha: ~ articles: assess-quality: assess-quality.html -last_built: 2025-01-03T21:30Z +last_built: 2025-01-03T21:35Z diff --git a/search.json b/search.json index 9f4a25c..b8f90c1 100644 --- a/search.json +++ b/search.json @@ -1 +1 @@ -[{"path":"/articles/assess-quality.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"Assessing Quality of Nighttime Lights Data","text":"quality nighttime lights data can impacted number factors, particularly cloud cover. facilitate analysis using high quality data, Black Marble (1) marks quality pixel (2) cases, uses data previous date fill value—using temporally-gap filled NTL value. page illustrates examine quality nighttime lights data. Setup Nighttime lights: Gap Filled Nighttime lights: Non Gap Filled Quality flag Nighttime lights using good quality observations Nighttime lights Number observations Quality Nighttime lights using good quality observations","code":""},{"path":"/articles/assess-quality.html","id":"setup","dir":"Articles","previous_headings":"","what":"Setup","title":"Assessing Quality of Nighttime Lights Data","text":"first load packages obtain polygon region interest; example, use Switzerland.","code":"library(blackmarbler) library(geodata) library(sf) library(raster) library(ggplot2) library(tidyterra) library(dplyr) library(exactextractr) library(lubridate) library(tidyr) library(geodata) library(knitr) bearer <- \"BEARER-TOKEN-HERE\" roi_sf <- gadm(country = \"CHE\", level=0, path = tempdir()) |> st_as_sf()"},{"path":"/articles/assess-quality.html","id":"daily-data","dir":"Articles","previous_headings":"","what":"Daily Data","title":"Assessing Quality of Nighttime Lights Data","text":"shows example examining quality daily data (VNP46A2).","code":""},{"path":"/articles/assess-quality.html","id":"gap-filled-nighttime-lights","dir":"Articles","previous_headings":"Daily Data","what":"Gap filled nighttime lights","title":"Assessing Quality of Nighttime Lights Data","text":"download data January 1st, 2023. variable parameter specified, bm_raster creates raster using Gap_Filled_DNB_BRDF-Corrected_NTL variable daily data. variable “gap fills” poor quality observations (ie, pixels cloud cover) using data previous days. Latest_High_Quality_Retrieval indicates number days since current date nighttime lights value comes gap filling.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Gap_Filled_DNB_BRDF-Corrected_NTL\") #### Prep data ntl_m_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_m_r[] <- log(ntl_m_r[]+1) ##### Map ggplot() + geom_spatraster(data = ntl_m_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\") ntl_tmp_gap_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Latest_High_Quality_Retrieval\") #### Prep data ntl_tmp_gap_r <- ntl_tmp_gap_r |> terra::mask(roi_sf) ##### Map ggplot() + geom_spatraster(data = ntl_tmp_gap_r) + scale_fill_distiller(palette = \"Spectral\", na.value = \"transparent\") + coord_sf() + theme_void() + labs(fill = \"Temporal\\nGap\\n(Days)\", title = \"Temporal gap between date (Jan 1, 2023)\\nand date of high quality pixel used\") + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"non-gap-filled-nighttime-lights","dir":"Articles","previous_headings":"Daily Data","what":"Non gap filled nighttime lights","title":"Assessing Quality of Nighttime Lights Data","text":"Instead using gap-filled data, also just use nighttime light values date selected using DNB_BRDF-Corrected_NTL variable. notice number observations missing. understand extent missing date, can use following code determine (1) total number pixels cover Switzerland, (2) total number non-NA nighttime light pixels, (3) proportion non-NA pixels. default, bm_extract function computes values: figure shows trends average nighttime lights (left) proportion country value nighttime lights (right). days, low number pixels corresponds low nighttime lights (eg, January 3 5th); however, days, low number pixels corresponds higher nighttime lights (eg, January 9 10). January 3 5, missing pixels typically high-lit areas (eg, cities)—January 9 10, missing pixels typically lower-lit areas.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\") #### Prep data ntl_m_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_m_r[] <- log(ntl_m_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_m_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\") n_pixel <- function(values, coverage_fraction){ length(values) } n_non_na_pixel <- function(values, coverage_fraction){ sum(!is.na(values)) } n_pixel_num <- exact_extract(ntl_r, roi_sf, n_pixel) n_non_na_pixel_num <- exact_extract(ntl_r, roi_sf, n_non_na_pixel) print(n_pixel_num) #> [1] 282934 print(n_non_na_pixel_num) #> [1] 122035 print(n_non_na_pixel_num / n_pixel_num) #> [1] 0.4313197 ntl_df <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2023-01-01\"), to = ymd(\"2023-01-10\"), by = 1), bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\") knitr::kable(ntl_df) ntl_df %>% dplyr::select(date, ntl_mean, prop_non_na_pixels) %>% pivot_longer(cols = -date) %>% ggplot(aes(x = date, y = value)) + geom_line() + facet_wrap(~name, scales = \"free\")"},{"path":"/articles/assess-quality.html","id":"quality","dir":"Articles","previous_headings":"Daily Data","what":"Quality","title":"Assessing Quality of Nighttime Lights Data","text":"daily data, quality values : 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues can map quality using Mandatory_Quality_Flag variable.","code":"quality_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Mandatory_Quality_Flag\") #### Prep data quality_r <- quality_r |> terra::mask(roi_sf) qual_levels <- data.frame(id=0:2, cover=c(\"0: High-quality, persistent\", \"1: High-quality, ephemeral\", \"2: Poor-quality\")) levels(quality_r) <- qual_levels ##### Map ggplot() + geom_spatraster(data = quality_r) + scale_fill_brewer(palette = \"Spectral\", direction = -1, na.value = \"transparent\") + labs(fill = \"Quality\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"nighttime-lights-for-good-quality-observations","dir":"Articles","previous_headings":"Daily Data","what":"Nighttime lights for good quality observations","title":"Assessing Quality of Nighttime Lights Data","text":"quality_flag_rm parameter determines pixels set NA based quality indicator. default, pixels filtered (except assigned “fill value” BlackMarble, always removed). However, want data good quality pixels, can adjust quality_flag_rm parameter.","code":"ntl_good_qual_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\", quality_flag_rm = 2) #### Prep data ntl_good_qual_r <- ntl_good_qual_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_good_qual_r[] <- log(ntl_good_qual_r[]+1) ##### Map ggplot() + geom_spatraster(data = ntl_good_qual_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/articles/assess-quality.html","id":"monthlyannual-data","dir":"Articles","previous_headings":"","what":"Monthly/Annual Data","title":"Assessing Quality of Nighttime Lights Data","text":"shows example examining quality monthly data (VNP46A3). approach can used annual data (VNP46A4); variables monthly annual data.","code":""},{"path":"/articles/assess-quality.html","id":"nighttime-lights","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Nighttime Lights","title":"Assessing Quality of Nighttime Lights Data","text":"download data January 2023. variable parameter specified, bm_raster creates raster using NearNadir_Composite_Snow_Free variable monthly annual data—nighttime lights, removing effects snow cover.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free\") #### Prep data ntl_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_r[] <- log(ntl_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/articles/assess-quality.html","id":"number-of-observations","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Number of Observations","title":"Assessing Quality of Nighttime Lights Data","text":"Black Marble removes poor quality observations, pixels covered clouds. determine number observations used generate nighttime light values pixel, add _Num variable name.","code":"cf_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free_Num\") #### Prep data cf_r <- cf_r |> terra::mask(roi_sf) ##### Map ggplot() + geom_spatraster(data = cf_r) + scale_fill_viridis_c(na.value = \"transparent\") + labs(fill = \"Number of\\nObservations\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"quality-1","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Quality","title":"Assessing Quality of Nighttime Lights Data","text":"monthly annual data, quality values : 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data can map quality adding _Quality variable name.","code":"quality_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free_Quality\") #### Prep data quality_r <- quality_r |> terra::mask(roi_sf) qual_levels <- data.frame(id=0:2, cover=c(\"0: Good quality\", \"1: Poor quality\", \"2: Gap filled\")) levels(quality_r) <- qual_levels ##### Map ggplot() + geom_spatraster(data = quality_r) + scale_fill_brewer(palette = \"Spectral\", direction = -1, na.value = \"transparent\") + labs(fill = \"Quality\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"nighttime-lights-for-good-quality-observations-1","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Nighttime lights for good quality observations","title":"Assessing Quality of Nighttime Lights Data","text":"quality_flag_rm parameter determines pixels set NA based quality indicator. default, pixels filtered (except assigned “fill value” BlackMarble, always removed). However, also want remove poor quality pixels remove pixels gap filled, can adjust quality_flag_rm parameter.","code":"ntl_good_qual_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free\", quality_flag_rm = c(1,2)) # 1 = poor quality; 2 = gap filled based on historical data #### Prep data ntl_good_qual_r <- ntl_good_qual_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_good_qual_r[] <- log(ntl_good_qual_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_good_qual_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Robert Marty. Author, maintainer. Gabriel Stefanini Vicente. Author.","code":""},{"path":"/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Marty R, Stefanini Vicente G (2025). blackmarbler: Black Marble Data Statistics. R package version 0.2.4, https://worldbank.github.io/blackmarbler/.","code":"@Manual{, title = {blackmarbler: Black Marble Data and Statistics}, author = {Robert Marty and Gabriel {Stefanini Vicente}}, year = {2025}, note = {R package version 0.2.4}, url = {https://worldbank.github.io/blackmarbler/}, }"},{"path":"/index.html","id":"blackmarbler-","dir":"","previous_headings":"","what":"Black Marble Data and Statistics","title":"Black Marble Data and Statistics","text":"BlackMarbleR R package provides simple way use nighttime lights data NASA’s Black Marble. Black Marble NASA Earth Science Data Systems (ESDS) project provides product suite daily, monthly yearly global nighttime lights. package automates process downloading relevant tiles NASA LAADS DAAC cover region interest, converting mosaicing raw files (HDF5 format) georeferenced rasters. Installation Bearer token Setup Make raster Make raster across multiple time periods Make map Make figure trends nighttime lights Workflow update data Functions Required Arguments Optional Arguments Argument bm_extract Black Marble Resources","code":""},{"path":"/index.html","id":"installation-","dir":"","previous_headings":"","what":"Installation","title":"Black Marble Data and Statistics","text":"package can installed via CRAN. install development version Github:","code":"install.packages(\"blackmarbler\") # install.packages(\"devtools\") devtools::install_github(\"worldbank/blackmarbler\")"},{"path":"/index.html","id":"bearer-token-","dir":"","previous_headings":"","what":"Bearer Token","title":"Black Marble Data and Statistics","text":"Follow steps obtain bearer token: Create NASA Earth Data account account. top right, click “Login” “Earthdata Login”. click “register” (blue button). Enter information registration page. must include following information; information required create account, bearer token work without information: Study Area User Type Organization Click “Register EarthData Login” (green button bottom). Check email, click link email activate account. Go Earth Data Login page login. panel near top, click “EULAs” “Accept New EULAs”. Accept: MERIS EULA Sentinel EULA “Profile Home” page, see something like . Information filled category, “Agreed Meris EULA” “Agreed Sentinel-3 EULA” True. Go NASA LAADS Archive login (login botton top right). see page authorize use Sentinel3 Meris. Click green “Authorize” button. obtain bearer token, go Earth Data Login page login. top panel, click “Generate token”. page, click “Show Token” see token. bearer token ever stops working, make need go “Generate token” page (see step 8), delete existing tokens, generate new token.","code":""},{"path":"/index.html","id":"programmatically-retrieve-token-","dir":"","previous_headings":"Bearer Token","what":"Programmatically retrieve token","title":"Black Marble Data and Statistics","text":"following steps, bearer token can programmatically retrieved using get_nasa_token() function usename password.","code":"bearer <- get_nasa_token(username = \"USERNAME-HERE\", password = \"PASSWORD-HERE\")"},{"path":[]},{"path":"/index.html","id":"setup-","dir":"","previous_headings":"Usage","what":"Setup","title":"Black Marble Data and Statistics","text":"downloading extracting Black Marble data, first load packages, define NASA bearer token, define region interest.","code":"#### Setup # Load packages library(blackmarbler) library(geodata) library(sf) library(terra) library(ggplot2) library(tidyterra) library(lubridate) #### Define NASA bearer token bearer <- \"BEARER-TOKEN-HERE\" ### ROI # Define region of interest (roi). The roi must be (1) an sf polygon and (2) # in the WGS84 (epsg:4326) coordinate reference system. Here, we use the # getData function to load a polygon of Ghana roi_sf <- gadm(country = \"GHA\", level=1, path = tempdir())"},{"path":"/index.html","id":"make-raster-of-nighttime-lights-","dir":"","previous_headings":"Usage","what":"Make raster of nighttime lights","title":"Black Marble Data and Statistics","text":"example shows making daily, monthly, annual rasters nighttime lights Ghana.","code":"### Daily data: raster for February 5, 2021 r_20210205 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-02-05\", bearer = bearer) ### Monthly data: raster for October 2021 r_202110 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-10-01\", # The day is ignored bearer = bearer) ### Annual data: raster for 2021 r_2021 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer)"},{"path":"/index.html","id":"make-raster-of-nighttime-lights-across-multiple-time-periods-","dir":"","previous_headings":"Usage","what":"Make raster of nighttime lights across multiple time periods","title":"Black Marble Data and Statistics","text":"extract data multiple time periods, add multiple time periods date. function return SpatRaster object multiple bands, band corresponds different date. code provides examples getting data across multiple days, months, years.","code":"#### Daily data in March 2021 r_daily <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2021-03-01\"), to = ymd(\"2021-03-31\"), by = \"day\"), bearer = bearer) #### Monthly aggregated data in 2021 and 2022 r_monthly <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = seq.Date(from = ymd(\"2021-01-01\"), to = ymd(\"2022-12-01\"), by = \"month\"), bearer = bearer) #### Yearly aggregated data in 2012 and 2021 r_annual <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2012:2021, bearer = bearer)"},{"path":"/index.html","id":"map-of-nighttime-lights-","dir":"","previous_headings":"Usage","what":"Map of nighttime lights","title":"Black Marble Data and Statistics","text":"Using one rasters, can make map nighttime lights","code":"#### Make raster r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-10-01\", bearer = bearer) #### Prep data r <- r |> terra::mask(roi_sf) ## Distribution is skewed, so log r[] <- log(r[] + 1) ##### Map ggplot() + geom_spatraster(data = r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4.5, na.value = \"transparent\") + labs(title = \"Nighttime Lights: October 2021\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/index.html","id":"trends-over-time-","dir":"","previous_headings":"Usage","what":"Trends over time","title":"Black Marble Data and Statistics","text":"can use bm_extract function observe changes nighttime lights time. bm_extract function leverages exactextractr package aggregate nighttime lights data polygons. show trends annual nighttime lights data across Ghana’s first administrative divisions.","code":"#### Extract annual data ntl_df <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2012:2022, bearer = bearer) #### Trends over time ntl_df |> ggplot() + geom_col(aes(x = date, y = ntl_mean), fill = \"darkorange\") + facet_wrap(~NAME_1) + labs(x = NULL, y = \"NTL Luminosity\", title = \"Ghana Admin Level 1: Annual Average Nighttime Lights\") + scale_x_continuous(labels = seq(2012, 2022, 4), breaks = seq(2012, 2022, 4)) + theme_minimal() + theme(strip.text = element_text(face = \"bold\"))"},{"path":"/index.html","id":"workflow-to-update-data-","dir":"","previous_headings":"Usage","what":"Workflow to update data","title":"Black Marble Data and Statistics","text":"users may want monitor near-real-time changes nighttime lights. example, daily Black Marble nighttime lights data updated regularly, data available roughly week delay; use cases may require examining trends daily nighttime lights data new data becomes available. shows example code regularly run produce updated daily dataset nighttime lights. code produces dataframe nighttime lights date, average nighttime lights Ghana’s 1st administrative division produced. code check whether data already downloaded/extracted specific date, download/extract new data.","code":"# Create directories to store data dir.create(file.path(getwd(), \"bm_files\")) dir.create(file.path(getwd(), \"bm_files\", \"daily\")) # Extract daily-level nighttime lights data for Ghana's first administrative divisions. # Save a separate dataset for each date in the `\"~/Desktop/bm_files/daily\"` directory. # The code extracts data from January 1, 2023 to today. Given that daily nighttime lights # data is produced on roughly a week delay, the function will only extract data that exists; # it will skip extracting data for dates where data has not yet been produced by NASA Black Marble. bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2023-01-01\"), to = Sys.Date(), by = 1), bearer = bearer, output_location_type = \"file\", file_dir = file.path(getwd(), \"bm_files\", \"daily\")) # Append daily-level datasets into one file file.path(getwd(), \"bm_files\", \"daily\") |> list.files(pattern = \"*.Rds\", full.names = T) |> map_df(readRDS) |> saveRDS(file.path(getwd(), \"bm_files\", \"ntl_daily.Rds\"))"},{"path":[]},{"path":"/index.html","id":"functions-","dir":"","previous_headings":"Functions and arguments","what":"Functions","title":"Black Marble Data and Statistics","text":"package provides two functions. bm_raster produces raster Black Marble nighttime lights. bm_extract produces dataframe aggregated nighttime lights region interest (e.g., average nighttime lights within US States). functions take following arguments:","code":""},{"path":"/index.html","id":"required-arguments-","dir":"","previous_headings":"Functions and arguments","what":"Required arguments","title":"Black Marble Data and Statistics","text":"roi_sf: Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. bm_extract, aggregates nighttime lights within polygon roi_sf. product_id: One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date: Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer: NASA bearer token. instructions create token, see .","code":""},{"path":"/index.html","id":"optional-arguments-","dir":"","previous_headings":"Functions and arguments","what":"Optional arguments","title":"Black Marble Data and Statistics","text":"variable: Variable used create raster (default: NULL). information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. NULL, uses following default variables: product_id \"VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. quality_flag_rm: Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value ther quality_flag_rm vector. (Default: NULL). 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist: Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na: data one date downloaded, whether interpolate NA values rasters using terra::approximate function. Additional arguments terra::approximate function can also passed bm_raster/bm_extract (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). h5_dir: Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. output_location_type: output stored (default: r_memory). Either: r_memory function return output R file function export data file. bm_raster, .tif file saved; bm_extract, .Rds file saved. file saved date. Consequently, date = c(2018, 2019, 2020), three datasets saved: one year. Saving dataset date can facilitate re-running function later downloading data dates data downloaded. output_location_type = \"file\", following arguments can used: file_dir: directory data exported (default: NULL, working directory used) file_prefix: Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].[tif/Rds] file_skip_if_exists: Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). function first run date = c(2018, 2019, 2020), later run date = c(2018, 2019, 2020, 2021), function download/extract data 2021. Skipping existing files can facilitate re-running function later date download recent data. file_return_null: Whether return NULL instead output R (SpatRaster dataframe). output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). …: Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/index.html","id":"argument-for-bm_extract-only-","dir":"","previous_headings":"Functions and arguments","what":"Argument for bm_extract only","title":"Black Marble Data and Statistics","text":"aggregation_fun: vector functions aggregate data (default: \"mean\"). exact_extract function exactextractr package used aggregations; parameter passed fun argument exactextractr::exact_extract. add_n_pixels: Whether add variable indicating number nighttime light pixels used compute nighttime lights statistics (eg, number pixels used compute average nighttime lights). TRUE, adds three values: n_non_na_pixels (number non-NA pixels used computing nighttime light statistics); n_pixels (total number pixels); prop_non_na_pixels proportion two. (Default: TRUE).","code":""},{"path":"/index.html","id":"black-marble-resources-","dir":"","previous_headings":"","what":"Black Marble Resources","title":"Black Marble Data and Statistics","text":"information NASA Black Marble, see: Academic paper Substack Post Webinar","code":""},{"path":"/reference/bm_extract.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract and Aggregate Black Marble Data — bm_extract","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Extract aggregate nighttime lights data NASA Black Marble data","code":""},{"path":"/reference/bm_extract.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"","code":"bm_extract( roi_sf, product_id, date, bearer, aggregation_fun = c(\"mean\"), add_n_pixels = TRUE, variable = NULL, quality_flag_rm = NULL, check_all_tiles_exist = TRUE, interpol_na = FALSE, output_location_type = \"memory\", file_dir = NULL, file_prefix = NULL, file_skip_if_exists = TRUE, file_return_null = FALSE, h5_dir = NULL, quiet = FALSE, ... )"},{"path":"/reference/bm_extract.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"roi_sf Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. product_id One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer NASA bearer token. instructions create token, see . aggregation_fun Function used aggregate nighttime lights data polygons; values passed fun argument exactextractr::exact_extract (Default: mean). add_n_pixels Whether add variable indicating number nighttime light pixels used compute nighttime lights statistics (eg, number pixels used compute average nighttime lights). TRUE, adds three values: n_non_na_pixels (number non-NA pixels used computing nighttime light statistics); n_pixels (total number pixels); prop_non_na_pixels proportion two. (Default: TRUE). variable Variable used create raster (default: NULL). NULL, uses following default variables: product_id :VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. quality_flag_rm Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value quality_flag_rm vector. Note quality_flag_rm apply VNP46A1. (Default: NULL). VNP46A2 (daily data): 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues VNP46A3 VNP46A4 (monthly annual data): 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na data one date downloaded, whether interpolate NA values rasters using terra::approximate function. Additional arguments terra::approximate function can also passed bm_extract (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). output_location_type produce output; either memory file. memory, functions returns dataframe R. file, function exports .csv file returns NULL. file_dir (output_location_type = file). directory data exported (default: NULL, working directory used) file_prefix (output_location_type = file). Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].csv file_skip_if_exists (output_location_type = file). Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). file_return_null Whether return NULL instead dataframe. output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return dataframe queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). h5_dir Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. quiet Suppress output show downloading progress messages. (Default: FALSE). ... Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/reference/bm_extract.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Raster","code":""},{"path":"/reference/bm_extract.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Robert Marty rmarty@worldbank.org","code":""},{"path":"/reference/bm_extract.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"","code":"if (FALSE) { # \\dontrun{ # Define bearer token bearer <- \"BEARER-TOKEN-HERE\" # sf polygon of Ghana library(geodata) roi_sf <- gadm(country = \"GHA\", level=1, path = tempdir()) %>% st_as_sf() # Daily data: raster for October 3, 2021 ken_20210205_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-10-03\", bearer = bearer) # Monthly data: raster for March 2021 ken_202103_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-03-01\", bearer = bearer) # Annual data: raster for 2021 ken_2021_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer) } # }"},{"path":"/reference/bm_raster.html","id":null,"dir":"Reference","previous_headings":"","what":"Make Black Marble Raster — bm_raster","title":"Make Black Marble Raster — bm_raster","text":"Make raster nighttime lights NASA Black Marble data","code":""},{"path":"/reference/bm_raster.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Make Black Marble Raster — bm_raster","text":"","code":"bm_raster( roi_sf, product_id, date, bearer, variable = NULL, quality_flag_rm = NULL, check_all_tiles_exist = TRUE, interpol_na = FALSE, output_location_type = \"memory\", file_dir = NULL, file_prefix = NULL, file_skip_if_exists = TRUE, file_return_null = FALSE, h5_dir = NULL, quiet = FALSE, ... )"},{"path":"/reference/bm_raster.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Make Black Marble Raster — bm_raster","text":"roi_sf Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. product_id One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer NASA bearer token. instructions create token, see . variable Variable used create raster (default: NULL). NULL, uses following default variables: product_id :VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. quality_flag_rm Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value quality_flag_rm vector. Note quality_flag_rm apply VNP46A1. (Default: NULL). VNP46A2 (daily data): 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues VNP46A3 VNP46A4 (monthly annual data): 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na data one date downloaded, whether interpolate NA values using terra::approximate function. Additional arguments terra::approximate function can also passed bm_raster (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). output_location_type produce output; either memory file. memory, functions returns raster R. file, function exports .tif file returns NULL. output_location_type = file: file_dir directory data exported (default: NULL, working directory used) file_prefix Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].tif file_skip_if_exists Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). file_return_null Whether return NULL instead SpatRaster. output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return SpatRaster queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). h5_dir Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. quiet Suppress output show downloading progress messages. (Default: FALSE). ... Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/reference/bm_raster.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Make Black Marble Raster — bm_raster","text":"Raster","code":""},{"path":"/reference/bm_raster.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Make Black Marble Raster — bm_raster","text":"Robert Marty rmarty@worldbank.org","code":""},{"path":"/reference/bm_raster.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Make Black Marble Raster — bm_raster","text":"","code":"if (FALSE) { # \\dontrun{ # Define bearer token bearer <- \"BEARER-TOKEN-HERE\" # sf polygon of Ghana library(geodata) roi_sf <- gadm(country = \"GHA\", level=0, path = tempdir()) %>% st_as_sf() # Daily data: raster for October 3, 2021 ken_20210205_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-10-03\", bearer = bearer) # Monthly data: raster for March 2021 ken_202103_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-03-01\", bearer = bearer) # Annual data: raster for 2021 ken_2021_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer) } # }"},{"path":"/reference/get_nasa_token.html","id":null,"dir":"Reference","previous_headings":"","what":"Get a NASA Earthdata bearer token — get_nasa_token","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"Fetch NASA Earthdata bearer token using Earthdata API. none exist, create one, one already exists fetch one instead.","code":""},{"path":"/reference/get_nasa_token.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"","code":"get_nasa_token(username, password)"},{"path":"/reference/get_nasa_token.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"username character. NASA Earthdata username password character. NASA Earthdata password","code":""},{"path":"/reference/get_nasa_token.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"character","code":""},{"path":"/reference/get_nasa_token.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"Simon E. H. Smart simon.smart@cantab.net","code":""}] +[{"path":"/articles/assess-quality.html","id":"overview","dir":"Articles","previous_headings":"","what":"Overview","title":"Assessing Quality of Nighttime Lights Data","text":"quality nighttime lights data can impacted number factors, particularly cloud cover. facilitate analysis using high quality data, Black Marble (1) marks quality pixel (2) cases, uses data previous date fill value—using temporally-gap filled NTL value. page illustrates examine quality nighttime lights data. Setup Nighttime lights: Gap Filled Nighttime lights: Non Gap Filled Quality flag Nighttime lights using good quality observations Nighttime lights Number observations Quality Nighttime lights using good quality observations","code":""},{"path":"/articles/assess-quality.html","id":"setup","dir":"Articles","previous_headings":"","what":"Setup","title":"Assessing Quality of Nighttime Lights Data","text":"first load packages obtain polygon region interest; example, use Switzerland.","code":"library(blackmarbler) library(geodata) library(sf) library(raster) library(ggplot2) library(tidyterra) library(dplyr) library(exactextractr) library(lubridate) library(tidyr) library(geodata) library(knitr) bearer <- \"BEARER-TOKEN-HERE\" roi_sf <- gadm(country = \"CHE\", level=0, path = tempdir()) |> st_as_sf()"},{"path":"/articles/assess-quality.html","id":"daily-data","dir":"Articles","previous_headings":"","what":"Daily Data","title":"Assessing Quality of Nighttime Lights Data","text":"shows example examining quality daily data (VNP46A2).","code":""},{"path":"/articles/assess-quality.html","id":"gap-filled-nighttime-lights","dir":"Articles","previous_headings":"Daily Data","what":"Gap filled nighttime lights","title":"Assessing Quality of Nighttime Lights Data","text":"download data January 1st, 2023. variable parameter specified, bm_raster creates raster using Gap_Filled_DNB_BRDF-Corrected_NTL variable daily data. variable “gap fills” poor quality observations (ie, pixels cloud cover) using data previous days. Latest_High_Quality_Retrieval indicates number days since current date nighttime lights value comes gap filling.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Gap_Filled_DNB_BRDF-Corrected_NTL\") #### Prep data ntl_m_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_m_r[] <- log(ntl_m_r[]+1) ##### Map ggplot() + geom_spatraster(data = ntl_m_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\") ntl_tmp_gap_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Latest_High_Quality_Retrieval\") #### Prep data ntl_tmp_gap_r <- ntl_tmp_gap_r |> terra::mask(roi_sf) ##### Map ggplot() + geom_spatraster(data = ntl_tmp_gap_r) + scale_fill_distiller(palette = \"Spectral\", na.value = \"transparent\") + coord_sf() + theme_void() + labs(fill = \"Temporal\\nGap\\n(Days)\", title = \"Temporal gap between date (Jan 1, 2023)\\nand date of high quality pixel used\") + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"non-gap-filled-nighttime-lights","dir":"Articles","previous_headings":"Daily Data","what":"Non gap filled nighttime lights","title":"Assessing Quality of Nighttime Lights Data","text":"Instead using gap-filled data, also just use nighttime light values date selected using DNB_BRDF-Corrected_NTL variable. notice number observations missing. understand extent missing date, can use following code determine (1) total number pixels cover Switzerland, (2) total number non-NA nighttime light pixels, (3) proportion non-NA pixels. default, bm_extract function computes values: figure shows trends average nighttime lights (left) proportion country value nighttime lights (right). days, low number pixels corresponds low nighttime lights (eg, January 3 5th); however, days, low number pixels corresponds higher nighttime lights (eg, January 9 10). January 3 5, missing pixels typically high-lit areas (eg, cities)—January 9 10, missing pixels typically lower-lit areas.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\") #### Prep data ntl_m_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_m_r[] <- log(ntl_m_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_m_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\") n_pixel <- function(values, coverage_fraction){ length(values) } n_non_na_pixel <- function(values, coverage_fraction){ sum(!is.na(values)) } n_pixel_num <- exact_extract(ntl_r, roi_sf, n_pixel) n_non_na_pixel_num <- exact_extract(ntl_r, roi_sf, n_non_na_pixel) print(n_pixel_num) #> [1] 282934 print(n_non_na_pixel_num) #> [1] 122035 print(n_non_na_pixel_num / n_pixel_num) #> [1] 0.4313197 ntl_df <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2023-01-01\"), to = ymd(\"2023-01-10\"), by = 1), bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\") knitr::kable(ntl_df) ntl_df %>% dplyr::select(date, ntl_mean, prop_non_na_pixels) %>% pivot_longer(cols = -date) %>% ggplot(aes(x = date, y = value)) + geom_line() + facet_wrap(~name, scales = \"free\")"},{"path":"/articles/assess-quality.html","id":"quality","dir":"Articles","previous_headings":"Daily Data","what":"Quality","title":"Assessing Quality of Nighttime Lights Data","text":"daily data, quality values : 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues can map quality using Mandatory_Quality_Flag variable.","code":"quality_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"Mandatory_Quality_Flag\") #### Prep data quality_r <- quality_r |> terra::mask(roi_sf) qual_levels <- data.frame(id=0:2, cover=c(\"0: High-quality, persistent\", \"1: High-quality, ephemeral\", \"2: Poor-quality\")) levels(quality_r) <- qual_levels ##### Map ggplot() + geom_spatraster(data = quality_r) + scale_fill_brewer(palette = \"Spectral\", direction = -1, na.value = \"transparent\") + labs(fill = \"Quality\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"nighttime-lights-for-good-quality-observations","dir":"Articles","previous_headings":"Daily Data","what":"Nighttime lights for good quality observations","title":"Assessing Quality of Nighttime Lights Data","text":"quality_flag_rm parameter determines pixels set NA based quality indicator. default, pixels filtered (except assigned “fill value” BlackMarble, always removed). However, want data good quality pixels, can adjust quality_flag_rm parameter.","code":"ntl_good_qual_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2023-01-01\", bearer = bearer, variable = \"DNB_BRDF-Corrected_NTL\", quality_flag_rm = 2) #### Prep data ntl_good_qual_r <- ntl_good_qual_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_good_qual_r[] <- log(ntl_good_qual_r[]+1) ##### Map ggplot() + geom_spatraster(data = ntl_good_qual_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/articles/assess-quality.html","id":"monthlyannual-data","dir":"Articles","previous_headings":"","what":"Monthly/Annual Data","title":"Assessing Quality of Nighttime Lights Data","text":"shows example examining quality monthly data (VNP46A3). approach can used annual data (VNP46A4); variables monthly annual data.","code":""},{"path":"/articles/assess-quality.html","id":"nighttime-lights","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Nighttime Lights","title":"Assessing Quality of Nighttime Lights Data","text":"download data January 2023. variable parameter specified, bm_raster creates raster using NearNadir_Composite_Snow_Free variable monthly annual data—nighttime lights, removing effects snow cover.","code":"ntl_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free\") #### Prep data ntl_r <- ntl_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_r[] <- log(ntl_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/articles/assess-quality.html","id":"number-of-observations","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Number of Observations","title":"Assessing Quality of Nighttime Lights Data","text":"Black Marble removes poor quality observations, pixels covered clouds. determine number observations used generate nighttime light values pixel, add _Num variable name.","code":"cf_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free_Num\") #### Prep data cf_r <- cf_r |> terra::mask(roi_sf) ##### Map ggplot() + geom_spatraster(data = cf_r) + scale_fill_viridis_c(na.value = \"transparent\") + labs(fill = \"Number of\\nObservations\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"quality-1","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Quality","title":"Assessing Quality of Nighttime Lights Data","text":"monthly annual data, quality values : 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data can map quality adding _Quality variable name.","code":"quality_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free_Quality\") #### Prep data quality_r <- quality_r |> terra::mask(roi_sf) qual_levels <- data.frame(id=0:2, cover=c(\"0: Good quality\", \"1: Poor quality\", \"2: Gap filled\")) levels(quality_r) <- qual_levels ##### Map ggplot() + geom_spatraster(data = quality_r) + scale_fill_brewer(palette = \"Spectral\", direction = -1, na.value = \"transparent\") + labs(fill = \"Quality\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5))"},{"path":"/articles/assess-quality.html","id":"nighttime-lights-for-good-quality-observations-1","dir":"Articles","previous_headings":"Monthly/Annual Data","what":"Nighttime lights for good quality observations","title":"Assessing Quality of Nighttime Lights Data","text":"quality_flag_rm parameter determines pixels set NA based quality indicator. default, pixels filtered (except assigned “fill value” BlackMarble, always removed). However, also want remove poor quality pixels remove pixels gap filled, can adjust quality_flag_rm parameter.","code":"ntl_good_qual_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2023-01-01\", bearer = bearer, variable = \"NearNadir_Composite_Snow_Free\", quality_flag_rm = c(1,2)) # 1 = poor quality; 2 = gap filled based on historical data #### Prep data ntl_good_qual_r <- ntl_good_qual_r |> terra::mask(roi_sf) ## Distribution is skewed, so log ntl_good_qual_r[] <- log(ntl_good_qual_r[] + 1) ##### Map ggplot() + geom_spatraster(data = ntl_good_qual_r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4, na.value = \"transparent\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Robert Marty. Author, maintainer. Gabriel Stefanini Vicente. Author.","code":""},{"path":"/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Marty R, Stefanini Vicente G (2025). blackmarbler: Black Marble Data Statistics. R package version 0.2.4, https://worldbank.github.io/blackmarbler/.","code":"@Manual{, title = {blackmarbler: Black Marble Data and Statistics}, author = {Robert Marty and Gabriel {Stefanini Vicente}}, year = {2025}, note = {R package version 0.2.4}, url = {https://worldbank.github.io/blackmarbler/}, }"},{"path":"/index.html","id":"blackmarbler-","dir":"","previous_headings":"","what":"Black Marble Data and Statistics","title":"Black Marble Data and Statistics","text":"BlackMarbleR R package provides simple way use nighttime lights data NASA’s Black Marble. Black Marble NASA Earth Science Data Systems (ESDS) project provides product suite daily, monthly yearly global nighttime lights. package automates process downloading relevant tiles NASA LAADS DAAC cover region interest, converting mosaicing raw files (HDF5 format) georeferenced rasters. Installation Bearer token Setup Make raster Make raster across multiple time periods Make map Make figure trends nighttime lights Workflow update data Functions Required Arguments Optional Arguments Argument bm_extract Black Marble Resources","code":""},{"path":"/index.html","id":"installation-","dir":"","previous_headings":"","what":"Installation","title":"Black Marble Data and Statistics","text":"package can installed via CRAN. install development version Github:","code":"install.packages(\"blackmarbler\") # install.packages(\"devtools\") devtools::install_github(\"worldbank/blackmarbler\")"},{"path":"/index.html","id":"bearer-token-","dir":"","previous_headings":"","what":"Bearer Token","title":"Black Marble Data and Statistics","text":"Follow steps obtain bearer token: Create NASA Earth Data account account. top right, click “Login” “Earthdata Login”. click “register” (blue button). Enter information registration page. must include following information; information required create account, bearer token work without information: Study Area User Type Organization Click “Register EarthData Login” (green button bottom). Check email, click link email activate account. Go Earth Data Login page login. panel near top, click “EULAs” “Accept New EULAs”. Accept: MERIS EULA Sentinel EULA “Profile Home” page, see something like . Information filled category, “Agreed Meris EULA” “Agreed Sentinel-3 EULA” True. Go NASA LAADS Archive login (login botton top right). see page authorize use Sentinel3 Meris. Click green “Authorize” button. obtain bearer token, go Earth Data Login page login. top panel, click “Generate token”. page, click “Show Token” see token. bearer token ever stops working, make need go “Generate token” page (see step 8), delete existing tokens, generate new token.","code":""},{"path":"/index.html","id":"programmatically-retrieve-token-","dir":"","previous_headings":"Bearer Token","what":"Programmatically retrieve token","title":"Black Marble Data and Statistics","text":"following steps, bearer token can also programmatically retrieved using get_nasa_token() function usename password.","code":"bearer <- get_nasa_token(username = \"USERNAME-HERE\", password = \"PASSWORD-HERE\")"},{"path":[]},{"path":"/index.html","id":"setup-","dir":"","previous_headings":"Usage","what":"Setup","title":"Black Marble Data and Statistics","text":"downloading extracting Black Marble data, first load packages, define NASA bearer token, define region interest.","code":"#### Setup # Load packages library(blackmarbler) library(geodata) library(sf) library(terra) library(ggplot2) library(tidyterra) library(lubridate) #### Define NASA bearer token bearer <- \"BEARER-TOKEN-HERE\" ### ROI # Define region of interest (roi). The roi must be (1) an sf polygon and (2) # in the WGS84 (epsg:4326) coordinate reference system. Here, we use the # getData function to load a polygon of Ghana roi_sf <- gadm(country = \"GHA\", level=1, path = tempdir())"},{"path":"/index.html","id":"make-raster-of-nighttime-lights-","dir":"","previous_headings":"Usage","what":"Make raster of nighttime lights","title":"Black Marble Data and Statistics","text":"example shows making daily, monthly, annual rasters nighttime lights Ghana.","code":"### Daily data: raster for February 5, 2021 r_20210205 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-02-05\", bearer = bearer) ### Monthly data: raster for October 2021 r_202110 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-10-01\", # The day is ignored bearer = bearer) ### Annual data: raster for 2021 r_2021 <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer)"},{"path":"/index.html","id":"make-raster-of-nighttime-lights-across-multiple-time-periods-","dir":"","previous_headings":"Usage","what":"Make raster of nighttime lights across multiple time periods","title":"Black Marble Data and Statistics","text":"extract data multiple time periods, add multiple time periods date. function return SpatRaster object multiple bands, band corresponds different date. code provides examples getting data across multiple days, months, years.","code":"#### Daily data in March 2021 r_daily <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2021-03-01\"), to = ymd(\"2021-03-31\"), by = \"day\"), bearer = bearer) #### Monthly aggregated data in 2021 and 2022 r_monthly <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = seq.Date(from = ymd(\"2021-01-01\"), to = ymd(\"2022-12-01\"), by = \"month\"), bearer = bearer) #### Yearly aggregated data in 2012 and 2021 r_annual <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2012:2021, bearer = bearer)"},{"path":"/index.html","id":"map-of-nighttime-lights-","dir":"","previous_headings":"Usage","what":"Map of nighttime lights","title":"Black Marble Data and Statistics","text":"Using one rasters, can make map nighttime lights","code":"#### Make raster r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-10-01\", bearer = bearer) #### Prep data r <- r |> terra::mask(roi_sf) ## Distribution is skewed, so log r[] <- log(r[] + 1) ##### Map ggplot() + geom_spatraster(data = r) + scale_fill_gradient2(low = \"black\", mid = \"yellow\", high = \"red\", midpoint = 4.5, na.value = \"transparent\") + labs(title = \"Nighttime Lights: October 2021\") + coord_sf() + theme_void() + theme(plot.title = element_text(face = \"bold\", hjust = 0.5), legend.position = \"none\")"},{"path":"/index.html","id":"trends-over-time-","dir":"","previous_headings":"Usage","what":"Trends over time","title":"Black Marble Data and Statistics","text":"can use bm_extract function observe changes nighttime lights time. bm_extract function leverages exactextractr package aggregate nighttime lights data polygons. show trends annual nighttime lights data across Ghana’s first administrative divisions.","code":"#### Extract annual data ntl_df <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2012:2022, bearer = bearer) #### Trends over time ntl_df |> ggplot() + geom_col(aes(x = date, y = ntl_mean), fill = \"darkorange\") + facet_wrap(~NAME_1) + labs(x = NULL, y = \"NTL Luminosity\", title = \"Ghana Admin Level 1: Annual Average Nighttime Lights\") + scale_x_continuous(labels = seq(2012, 2022, 4), breaks = seq(2012, 2022, 4)) + theme_minimal() + theme(strip.text = element_text(face = \"bold\"))"},{"path":"/index.html","id":"workflow-to-update-data-","dir":"","previous_headings":"Usage","what":"Workflow to update data","title":"Black Marble Data and Statistics","text":"users may want monitor near-real-time changes nighttime lights. example, daily Black Marble nighttime lights data updated regularly, data available roughly week delay; use cases may require examining trends daily nighttime lights data new data becomes available. shows example code regularly run produce updated daily dataset nighttime lights. code produces dataframe nighttime lights date, average nighttime lights Ghana’s 1st administrative division produced. code check whether data already downloaded/extracted specific date, download/extract new data.","code":"# Create directories to store data dir.create(file.path(getwd(), \"bm_files\")) dir.create(file.path(getwd(), \"bm_files\", \"daily\")) # Extract daily-level nighttime lights data for Ghana's first administrative divisions. # Save a separate dataset for each date in the `\"~/Desktop/bm_files/daily\"` directory. # The code extracts data from January 1, 2023 to today. Given that daily nighttime lights # data is produced on roughly a week delay, the function will only extract data that exists; # it will skip extracting data for dates where data has not yet been produced by NASA Black Marble. bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = seq.Date(from = ymd(\"2023-01-01\"), to = Sys.Date(), by = 1), bearer = bearer, output_location_type = \"file\", file_dir = file.path(getwd(), \"bm_files\", \"daily\")) # Append daily-level datasets into one file file.path(getwd(), \"bm_files\", \"daily\") |> list.files(pattern = \"*.Rds\", full.names = T) |> map_df(readRDS) |> saveRDS(file.path(getwd(), \"bm_files\", \"ntl_daily.Rds\"))"},{"path":[]},{"path":"/index.html","id":"functions-","dir":"","previous_headings":"Functions and arguments","what":"Functions","title":"Black Marble Data and Statistics","text":"package provides two functions. bm_raster produces raster Black Marble nighttime lights. bm_extract produces dataframe aggregated nighttime lights region interest (e.g., average nighttime lights within US States). functions take following arguments:","code":""},{"path":"/index.html","id":"required-arguments-","dir":"","previous_headings":"Functions and arguments","what":"Required arguments","title":"Black Marble Data and Statistics","text":"roi_sf: Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. bm_extract, aggregates nighttime lights within polygon roi_sf. product_id: One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date: Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer: NASA bearer token. instructions create token, see .","code":""},{"path":"/index.html","id":"optional-arguments-","dir":"","previous_headings":"Functions and arguments","what":"Optional arguments","title":"Black Marble Data and Statistics","text":"variable: Variable used create raster (default: NULL). information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. NULL, uses following default variables: product_id \"VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. quality_flag_rm: Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value ther quality_flag_rm vector. (Default: NULL). 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist: Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na: data one date downloaded, whether interpolate NA values rasters using terra::approximate function. Additional arguments terra::approximate function can also passed bm_raster/bm_extract (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). h5_dir: Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. output_location_type: output stored (default: r_memory). Either: r_memory function return output R file function export data file. bm_raster, .tif file saved; bm_extract, .Rds file saved. file saved date. Consequently, date = c(2018, 2019, 2020), three datasets saved: one year. Saving dataset date can facilitate re-running function later downloading data dates data downloaded. output_location_type = \"file\", following arguments can used: file_dir: directory data exported (default: NULL, working directory used) file_prefix: Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].[tif/Rds] file_skip_if_exists: Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). function first run date = c(2018, 2019, 2020), later run date = c(2018, 2019, 2020, 2021), function download/extract data 2021. Skipping existing files can facilitate re-running function later date download recent data. file_return_null: Whether return NULL instead output R (SpatRaster dataframe). output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). …: Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/index.html","id":"argument-for-bm_extract-only-","dir":"","previous_headings":"Functions and arguments","what":"Argument for bm_extract only","title":"Black Marble Data and Statistics","text":"aggregation_fun: vector functions aggregate data (default: \"mean\"). exact_extract function exactextractr package used aggregations; parameter passed fun argument exactextractr::exact_extract. add_n_pixels: Whether add variable indicating number nighttime light pixels used compute nighttime lights statistics (eg, number pixels used compute average nighttime lights). TRUE, adds three values: n_non_na_pixels (number non-NA pixels used computing nighttime light statistics); n_pixels (total number pixels); prop_non_na_pixels proportion two. (Default: TRUE).","code":""},{"path":"/index.html","id":"black-marble-resources-","dir":"","previous_headings":"","what":"Black Marble Resources","title":"Black Marble Data and Statistics","text":"information NASA Black Marble, see: Academic paper Substack Post Webinar","code":""},{"path":"/reference/bm_extract.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract and Aggregate Black Marble Data — bm_extract","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Extract aggregate nighttime lights data NASA Black Marble data","code":""},{"path":"/reference/bm_extract.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"","code":"bm_extract( roi_sf, product_id, date, bearer, aggregation_fun = c(\"mean\"), add_n_pixels = TRUE, variable = NULL, quality_flag_rm = NULL, check_all_tiles_exist = TRUE, interpol_na = FALSE, output_location_type = \"memory\", file_dir = NULL, file_prefix = NULL, file_skip_if_exists = TRUE, file_return_null = FALSE, h5_dir = NULL, quiet = FALSE, ... )"},{"path":"/reference/bm_extract.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"roi_sf Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. product_id One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer NASA bearer token. instructions create token, see . aggregation_fun Function used aggregate nighttime lights data polygons; values passed fun argument exactextractr::exact_extract (Default: mean). add_n_pixels Whether add variable indicating number nighttime light pixels used compute nighttime lights statistics (eg, number pixels used compute average nighttime lights). TRUE, adds three values: n_non_na_pixels (number non-NA pixels used computing nighttime light statistics); n_pixels (total number pixels); prop_non_na_pixels proportion two. (Default: TRUE). variable Variable used create raster (default: NULL). NULL, uses following default variables: product_id :VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. quality_flag_rm Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value quality_flag_rm vector. Note quality_flag_rm apply VNP46A1. (Default: NULL). VNP46A2 (daily data): 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues VNP46A3 VNP46A4 (monthly annual data): 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na data one date downloaded, whether interpolate NA values rasters using terra::approximate function. Additional arguments terra::approximate function can also passed bm_extract (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). output_location_type produce output; either memory file. memory, functions returns dataframe R. file, function exports .csv file returns NULL. file_dir (output_location_type = file). directory data exported (default: NULL, working directory used) file_prefix (output_location_type = file). Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].csv file_skip_if_exists (output_location_type = file). Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). file_return_null Whether return NULL instead dataframe. output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return dataframe queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). h5_dir Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. quiet Suppress output show downloading progress messages. (Default: FALSE). ... Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/reference/bm_extract.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Raster","code":""},{"path":"/reference/bm_extract.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"Robert Marty rmarty@worldbank.org","code":""},{"path":"/reference/bm_extract.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract and Aggregate Black Marble Data — bm_extract","text":"","code":"if (FALSE) { # \\dontrun{ # Define bearer token bearer <- \"BEARER-TOKEN-HERE\" # sf polygon of Ghana library(geodata) roi_sf <- gadm(country = \"GHA\", level=1, path = tempdir()) %>% st_as_sf() # Daily data: raster for October 3, 2021 ken_20210205_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-10-03\", bearer = bearer) # Monthly data: raster for March 2021 ken_202103_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-03-01\", bearer = bearer) # Annual data: raster for 2021 ken_2021_r <- bm_extract(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer) } # }"},{"path":"/reference/bm_raster.html","id":null,"dir":"Reference","previous_headings":"","what":"Make Black Marble Raster — bm_raster","title":"Make Black Marble Raster — bm_raster","text":"Make raster nighttime lights NASA Black Marble data","code":""},{"path":"/reference/bm_raster.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Make Black Marble Raster — bm_raster","text":"","code":"bm_raster( roi_sf, product_id, date, bearer, variable = NULL, quality_flag_rm = NULL, check_all_tiles_exist = TRUE, interpol_na = FALSE, output_location_type = \"memory\", file_dir = NULL, file_prefix = NULL, file_skip_if_exists = TRUE, file_return_null = FALSE, h5_dir = NULL, quiet = FALSE, ... )"},{"path":"/reference/bm_raster.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Make Black Marble Raster — bm_raster","text":"roi_sf Region interest; sf polygon. Must WGS 84 (epsg:4326) coordinate reference system. product_id One following: \"VNP46A1\": Daily (raw) \"VNP46A2\": Daily (corrected) \"VNP46A3\": Monthly \"VNP46A4\": Annual date Date raster data. Entering one date produce SpatRaster object. Entering multiple dates produce SpatRaster object multiple bands; one band per date. product_ids \"VNP46A1\" \"VNP46A2\", date (eg, \"2021-10-03\"). product_id \"VNP46A3\", date year-month (e.g., \"2021-10-01\", day ignored, \"2021-10\"). product_id \"VNP46A4\", year date (e.g., \"2021-10-01\", month day ignored, 2021). bearer NASA bearer token. instructions create token, see . variable Variable used create raster (default: NULL). NULL, uses following default variables: product_id :VNP46A1\", uses DNB_At_Sensor_Radiance_500m. product_id \"VNP46A2\", uses Gap_Filled_DNB_BRDF-Corrected_NTL. product_ids \"VNP46A3\" \"VNP46A4\", uses NearNadir_Composite_Snow_Free. information variable choices, see ; VNP46A1, see Table 3; VNP46A2 see Table 6; VNP46A3 VNP46A4, see Table 9. quality_flag_rm Quality flag values use set values NA. pixel quality flag value, low quality values can removed. Values set NA value quality_flag_rm vector. Note quality_flag_rm apply VNP46A1. (Default: NULL). VNP46A2 (daily data): 0: High-quality, Persistent nighttime lights 1: High-quality, Ephemeral nighttime Lights 2: Poor-quality, Outlier, potential cloud contamination, issues VNP46A3 VNP46A4 (monthly annual data): 0: Good-quality, number observations used composite larger 3 1: Poor-quality, number observations used composite less equal 3 2: Gap filled NTL based historical data check_all_tiles_exist Check whether Black Marble nighttime light tiles exist region interest. Sometimes tiles available, full region interest may covered. TRUE, skips cases tiles available. (Default: TRUE). interpol_na data one date downloaded, whether interpolate NA values using terra::approximate function. Additional arguments terra::approximate function can also passed bm_raster (eg, method, rule, f, ties, z, NA_rule). (Default: FALSE). output_location_type produce output; either memory file. memory, functions returns raster R. file, function exports .tif file returns NULL. output_location_type = file: file_dir directory data exported (default: NULL, working directory used) file_prefix Prefix add file saved. file saved following: [file_prefix][product_id]_t[date].tif file_skip_if_exists Whether function first check wither file already exists, skip downloading extracting data data date file already exists (default: TRUE). file_return_null Whether return NULL instead SpatRaster. output_location_type = 'file', function export data file_dir directory. file_return_null = FALSE, function also return SpatRaster queried data—data available R memory. Setting file_return_null = TRUE, data saved file_dir data returned function R memory (default: FALSE). h5_dir Black Marble data originally downloaded h5 files. h5_dir = NULL, function downloads temporary directory deletes directory. h5_dir set path, h5 files saved directory deleted. function check needed h5 file already exists directory; exists, function re-download h5 file. quiet Suppress output show downloading progress messages. (Default: FALSE). ... Additional arguments terra::approximate, interpol_na = TRUE","code":""},{"path":"/reference/bm_raster.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Make Black Marble Raster — bm_raster","text":"Raster","code":""},{"path":"/reference/bm_raster.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Make Black Marble Raster — bm_raster","text":"Robert Marty rmarty@worldbank.org","code":""},{"path":"/reference/bm_raster.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Make Black Marble Raster — bm_raster","text":"","code":"if (FALSE) { # \\dontrun{ # Define bearer token bearer <- \"BEARER-TOKEN-HERE\" # sf polygon of Ghana library(geodata) roi_sf <- gadm(country = \"GHA\", level=0, path = tempdir()) %>% st_as_sf() # Daily data: raster for October 3, 2021 ken_20210205_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A2\", date = \"2021-10-03\", bearer = bearer) # Monthly data: raster for March 2021 ken_202103_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A3\", date = \"2021-03-01\", bearer = bearer) # Annual data: raster for 2021 ken_2021_r <- bm_raster(roi_sf = roi_sf, product_id = \"VNP46A4\", date = 2021, bearer = bearer) } # }"},{"path":"/reference/get_nasa_token.html","id":null,"dir":"Reference","previous_headings":"","what":"Get a NASA Earthdata bearer token — get_nasa_token","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"Fetch NASA Earthdata bearer token using Earthdata API. none exist, create one, one already exists fetch one instead.","code":""},{"path":"/reference/get_nasa_token.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"","code":"get_nasa_token(username, password)"},{"path":"/reference/get_nasa_token.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"username character. NASA Earthdata username password character. NASA Earthdata password","code":""},{"path":"/reference/get_nasa_token.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"character","code":""},{"path":"/reference/get_nasa_token.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Get a NASA Earthdata bearer token — get_nasa_token","text":"Simon E. H. Smart simon.smart@cantab.net","code":""}]