Skip to content

Latest commit

 

History

History
157 lines (106 loc) · 4.9 KB

README.md

File metadata and controls

157 lines (106 loc) · 4.9 KB
Raw

marapp-metrics

Marapp Python package for shape metric calculations with Google Earth Engine.

Installation

To install the Python package use:

pipenv install -e git+git@github.com/natgeosociety/marapp-metrics.git@1.0.0#egg=marapp-metrics

For all available versions see tagged release versions.

Usage

Basic usage example:

import geopandas as gpd
from marapp_metrics.metrics.terrestrial_carbon import TerrestrialCarbon

# create a geopandas GeoDataFrame from a geojson shape file
gdf = gpd.read_file('./sample-data/rothschild-giraffe.geojson')

# instantiate the metric object
terrestrial_carbon = TerrestrialCarbon()

# compute the metric
metric = terrestrial_carbon.measure(gdf)

Setup

Available commands:

Command Description
make setup Install dependencies
make clean Clean all dependencies
make test Run all tests
make lint Lint code sources

Install all dependency packages.

$ make setup

A virtualenv will automatically be created, and packages from the Pipfile installed.

Running

Activate the virtualenv.

$ pipenv shell

Install the project in editable mode (i.e. setuptools "develop mode").

$ pip3 install -e .

The following environment variables are required by the application.

Key Description
GOOGLE_SERVICE_ACCOUNT GCP Service Account Private Key.

The required environment variables are also described in .env.sample.

If you do not have a service account file to export via the GOOGLE_SERVICE_ACCOUNT argument, you can manually authenticate via the Earth Engine command line tool.

$ earthengine authenticate

Earth Engine uses the OAuth 2.0 protocol for authenticating clients. Running this command will prompt you through the authentication process using your web browser.

Running a single example. Data from sample-data directory is bundled for running samples.

$ python3 -m marapp_metrics.metrics.biodiversity_intactness

To kill the virtualenv.

$ deactivate

Tests

The fixture data for the metric computations are generated on the first run of the tests, because results are highly dependent on the Earth Engine assets used.

Subsequent test runs will use the previously generated data as reference for thresholding results.

Sequential execution.

$ pytest -v tests/

Parallel execution. Speed up test runs by making use of multiple CPUs.

$ pytest -v -n 4 tests/

Especially for longer running tests or tests requiring a lot of I/O this can lead to considerable speed ups. This option can also be set to auto for automatic detection of the number of CPUs.

Restrict a test run to only run tests marked with markers. Options are: basic, grid.

$ pytest -v -m basic tests/

Packaging & deployment

Increment the package version from setup.py as well as any dependencies changed.

Note: To get a list of all packages specified in Pipfile.lock run:

pipenv run pip freeze

Create a Git tag using the package version from setup.py.

git tag 1.0.0

Push the Git tags.

git push origin --tags

The package can now be installed from the Git repository.

Configure Earth Engine assets

The template from earthengine.yaml is required to map existing Google Earth Engine image assets to computations supported by the library.

For more details about managing assets in Earth Engine, see: https://developers.google.com/earth-engine/asset_manager

The following public assets serve as examples for different types of computations supported by the library.

Type Dataset
biodiversity_intactness https://data.nhm.ac.uk/dataset/global-map-of-the-biodiversity-intactness-index-from-newbold-et-al-2016-science
human_footprint https://datadryad.org/stash/dataset/doi:10.5061/dryad.052q5
human_impact http://hdr.undp.org/en/content/human-development-index-hdi
land_cover http://maps.elie.ucl.ac.be/CCI/viewer/
modis_evi https://lpdaac.usgs.gov/products/mod13q1v006/
modis_fire http://modis-fire.umd.edu/
protected_areas https://www.protectedplanet.net/
terrestrial_carbon https://developers.google.com/earth-engine/datasets/catalog/WCMC_biomass_carbon_density_v1_0
tree_loss https://earthenginepartners.appspot.com/science-2013-global-forest/download_v1.5.html