Running the GeoCARET Script

Note

The following instructions describe running GeoCARET to calculate input data for GHG Emission Estimation Tool RE-Emission. See Running GeoCARET.

First Steps

Syntax

The syntax to run GeoCARET from command line is:

> python heet_cli.py [input-file.csv] [projectname] [jobname] [output-option]

where:

  • [input-file.csv] is the path to the user input file.

  • [projectname] is the name of your Google Earth Engine project

  • [jobname] is a short 10 character jobname to be used when creating output folders. May only contain the following characters A-Z, a-z, 0-9, -.

  • [output-option] is the output data option defining the amount of output data: standard, extended, diagnostic, diagnostic-catch, diagnostic-res, diagnostic-riv. - see Output Data for details.

GeoCARET repository is shipped with an empty data/ folder. Its purpose is to store user-defined input data. An example dams.csv file is included in tests/data; In below examples, we will refer to this file’s location. Assuming your Earth Engine project is called my-ee-project, your jobname is called job01 and you want to generate standard output data, you can run GeoCARET as follows:

> python heet_cli.py tests/data/dams.csv my-ee-project job01 standard

Google Cloud authentication

Hint

Needed when running GeoCARET for the first time only.

If this is the first time you’ve run the GeoCARET tool, you will be asked to authenticate with Google’s cloud services:

  1. You’ll be shown a URL, which you should copy and paste into a web browser. In Windows PowerShell you can hold down the Ctrl key and click the URL to open it automatically.

  2. Follow the instructions to authenticate with Google

  3. After authenticating, you’ll be given a token, which you should paste back into the GeoCARET tool command line.

  4. Press enter to start the analysis.

Once authenticated the GeoCARET analysis will run. This could take several minutes to complete.

Results and Visualization

Once GeoCARET completes its analysis, it will generate a number of output data files, both locally and inside your Cloud Project. See the Output Data for full details.

You will also be shown a link to a Google Earth Engine script for visualizing the results inside Earth Engine. If you paste this link into a web browser, you will be taken to the Earth Engine Code Editor, with the script pre-loaded.

The visualization script is generic and the ‘user specified parameters’ section at the top will need to be modified to visualize the results of a specific GeoCARET analysis. There are instructions for how to do this in the comments at the top of the script.

Note

The script will need modification of paths so that the paths point to the location of files generated by your job run. We are working on dynamic generation of the visualisation script for each run which will contain the correct paths each time a script is run. We will update the documentation soon.

In the meantime, you will need to change the asset_folder variable to point to the location of the outputs of GeoCARET analysis you wish to visualize:

var asset_folder = "projects/your-project-name/assets/top-level-folder/XHEET/JOBNAME_YYYYMMDD-HHMM";

Where:

  • your-project-name should be replaced with the name of your Earth Engine Cloud Project

  • top-level-folder should be replaced with the name of the top-level assets folder inside that project

  • JOBNAME_YYYYMMDD-HHMM should be replaced with the appropriate GeoCARET outputs folder

Once you’ve modified the parameters as appropriate, you can run the script.

Logs

Any errors and issues will be logged in the logfile heet.log. A new log file is created with each run.

Usage Examples

Usage example for each operating system and command shell / prompt is listed below and includes virtual environment initialisation and deactivation steps. However, there are many tools available for managing virtual environments and they all have different syntax. We follow the syntax provided by the tool called virtualenv. More information about command-line shell options available for each operating system, setting up virtual environments and the tools available for this task, can be found in Installation as a Python Package. All examples below assume that the command prompt points to the root (main) folder in the GeoCARET installation.

Windows cmd/Windows PowerShell (anaconda prompt)

  • Activate the virtual environment:

> .\geocaretenv\Scripts\activate

  • Run the GeoCARET tool code

> python heet_cli.py tests/data/dams.csv job01 standard

  • When done, deactivate environment

deactivate

Windows (git bash)

  • Activate the virtual environment:

> source geocaretenv/Scripts/activate

  • Ensure UTF-8 characters display in terminal:

> export PYTHONIOENCODING=utf-8

  • Run code

> python heet_cli.py tests/data/dams.csv job01 standard

  • When done, deactivate environment.

deactivate

macOS / Linux

  • Activate the virtual environment:

> source geocaretenv/bin/activate

  • Run code

> python heet_cli.py tests/data/dams.csv job01 standard

  • Deactivate environment

deactivate