Area of Interest Selection#

In the majority of SEPAL modules, the first mandatory input, is the area of interest (AOI), this input will be used as a boundary to cut the processes and its outputs. Depending on if you are using the default process recipes or the custom applications you will find different user interfaces.

Recipe AOI#

The recipes are accessible through the orange globe icon located at the left side of the SEPAL window.

For many of the recipes, an area of interest has to be selected. Locate the AOI selection button at the bottom right corner. Click the AOI button to open the selection window.

There are multiple methods to select AOI’s in the SEPAL process recipes:

  • Country/province (administrative boundaries).

  • EE Tables (Earth Engine).

  • Drawn polygons.

Tip

The selected method at this step is not definitive, you can change it at any stage by simply clicking the selected method dropdown on the top of the AOI window and a list with the available methods will be displayed.

Administrative boundaries#

You can select administrative layers as AOI. These geometries are extracted from the FAO GAUL Level 0 dataset available on GEE. To use them, select the Select country/province method in the dropdown list.

Note

As GEE does not support non-Latin characters, accents and special characters have been removed from country and province names.

In the first dropdown menu, you will be able to select a Country (administrative layer 0) from the country list and optionally, you can select a province (administrative level 1) within the country selected. The dropdown list is updated on the fly with the 1st administrative level boundaries according to the country selection. If nothing is selected, the whole country will be considered.

A buffer can be applied to the AOI boundaries, define its size using the provided slider (in km). It is by default set to 0, i.e. disabled.

Note

The area of interest and preview will take longer to show up when buffering is enabled.

Once all the parameters are selected, the AOI will be previewed in the small map at the bottom of the frame. To validate it click the Apply button. Once validated, the map will zoom on the AOI and draw it in grey on the map.

EE table#

You can use custom AOI defined by shapes. These shapes need to be ingested in Earth Engine as a ee.FeatureCollection (see how to upload custom assets to GEE). To use this method, select EE table .

In the first dropdown, provide a completely qualified GEE asset name (e.g. projects/gtfp-fao/assets/aoi_ecowas).

Warning

Make sure you have access to this asset. If that is not the case, ask the owner of the source to modify the sharing permission, otherwise, you won’t be able to use the dataset.

  • Select include all and the whole geometries associated with the features will be used as an AOI.

  • Select filter and you will be able to provide a column name and a value to filter the table. The Aoi will then be reduced to the filtered features in the input asset.

A buffer can be applied on these boundaries, define its size using the provided slider (in km). It is by default set to 0, i.e. disabled.

Note

The area of interest and the preview will take longer to show up when buffering is enabled.

Once all the parameters are selected, the AOI will be previewed in the small map at the bottom of the frame. To validate it, click the Apply button. Once validated, the map will zoom in on the AOI and draw it in grey on the map.

Draw polygon#

You can use a custom AOI defined by a drawn shape. This shape will be converted into a ee.FeatureCollection on the fly. Select draw a polygon to use this method.

The pointer in the map will be converted into a . Click successively on the map to draw a polygon.

Once the geometry is closed, the AOI will be previewed in the small map at the bottom of the frame. To validate it click the Apply button. Once validated, the map will zoom on the AOI and draw it in grey on the map.

Module AOI#

The module AOI selector is available in some of the SEPAL-contrib modules. To access an app, click the purple wrench located on the left side of the SEPAL platform, use the app’s dashboard to search and open a module.

An AOI selector module is composed of two main sections: the available methods (1) and the map (2). Although we will mention all the features and methods available, some of them might not be available in the context of the module you are working on.

Available methods#

There are two types of processes that require different AOI inputs and it will depend on the way the module is created and where are the core processes done: directly in a SEPAL instance or in GEE. Although both interfaces look exactly the same, the methods and the inner data sources might vary, e.g. the administrative definitions.

Administrative definitions#

Similar to the previously mentioned recipe AOI selector, the module AOI uses the FAO GAUL GEE boundaries for GEE and the GADM 3.6 features for local processes, however, in this case, the tool allows you to recurse at a maximum second administrative level. The available sources are the following:

GEE#

Local#

  • All the administrative levels are accessible from the GADM website .

Use the AOI selection method dropdown list, and select the target administrative level, a new dropdown will load up with all the corresponding boundaries to the next administrative level that is linked with the base level, i.e. select Admin level 2 as the method, chose Colombia as a country, select the Amazonas department as the next level, and finally select Leticia municipality.

Custom geometries#

When you are looking for a more specific area of interest, the module AOI selector have at your disposal the following options:

  • Vector file

  • Drawn shape

  • Point file

  • GEE asset

Vector file#

Use this option to upload a custom vector file. Select the Vector file method in the dropdown list, a file manager (1) widget will be displayed below allowing you to search and select a vector file stored in your SEPAL environment (see how to exchange files with SEPAL). The below dropdown named Column (2) is useful to filter the features of the vector file, the default option is Use all features which means that any filter is done. To filter the collection, select a column and a Value (3) in the corresponding dropdown list, then click the Select aoi button.

Note

he available vector formats are: [.shp, .geojson, .gpkg, .kml]. Once selected, the module will transform its original coordinate system into EPSG:4326.

Remember that if the module you are using is doing the computation in GEE, a new feature collection asset will be created and stored in you GEE root folder using the name of the provided file prefixed by aoi_.

Drawn shape#

Use this option to manually draw geometries in the map. Select the Drawn shapes method in the dropdown list, and optionally create a name for your draw, if not provided, the tool will assign a unique name containing the following structure:

Manual_aoi_YYYY-MM-DD_HH-MM-SS

Note

If the module you are using is doing the process in GEE, a new asset will be created and stored in the root of your GEE account with the given name prefixed by aoi_.

Three drawing geometries will be shown up at the top left corner of the map: a polygon, a square and a circle.

Tip

To draw, zoom in at your area of interest by using the mouse wheel or the and buttons located at the top right corner.

  • (polygon): Draw your custom polygon by clicking the vertices of the geometry in the map. To close and finish your geometry, click the first vertex or use the finish button. Note that once you select the polygon geometry, three new buttons will be available at the top of the map: Finish, Delete last point and Cancel.

  • (rectangle): Click the top left corner of the rectangle in the map, it will be the first vertex of the geometry, now, —without clicking—, move the mouse to the opposite corner (bottom left) and click the map, it will close the geometry and the rectangle will be colored in a teal color.

  • (circle): Click the center of the circle and —without stopping clicking— draw the distance (radius), then drop the click. A new blue marker will appear on the map showing the center of the circle. The geometry won’t be drawn in the map until you click the Select AOI button, so do not worry if you can’t see the circle at this time, the module will save the geometry in the background.

Point file#

Use this method to load a single or multiple point dataset. Select Point file in the dropdown method list. Four new widgets will appear: a File selector (1) and three dropdown lists: ID (2), Longitude (3) and Latitude (4).

Use the file selector widget to navigate through your SEPAL environment and search a table file (.csv or .txt) containing the coordinates of your points. Make sure the file use the following structure: - at least 3 columns - 1 providing an id (unique point identifier) - 1 providing longitude coordinates - 1 providing latitude coordinates

Danger

The points coordinates need to be set in EPSG:4326.

Here is an example of a compatible point file:

Id

x

y

1

-74.0

4.0

2

-75.0

5.0

Once the table is loaded, the system will try to automatically identify the Id, Longitude and Latitude columns. When this is not possible, the fields will remain empty and you will have to manually match them.

Note

note that the columns don’t have to be named with any specific structure, the only requirement is that your dataset has to be composed of an Id, Longitude, and Latitude columns.

GEE asset#

Use this method to load a custom feature collection available as an asset in GEE. Select GEE asset name in the dropdown method list. Two widgets will appear by default: an Asset selector (1), a dropdown list containing the columns of the selected asset (2) and optionally the column unique fields (3).

The File selector widget will search for all the Table assets (i.e. Feature Collection) stored in your GEE account. You can also copy and paste in the text field a custom third-party asset, however, be sure that you have the access permission, otherwise, the module won’t be able to use that source and an error will be displayed.

Once you have selected a valid asset, the module will query all the available columns in your provided asset and will display them in the column dropdown widget. By default, all the features in the dataset will be selected Use all features, however, if you are interested in using a specific geometry, select a column to filter your dataset, and a new dropdown will load all the unique values for that specific column, select one.

Note

note that this method will only be available when you are using a module that requires a connection to your GEE account. You can check this by navigating through the app’s dashboard and noticing the icon at the right side of the drawer.

Note

Not all the modules have all the mentioned methods, their availability will depend on the module context, i.e. some apps would require polygons while others points.

Finally, click the Select AOI button, if all the inputs are correct you will see a success message and your aoi will be displayed in green on the map. Otherwise, an indicative error message will be displayed.