Metadata-Version: 2.1
Name: ecoscape-layers
Version: 0.0.6
Summary: EcoScape habitat and matrix layer creation
Author-email: Jasmine Tai <cjtai@ucsc.edu>, Coen Adler <ctadler@ucsc.edu>, Luca de Alfaro <luca@ucsc.edu>, Artie Nazarov <anazarov@ucsc.edu>, Natalia Ocampo-Peñuela <nocampop@ucsc.edu>, Natalie Valett <nvalett@ucsc.edu>
Project-URL: Homepage, https://github.com/ecoscape-earth/ecoscape-layers
Project-URL: Bug Tracker, https://github.com/ecoscape-earth/ecoscape-layers/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ebird-api>=3.0.0
Requires-Dist: fiona>=1.8.22
Requires-Dist: numpy>=1.20.0
Requires-Dist: pyproj>=2.6.1
Requires-Dist: rasterio>=1.2.10
Requires-Dist: Requests>=2.28.1
Requires-Dist: scgt>=0.0.5
Requires-Dist: Shapely>=1.8.4

# EcoScape Layers

This package implements the computation of the landscape matrix layer, habitat layers, and landcover-to-resistance mappings that are needed as inputs to the EcoScape algorithm.

## Setup

To use the package, you will need to have API keys for the IUCN Red List and eBird APIs, which are used to obtain various data on bird species:

- A key for the IUCN Red List API is obtainable from http://apiv3.iucnredlist.org/.

- A key for the eBird Status and Trends API is obtainable from https://science.ebird.org/en/status-and-trends/download-data. We use the data for 2022 in this version of the package. The EcoScape paper uses data from 2020, which has been archived by eBird; see the paper for more details.

The initial ladncover raster that we use to produce our layers originates from a global map produced by [Jung et al.](https://doi.org/10.1038/s41597-020-00599-8) and is available for download at https://zenodo.org/record/4058819 (iucn_habitatclassification_composite_lvl2_ver004.zip). It follows the [IUCN Red List Habitat Classification Scheme](https://www.iucnredlist.org/resources/habitat-classification-scheme). Since this raster is quite large, it is advisable to crop to the rough area of study rather than letting the package process the entire global landcover.

## Usage

This package can be used on the command line or as a Python module.

For the command line, view argument options with `ecoscape_layers --help`.

For use as a module, the class `LayerGenerator` in `layers.py` can be used to process landcover matrix layers and create habitat layers for various bird species.

### Arguments

Required:

- `redlist_key`: IUCN Red List API key.

- `ebird_key`: eBird API key.

- `species_code`: 6-letter eBird code of the species for which habitat layers should be generated. This can be found by looking up the species on eBird and taking the 6-letter code found at the end of the species page's URL.

- `landcover_fn`: path to initial landcover raster.

Optional:

- `habitat_fn` name of output habitat layer.

- `out_landcover_fn`: name of outputted landcover matrix layer if a new one is produced by cropping/reprojection/rescaling. If not given, one can be generated from the initial landcover matrix from landcover_fn based on the parameters applied.

- `resistance_dict_fn` name of output resistance dictionary CSV.

- `range_fn`: name of output range map for the species, which is downloaded as an intermediate step for producing the habitat layer.
    
- `crs`: desired common CRS of the outputted layers as an ESRI WKT string, or None to use the CRS of the input landcover raster.
    - <b>Note</b>: if the ESRI WKT string contains double quotes that are ignored when the string is given as a command line argument, use single quotes in place of double quotes.

- `resolution`: desired resolution in the units of the chosen CRS, or None to use the resolution of the input landcover raster.

- `resampling`: resampling method to use if reprojection of the input landcover layer is required; see https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r for valid options.

- `bounds`: four coordinate numbers representing a bounding box (xmin, ymin, xmax, ymax) for the output layers in terms of the chosen CRS.

- `padding`: padding to add around the bounds in the units of the chosen CRS.

- `refine_method`: method by which habitat pixels should be selected when creating a habitat layer.
    - `forest`: selects all forest pixels.
    - `forest_add308`: selects all forest pixels and pixels with code "308" (Shrubland – Mediterranean-type shrubby vegetation).
    - `allsuitable`: selects all pixels with landcover deemed suitable for the species, as determined by the IUCN Red List.
    - `majoronly`: selects all pixels with landcover deemed of major importance to the species, as determined by the IUCN Red List.

- `refine_list`: list of map codes for which the corresponding pixels should be considered habitat. This is provided as an alternative to refine_method, which offers limited options, and overrides refine_method if both refine_method and refine_list are specified.

## Known issues

- The eBird and IUCN Red List scientific names do not match for certain bird species, such as the white-headed woodpecker (eBird code: whhwoo). As the IUCN Red List API only accepts scientific names for its API queries, if this occurs for a bird species, the 6-letter eBird species code for the species must be manually matched to the corresponding scientific name from the IUCN Red List.

- Bird species with different seasonal ranges on eBird are currently not supported.
