Allen Coral Atlas web interface Snapshot

Chasing Coral Data

Samapriya Roy
8 min readJun 4, 2021

Over the period of decades the emphasis towards studying global coastal reefs and the need to constantly monitor them has accelerated. With an understanding that such insights might be valuable given the dynamic nature of such systems. This has also been made possible with advances in technology , capability to study them at scale and more frequently, meaning we might have a better than ever glimpse at this changing ecosystem and landscape.

Models predict that without intervention, 70% to 90% of coral reefs will be lost in the next 30 years due to warmer, polluted, and acidic ocean waters.

and efforts like the Allen Coral Atlas (ACA) have made it possible to look at the changing coral reefs under sustained pressures and allow for efforts to mobilize against that future. The ACA allows for an effective monitoring system to be in place while the underlying models and datasets get better over time. And rightfully from their recent blog the setup points towards where to focus locally and towards taking action in general allowing for conservationists, policy makers and governments to react. This blog provides a simple hands on with Allen Coral Atlas web interface and PyCoral: A Simple Command Line tool to interact with ACA programmatically. Throughout the article I will use Allen Coral Atlas and ACA interchangeably.

Getting Started: Signing Up and Ready to Go

The Allen Coral Atlas has a simple sign up and you can be up and ready in no time this also makes sure you can interact and download data from the atlas and the dataset requests are sent to your email as notifications

Remember that an activation link is sent to your email and it has be used within 6 hours

Once activated you will be prompted to sign in and log into your account with the email address and password you used earlier to sign up. Click on the Atlas link on the top and you are in , note that the right hand side now says My Account instead of the Sign in button. There is a also list of Mapped areas and usually I start by choosing where I want to go from the drop down list but you can use it like google Maps to zoom and check if data for your Area of Interest is available or has been mapped.

The page does have some level of persistence/state memory in the sense that it remembers where you were on the map and what you were doing the last time you logged in.

Querying for Stats

This is one of my favorite bits and gives you a glimpse of two things one being the Geomorphic zones and the Benthic classes. You can draw an area of interest to get started. Please note that while you may be drawing a free hand area of interest the tool implements a bounding box approach in the backend to keep querying the data simple.

ACA querying for Stats

For areas larger than a 100 square kilometers you would have to save the Area of Interest (AOI) and a query is then placed based on that. This is also useful because the saved area is now available for you to use in the future. Please also note that the 100 square kilometers is a limit for the AOI and not the actual mapped area.

Downloading Data

Not only are the stats useful they allow you to analyze and change area of interest before placing an order for download. The download option for large areas includes the same restrictions (areas larger than 100 square kilometers have to be saved) . In our case we will use the saved area to then place and order to download, since the downloads maybe large and take time to gather, a download link is sent as an email so you don’t have to wait. Another useful feature is that for some of the files you can choose file types so Shapefile instead of GeoJSON for example.

ACA Download files for your Area of Interest

There is so much more that the Allen Coral Atlas offers including Bleaching data, Coral Reef watch data among other layers, tools and functionalities that are built into ACA and extremely useful as a resources to explore.

pycoral: Simple CLI for Allen Coral Atlas

First things first, the pycoral command line tool written in python is not an official tool but an unofficial one which allows users to interact with the Allen Coral Atlas data and basically perform the same functions but programmatically. The motivation to build this tool was to collate more data as part of the effort of a remote sensing module I am helping teach along for the 2021 Schmidt Summer Program at the Hawai’i Institute of Marine Biology.

Field Work at the Summer Program: Measuring Reefs

This tool is useful if you have one or more existing areas of interest and has some helpful functionalities built in. Since it is not built on any available or standard API, some things might break over time and I will try my best to maintain and improve on this over time as well. You can find the GitHub page for the project here and the most updated version of the readme on the readme page here. You can star and follow the project for more updates

pycoral: Simple CLI for Allen Coral Atlas

Getting Started and Installation Guide

The tool is a simple standalone tool and the requirements for the setup are included in the requirements.txt file as well as the installer. To install pycoral you can use any of the two methods below

pip install pycoral

or you can also try

git clone
cd pycoral
python install

I recommend installation within a virtual environment. Find more information on creating virtual environments here

Getting to the Docs & Persistent Check

The pycoral cool is designed to check is a newer or more updated version is available apart from that if you ever want to go to the readme page you can simply type or go to

pycoral readme

pycoral authenticate

This is similar to you logging in with your username and password on the web interface. This saves this information locally and for you to use while utilizing it as needed to authenticate. This is only needed once unless you change your password or you are logging into a different account.

pycoral authenticate

Finding Areas of Interest

The aoi-find tool can be handy if you are looking for a specific aoi-name and is mostly useful to list all allowed polygons including those that are default or stored by the atlas vs your own areas of interest. This is useful since you can list them all by simply typing

pycoral aoi-find
pycoral aoi-find tool to search for or list all available areas of interest

You can also pass an AOI name to get an AOI ID if there is a matching AOI. This is helpful to parse through and confirm any existing AOI as well as the ones available to you and that you have saved.

Areas of interests saved by you type User Poly compared to Default Poly as AOIs saved by the Atlas. This is to differentiate between the two types.

Creating Area of Interest

To make it easier for users with existing geometries, it is possible to simply pass a geometry GeoJSON file to pycoral to be saved to your My area space and once created it returns an ID which can then be used as either/or to generate stats or download data.

pycoral tool to create an AOI using user geometry

While the ACA allows you to use the same name multiple times and is non unique, to avoid any confusion, the tool checks if a area of interest (AOI) exists with the same name and if yes then suggests you to change the name. This allows you to keep names distinct and make things easier to search.

Getting Stats

This tool allows you to get to the statistics for an area of interest (AOI) and on the Geomorphic zones and the Benthic classes. The tool is helpful because not only does it allow you to pass an existing AOI using its name, or an ID , you can also pass a geometry GeoJSON file. Depending on the size of the geometry it might take time to run the analysis. Since the atlas needs you to save your area of interest if the area is larger than 100 sqkm, this checks for area constraints and if the area is larger then it creates a AOI and saves it to your account automatically before running stats.

pycoral aoi-stats tool to generate stats using geometry or saved AOI

To avoid asking the user for a AOI name, it uses the current local timestamp and encodes it into a unique string and returns to you the ID for the AOI along with the stats after a while.

Delete an Area of Interest

You can delete AOIs from your list of AOIs , these are the ones you created either in the web interface or through the pycoral tools as described earlier. I like to think of this as a housekeeping tool and allows you to thin down the number of AOIs you are saving and querying over time.

AOI delete using pycoral

If an AOI name or ID you provide does not exist the tool gracefully exists out while informing the user of the same.

Downloading your Data

The download tool for both the web interface or the pycoral tool can only be utilized for area of interest that have been saved to your my areas. As such this tool utilizes either the AOI name or ID. This tool submits the request and then waits for files to be gathered, zipping to complete to then download a single zip files with all sources. Since v0.0.7 this tool also allows you to choose some file formats similar to the web interface for ease of users.

pycoral download tool to download AOI stats

As datasets that monitor our oceans change and evolve this data can be tied and used in conjunction in sea temperature data or the bleaching results being built by the ACA. There is potential for other datasets to join the need to better understand our changing corals betters.

Efforts like the Allen Coral Atlas serve as sentinels of time while being hopeful that these efforts effects change where change is needed. I hope to keep building on the pycoral tool as I learn more from the Atlas and other initiatives while chasing corals in my own way through data for now :) .



Samapriya Roy

Remote sensing applications, large scale data processing and management, API applications along with network analysis and geostatistical methods