Prepare v0.2.0 (#28)

* Add favicon and logo without background * Update example * Update README * Bump v0.2.0
worldbank · Dec 7, 2023 · 4d57ded · 4d57ded
1 parent 1b80afc
commit 4d57ded
Show file tree

Hide file tree

Showing 13 changed files with 1,013 additions and 896 deletions.
diff --git a/README.md b/README.md
@@ -1,29 +1,54 @@
 # BlackMarblePy
 
-[![Python](https://img.shields.io/pypi/pyversions/blackmarblepy.svg)](https://badge.fury.io/py/blackmarblepy)
 [![PyPI version](https://badge.fury.io/py/blackmarblepy.svg)](https://badge.fury.io/py/blackmarblepy)
 [![docs](https://github.com/worldbank/blackmarblepy/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/worldbank/blackmarblepy/actions/workflows/gh-pages.yml)
+[![GitHub Repo stars](https://img.shields.io/github/stars/worldbank/blackmarblepy)](https://github.com/worldbank/blackmarblepy)
+[![activity](https://img.shields.io/github/commit-activity/m/worldbank/blackmarblepy)](https://github.com/worldbank/blackmarblepy/graphs/commit-activity)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**BlackMarblePy** is a Python package for working with Black Marble data. [Black Marble](https://blackmarble.gsfc.nasa.gov) is a [NASA Earth Observatory](https://earthobservatory.nasa.gov) project that provides global nighttime lights data. The package automates the process of downloading all relevant tiles from the [NASA LAADS archive](https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/5000/VNP46A3/) to cover a region of interest, converting the raw files (in H5 format) to georeferenced rasters, and mosaicing rasters together when needed.
+**BlackMarblePy** provides a simple and efficient way to retrieve and extract nighttime lights data from NASA's Black Marble project. [Black Marble](https://blackmarble.gsfc.nasa.gov) is a [NASA Earth Observatory](https://earthobservatory.nasa.gov) 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 archive](https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/5000/VNP46A3/) to cover a region of interest, converting the raw files (in HDF5 format), to georeferenced rasters, and mosaicing rasters together when needed.
 
 ## Features
 
-- Download Black Marble data for specific time periods and regions.
-- Visualize nighttime lights using customizable color palettes.
-- Calculate basic statistics from Black Marble images.
-- Perform time-series analysis on nighttime lights data.
+- Download daily, monthly, and yearly nighttime lights data  for user-specified region of interest and time range.
+- 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](https://pypi.org); you can install it using `pip`:
+**BlackMarblePy** is available on [PyPI](https://pypi.org) as [blackmarblepy](https://pypi.org/project/blackmarblepy) and can installed using `pip`:
 
 ```shell
 pip install blackmarblepy
 ```
 
 ## Usage
 
-Before downloading and extracting Black Marble data, define the NASA bearer token, and define a region of interest. For more detailed documentation and examples, please refer to the [documentation](https://worldbank.github.io/blackmarblepy/examples/blackmarblepy.html).
+Before downloading and extracting Black Marble data, define the [NASA LAADS archive](https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/5000/VNP46A3/) `bearer` token, and define a region of interest (i.e., `gdf` as a [`geopandas.GeoDataFrame`](https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.html)).
+
+```python
+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](https://worldbank.github.io/blackmarblepy/examples/blackmarblepy.html).
 
 ## Contributing
 

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,6 +1,6 @@
 # Book settings
 title:
-author: Development Data Group
+author: World Bank Development Data Group
 logo: images/logo.png
 only_build_toc_files: true
 
@@ -17,6 +17,7 @@ html:
   use_repository_button: true
   use_issues_button: true
   baseurl: https://worldbank.github.io/blackmarblepy
+  html_favicon: "images/favicon.ico"
 
 #######################################################################################
 # Execution settings

diff --git a/docs/bibliography.bib b/docs/bibliography.bib
@@ -0,0 +1,13 @@
+@article{ROMAN2018113,
+title = {NASA's Black Marble nighttime lights product suite},
+journal = {Remote Sensing of Environment},
+volume = {210},
+pages = {113-143},
+year = {2018},
+issn = {0034-4257},
+doi = {https://doi.org/10.1016/j.rse.2018.03.017},
+url = {https://www.sciencedirect.com/science/article/pii/S003442571830110X},
+author = {Miguel O. Román and Zhuosen Wang and Qingsong Sun and Virginia Kalb and Steven D. Miller and Andrew Molthan and Lori Schultz and Jordan Bell and Eleanor C. Stokes and Bhartendu Pandey and Karen C. Seto and Dorothy Hall and Tomohiro Oda and Robert E. Wolfe and Gary Lin and Navid Golpayegani and Sadashiva Devadiga and Carol Davidson and Sudipta Sarkar and Cid Praderas and Jeffrey Schmaltz and Ryan Boller and Joshua Stevens and Olga M. {Ramos González} and Elizabeth Padilla and José Alonso and Yasmín Detrés and Roy Armstrong and Ismael Miranda and Yasmín Conte and Nitza Marrero and Kytt MacManus and Thomas Esch and Edward J. Masuoka},
+keywords = {Suomi-NPP, JPSS, NASA black marble, VIIRS, Night lights, NTL, Urban dynamics, Long-term monitoring, Lunar BRDF, Albedo, Atmospheric correction},
+abstract = {NASA's Black Marble nighttime lights product suite (VNP46) is available at 500 m resolution since January 2012 with data from the Visible Infrared Imaging Radiometer Suite (VIIRS) Day/Night Band (DNB) onboard the Suomi National Polar-orbiting Platform (SNPP). The retrieval algorithm, developed and implemented for routine global processing at NASA's Land Science Investigator-led Processing System (SIPS), utilizes all high-quality, cloud-free, atmospheric-, terrain-, vegetation-, snow-, lunar-, and stray light-corrected radiances to estimate daily nighttime lights (NTL) and other intrinsic surface optical properties. Key algorithm enhancements include: (1) lunar irradiance modeling to resolve non-linear changes in phase and libration; (2) vector radiative transfer and lunar bidirectional surface anisotropic reflectance modeling to correct for atmospheric and BRDF effects; (3) geometric-optical and canopy radiative transfer modeling to account for seasonal variations in NTL; and (4) temporal gap-filling to reduce persistent data gaps. Extensive benchmark tests at representative spatial and temporal scales were conducted on the VNP46 time series record to characterize the uncertainties stemming from upstream data sources. Initial validation results are presented together with example case studies illustrating the scientific utility of the products. This includes an evaluation of temporal patterns of NTL dynamics associated with urbanization, socioeconomic variability, cultural characteristics, and displaced populations affected by conflict. Current and planned activities under the Group on Earth Observations (GEO) Human Planet Initiative are aimed at evaluating the products at different geographic locations and time periods representing the full range of retrieval conditions.}
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,10 +4,10 @@
 # re-generate this one.
 ###############################################################################
 apidoc_module_dir = "../src"
-author = "Development Data Group"
+author = "World Bank Development Data Group"
 bibtex_bibfiles = ["bibliography.bib"]
 comments_config = {"hypothesis": False, "utterances": False}
-copyright = "2022"
+copyright = "2023"
 exclude_patterns = ["**.ipynb_checkpoints", ".DS_Store", "Thumbs.db", "_build"]
 extensions = [
     "sphinx_togglebutton",
@@ -29,7 +29,7 @@
 external_toc_path = "_toc.yml"
 extra_extensions = ["sphinxcontrib.apidoc"]
 html_baseurl = "https://worldbank.github.io/blackmarblepy"
-html_favicon = ""
+html_favicon = "images/favicon.ico"
 html_last_updated_fmt = "%b %d, %Y"
 html_logo = "images/logo.png"
 html_show_copyright = False

diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
diff --git a/docs/images/logo.png b/docs/images/logo.png
diff --git a/docs/ntl_usa.png b/docs/ntl_usa.png
diff --git a/docs/raster_example.png b/docs/raster_example.png
diff --git a/docs/trends_example.png b/docs/trends_example.png
diff --git a/examples/blackmarblepy.ipynb b/examples/blackmarblepy.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -44,7 +44,13 @@ dependencies = [
 	"aiohttp",
 ]
 [project.optional-dependencies]
-docs = ["jupyter-book >= 0.15.1", "sphinxcontrib-apidoc >= 0.4.0, <1"]
+docs = [
+	"docutils==0.17.1",                  # https://jupyterbook.org/en/stable/content/citations.html?highlight=docutils#citations-and-bibliographies
+	"jupyter-book >= 0.15.1",
+	"sphinxcontrib-apidoc >= 0.4.0, <1",
+	"docutils==0.17.1",
+]
+
 
 [project.urls]
 "Homepage" = "https://github.com/worldbank/blackmarblepy"

diff --git a/src/blackmarble/.DS_Store b/src/blackmarble/.DS_Store
diff --git a/src/blackmarble/VERSION b/src/blackmarble/VERSION
@@ -1 +1 @@
-0.1.1
+0.2.0