Raster and Vector Code: Access and Filters
As mentioned in Data Structures, image data is stored in ImageCollections. To find out which ImageCollections exist and how to access them, enter the name of a sensor you are interested in into the Search bar at the top of the browser interface.
In this example, we are going to look for Sentinel 2 data. By typing 'sentinel 2' into the search bar, it shows all of the available raster datasets that include the words ‘Sentinel’ and ‘2’. We are going to choose ‘Sentinel-2 MSI: MultiSpectral Instrument, Level-2A’, as this is already pre-processed for Surface Reflectance. Click on the link to get to the documentation page, where you can find all the necessary information on the dataset, the available bands, the image properties as well as a code snippet which shows how to import the collection into your script.
Let’s try to work with the ImageCollection by defining a variable for it and printing it to our collection.
var IC = ee.ImageCollection('COPERNICUS/S2_SR')
After a short while of calculating, we will receive an error message;
ImageCollection (Error): Collection query aborted after accumulating over 5000 elements.
Just to recall: What we just tried to do is accessing the whole, unfiltered Sentinel 2 Level 2-A – Archive, globally and ever since it started transmitting in 2017. It is not surprising that even the GEE will have to bend to that amount of data, and so it does after accumulating over 5000 elements.
This raises the attention to the necessity of two things: Spatially defining the research area and filtering the image data.
Spatially defining the research area
There are multiple approaches to define your Area of Interest in the GEE.
The most basic and fastest method you can always fall back on is to simply draw a point or polygon shape with the geometries-tools and use its extents as a boundary filter.
Another method is to use one of the GEE Data Catalogs numerous vector datasets and filter it for the geometry of your needs. If you want to make sure to get imagery for complete administrative layers for example, you can make use of the various ‘Global Administrative Unit Layers 2015’ vector datasets.
Alternatively, you can also upload your own shapefiles via the Assets tab in the left panel, if you have those prepared and ready.
var dataset = ee.FeatureCollection('FAO/GAUL/2015/level0') var dataset = ee.FeatureCollection('FAO/GAUL/2015/level1') var dataset = ee.FeatureCollection('FAO/GAUL/2015/level2')
Filtering data allows us to only access the data that is of relevance for our research questions. To draft a drastic example: If we are interested in monitoring wildfires in Syria, there is absolutely no need to account for imagery of North America as it will only blow up our processing times and capacities.
Filters can easily be added to your desired image collection by adding .filter(). There are lots of possible filters for your imagery, for example:
.filterBounds() //filters for images that lie within your Area of Interest
.filterDate() //filters for images within the selected range of dates (YYYY-MM-DD)
ee.filter.eq('ImageProperty', 'Name') //filters 'equals' for Metadata (a comprehensive list of every sensors Image Properties can be found in the sensor documentation from the search bar)
ee.filter.lt('ImageProperty', 'Name') //filters 'less than' for Metadata
ee.filter.gt('ImageProperty', 'Name') //filters 'greater than' for metadata
Other useful commands to further filter your ImageCollection include:
.select() //selects specific bands of your imagery, can also be used as a list
.sort('Imageproperty') //sorts imagery for specific image properties, for example 'Cloudy_Pixel_Percentage' for Sentinel-2 data
.mean() //generates a single image composed of the mean values of all images in the IC
Actually accessing and filtering data
After this flood on information, let us have a look on how to actually access and filter image data in practice. You will see that it is really not that complex at all.
For this lesson, we will look at a very simple example that lets us access Sentinel-2 Level-2A imagery of the whole year 2020 for a chosen research area. Please, open the GEE in your Web Browser, copy the following snippet of code in your Code Editor and run it.
//Step 1: Use the map panel to browse to your research area. Define an Area of Interest by defining a point or polygon geometrie, or upload a shapefile to your assets. //In this example, we use the Global Administration Units Layer(GAUL) 2015 to access geometry data of Lebanon. Please check the official documentation to learn more about its table schema. //Keep in mind that this will not clip the imagery to the extents of Lebanon, so we will have a lot of excess data! var extent_lebanon = ee.FeatureCollection('FAO/GAUL/2015/level0') .filter(ee.Filter.eq('ADM0_NAME', 'Lebanon')) //filter for entry that equals the UN country name 'Lebanon' //Step 2: Access the Sentinel-2 Level-2A data and filter it for all the the images of the year 2020 that lie within the geometries boundaries. Keep only the relevant bands. var s2a = ee.ImageCollection('COPERNICUS/S2_SR') .filterBounds(extent_lebanon) .filterDate('2020-01-01', '2020-12-31') .select('B1','B2','B3','B4','B5','B6','B7','B8','B8A','B9','B11','B12') //Print your ImageCollection to your console tab to inspect it print(s2a, 'Image Collection 2020') /* You can now check the printed ImageCollection in your Console to see that we have 678 images that we can freely use for further analysis and processing. By clicking on the arrows, you can look at further details and properties of the single Images of the ImageCollection. */ //if we want to shrink this ImageCollection further down by reducing bloating images that are not of much use, we can filter for clouds as well. var s2a_cloudfree = s2a .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', 10)) //filters for entries with less than 10% cloudy pixel percentage print(s2a_cloudfree, 'Image Collection 2020 < 10% Cloud Cover') // now, only 363 images are left //if we are interested in getting the 20 least cloudy images of 2020, this can also be easily achieved: var s2a_leastcloudy = s2a_cloudfree .sort('CLOUD_COVERAGE_ASSESSMENT', true) .limit(20); print(s2a_leastcloudy, 'Image Collection 2020 20 least cloudy images') //Alternatively, add .mean() to generate a single image that is composed of the mean values of all images in the IC. var s2a_mean = ee.ImageCollection('COPERNICUS/S2_SR') .filterBounds(extent_lebanon) .filterDate('2020-01-01', '2020-12-31') .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE',10)) .mean(); print(s2a_mean, 'Image Collection 2020 mean')