BlackMarblePy

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

Documentation#

The BlackMarblePy library allows you to interact with and manipulate data from NASA’s Black Marble, which provides global nighttime lights data. Below is a guide on how to use the key functionalities of the library.

Installation#

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

From PyPI#

pip install blackmarblepy

From Source#

Clone or download this repository to your local machine. Then, navigate to the root directory of the repository:
```
git clone https://github.com/worldbank/blackmarblepy.git
cd blackmarblepy
```

Create a virtual environment (optional but recommended):

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

Install the package with dependencies:
```
pip install .
```
Install the package in editable mode with dependencies:
```
pip install -e .
```
The -e flag stands for “editable,” meaning changes to the source code will immediately affect the installed package.

Building Documentation Locally#

To build the documentation locally, after (1) and (2) above, please follow these steps:

Install the package with documentation dependencies:
```
  pip install -e .[docs]
```

Build the documentation:

  sphinx-build docs _build/html -b html

The generated documentation will be available in the _build/html directory. Open the index.html file in a web browser to view it.

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

# Retrieve VNP46A2 for date range into a Xarray Dataset
daily = bm_raster(
    gdf,
    product_id="VNP46A2",
    date_range=pd.date_range("2022-01-01", "2022-03-31", freq="D"),
    bearer=bearer,
)

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

Full API Reference#

For a full reference of all available functions and their parameters, please refer to the official documentation.

Contributing#

We welcome contributions to improve this documentation. If you find errors, have suggestions, or want to add new content, please follow our contribution guidelines.

Feedback and Issues#

If you have any feedback, encounter issues, or want to suggest improvements, please open an issue.

Versioning#

This project follows the CALVER (Calendar Versioning) scheme for versioning. If you have any questions or need more information about our versioning approach, feel free to ask.

Contributors#

This project follows the all-contributors specification. Contributions of any kind are welcome!

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},
  howpublished = {\url{https://worldbank.github.io/blackmarblepy}},
  doi = {10.5281/zenodo.10667907},
  url = {https://worldbank.github.io/blackmarblepy},
}

1: Gabriel Stefanini Vicente and Robert Marty. BlackMarblePy: Georeferenced Rasters and Statistics of Nighttime Lights from NASA Black Marble. https://worldbank.github.io/blackmarblepy, 2023. URL: https://worldbank.github.io/blackmarblepy, doi:10.5281/zenodo.10667907.

License#

This projects is licensed under the Mozilla Public License - see the LICENSE file for details.