init

.github/workflows/deploy-docs.yml

@@ -0,0 +1,21 @@
+name: deploy-docs
+
+on:
+  workflow_run:
+    branches: [ "main" ]
+    workflows: ["run-pytest"]
+    types:
+        - completed
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - run: pip install .
+      - run: pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter livereload
+      - run: mkdocs gh-deploy --force

.github/workflows/run-pytest.yml

@@ -0,0 +1,29 @@
+name: run-pytest
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-cov pytest-xdist -r requirements.txt
+        pip install .
+    - name: Run pytest
+      run: |
+        pytest -n auto --cov --no-cov-on-fail --cov-report=term-missing:skip-covered --cov-report xml:coverage.xml

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+default_language_version:
+  python: python3.10
+
+repos:
+  - repo: https://github.com/ambv/black
+    rev: 22.6.0
+    hooks:
+      - id: black
+        args: ["earthlib", "--line-length=88", "--target-version=py310"]
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 5.0.4
+    hooks:
+      - id: flake8
+        args: ["--select=C,E,F,W,B,B950", "--max-line-length=88", "--ignore=E203,E501,W503,F401,F403,E266,F821", "--exclude=bin,ipython,legacy,plots"]
+
+  - repo: https://github.com/timothycrosley/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+        args: ["-l 88", "--profile", "black", "."]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: requirements-txt-fixer

Makefile

@@ -0,0 +1,42 @@
+####################
+# setup
+
+NAME=earthlib
+CONDA=conda run --no-capture-output --name ${NAME}
+PYVERSION=3.10
+.PHONY: create docs test collections pypi
+
+# help docs
+.DEFAULT: help
+help:
+	@echo "--- [ $(NAME) developer tools ] --- "
+	@echo ""
+	@echo "make create - initialize conda dev environment"
+	@echo "make docs   - install mkdocs dependencies"
+	@echo "make test   - run package tests"
+	@echo "make collections - generate new formatted collections.json file"
+	@echo "make pypi   - build and upload pypi package"
+
+####################
+# utils
+
+init:
+	poetry init --python=^3.7
+	poetry add --lock "earthengine-api>=0.1.317" "numpy>=1.21.5" "pandas>=1.3.5" "spectral>=0.22.4" "tqdm>=4.63.0"
+	poetry add --lock --group dev "ipython^8.5.0" jupyter geemap pre-commit pytest pytest-cov pytest-xdist twine mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter livereload
+
+create:
+	conda env list | grep -q ${NAME} || conda create --name=${NAME} python=${PYVERSION} -y
+	${CONDA} poetry install
+	${CONDA} pre-commit install
+
+test:
+	${CONDA} pytest -n auto --cov --no-cov-on-fail --cov-report=term-missing:skip-covered
+
+collections:
+	${CONDA} python scripts/generate_collections.py
+
+pypi:
+	rm -rf dist/
+	${CONDA} poetry build
+	twine upload dist/*

README.md

@@ -1,2 +1,54 @@
-# earthlib
-Spectral library and unmixing tools for satellite land cover mapping.
+# The Earth Library
+
+<img src="docs/img/earth-unmixed.png">
+
+<p align="center">
+  <em>A global spectral library, and earth engine tools for satellite land cover mapping..</em>
+</p>
+
+---
+
+**Documentation**: [earth-chris.github.io/earthlib](https://earth-chris.github.io/earthlib)
+
+**Source code**: [earth-chris/earthlib](https://github.com/earth-chris/earthlib)
+
+---
+
+## :earth_asia: Introduction
+
+`earthlib` is a python package featuring a global spectral library of reference spectra, and a set of software tools for satellite-based land cover mapping in Earth Engine.
+
+The library contains several thousand unique spectral endmembers representing green vegetation, soil, non-photosynthetic vegetation, urban materials, and burned materials. The reflectance data cover the visible to the shortwave infrared wavelengths (400-2450 nm) at 10 nm band widths.
+
+The software tools (1) resample these data to match the wavelengths of popular satellite and airborne earth observing sensors and (2) run [spectral mixture analysis](docs/introduction.md) in Google Earth Engine via the `earthengine` python package.
+
+The goal is to quantify spatial and temporal patterns of change in global vegetation cover, as well as patterns of soil cover, burned area, non-photosynthetic vegetation, and impervious surfaces. With `earthlib`, you can do this using a wide variety of public satellite [data sources](docs/sources.md).
+
+
+## :seedling: Installation
+
+This library can be installed via `pip`.
+
+```bash
+pip install earthlib
+```
+
+You can also clone the source repository and install it locally.
+
+```bash
+git clone https://github.com/earth-chris/earthlib.git
+cd earthlib
+pip install -e .
+```
+
+## :deciduous_tree: Developed by
+
+[Christopher Anderson](https://cbanderson.info)[^1] [^2]
+
+<a href="https://twitter.com/earth_chris">![Twitter Follow](https://img.shields.io/twitter/follow/earth_chris)</a>
+<a href="https://github.com/earth-chris">![GitHub Stars](https://img.shields.io/github/stars/earth-chris?affiliations=OWNER%2CCOLLABORATOR&style=social)</a>
+
+This work was primarily developed at the Stanford Center for Conservation Biology with the Natural Capital Project.
+
+[^1]: [Earth Observation Lab, Planet Labs PBC](https://www.planet.com)
+[^2]: [Center for Conservation Biology, Stanford University](https://ccb.stanford.edu)

docs/index.md

@@ -0,0 +1,54 @@
+# The Earth Library
+
+![earthlib unmixed](img/earth-unmixed.png)
+
+<p align="center">
+  <em>A global spectral library, and earth engine tools for satellite land cover mapping..</em>
+</p>
+
+---
+
+**Documentation**: [earth-chris.github.io/earthlib](https://earth-chris.github.io/earthlib)
+
+**Source code**: [earth-chris/earthlib](https://github.com/earth-chris/earthlib)
+
+---
+
+## :earth_asia: Introduction
+
+`earthlib` is a python package featuring a global spectral library of reference spectra, and a set of software tools for satellite-based land cover mapping in Earth Engine.
+
+The library contains several thousand unique spectral endmembers representing green vegetation, soil, non-photosynthetic vegetation, urban materials, and burned materials. The reflectance data cover the visible to the shortwave infrared wavelengths (400-2450 nm) at 10 nm band widths.
+
+The software tools (1) resample these data to match the wavelengths of popular satellite and airborne earth observing sensors and (2) run [spectral mixture analysis](introduction.md) in Google Earth Engine via the `earthengine` python package.
+
+The goal is to quantify spatial and temporal patterns of change in global vegetation cover, as well as patterns of soil cover, burned area, non-photosynthetic vegetation, and impervious surfaces. With `earthlib`, you can do this using a wide variety of public satellite [data sources](sources.md).
+
+
+## :seedling: Installation
+
+This library can be installed via `pip`.
+
+```bash
+pip install earthlib
+```
+
+You can also clone the source repository and install it locally.
+
+```bash
+git clone https://github.com/earth-chris/earthlib.git
+cd earthlib
+pip install -e .
+```
+
+## :deciduous_tree: Developed by
+
+[Christopher Anderson](https://cbanderson.info)[^1] [^2]
+
+<a href="https://twitter.com/earth_chris">![Twitter Follow](https://img.shields.io/twitter/follow/earth_chris)</a>
+<a href="https://github.com/earth-chris">![GitHub Stars](https://img.shields.io/github/stars/earth-chris?affiliations=OWNER%2CCOLLABORATOR&style=social)</a>
+
+This work was primarily developed at the Stanford Center for Conservation Biology with the Natural Capital Project.
+
+[^1]: [Earth Observation Lab, Planet Labs PBC](https://www.planet.com)
+[^2]: [Center for Conservation Biology, Stanford University](https://ccb.stanford.edu)

docs/introduction.md

@@ -0,0 +1,9 @@
+# Spectral Mixture Analysis
+
+The contents of a satellite image pixel are rarely homogeneous. An area 30x30m in size can include buildings, trees, and roads in urban environments; grasses, soils, and char in recently burned landscapes; trees, gaps, and downed logs in forested areas. These patterns all affect the reflectance patterns measured by satellites, and it's important to be able to estimate the sub-pixel abundances of each of these land cover types.
+
+![earthlib spectral mixture analysis](img/sma-basics.png)
+
+Spectral mixture analysis is an approach to estimating the sub-pixel contents of an image pixel based on a set of representaive reflectance spectra (i.e., a reference library). Linear spectral mixture analysis uses an iterative, least-squares fitting approach to estimate the proportions of land cover types based on observed reflectance measurements. In order to run these analyses, you need 1) a high quality reference library of different land cover types, and 2) to resample these reference data to the wavelengths of the instrument you plan to analyze.
+
+To support these analysise, `earthlib` provides a rich spectral library with thousands of [labeled reference spectra](sources.md) and tools for working with common satellite instruments.

docs/module/BRDFCorrect.md

@@ -0,0 +1 @@
+::: earthlib.BRDFCorrect

docs/module/BrightMask.md

@@ -0,0 +1 @@
+::: earthlib.BrightMask

docs/module/BurnPVSoil.md

@@ -0,0 +1 @@
+::: earthlib.BurnPVSoil

docs/module/CloudMask.md

@@ -0,0 +1 @@
+::: earthlib.CloudMask

docs/module/NIRv.md

@@ -0,0 +1 @@
+::: earthlib.NIRv

docs/module/Scale.md

@@ -0,0 +1 @@
+::: earthlib.Scale

docs/module/ShadeMask.md

@@ -0,0 +1 @@
+::: earthlib.ShadeMask