Create Documentation (#12)

* Migrate to quickstart

* Add config for Sphinx documentation

* Update README

* Remove unnecessary content

* Create GH action documentation workflow

.github/workflows/gh-pages.yml

@@ -0,0 +1,30 @@
+name: Publish Documentation on GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+          cache: "pip"
+      - name: Dependencies
+        run: |
+          if [ -f pyproject.toml ]; then pip install ".[docs]"; fi
+      - name: Build Sphinx Documentation
+        run: |
+          sphinx-build docs _build/html -b html
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: job.status == 'success'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_build/html
+          enable_jekyll: false

README.md

@@ -1,132 +1,34 @@
-# blackmarblepy
+# BlackMarblePy
 
-[![codecov](https://codecov.io/gh/ramarty/blackmarblepy/branch/main/graph/badge.svg?token=blackmarblepy_token_here)](https://codecov.io/gh/ramarty/blackmarblepy)
-[![CI](https://github.com/ramarty/blackmarblepy/actions/workflows/main.yml/badge.svg)](https://github.com/ramarty/blackmarblepy/actions/workflows/main.yml)
+[![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)
 
-<p align="center">
-<img src="ntl_usa.png" alt="Nighttime Lights Map" width="1000"/>
-</p>
+**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.
 
-Create Georeferenced Rasters of Nighttime Lights from [NASA Black Marble data](https://blackmarble.gsfc.nasa.gov/).
+## Features
 
-* [Overview](#overview)
-* [Installation](#installation)
-* [Bearer token](#token)
-* [Functions and arguments](#function-args)
-  * [Functions](#functions)
-  * [Required Arguments](#args-required)
-  * [Optional Arguments](#args-optional)
-  * [Argument only for `bm_extract`](#args-extract)
-* [Quick start](#quickstart)
-  * [Setup](#quickstart-setup)
-  * [Nighttime Lights Raster](#quickstart-raster)
-  * [Nighttime Lights Trends](#quickstart-trends)
-* [Additional Usage](#usage)
+- 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.
 
-## Overview <a name="overview"></a>
+## Installation
 
-This package facilitates downloading nighttime lights [Black Marble](https://blackmarble.gsfc.nasa.gov/) data. Black Marble data is downloaded from the [NASA LAADS Archive](https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/5000/VNP46A3/).  The package automates the process of downloading all relevant tiles from the NASA LAADS archive to cover a region of interest, converting the raw files (in H5 format) to georeferenced rasters, and mosaicing rasters together when needed.
+You can install BlackMarblePy using pip:
 
-## Installation <a name="installation">
-
-The package can be installed via pip.
-
-```bash
-pip install git+https://github.com/ramarty/blackmarblepy.git
-```
-
-```py
-from blackmarblepy.bm_raster import bm_raster
-from blackmarblepy.bm_extract import bm_extract
+```shell
+pip install blackmarblepy
 ```
 
-## Bearer Token <a name="token">
-
-The function requires using a **Bearer Token**; to obtain a token, follow the below steps:
-
-1. Go to the [NASA LAADS Archive](https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/5000/VNP46A3/)
-2. Click "Login" (bottom on top right); create an account if needed.
-3. Click "See wget Download Command" (bottom near top, in the middle)
-4. After clicking, you will see text that can be used to download data. The "Bearer" token will be a long string in red.
-
-## Functions and arguments <a name="function-args">
-
-### Functions <a name="functions">
-
-The package provides two functions:
-
-* `bm_raster` produces a raster of Black Marble nighttime lights.
-* `bm_extract` produces a dataframe of aggregated nighttime lights to a region of interest (e.g., average nighttime lights within US States).
-
-Both functions take the following arguments:
-
-### Required arguments <a name="args-required">
-
-* **roi_sf:** Region of interest; geopandas dataframe. Must be in the [WGS 84 (epsg:4326)](https://epsg.io/4326) coordinate reference system. For `bm_extract`, aggregates nighttime lights within each polygon of `roi_sf`.
-
-* **product_id:** One of the following:
-
-  * `"VNP46A1"`: Daily (raw)
-  * `"VNP46A2"`: Daily (corrected)
-  * `"VNP46A3"`: Monthly
-  * `"VNP46A4"`: Annual
-
-* **date:**  Date of raster data. Entering one date will produce a raster. Entering multiple dates will produce a raster stack.
-
-  * For `product_id`s `"VNP46A1"` and `"VNP46A2"`, a date (eg, `"2021-10-03"`).
-  * For `product_id` `"VNP46A3"`, a date or year-month (e.g., `"2021-10-01"`, where the day will be ignored, or `"2021-10"`).
-  * For `product_id` `"VNP46A4"`, year or date  (e.g., `"2021-10-01"`, where the month and day will be ignored, or `2021`).
-
-* **bearer:** NASA bearer token. For instructions on how to create a token, see [here](https://github.com/ramarty/blackmarblepy#bearer-token-).
-
-### Optional arguments <a name="args-optional">
-
-* **variable:** Variable to used to create raster (default: `NULL`). For information on all variable choices, see [here](https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document%20Archive/Science%20Data%20Product%20Documentation/VIIRS_Black_Marble_UG_v1.2_April_2021.pdf); for `VNP46A1`, see Table 3; for `VNP46A2` see Table 6; for `VNP46A3` and `VNP46A4`, see Table 9. If `NULL`, uses the following default variables:
-
-  * For `product_id` `"VNP46A1"`, uses `DNB_At_Sensor_Radiance_500m`.
-  * For `product_id` `"VNP46A2"`, uses `Gap_Filled_DNB_BRDF-Corrected_NTL`.
-  * For `product_id`s `"VNP46A3"` and `"VNP46A4"`, uses `NearNadir_Composite_Snow_Free`.
-
-* **quality_flag_rm:** Quality flag values to use to set values to `NA`. Each pixel has a quality flag value, where low quality values can be removed. Values are set to `NA` for each value in ther `quality_flag_rm` vector. (Default: `[255]`).
-
-  * For `VNP46A1` and `VNP46A2` (daily data):
-    * `0`: High-quality, Persistent nighttime lights
-    * `1`: High-quality, Ephemeral nighttime Lights
-    * `2`: Poor-quality, Outlier, potential cloud contamination, or other issues
-    * `255`: No retrieval, Fill value (masked out on ingestion)
-
-  * For `VNP46A3` and `VNP46A4` (monthly and annual data):
-    * `0`: Good-quality, The number of observations used for the composite is larger than 3
-    * `1`: Poor-quality, The number of observations used for the composite is less than or equal to 3
-    * `2`: Gap filled NTL based on historical data
-    * `255`: Fill value
-
-* **output_location_type:** Where output should be stored (default: for `bm_raster`, `"tempfile"`; for `bm_extract`, `"memory"`). Either:
-
-  * [For `bm_raster`] `tempfile` where the function will export the raster as a tempfile
-  * [For `bm_extract`] `memory` where the function will export the data as pandas dataframe
-  * `file` where the function will export the data as a file. For `bm_raster`, a `.tif` file will be saved; for `bm_extract`, a `.csv` file will be saved. A file is saved for each date. Consequently, if `date = [2018, 2019, 2020]`, three datasets will be saved: one for each year. Saving a dataset for each date can facilitate re-running the function later and only downloading data for dates where data have not been downloaded.
-
-If `output_location_type = "file"`, the following arguments can be used:
-
-* **file_dir:** The directory where data should be exported (default: `NULL`, so the working directory will be used)
-* **file_prefix:** Prefix to add to the file to be saved. The file will be saved as the following: `[file_prefix][product_id]_t[date].[tif/csv]`
-* **file_skip_if_exists:** Whether the function should first check wither the file already exists, and to skip downloading or extracting data if the data for that date if the file already exists (default: `TRUE`). If the function is first run with `date = c(2018, 2019, 2020)`, then is later run with `date = c(2018, 2019, 2020, 2021)`, the function will only download/extract data for 2021. Skipping existing files can facilitate re-running the function at a later date to download only more recent data.
-
-### Argument for `bm_extract` only <a name="args-extract">
-
-* **aggregation_fun:** A vector of functions to aggregate data (default: `"mean"`). The `zonal_stats` function from the `rasterstats` package is used for aggregations; this parameter is passed to `stats` argument in `zonal_stats`.
-
-## Quickstart <a name ="quickstart">
-
-### Setup <a name="quickstart-setup"></a>
+## Usage
 
 Before downloading and extracting Black Marble data, we first load libraries, define the NASA bearer token, and define a region of interest.
 
 ```python
 ## Libraries
-from blackmarblepy.bm_raster import bm_raster
-from blackmarblepy.bm_extract import bm_extract
+from blackmarble.bm_raster import bm_raster
+from blackmarble.bm_extract import bm_extract
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -165,39 +67,12 @@ plt.tight_layout()
 plt.axis("off")
 ```
 
-<p align="center">
-<img src="raster_example.png" alt="Nighttime Lights Map" width="500"/>
-</p>
-
-### Trends in Nighttime Lights <a name="quickstart-trends"></a>
-
-The below example shows extracting average annual nighttime lights data for Ghana at the administrative 1 level and plotting the trends.
-
-```python
-## Annual trends in nighttime lights
-ntl_df = bm_extract(roi_sf = ghana_adm1,
-                    product_id = "VNP46A4",
-                    date = list(range(2012, 2023)),
-                    bearer = bearer)
-
-## Plot Trends
-sns.set(style="whitegrid")
-g = sns.catplot(data=ntl_df, kind="bar", x="date", y="ntl_mean", col="NAME_1", height=2.5, col_wrap = 3, aspect=1.2, color = "orange")
-
-# Set the x-axis rotation for better visibility
-g.set_xticklabels(rotation=45)
+For more detailed documentation and examples, please refer to the [documentation](https://worldbank.github.io/blackmarblepy/quickstart.html).
 
-# Adjust spacing between subplots
-plt.tight_layout()
-
-# Show the plot
-plt.show()
-```
+## Contributing
 
-<p align="center">
-<img src="trends_example.png" alt="Nighttime Lights Map" width="1000"/>
-</p>
+Contributions are welcome! If you'd like to contribute, please follow our [contribution guidelines](CONTRIBUTING.md).
 
-## Additional Usage <a name="usage">
+## License
 
-To see additional examples of using the package, see [here](https://github.com/ramarty/blackmarblepy/blob/main/examples/blackmarbley_example.ipynb).
+This project is open-source - see the [LICENSE](LICENSE) file for details

docs/README.md

@@ -0,0 +1 @@
+../README.md

docs/_config.yml

@@ -0,0 +1,39 @@
+# Book settings
+title:
+author: Development Data Group
+logo: images/logo.png
+only_build_toc_files: true
+
+repository:
+  url: https://github.com/worldbank/blackmarblepy
+  branch: main
+
+#######################################################################################
+# HTML-specific settings
+html:
+  home_page_in_navbar: false
+  extra_navbar: ""
+  use_edit_page_button: true
+  use_repository_button: true
+  use_issues_button: true
+  baseurl: https://worldbank.github.io/blackmarblepy
+
+#######################################################################################
+# Execution settings
+execute:
+  execute_notebooks: "off"
+
+#######################################################################################
+# Bibliography settings
+bibtex_bibfiles:
+  - bibliography.bib
+
+#######################################################################################
+# Sphinx settings
+sphinx:
+  config:
+    html_show_copyright: false
+    html_last_updated_fmt: "%b %d, %Y"
+    apidoc_module_dir: "../src"
+    extra_extensions:
+      - "sphinxcontrib.apidoc"

docs/_toc.yml

@@ -0,0 +1,12 @@
+format: jb-book
+root: README
+
+parts:
+  - caption: Documentation
+    chapters:
+      - file: api/blackmarble.rst
+      - file: CONTRIBUTING
+  - caption: Examples
+    chapters:
+      - file: quickstart
+      - file: examples/blackmarbley_example.ipynb

docs/conf.py

@@ -0,0 +1,78 @@
+###############################################################################
+# Auto-generated by `jupyter-book config`
+# If you wish to continue using _config.yml, make edits to that file and
+# re-generate this one.
+###############################################################################
+apidoc_module_dir = "../src"
+author = "Development Data Group"
+bibtex_bibfiles = ["bibliography.bib"]
+comments_config = {"hypothesis": False, "utterances": False}
+copyright = "2022"
+exclude_patterns = ["**.ipynb_checkpoints", ".DS_Store", "Thumbs.db", "_build"]
+extensions = [
+    "sphinx_togglebutton",
+    "sphinx_copybutton",
+    "myst_nb",
+    "jupyter_book",
+    "sphinx_thebe",
+    "sphinx_comments",
+    "sphinx_external_toc",
+    "sphinx.ext.intersphinx",
+    "sphinx_design",
+    "sphinx_book_theme",
+    "sphinxcontrib.bibtex",
+    "sphinx_jupyterbook_latex",
+    "sphinxcontrib.apidoc",
+]
+external_toc_exclude_missing = True
+external_toc_path = "_toc.yml"
+extra_extensions = ["sphinxcontrib.apidoc"]
+html_baseurl = "https://worldbank.github.io/blackmarblepy"
+html_favicon = ""
+html_last_updated_fmt = "%b %d, %Y"
+html_logo = "images/logo.png"
+html_show_copyright = False
+html_sourcelink_suffix = ""
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "search_bar_text": "Search this book...",
+    "launch_buttons": {
+        "notebook_interface": "classic",
+        "binderhub_url": "",
+        "jupyterhub_url": "",
+        "thebe": False,
+        "colab_url": "",
+    },
+    "path_to_docs": "",
+    "repository_url": "https://github.com/worldbank/blackmarblepy",
+    "repository_branch": "main",
+    "extra_footer": "",
+    "home_page_in_toc": False,
+    "announcement": "",
+    "analytics": {"google_analytics_id": ""},
+    "use_repository_button": True,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+}
+html_title = ""
+latex_engine = "pdflatex"
+myst_enable_extensions = [
+    "colon_fence",
+    "dollarmath",
+    "linkify",
+    "substitution",
+    "tasklist",
+]
+myst_url_schemes = ["mailto", "http", "https"]
+nb_execution_allow_errors = False
+nb_execution_cache_path = ""
+nb_execution_excludepatterns = []
+nb_execution_in_temp = False
+nb_execution_mode = "off"
+nb_execution_timeout = 30
+nb_output_stderr = "show"
+numfig = True
+pygments_style = "sphinx"
+suppress_warnings = ["myst.domains"]
+use_jupyterbook_latex = True
+use_multitoc_numbering = True

docs/examples

@@ -0,0 +1 @@
+../examples