Quick Start

Example Run

As an example, follow the code block below. Please remember that you MUST have access to the RDRSv2.1 model outputs on your HPC of interest. Enter the following codes in your bash shell as a test case:

foo@bar:~$ git clone https://github.com/CH-Earth/gistool.git # clone the repository
foo@bar:~$ cd ./gistool/ # move to the repository's directory
foo@bar:~$ ./extract-dataset.sh -h # view the usage message
foo@bar:~$ ./extract-dataset.sh  \
             --dataset="modis" \
             --dataset-dir="/work/comphyd_lab/data/geospatial-data/MODIS" \
             --output-dir="$HOME/test-gistool/modis" \
             --print-geotiff=true \
             --variable="MCD12Q1.061" \
             --prefix="test_" \
             --shape-file="/modify/the/path/to/polygons.shp" \
             --stat="frac" \
             --start-date="2020-01-01" \
             --end-date="2020-01-01" \
             --fid="COMID" \
             --cache='$TMPDIR' \
             --cluster=./etc/clusters/ucalgary-arc.json \
             -j;

The test case above is assumed to be run on the University of Calgary’s ARC cluster. Nevertheless, the test case can run on any cluster where the data are available. View the details of the JSON configuration file to configure the tool for various HPCs.

There are a few examples available in the examples directory of the repository.

Setup on Other Clusters

If you are attempting to set up Gistool on a cluster that is not supported by default, you may need to manually install the required environment using the install-env.sh script. This script automates the installation of the necessary dependencies and tools for Gistool to function correctly on your target HPC system.

Usage of install-env.sh

The install-env.sh script requires a JSON file describing the target HPC system and optionally allows you to specify an installation path. Below is the help message for the script:

Usage:
  install-env.sh -j HPCJSON [-p INSTALL_PATH] [-h]

Options:
  -j HPCJSON       The JSON file describing the target HPC system (required)
  -p INSTALL_PATH  The installation path for the environment required
                   for the tool [default: \$HOME/.local/R/exact-extract-renv]
  -h               Show this help message and exit

Specifying the Installation Path in the Cluster JSON

Once the environment is installed using the install-env.sh script, you can use the installation path (specified with the -p option or the default path) as the value for the lib-path entry in the cluster-specific JSON file. This ensures that gistool can locate the required libraries and dependencies during execution.

Example JSON entry:

{
    "lib-path": "/path/to/installation"
}

Replace /path/to/installation with the actual installation path used during the environment setup. This step is crucial for ensuring compatibility and proper functionality of Gistool on your cluster.

The ./etc/clusters/ directory contains example JSON configuration files that describe various HPC systems. These files can serve as templates for creating your own cluster-specific JSON configuration.

Logs

The datasets logs are generated under the $HOME/.gistool directory, only in cases where jobs are submitted to clusters’ schedulers. If processing is not submitted as a job, then the logs are printed on screen (i.e., stdout).

Support

Please open a new ticket on the Issues tab of this repository for support.