From 9064b4a4b5939127ebaf3de85ae90bcc5e6d4d9e Mon Sep 17 00:00:00 2001 From: ramarty Date: Fri, 3 Jan 2025 21:28:09 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20worldban?= =?UTF-8?q?k/blackmarbler@2d5e125336d2624607556c551db8a103951fd03e=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- index.html | 58 ++++++++++++++---------- pkgdown.yml | 2 +- reference/figures/nasa_profile_info.png | Bin 0 -> 33051 bytes search.json | 2 +- 4 files changed, 36 insertions(+), 26 deletions(-) create mode 100644 reference/figures/nasa_profile_info.png diff --git a/index.html b/index.html index a562d37..7fc0bad 100644 --- a/index.html +++ b/index.html @@ -107,38 +107,48 @@

Installation

Bearer Token

-

To obtain a bearer token, you’ll need to have a registered NASA Earth Data account. On the webpage, click “login” and create a username/password if needed.

-

After an account is created, the NASA Bearer Token can be retrieved either using the get_nasa_token function or manually (see below).

+

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. +
+ +
    +
  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. +
+ +
    +
  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. +
+

+NASA Profile Home Information

+
    +

  1. Go to the NASA LAADS Archive and login (login botton on top right). You will see a page to authorize use of Sentinel3 and Meris. Click the green “Authorize” button.

    2. +

  2. To obtain the bearer token, go to the Earth Data Login page and login. On the top panel, click “Generate token”. On this page, click “Show Token” to see the token.

    3. +
+

+NASA LAADS Bearer Token

+
    +
  1. If the bearer token ever stops working, you make need to go to the “Generate token” page (see step 8), delete any existing tokens, and generate a new token.
    2. +

Programmatically retrieve token

-

The NASA Bearer Token can also be programmatically retrieved using the get_nasa_token() function. After making an account, the get_nasa_token() function uses your username and password to retrieve the Bearer token.

+

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

 bearer <- get_nasa_token(username = "USERNAME-HERE", 
                          password = "PASSWORD-HERE")
-
-

Manually retrieve token - -

-

The function requires using a Earthdata Download Bearer Token; to obtain a token, follow the below steps:

-
    -
  1. Go to the NASA LAADS Archive -
    2. -
  2. Click “Login” (button on top right), and click “Earthdata Login”; create an account if needed.
    3. -
  3. Enter your username and password.
    4. -
  4. Click “Login”, then “Generate Token” on the dropdown.
    5. -
  5. Click the “Generate Token” tab, then click the green button to generate a token
    6. -
  6. Click the blue “Show token” button; this is your bearer token. It will be a long string of text (over 500 characters).
    7. -
-

-NASA LAADS Bearer Token

-

-NASA LAADS Bearer Token

-

-NASA LAADS Bearer Token

-

Usage diff --git a/pkgdown.yml b/pkgdown.yml index 60c4793..04e4ebb 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-03T18:37Z +last_built: 2025-01-03T21:25Z diff --git a/reference/figures/nasa_profile_info.png b/reference/figures/nasa_profile_info.png new file mode 100644 index 0000000000000000000000000000000000000000..db855542655f09165e7889b2a0df404e9f48a531 GIT binary patch literal 33051 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 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":"obtain bearer token, ’ll need registered NASA Earth Data account. webpage, click “login” create username/password needed. account created, NASA Bearer Token can retrieved either using get_nasa_token function manually (see ).","code":""},{"path":"/index.html","id":"programmatically-retrieve-token-","dir":"","previous_headings":"Bearer Token","what":"Programmatically retrieve token","title":"Black Marble Data and Statistics","text":"NASA Bearer Token can also programmatically retrieved using get_nasa_token() function. making account, get_nasa_token() function uses username password retrieve Bearer token.","code":"bearer <- get_nasa_token(username = \"USERNAME-HERE\", password = \"PASSWORD-HERE\")"},{"path":"/index.html","id":"manually-retrieve-token-","dir":"","previous_headings":"Bearer Token","what":"Manually retrieve token","title":"Black Marble Data and Statistics","text":"function requires using Earthdata Download Bearer Token; obtain token, follow steps: Go NASA LAADS Archive Click “Login” (button top right), click “Earthdata Login”; create account needed. Enter username password. Click “Login”, “Generate Token” dropdown. Click “Generate Token” tab, click green button generate token Click blue “Show token” button; bearer token. long string text (500 characters).","code":""},{"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 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":""}]