You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains code for making Area of Habitat (AOH) rasters from a mix of data sources, following the methodology described in [Brooks et al](https://www.cell.com/trends/ecology-evolution/fulltext/S0169-5347(19)30189-2) and adhearing to the IUCN Redlist Technical Working Group guidance on AoH production. This work is part of the [LIFE biodiversity map](https://www.cambridge.org/engage/coe/article-details/660e6f08418a5379b00a82b2) work at the University of Cambridge. It also contains some scripts for summarising AOH data into maps of species richness and species endemism.
3
+
This repository contains code for making Area of Habitat (AOH) rasters from a mix of data sources, following the methodology described in [Brooks et al](https://www.cell.com/trends/ecology-evolution/fulltext/S0169-5347(19)30189-2) and adhering to the IUCN Redlist Technical Working Group guidance on AoH production. This work is part of the [LIFE biodiversity map](https://www.cambridge.org/engage/coe/article-details/660e6f08418a5379b00a82b2) work at the University of Cambridge. It also contains some scripts for summarising AOH data into maps of species richness and species endemism.
4
+
5
+
## Installation
6
+
7
+
The AOH Calculator is available as a Python package and can be installed via pip:
8
+
9
+
```bash
10
+
pip install aoh
11
+
```
12
+
13
+
This provides both command-line tools and a Python library for programmatic use.
14
+
15
+
For validation tools that require R, install with the validation extra:
16
+
17
+
```bash
18
+
pip install aoh[validation]
19
+
```
20
+
21
+
### Prerequisites
22
+
23
+
You'll need GDAL installed on your system. The Python GDAL package version should match your system GDAL version. You can check your GDAL version with:
24
+
25
+
```bash
26
+
gdalinfo --version
27
+
```
28
+
29
+
Then install the matching Python package:
30
+
31
+
```bash
32
+
pip install gdal[numpy]==YOUR_VERSION_HERE
33
+
```
34
+
35
+
### Library Usage
36
+
37
+
You can also use AOH Calculator as a Python library:
38
+
39
+
```python
40
+
import aoh
41
+
from aoh import tidy_data
42
+
from aoh.summaries import species_richness
43
+
from aoh.validation import collate_data
44
+
45
+
# Use core functions programmatically
46
+
# See function documentation for parameters
47
+
```
4
48
5
49
To generate a set of AOH rasters you will need:
6
50
@@ -14,41 +58,38 @@ For examples on how to run the code see the docs directory.
14
58
15
59
This project makes heavy use of [Yirgacheffe](https://github.com/quantifyearth/yirgacheffe) to do the numerical work, and the code in this repository is mostly for getting the data to feed to yirgacheffe. The advantages of using Yirgacheffe are that it hides all the offsetting required for the math to keep the AoH logic simple, deals with the archaic GDAL API bindings, and uses map chunking to mean progress can made with minimal memory footprints despite some base map rasters being 150GB and up.
16
60
17
-
# Scripts
61
+
# Command Line Tools
18
62
19
-
## aohcalc.py
63
+
## aoh-calc
20
64
21
-
This is the main script designed to calculate the AOH of a single species.
65
+
This is the main command designed to calculate the AOH of a single species.
Directory of habitat rasters, one per habitat class.
40
81
--elevation-min MIN_ELEVATION_PATH
41
-
min elevation raster
82
+
Minimum elevation raster.
42
83
--elevation-max MAX_ELEVATION_PATH
43
-
max elevation raster
44
-
--area AREA_PATH optional area per pixel raster. Can be 1xheight.
84
+
Maximum elevation raster
85
+
--area AREA_PATH Optional area per pixel raster. Can be 1xheight.
45
86
--crosswalk CROSSWALK_PATH
46
-
habitat crosswalk table path
87
+
Path of habitat crosswalk table.
47
88
--speciesdata SPECIES_DATA_PATH
48
-
Single species/seasonality geojson
49
-
--force-habitat If set, don't treat an empty habitat layer layer as per IRTWG.
50
-
--output OUTPUT_PATH directory where area geotiffs should be stored
51
-
89
+
Single species/seasonality geojson.
90
+
--force-habitat If set, don't treat an empty habitat layer layer as
91
+
per IRTWG.
92
+
--output OUTPUT_PATH Directory where area geotiffs should be stored.
52
93
```
53
94
54
95
To calculate the AoH we need the following information:
@@ -67,46 +108,42 @@ To calculate the AoH we need the following information:
67
108
- Force habitat: An optional flag that means rather than following the IUCN RLTWG guidelines, whereby if there is zero area in the habitat layer after filtering for species habitat preferneces we should revert to range, this flag will keep the result as zero. This is to allow for evaluation of scenarios that might lead to extinction via land use chnages.
68
109
- Output directory - Two files will be output to this directory: an AoH raster with the format `{id_no}_{seasonal}.tif` and a manifest containing information about the raster `{id_no}_{seasonal}.json`.
69
110
70
-
## habitat_process.py
111
+
## aoh-habitat-process
71
112
72
-
Whilst for terrestrial AOH calculations there is normally just one habitat class per pixel, for other realms like marine (which is a 3D space) this isn't the case, and so for these realms there is a requirement . To allow this code to work for all realms, we must split out terrestrial habitat maps that combine all classes into a single raster. To assist with this, we provide the `habitat_process.py` script, which also allows for rescaling and reprojecting.
113
+
Whilst for terrestrial AOH calculations there is normally just one habitat class per pixel, for other realms like marine (which is a 3D space) this isn't necessarily the case. To allow this package to work for all realms, we must split out terrestrial habitat maps that combine all classes into a single raster into per layer rasters. To assist with this, we provide the `aoh-habitat-process` command, which also allows for rescaling and reprojecting.
Downsample habitat map to raster per terrain type.
84
122
85
123
options:
86
124
-h, --help show this help message and exit
87
125
--habitat HABITAT_PATH
88
126
Path of initial combined habitat map.
89
-
--output OUTPUT_PATH Destination folder for raster files.
90
-
--scale PIXEL_SCALEOptional output pixel scale value, otherwise same as source.
127
+
--scale PIXEL_SCALE Optional output pixel scale value, otherwise same as
128
+
source.
91
129
--projection TARGET_PROJECTION
92
130
Optional target projection, otherwise same as source.
131
+
--output OUTPUT_PATH Destination folder for raster files.
93
132
-j PROCESSES_COUNT Optional number of concurrent threads to use.
94
133
```
95
134
96
-
# Summaries
135
+
#Summary Tools
97
136
98
-
In the `summaries` directory you will find two scripts for taking a set of AOH maps and generating a single summary that can be useful for inferring things about a group of maps.
137
+
These commands take a set of AOH maps and generate summary statistics useful foranalysing groups of species.
99
138
100
-
## Species richness
139
+
## aoh-species-richness
101
140
102
-
The species richness map is just an indicator of how many species exist in a given area. It takes each AOH map, converts it to a boolean layer to indicate precense, and then sums the resulting boolean raster layers to give you a count in each pixel of how many species are there.
141
+
The species richness map is just an indicator of how many species exist in a given area. It takes each AOH map, converts it to a boolean layer to indicate presence, and then sums the resulting boolean raster layers to give you a count in each pixel of how many species are there.
-j PROCESSES_COUNT Number of concurrent threads to use.
118
155
```
119
156
120
-
## Endemism
157
+
## aoh-endemism
121
158
122
-
Endemism is an indicator of how much and area of land contributes to a species overall habitat: for a species with a small area of habitat then each pixel is more precious to it than it is for a species with a vast area over which they can be found. The endemism map takes the set of AoHs and the species richness map to generate, and for each species works out the proportion of its AoH is within a given pixel, and the calculates the geometric mean per pixel across all species in that pixel.
159
+
Endemism is an indicator of how much an area of land contributes to a species overall habitat: fora species with a small area of habitat then each pixel is more precious to it than it is for a species with a vast area over which they can be found. The endemism map takes the set of AoHs and the species richness map to generate, and for each species works out the proportion of its AoH is within a given pixel, and calculates the geometric mean per pixel across all speciesin that pixel.
-j PROCESSES_COUNT Number of concurrent threads to use.
141
176
```
142
177
143
-
# Validation
178
+
# Validation Tools
179
+
180
+
In [Dahal et al](https://gmd.copernicus.org/articles/15/5093/2022/) there is a method described for validating a set of AoH maps. This is implemented as validation commands, and borrows heavily from work by [Franchesca Ridley](https://www.researchgate.net/profile/Francesca-Ridley).
144
181
145
-
In [Dahal et al](https://gmd.copernicus.org/articles/15/5093/2022/) there is a method described for validating a set of AoH maps. This is implemented in the validation directory, and borrows heavily from work by [Franchesca Ridley](https://www.researchgate.net/profile/Francesca-Ridley).
182
+
## aoh-collate-data
146
183
147
-
Before running validation, the metadata provided for each AoH map must be collated into a single table using the following script:
184
+
Before running validation, the metadata provided for each AoH map must be collated into a single table using this command:
0 commit comments