BlackMarblePy

BlackMarblePy is a Python package that provides a simple way to use nighttime lights data from NASA's Black Marble project. Black Marble is a NASA Earth Science Data Systems (ESDS) project that provides a product suite of daily, monthly and yearly global nighttime lights. This package automates the process of downloading all relevant tiles from the NASA LAADS DAAC to cover a region of interest, converting the raw files (in HDF5 format), to georeferenced rasters, and mosaicing rasters together when needed.

Features

Download daily, monthly, and yearly nighttime lights data for user-specified region of interest and time.
Parallel downloading for faster data retrieval and automatic retry mechanism for handling network errors.
Access NASA Black Marble as a Xarray Dataset
- Integrated data visualization with customization options
  - Choose between various plot types, including bar charts, line graphs, and heatmaps.
  - Customize plot appearance with color palettes, axes labels, titles, and legends.
  - Save visualizations as high-resolution images for presentations or reports.
- Perform time series analysis on nighttime lights data.
  - Calculate zonal statistics like mean and sum.
  - Plot time series of nighttime lights data.

Installation

BlackMarblePy is available on PyPI as blackmarblepy and can installed using pip:

pip install blackmarblepy

Usage

Before downloading and extracting Black Marble data, define the NASA LAADS archive bearer token, and define a region of interest (i.e., gdf as a geopandas.GeoDataFrame).

from blackmarble.raster import bm_raster

# Raster stack of daily data
date_range = pd.date_range("2022-01-01", "2022-03-31", freq="D")

# Retrieve VNP46A2 for date range into a Xarray Dataset
daily = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range=date_range,
    bearer=bearer,
)

For more detailed information and examples, please refer to the documentation.

Contributing

Contributions are welcome! If you'd like to contribute, please follow our contribution guidelines.

Contributors

Gabriel Stefanini Vicente

Robert Marty

Citation

When using BlackMarblePy, your support is much appreciated! Please consider using the following citation or download bibliography.bib:

@misc{blackmarblepy,
  title = {{BlackMarblePy: Georeferenced Rasters and Statistics of Nighttime Lights from NASA Black Marble}},
  author = {Gabriel {Stefanini Vicente} and Robert Marty},
  year = {2023},
  note = {{BlackMarblePy} v0.2.2},
  url = {https://worldbank.github.io/blackmarblepy},
}

{cite:empty}blackmarblepy

:filter: docname in docnames
:style: plain

License

This project is open-source - see the LICENSE file for details

Abdulazizbek/blackmarblepy