4. Custom Configuration Directories

Geo2Grid allows users to customize various parts of its configuration. This allows for changing existing default behavior all the way to adding completely new functionality. The configuration mechanism used by Geo2Grid is borrowed from the Satpy project. It controls every component like readers, writers, composites, resampling, and enhancements that can be applied and when they are applied. The below sections will describe how custom configuration can be provided to Geo2Grid and how different parts can be customized.

4.1. Configuration Directories

Satpy and therefore Geo2Grid use a series of directories to configure themselves and the components they use. Most files are in the YAML text format. Satpy comes with its own builtin directory and allows users to specify additional external directories to replace or supplement the builtin configuration. Each user directory is the “root” directory for YAML files and sub-component directories with YAML files. These directories will typically look like:

/path/to/my_custom_dir/
    readers/
        my_custom_reader.yaml
    writers/
        my_custom_writer.yaml
    enhancements/
    composites/

Geo2Grid takes advantage of this Satpy feature and provides its own directory in the etc/polar2grid/ directory in $GEO2GRID_HOME. The configuration in this directory is required for Geo2Grid to work properly and work as expected.

Warning

Any changes to Geo2Grid’s configuration directory could lead to unexpected output or even make it impossible for Geo2Grid to run properly. Care should be taken when customizing files in etc/polar2grid/.

Users of Geo2Grid can create your own configuration directories and specify them to Geo2Grid (see below). This makes sure that your Geo2Grid installation stays in its original state.

4.2. Additional Directories

As mentioned above, users can create their own configuration directories and tell Geo2Grid to use them. This allows for Geo2Grid to stay in its original state while allowing full customization of the underlying Satpy functionality. To tell Geo2Grid about your directories add --extra-config-path /path/to/root_config_dir to your geo2grid.sh call. You can specify this flag multiple times to add additional directories. This directory must be the root directory of configuration. So it should have sub-directories for the components you are customizing (ex. ‘readers’, ‘composites’). You only need to have the configuration files that you are customizing.

Directories are loaded in reverse order that they are specified, but this means that the earlier directories have priority. For example,

polar2grid.sh ... --extra-config-path /path/to/root1 --extra-config-path /path/to/root2 ...

This call will result in Satpy loading Satpy’s builtin configuration first, it will then load and apply Geo2Grid’s builtin configuration on top of this, then the “root2” directory will be loaded, and lastly “root1”. Every time configuration is loaded it overwrites and adds on to any configuration that was already loaded.

4.3. Satpy Configuration

Satpy allows for additional configuration via environment variables. In most cases this is not recommended when working with Geo2Grid as most of these values are already customized to keep Satpy’s searches for information internal to the Geo2Grid installation rather than the rest of your system. Change these environment variables at your own risk.

4.4. Custom Composites

Satpy provides information on creating your own custom composites here. This documentation includes information on some of the builtin Python compositor classes provided by the library that can be combined to make complex products.

4.5. Resampling Configuration

Geo2Grid uses a special resampling.yaml configuration file not used by Satpy at the time of writing. This is because the implementation has not been finalized for Satpy and currently only lives in Geo2Grid. It still follows the same configuration rules described above and is a “decision tree” based file like enhancements (see below).

4.6. Decision Tree Configuration

Most configuration files used by Satpy are relatively straight forward; what you see is what you get. You give something a name and define various properties. The interconnection between the configuration sections in the YAML is relatively explicit or doesn’t exist at all. This is not true for enhancement and resampling configuration which describe a series of “decisions” that can be taken.

In decision tree configuration files you specify a “decision” (a.k.a “rule”) that Satpy will match against when determining how to process the current data. For example here is a section of an enhancement configuration file:

brightness_temperature_default_celsius:
  standard_name: toa_brightness_temperature
  units: celsius
  operations:
  - name: btemp_threshold
    method: !!python/name:satpy.enhancements.btemp_threshold
    kwargs:
      threshold: -31.15
      min_in: -110.15
      max_in: 56.85

The name of this section is “brightness_temperature_default_celsius”. It has no purpose other than to provide a unique and understandable summary of what the contained configuration is used for. The first two elements are part of the “decision” and say that if the current data has “standard_name” metadata equal to “toa_brightness_temperature” and has “units” of “celsius” then we should use the enhancement defined in “operations”. The standard name and units are two of many other options we can use in our rule. Others include name, reader, platform_name, and sensor. Resampling configuration has the additional area_type parameter. When Geo2Grid is processing some data it will try to find the section of configuration that matches the most (name has priority).