BlackMarblePy

https://worldbank.github.io/blackmarblepy/
Admin
A Python package that provides a simple way to download, extract, and process NASA's Black Marble...
Tokens:29,475
Snippets:256
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install BlackMarblePy with Documentation Dependencies

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Install the BlackMarblePy package along with its documentation dependencies. This is required for building the documentation locally.

```bash
pip install -e .[docs]

```

--------------------------------

### Install BlackMarblePy with Documentation Dependencies

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Install the BlackMarblePy package along with its documentation-specific dependencies. This is required for building documentation locally.

```shell
pip install -e .[docs]
```

--------------------------------

### Install BlackMarblePy from Source

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Install the BlackMarblePy package from its source code after cloning the repository. This command installs the package with its dependencies.

```bash
pip install .

```

--------------------------------

### Install BlackMarblePy using uv

Source: https://worldbank.github.io/blackmarblepy/_sources/README.md

Install the BlackMarblePy package using uv, the recommended package manager. This method is generally faster.

```shell
uv add blackmarblepy
```

--------------------------------

### Install BlackMarblePy from Source

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Install the BlackMarblePy package from the cloned source code, including all dependencies. This is useful for development.

```shell
pip install .
```

--------------------------------

### Install BlackMarblePy from PyPI

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Install the BlackMarblePy package using pip. This is the recommended method for most users.

```shell
pip install blackmarblepy
```

--------------------------------

### Install BlackMarblePy from PyPI

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Install the BlackMarblePy package using pip. This is the recommended method for most users.

```bash
pip install blackmarblepy

```

--------------------------------

### Create and Activate Virtual Environment

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Create a Python virtual environment for the project. This helps manage dependencies and isolate project environments. Activate the environment before installing packages.

```bash
python3 -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

```

--------------------------------

### Install BlackMarblePy using uv

Source: https://worldbank.github.io/blackmarblepy/README.html

Install the BlackMarblePy package using uv, the recommended package manager. It is recommended to use a virtual environment.

```bash
uv add blackmarblepy

```

--------------------------------

### Install BlackMarblePy in Editable Mode

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Install the BlackMarblePy package in editable mode from the source. Changes to the source code will be immediately reflected in the installed package.

```shell
pip install -e .
```

--------------------------------

### Install BlackMarblePy in Editable Mode

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Install the BlackMarblePy package in editable mode from source. Changes made to the source code will be immediately reflected in the installed package without reinstallation.

```bash
pip install -e .

```

--------------------------------

### Download Black Marble Data using BlackMarblePy

Source: https://worldbank.github.io/blackmarblepy/README.html

This example demonstrates how to initialize the BlackMarble client and download VNP46 data for a specified region of interest and date range. Ensure your NASA Earthdata token is set as an environment variable or passed directly.

```python
import geopandas as gpd

from blackmarble import BlackMarble, Product

# ------------------------------------------------------------------------------
# 1. Define your region of interest
# ------------------------------------------------------------------------------
# In this example ,we load a region from a GeoJSON.
gdf = gpd.read_file("path/to/your/shapefile.geojson")

# ------------------------------------------------------------------------------
# 2. Set up the BlackMarble client
# ------------------------------------------------------------------------------
# If the environment variable `BLACKMARBLE_TOKEN` is set, it will be used automatically.
# You can also pass your token directly, but using the environment variable is recommended.
bm = BlackMarble(token="YOUR_BLACKMARBLE_TOKEN")

# ------------------------------------------------------------------------------
# 3. Download VNP46 data from NASA Earthdata
# ------------------------------------------------------------------------------
# In this example, we request the VNP46A2 product for a specific date.
# The data is returned as an xarray.Dataset.
raster_earth_day = bm.raster(
    gdf,
    product_id=Product.VNP46A2,
    date_range="2025-04-22",
)

```

--------------------------------

### Clone BlackMarblePy Repository

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Clone the BlackMarblePy repository from GitHub and navigate to the project directory. This is the first step for installing from source.

```shell
git clone https://github.com/worldbank/blackmarblepy.git
cd blackmarblepy
```

--------------------------------

### Import Libraries and Setup Plotting

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Imports necessary libraries for data manipulation, plotting, and geospatial analysis. Sets up plotting configurations for figure size and enables autoreload for development.

```python
import os

import colorcet as cc
import contextily as cx
import geopandas
import matplotlib.colors as mcolors
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from rasterstats import zonal_stats

from blackmarble.extract import bm_extract
from blackmarble.raster import bm_raster, transform

plt.rcParams["figure.figsize"] = (15, 5)
%load_ext autoreload
%autoreload 2

```

--------------------------------

### Get Temporal Gap Information

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download nighttime lights data using the 'Latest_High_Quality_Retrieval' variable to understand temporal gap filling. This variable indicates the date from which the nighttime lights value was sourced.

```python
ntl_tmp_gap_r = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range="2023-01-01",
    token=bearer,
    variable="Latest_High_Quality_Retrieval",
)
```

--------------------------------

### Create Monthly Nighttime Lights Raster

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a monthly raster of nighttime lights. This example uses the International Day of Forests (March 21, 2024) as the target date.

```python
# Create monthly raster
blackmarble.create_raster(
    date_min="2024-03-21",
    date_max="2024-03-21",
    output_directory="data",
    output_skip_if_exists=True
)
```

--------------------------------

### Plot Monthly Aggregate Nighttime Light Radiance

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

This snippet visualizes monthly aggregate nighttime light radiance data for a specific region and time. It uses matplotlib and xarray for plotting and cartopy for basemaps. Ensure the necessary libraries (matplotlib, xarray, cartopy) are installed and the data (VNP46A3) is loaded.

```python
fig, ax = plt.subplots(figsize=(8, 9))

VNP46A3["NearNadir_Composite_Snow_Free"].sel(time="2024-03-01").plot.pcolormesh(
    ax=ax,
    cmap=cc.cm.bmy,
    robust=True,
)

ax.set_title(
    "Monthly Aggregate Nighttime Light Radiance in Ghana, Mar 2024", fontsize=16
)
ax.text(
    0,
    -0.1,
    "Source: NASA Black Marble VNP46A3",
    ha="left",
    va="center",
    transform=ax.transAxes,
    fontsize=12,
    color="black",
    weight="normal",
)
cx.add_basemap(ax, source=cx.providers.CartoDB.Positron, crs=gdf.crs.to_string());

```

--------------------------------

### Build BlackMarblePy Documentation Locally

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Build the project's documentation locally using Sphinx. The generated HTML documentation will be placed in the `_build/html` directory.

```bash
sphinx-build docs _build/html -b html

```

--------------------------------

### Create and Activate Virtual Environment

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Create a Python virtual environment for the project. This helps manage dependencies and isolate project environments. Activation commands differ for Windows.

```shell
python3 -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
```

--------------------------------

### Build BlackMarblePy Documentation Locally

Source: https://worldbank.github.io/blackmarblepy/_sources/CONTRIBUTING.md

Build the project's documentation locally using Sphinx. The generated HTML files will be placed in the `_build/html` directory.

```shell
sphinx-build docs _build/html -b html
```

--------------------------------

### Create Annual Nighttime Lights Raster

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates an annual raster of nighttime lights. The example date range corresponds to the International Day of Forests in 2024.

```python
# Create annual raster
blackmarble.create_raster(
    date_min="2024-03-21",
    date_max="2024-03-21",
    output_directory="data",
    output_skip_if_exists=True
)
```

--------------------------------

### Initialize Black Marble Instance and Retrieve Raster Data

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Demonstrates how to create a BlackMarble instance and retrieve raster data for a specified region of interest and date range. The instance can be initialized with an optional bearer token or by reading from the environment variable BLACKMARBLE_TOKEN.

```python
>>> # Option 1: Class-based interface
>>> from blackmarble import BlackMarble, Product
>>>
>>> # Create a BlackMarble instance. If no bearer token is passed explicitly,
>>> # it will attempt to read from the BLACKMARBLE_TOKEN environment variable.
>>> bm = BlackMarble()  # or: BlackMarble(token="YOUR_BLACKMARBLE_TOKEN")
>>>
>>> # Define your region of interest as a GeoDataFrame (gdf)
>>> # For example: gdf = gpd.read_file("path_to_shapefile.geojson")
>>>
>>> # Retrieve VNP46A2 for date range into a Xarray Dataset
>>> daily = bm.raster(
>>>     gdf,
>>>     product_id=Product.VNP46A2,
>>>     date_range="2020-04-22",
>>> )
```

--------------------------------

### Downloading and Storing Black Marble Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Demonstrates how to download NASA Black Marble data and save it to a specified local directory using the `BlackMarble` class. Files already downloaded are skipped by default.

```python
BlackMarble(
    output_directory="data/",     # Save files to local data/ directory
    output_skip_if_exists=True,   # Set to skip if exists
).raster(
    gdf,
    product_id,
    date_range,
)
```

--------------------------------

### download Method

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Downloads files asynchronously from the NASA Black Marble archive for a specified region, product, and date range.

```APIDOC
## async download(gdf: GeoDataFrame, product_id: Product, date_range: List[date], skip_if_exists: bool = True)

### Description
Downloads files asynchronously from NASA Black Marble archive.

### Parameters
* **gdf** (geopandas.GeoDataFrame) - Region of Interest. Converted to EPSG:4326 and intersected with Black Marble tiles.
* **product_id** (Product) - Nasa Black Marble Product Id (e.g, VNP46A1).
* **date_range** (List[datetime.date]) - Date range for which to download NASA Black Marble data.
* **skip_if_exists** (bool) - Optional - Whether to skip downloading data if file already exists. Defaults to True.

### Returns
* **list** - List of downloaded H5 filenames.

### Return Type
List[pathlib.Path]
```

--------------------------------

### Initialize Black Marble Class

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Instantiate the BlackMarble class to interact with the API. It can automatically read the bearer token from environment variables or accept it explicitly.

```python
from blackmarble import BlackMarble, Product

bm = BlackMarble()  # or: BlackMarble(token="YOUR_BLACKMARBLE_TOKEN")
```

--------------------------------

### Download VNP46 Data with BlackMarblePy

Source: https://worldbank.github.io/blackmarblepy/_sources/README.md

This snippet demonstrates how to initialize the BlackMarble client and download VNP46 data for a specified region and date. It assumes a GeoDataFrame is loaded and recommends using an environment variable for the NASA Earthdata token.

```python
import geopandas as gpd

from blackmarble import BlackMarble, Product

# ------------------------------------------------------------------------------
# 1. Define your region of interest
# ------------------------------------------------------------------------------
# In this example ,we load a region from a GeoJSON.
gdf = gpd.read_file("path/to/your/shapefile.geojson")

# ------------------------------------------------------------------------------
# 2. Set up the BlackMarble client
# ------------------------------------------------------------------------------
# If the environment variable `BLACKMARBLE_TOKEN` is set, it will be used automatically.
# You can also pass your token directly, but using the environment variable is recommended.
bm = BlackMarble(token="YOUR_BLACKMARBLE_TOKEN")

# ------------------------------------------------------------------------------
# 3. Download VNP46 data from NASA Earthdata
# ------------------------------------------------------------------------------
# In this example, we request the VNP46A2 product for a specific date.
# The data is returned as an xarray.Dataset.
raster_earth_day = bm.raster(
    gdf,
    product_id=Product.VNP46A2,
    date_range="2025-04-22",
)
```

--------------------------------

### get_manifest Method

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Retrieves the NASA Black Marble data manifest, including download links, for a given product and date range.

```APIDOC
## async get_manifest(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]]) -> DataFrame

### Description
Retrieve NASA Black Marble data manifest. i.e., download links.

### Parameters
* **product_id** (Product) - NASA Black Marble product suite (VNP46) identifier.
* **date_range** (datetime.date | List[datetime.date]) - Date range for which to retrieve NASA Black Marble data manifest.

### Returns
* **DataFrame** - NASA Black Marble data manifest (i.e., downloads links).

### Return Type
pandas.DataFrame
```

--------------------------------

### Load and Preprocess Daily and Monthly Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/collection-comparison.html

Loads daily and monthly data extracts from CSV files and performs initial processing. This step is crucial for preparing the data for comparison.

```python
daily_sum_data = pd.read_csv("../data/collection1/daily_sum.csv")
monthly_sum_data = pd.read_csv("../data/collection1/monthly_sum.csv")

print("Daily sum data loaded successfully")
print("Monthly sum data loaded successfully")

```

--------------------------------

### BlackMarbleDownloader Class

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

The `BlackMarbleDownloader` class handles the downloading of Black Marble data from specified sources.

```APIDOC
## Class: BlackMarbleDownloader

### Description
Handles the downloading of Black Marble data from specified sources.

### Attributes
- **token** (str): Authentication token for accessing data.
- **directory** (str): The local directory to save downloaded data.
- **collection** (str): The Black Marble collection to download (e.g., '006', '007').
- **URL** (str): The base URL for data downloads.

### Methods
- **download()**: Initiates the download of specified data.
- **get_manifest()**: Retrieves the manifest file for the data.
```

--------------------------------

### Set NASA Earthdata Token Environment Variable

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Demonstrates how to set the NASA Earthdata token as an environment variable for secure access. This is the recommended method for storing your token.

```bash
export BLACKMARBLE_TOKEN=<YOUR_NASA_EARTHDATA_TOKEN>
```

--------------------------------

### Clone BlackMarblePy Repository

Source: https://worldbank.github.io/blackmarblepy/CONTRIBUTING.html

Clone the BlackMarblePy repository from GitHub to your local machine. This is the first step for contributing code or building from source.

```bash
git clone https://github.com/worldbank/blackmarblepy.git
cd blackmarblepy

```

--------------------------------

### Product Enum

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Enumeration of available Black Marble product types.

```APIDOC
## Enum: Product

### Description
Enumeration of available Black Marble product types.

### Members
- **VNP46A1**
- **VNP46A2**
- **VNP46A3**
- **VNP46A4**
```

--------------------------------

### Initialize BlackMarblePy Interface

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Initializes the BlackMarble class, which provides an interface for downloading and processing Black Marble data. Configuration options can be passed during initialization or set via environment variables.

```python
# Class-based interface example

# Initialize the BlackMarble interface
bm = BlackMarble()

# Optional: configure options
# bm = BlackMarble(
#     token="your_token_here",           # NASA Earthdata bearer token (can also be set via env var)
#     check_all_tiles_exist=True,        # Skip dates if any tile is missing
#     drop_values_by_quality_flag=[255], # Mask out invalid data (e.g., fill value)
# )
```

--------------------------------

### Download Number of Observations for Monthly Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download the number of observations used to generate monthly nighttime light values. This is achieved by appending '_Num' to the variable name.

```python
cf_r = bm_raster(
    gdf,
    product_id="VNP46A3",
    date_range="2023-01-01",
    token=bearer,
    variable="NearNadir_Composite_Snow_Free_Num",
)
```

--------------------------------

### Create Raster Stack of Daily Nighttime Lights

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Retrieves NASA Black Marble data for a daily period leading up to Earth Day (April 22, 2025) and creates a raster stack. Each band in the stack represents a different day.

```python
import pandas as pd
from blackmarblepy.api import BlackMarble

date_range = pd.date_range(start='2025-04-20', end='2025-04-22', freq='D')
blackmarble = BlackMarble()

# Get daily data
blackmarble.get_data(date_range=date_range, product='VNP46A2')

# Create raster stack
blackmarble.create_raster_stack()

# Access the raster stack
print(blackmarble.raster_stack)
```

--------------------------------

### Create Daily Raster Stack

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a raster stack of daily data using a GeoDataFrame and a specified product ID. The date range and frequency can be customized.

```python
r_daily = bm.raster(
    gdf,
    product_id="VNP46A2",
    date_range=pd.date_range("2025-01-01", "2025-04-22", freq="D"),
)
```

--------------------------------

### Download Monthly Nighttime Lights

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download monthly nighttime lights data for January 2023 using the 'NearNadir_Composite_Snow_Free' variable. This variable represents nighttime lights, removing snow cover effects.

```python
ntl_r = bm_raster(
    gdf,
    product_id="VNP46A3",
    date_range="2023-01-01",
    token=bearer,
    variable="NearNadir_Composite_Snow_Free",
)
```

--------------------------------

### Download Monthly Quality Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download the quality indicator for monthly nighttime light data. This variable helps identify good-quality, poor-quality, gap-filled, or fill-value pixels.

```python
quality_r = bm_raster(
    gdf,
    product_id="VNP46A3",
    date_range="2023-01-01",
    token=bearer,
    variable="NearNadir_Composite_Snow_Free_Quality",
)
```

--------------------------------

### Load Black Marble Token

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Loads the Black Marble API token from environment variables. Ensure the BLACKMARBLE_TOKEN environment variable is set before running.

```python
bearer = os.getenv("BLACKMARBLE_TOKEN")

```

--------------------------------

### Download Daily Nighttime Lights Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Downloads daily nighttime lights data (VNP46A2) for a specified date range and region. Uses the 'Gap_Filled_DNB_BRDF-Corrected_NTL' variable by default if not specified.

```python
ntl_r = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range="2023-01-01",
    token=bearer,
    variable="Gap_Filled_DNB_BRDF-Corrected_NTL",
)

```

--------------------------------

### Create Yearly Raster Stack

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a raster stack of yearly data for a specified product and date range. Requires a GeoDataFrame and pandas for date range generation.

```python
import pandas as pd
import blackmarblepy as bm

r_yearly = bm.raster(
    gdf,
    product_id="VNP46A4",
    date_range=pd.date_range("2019-01-01", "2024-01-01", freq="YS"),
)
```

--------------------------------

### Create Monthly Raster Stack

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a raster stack of monthly data for a specified geographic area and date range. Requires a GeoDataFrame, product ID, and a date range.

```python
r_monthly = bm.raster(
    gdf,
    product_id="VNP46A3",
    date_range=pd.date_range("2023-01-01", "2025-04-01", freq="MS"),
)
```

--------------------------------

### Filter Nighttime Lights by Quality

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download nighttime lights data, filtering out pixels with quality flags 2 and 255. This ensures only good quality observations are used.

```python
ntl_good_qual_r = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range="2023-01-01",
    token=bearer,
    variable="Gap_Filled_DNB_BRDF-Corrected_NTL",
    quality_flag_rm=[2, 255],
)
```

--------------------------------

### Download Non-Gap Filled Nighttime Lights

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Download nighttime lights data using the 'DNB_BRDF-Corrected_NTL' variable, excluding gap-filled observations and poor quality pixels. This provides data directly from the observation date.

```python
ntl_r = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range="2023-01-01",
    token=bearer,
    variable="DNB_BRDF-Corrected_NTL",
    quality_flag_rm=[2, 255],
)
```

--------------------------------

### Visualizing Nighttime Light Trends

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Generate plots to visualize trends in average nighttime lights (ntl_mean) and the proportion of non-NaN pixels over a date range. This helps identify patterns and potential data issues.

```python
fig, axs = plt.subplots(
    1, 2, figsize=(12, 5)
)  # 1 row, 2 columns for side-by-side plots

# Left plot (date vs ntl_mean)
axs[0].plot(ntl_df["date"], ntl_df["ntl_mean"], marker="o", linestyle="-")
axs[0].set_title("ntl_mean")
axs[0].set_xlabel("Date")
axs[0].set_ylabel("ntl_mean")
axs[0].tick_params(axis="x", rotation=90)

# Right plot (date vs prop_na)
axs[1].plot(
    ntl_df["date"],
    ntl_df["prop_non_na_pixels"],
    marker="o",
    linestyle="-",
    color="orange",
)
axs[1].set_title("prop_non_na_pixels")
axs[1].set_xlabel("Date")
axs[1].set_ylabel("prop_non_na_pixels")
axs[1].tick_params(axis="x", rotation=90)

# Adjust layout for better spacing
plt.tight_layout()

# Display the plots
plt.show()
```

--------------------------------

### bm_extract()

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Extracts data from NASA Black Marble HDF5 files.

```APIDOC
## bm_extract()

### Description
Extracts data from NASA Black Marble HDF5 files.

### Method
Not specified (likely a function)

### Parameters
* **date_range** (_datetime.date_ or _List_[_datetime.date_]_) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.
* **token** (_str_) – NASA Earthdata bearer token.
* **variable** (_str_, optional) – Variable for which to generate a GeoTIFF raster. Defaults to product-specific variables.
* **drop_values_by_quality_flag** (_List_[_int_], optional) – List of quality flag values to drop data for.
* **check_all_tiles_exist** (_bool_, optional) – Whether to check if all Black Marble nighttime light tiles exist for the region of interest. Defaults to True.
* **output_directory** (_pathlib.Path_, optional) – Directory to produce output. Defaults to a temporary directory.
* **output_skip_if_exists** (_bool_, optional) – Whether to skip downloading or extracting data if the data file for that date already exists. Defaults to True.

### Returns
xarray.Dataset containing a stack of nighttime lights rasters

### Request Example
```python
# Example usage
# data = bm_extract(date_range='2022-01-01', token='YOUR_TOKEN', product='VNP46A1')
```

### Response
#### Success Response
- **xarray.Dataset**: A dataset containing the extracted nighttime light rasters.
```

--------------------------------

### Plotting Total Annual Nighttime Lights Radiance Trends with Bokeh

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates an interactive Bokeh plot showing the total annual nighttime lights radiance trends across different administrative divisions over time. Includes hover tools for detailed data inspection and legend for hiding/showing lines.

```python
p = figure(
    title="Ghana: Total Annual Nighttime Lights Radiance",
    width=760,
    height=600,
    x_axis_label="Year",
    x_axis_type="datetime",
    y_axis_type="log",
    y_axis_label="NTL Radiance",
    tools="pan,wheel_zoom,box_zoom,reset,save,box_select",
)
p.add_layout(
    Title(
        text=f"Source: NASA Black Marble. Creation date: {datetime.datetime.today().strftime('%d %B %Y')}.",
        text_font_size="10pt",
        text_font_style="italic",
    ),
    "below",
)
p.add_tools(
    HoverTool(
        tooltips=[
            ("Year", "@x{%Y}"),
            ("Radiance", "@y{0.00}"),
        ],
        formatters={"@x": "datetime"},
    )
)

data = VNP46A4.pivot_table(
    index="date", columns=["NAME_1"], values=["ntl_sum"], aggfunc="sum"
)

for column, color in zip(data.columns, cc.glasbey):
    r = p.line(
        data.index,
        data[column],
        legend_label=column[1],
        line_color=color,
        line_dash="dotdash",
        line_width=2,
    )

p.legend.click_policy = "hide"
p.title.text_font_size = "16pt"
p.add_layout(p.legend[0], "right")

output_notebook()
show(p)
```

--------------------------------

### Calculating and Visualizing Year-over-Year Radiance Change

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Computes and visualizes the percentage change in nighttime lights radiance between two specific years (2019 and 2024) for Ghana, overlaid with a dark basemap.

```python
fig, ax = plt.subplots(figsize=(10, 12))

delta = (
    (
        (
            r_yearly["NearNadir_Composite_Snow_Free"].sel(time="2024-01-01")
            - r_yearly["NearNadir_Composite_Snow_Free"].sel(time="2019-01-01")
        )
        / r_yearly["NearNadir_Composite_Snow_Free"].sel(time="2019-01-01")
    )
    # .drop("time")
    .plot.pcolormesh(ax=ax, cmap="Spectral", robust=True)
)

ax.set_title("Ghana: NTL Radiance Increase/Decrease (2019-2024)", fontsize=16)
ax.text(
    0,
    -0.1,
    "Source: NASA Black Marble VNP46A3",
    ha="left",
    va="center",
    transform=ax.transAxes,
    fontsize=10,
    color="black",
    weight="normal",
)
cx.add_basemap(ax, source=cx.providers.CartoDB.DarkMatter, crs=gdf.crs.to_string())
```

--------------------------------

### BlackMarble.raster()

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Retrieves NASA Black Marble nighttime light data for a specified date range and product. It allows for filtering by quality flags and specifying output options.

```APIDOC
## BlackMarble.raster()

### Description
Retrieves NASA Black Marble nighttime light data for a specified date range and product. It allows for filtering by quality flags and specifying output options.

### Method
Not specified (likely a method within a class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **date_range** (_datetime.date_ or _List_[_datetime.date_]_) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.
* **token** (_str_) – NASA Earthdata bearer token.
* **variable** (_str_, optional) – Variable for which to generate a GeoTIFF raster. Defaults to product-specific variables.
* **drop_values_by_quality_flag** (_List_[_int_], optional) – List of quality flag values to drop data for.
* **check_all_tiles_exist** (_bool_, optional) – Whether to check if all Black Marble nighttime light tiles exist for the region of interest. Defaults to True.
* **output_directory** (_pathlib.Path_, optional) – Directory to produce output. Defaults to a temporary directory.
* **output_skip_if_exists** (_bool_, optional) – Whether to skip downloading or extracting data if the data file for that date already exists. Defaults to True.

### Returns
xarray.Dataset containing a stack of nighttime lights rasters

### Request Example
```python
# Example usage (assuming BlackMarble class is instantiated)
# bm = BlackMarble(token='YOUR_TOKEN')
# data = bm.raster(date_range=['2022-01-01', '2022-01-05'], product='VNP46A2')
```

### Response
#### Success Response
- **xarray.Dataset**: A dataset containing the requested nighttime light rasters.
```

--------------------------------

### Create Daily Nighttime Lights Raster

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a daily raster of nighttime lights for a specified date range. Ensure the necessary libraries are imported and the region of interest is defined.

```python
# Create daily raster
blackmarble.create_raster(
    date_min="2024-03-21",
    date_max="2024-03-21",
    output_directory="data",
    output_skip_if_exists=True
)
```

--------------------------------

### BlackMarbleDownloader Class

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

The BlackMarbleDownloader class is used to retrieve NASA Black Marble data. It requires a NASA EarthData bearer token, a local directory for downloads, and optionally a collection version.

```APIDOC
## class BlackMarbleDownloader(token: str, directory: Path, collection: str = '5200')

### Description
A downloader to retrieve NASA Black Marble data.

### Parameters
* **token** (str) - Required - NASA EarthData bearer token.
* **directory** (Path) - Required - Local directory to which download.
* **collection** (str) - Optional - NASA Black Marble collection version (‘5000’ for collection-1, ‘5200’ for collection-2). Defaults to '5200'.

### Attributes
* **URL** (ClassVar[str]) - Base URL for data retrieval.
* **collection** (str)
* **directory** (Path)
```

--------------------------------

### Forcing Redownload of Black Marble Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Shows how to force the redownload of NASA Black Marble data by setting `output_skip_if_exists` to `False` when initializing the `BlackMarble` class.

```python
BlackMarble(
    output_directory="data/",
    output_skip_if_exists=False,  # Force redownload
).raster(
    gdf,
    product_id,
    date_range,
)
```

--------------------------------

### Plotting Daily Aggregate Nighttime Light Radiance

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

This snippet visualizes daily aggregate nighttime light radiance data from the VNP46A2 dataset for a specific date. It requires matplotlib, cartopy, and the Black Marble dataset loaded into a xarray DataArray. The plot uses a custom colormap and adds a basemap for geographical context.

```python
fig, ax = plt.subplots(figsize=(8, 9))

VNP46A2["DNB_BRDF-Corrected_NTL"].sel(time="2024-03-21").plot.pcolormesh(
    ax=ax,
    cmap=cc.cm.bmy,
    robust=True,
)

ax.set_title(
    "Daily Aggregate Nighttime Light Radiance in Ghana, Day of Forests 2024",
    fontsize=16,
)
ax.text(
    0,
    -0.1,
    "Source: NASA Black Marble VNP46A2",
    ha="left",
    va="center",
    transform=ax.transAxes,
    fontsize=12,
    color="black",
    weight="normal",
)
cx.add_basemap(ax, source=cx.providers.CartoDB.Positron, crs=gdf.crs.to_string());

```

--------------------------------

### get_url Function

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Asynchronously fetches an HTTP response from a given URL with specified parameters.

```APIDOC
## async get_url(_client: AsyncClient, _url: str, _params: dict) -> Response

### Description
Fetches an HTTP response from a given URL.

### Parameters
* **client** (AsyncClient) - The asynchronous HTTP client.
* **url** (str) - The URL to fetch.
* **params** (dict) - Parameters to include in the request.

### Returns
* **Response** - The HTTP response object.

### Return Type
httpx.Response
```

--------------------------------

### BlackMarble.raster

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

Creates a stack of nighttime lights rasters by retrieving data from NASA Black Marble. It takes a region of interest, product ID, and date range as input, and can optionally specify a variable to retrieve.

```APIDOC
## raster

### Description
Create a stack of nighttime lights rasters by retrieving from NASA Black Marble data.

### Method
`raster(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], variable: Optional[str] = None) -> Dataset`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **gdf** (_geopandas.GeoDataFrame_) – Region of interest
* **product_id** (_Product_) – Identifier for the NASA Black Marble VNP46 product. For detailed product descriptions, see also https://blackmarble.gsfc.nasa.gov/#product.
* **date_range** (_datetime.date_ _|__List_ _[__datetime.date_ _]_) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.
* **variable** (_str_ _,__default = None_) – 
Variable for which to a GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:
    * For `VNP46A1`, uses `DNB_At_Sensor_Radiance_500m`
    * For `VNP46A2`, uses `Gap_Filled_DNB_BRDF-Corrected_NTL`
    * For `VNP46A3`, uses `NearNadir_Composite_Snow_Free`.
    * For `VNP46A4`, uses `NearNadir_Composite_Snow_Free`.

### Returns
A stack of nighttime lights rasters.

### Return type
xarray.Dataset
```

--------------------------------

### BlackMarble Class

Source: https://worldbank.github.io/blackmarblepy/api/blackmarble.html

The `BlackMarble` class provides methods for interacting with Black Marble data, including collating tiles, extracting data, and generating rasters.

```APIDOC
## Class: BlackMarble

### Description
Provides methods for interacting with Black Marble data, including collating tiles, extracting data, and generating rasters.

### Methods
- **close()**: Closes any open resources.
- **collate_tiles()**: Collates downloaded tiles into a single dataset.
- **extract()**: Extracts specified data from the Black Marble dataset.
- **raster()**: Generates a raster representation of the data.
```

--------------------------------

### Plot Monthly Nighttime Light Radiance

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

Generates a plot of monthly aggregate nighttime light radiance using the VNP46A3 product. Ensure matplotlib and the relevant data (r_monthly) are imported and available.

```python
import matplotlib.pyplot as plt

# Assuming r_monthly is a pre-loaded xarray DataArray
# Example placeholder for r_monthly:
# import xarray as xr
# import numpy as np
# dates = pd.date_range('2020-01-01', '2020-12-31', freq='MS')
# r_monthly = xr.DataArray(
#     np.random.rand(len(dates), 100, 100),
#     coords={'time': dates, 'y': np.arange(100), 'x': np.arange(100)},
#     dims=['time', 'y', 'x'],
#     name='NearNadir_Composite_Snow_Free'
# )

# Create the figure and axis
fig, ax = plt.subplots(figsize=(10, 5))

# Plot NTL radiance
r_monthly["NearNadir_Composite_Snow_Free"].sum(dim=["x", "y"]).plot(ax=ax)

ax.set_title(
    "Monthly Aggregate Nighttime Light Radiance in Ghana", fontsize=18, weight="bold"
)
ax.set_xlabel("Date", fontsize=12)
ax.set_ylabel("Radiance (nW/cm²/sr)", fontsize=12)
plt.ylim(bottom=0)
ax.text(
    0,
    -0.2,
    "Source: NASA Black Marble VNP46A3",
    ha="left",
    va="center",
    transform=ax.transAxes,
    fontsize=10,
    color="black",
    weight="normal",
)

fig.tight_layout()
plt.show()
```

--------------------------------

### Plotting Yearly Aggregate Nighttime Light Radiance

Source: https://worldbank.github.io/blackmarblepy/notebooks/blackmarblepy.html

This snippet visualizes the yearly aggregate nighttime light radiance for a specific region and date using the Black Marble VNP46A4 dataset. It requires matplotlib, cartopy, and the xarray library for plotting.

```python
fig, ax = plt.subplots(figsize=(8, 9))

VNP46A4["NearNadir_Composite_Snow_Free"].sel(time="2024-01-01").plot.pcolormesh(
    ax=ax,
    cmap=cc.cm.bmy,
    robust=True,
)

ax.set_title("Yearly Aggregate Nighttime Light Radiance in Ghana, 2024", fontsize=16)
ax.text(
    0,
    -0.1,
    "Source: NASA Black Marble VNP46A4",
    ha="left",
    va="center",
    transform=ax.transAxes,
    fontsize=12,
    color="black",
    weight="normal",
)
cx.add_basemap(ax, source=cx.providers.CartoDB.Positron, crs=gdf.crs.to_string());

```

--------------------------------

### Plot Monthly Quality Data

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Visualize the quality assessment of monthly nighttime light data using a discrete colormap. The colors represent different quality levels: blue (good), green (poor), yellow (gap filled), and red (fill value).

```python
fig, ax = plt.subplots()

# Create a discrete colormap
cmap = mcolors.ListedColormap(["blue", "green", "yellow", "red"])
# Plot
quality_r["NearNadir_Composite_Snow_Free_Quality"].sel(time="2023-01-01").plot(
    ax=ax, cmap=cmap
)
cx.add_basemap(ax, crs=gdf.crs.to_string(), source=cx.providers.CartoDB.Positron)

plt.axis("off")
plt.tight_layout()
```

--------------------------------

### Display Total Number of Pixels

Source: https://worldbank.github.io/blackmarblepy/notebooks/quality-assessment.html

Prints the total number of pixels covering the region of interest, including both valid and NA values.

```python
## Number of pixels
n_pixel[0]["count"] + n_pixel[0]["nan"]

```
Tokens:
Raw