If you use this tool please cite Lea et al. (2024) and any citations from the data extracted using the tool.
© Copyright, Prof. James Lea, University of Liverpool 2024. All Rights Reserved.
The Google Earth Engine Climate Tool (GEEClimT) is an easy to use point and click interface to extract climate reanalysis data for academic research, education and outreach purposes. More details about the tool and case studies of its use can be found in the associated paper (Lea et al., 2024). Users who are interested in model projections of future climates may also wish to use GEEClimT's partner tool, the Google Earth Engine CMIP6 Explorer (GEECE) .
The following provides a step by step walkthrough of how to use GEEClimT, and demonstrates its functionality. If you have not used Google Earth Engine before you will need to create a Google Earth Engine account and register for a non-commerical cloud project before you can use GEEClimT. Google will ask you a few questions to make sure that you qualify for a non-commercial project (everything for research and education purposes is covered), and you only need to do this the first time that you use Google Earth Engine. Note that use of GEEClimT through this route is not permitted for commercial purposes. Users who wish to use GEEClimT for commercial purposes should contact the authors.
GEEClimT and its code is run through Google Earth Engine using JavaScript API. To access the tools click here, where you will be asked for brief user information before being provided with a link to the tool. Once the interface has been opened a welcome page will appear as shown below:
The first step in the interface is to select the desired export format by clicking on the drop-down arrows under step 1(a). The user can choose to export the final dataset as either a CSV spreadsheet (point data) or a GeoTIFF (spatially referenced information in the form of georeferenced raster imagery). For this example, we will select the raster grid (GeoTIFF) format for the data output.
Once the formatting for the data export has been chosen, the user is required to select a reanalysis dataset. By clicking the drop-down menu on step 1(b), all available datasets will be displayed. For this example, we will use the ERA5 Daily Aggregates (0.25 deg), where deg refers to the spatial resolution of the data in degrees.
Once the ERA5 Daily Aggregates data is selected in the drop-down menu, the data will be displayed on top of the map as shown below. For more information on the selected data, click the blue text below step 1 in the interface. This will open a new tab in Earth Engine Data Catalog and provide a description of the dataset, its properties and citations.
When the selected dataset is loaded, variables can be chosen/refined to suit the user's needs. All available variables are automatically selected. To refine the data, click on the ‘variables selected’ tab and untick the boxes next to any unwanted variables in the menu OR the user can also click ‘unselect all’ to clear all variables and then reselect those required. See below for this menu. For this example, we have chosen to keep all variables.
Once the desired variables are chosen, click ok and this will take the user back to the original interface display.
After the variables are selected, the date range needs defining. The full date range of the dataset will automatically be displayed and does not need altering by the user if the full date range is needed.
If required, users can manually change this in the text box to a desired start and end date in a year-month-day format (YYYY-MM-DD). As an example, we will change this data to start on March 5th, 1989 (1989-03-05) and end on July 18th, 2019 (2019-07-18). Note that month and day values <10 need a leading 0 for the date to be accepted (e.g. 1989-3-5 will result in the interface returning an error, whereas 1989-03-05 will not).
If only certain months are desired from the dataset, users can define these by clicking on the month options below. This option can be particularly useful when investigating seasonal change. If a range of months that span the end of the year are required (e.g. northern hemisphere winter), the start month selected would be December, and end month would be February. In this example we will use the default months from January to December.
To view walkthrough for obtaining image data in GeoTIFF format click here.
To view walkthrough for obtaining vector data in spreadsheet format click here.
This step has 2 options for the user when exporting data in CSV or GeoTIFF format.
- Manually draw a region of interest (ROI) as a polygon using the drawing tools in the top left of the map display.
- Manually enter a comma separated list of latitudes and longitudes and import as a polygon. Coordinates will be imported within a WGS84 projection (EPSG:4326).
In this example we will define a ROI using the drawing tools.
The user again has 2 options when drawing a ROI.
- Select ‘draw a shape’
. This will allow the user to draw points on the map, which when joined, creates a ROI in the form of a polygon. - Select ‘draw a rectangle’
. This will allow the user to draw a rectangle on the map which will define the ROI.
In this example, we will define a ROI using the ‘draw a shape’ tool. The ROI example is displayed as a pink polygon over Australia.
When the user is happy with the data output type, variables, date range and ROI, click ‘create export task(s)’ in step 5. This will process the data and once complete, a message will be displayed at the top of the interface.
If the user wishes to create a new dataset to export the user can click on the reset button in the bottom right of the interface.
Note that resetting will change the interface back to the original display but will keep any tasks created from step 5. If a user clicks the 'Run' button above the code editor window this will remove any unsubmitted tasks.
To export the data, drag the top of the interface down using the grey line with two rows of dots. This will reveal the code editor and task export panel. Click tasks highlighted in orange.
After tasks have been selected, it will display the name of the data variables selected (GeoTIFF data), along with CSV files that contain timestamp information for each output band of the selected variables. As we selected all 9 variables from the data, a total of 9 tasks will need running. However, as the ROI is quite large, each variable from this example is split into 3 different tasks, therefore a total of 27 GeoTIFF tasks are displayed, alongside 3 CSV files.
Note that the number of tasks at the end will vary depending on the number of variables selected and the ROI.
Click run on each task to submit to the server. The user can change the name of the dataset from the pop-up ‘initiate image export’ box. If this is all ok, click run again.
Run tasks...
The task will be moved to submitted tasks and will turn from a grey to blue background once complete. The user can keep an eye on the runtime to the right of the task.
Once completed, the bar showing the submitted task will turn blue:
At this point, the output data can be downloaded from a user's Google Drive for use in further analysis and/or visualisation.
Tip: if your query generates a lot of export tasks, the Open Earth Engine Google Chrome browser extension developed by Mathieu Gravey provides users with a "Run all tasks" option.
If a CSV format was selected as the data output in step 1, the steps in the interface will be displayed slightly differently. Follow steps 1-3 as outlined above and input the desired daterange. When the user gets to step 4, they are required to choose how GEEClimT will process the data for export. There are two processing options in GEEClimT:
- Mean of all point locations/polygon - this will return the mean of all the points/the entire region defined by the ROI (e.g. if three points are defined in the ROI the values returned will be the average of the three points). This option is likely to be most useful where the ROI is a polygon.
- Values of individual point locations (data for multiple points/polygon) - this will return data for each individual data point that overlaps with the the ROI (e.g. if three points are defined in the ROI the values for each of the three individual data points will be returned). This option is likely to be most useful where the ROI a point/multiple points.
For this example, where we have defined a polygon, we will tick the ‘table of mean values across entire ROI’ option.
This step requires the user to choose whether the data will be extracted from the dataset as either:
- Values from the nearest grid cell within the dataset, or
- Interpolated values from the grid cells nearest to ROI. For points data this will be based on bilinear interpolation of the four nearest grid cell values, and for a polygon ROI where the boundaries include part of a grid cell results will be spatially weighted to account for this.
Here we will select results to be analysed from ‘nearest full grid squares returned’.
In this step, once the previous steps are completed, the ROI can be defined. Within this step there are two options that are also the same for the raster/image export example GeoTIFF data:
- The first option allows the user to manually draw the ROI required, whether points or a single polygon, using the drawing tools in the top left of the map.
- The second option instead allows data to be defined through longitude/latitude coordinates, and site names to be defined. These can be entered into the boxes as comma separated lists (note that the interface will automatically remove any spaces and/or trailing commas).
Once the above is defined, the import option must be specified, between points or polygon data. This is only required when defining custom point location/polygon coordinates. This then completes the actions required for step 6 in the interface. This example will use the first option to manually draw the ROI (e.g. see the raster/image export example GeoTIFF data).
To generate the gridded area of interest, click the Generate gridded area of interest and Get data buttons to prepare the data for export,:
Once the Get data button is clicked, a ‘Processing’ bar will appear on the screen for a few seconds to confirm that data is being processed in preparation for export. The time taken for this process to complete depends on the dataset size requested.
Once the data has been processed, a preview of the data will appear on the left panel of the screen that also provides the opportunity for users to view data for different sites and different variables selected. Note that this preview is limited to the first 1000 observations. If the dataset size exceeds 1000 observations per site these data have been processed, but are not visualised.
The export task for the processed data can then be generated.
The code editor and export panel can be revealed when dragging the top of the screen downwards.
In the export panel, click Run to submit the export task for processing. While the data is exported, you must wait. This is indicated by the bar having a grey background. When this is finished, the background will turn blue.
Tip: if your query generates a lot of export tasks, the Open Earth Engine Google Chrome browser extension developed by Mathieu Gravey provides users with a "Run all tasks" option.
This means that all the steps have been completed, and resulting data can then be downloaded from a user’s Google Drive.
Well done! You have now completed all the steps for receiving data from GEEClimT.
This readme file was written by Georgia Carr and Natasha Jones (University of Liverpool). James Lea is responsible for the accuracy of the workflow description above, and any queries should be directed to him.
Data in GEEClimT are provided as given, and the authors take no responsibility for how data extracted from GEEClimT are used. GEEClimT is strictly intended for non-commercial use. To discuss potential commercial applications, users should contact James Lea (j.lea@liverpool.ac.uk).