Extend GeoIPS with a new Algorithm#

Creating an Algorithm#

The following steps will teach you how to create a custom algorithm plugin. First off, change directories to your algorithms directory.

cd $MY_PKG_DIR/$MY_PKG_NAME/plugins/modules/algorithms

Create a file called my_cloud_depth.py (see below). To convert this algorithm to my_cloud_depth you’ll need to update the docstring (multiline string at the top of the file) and update the name to my_cloud_depth.

Copy and paste the code block below into my_cloud_depth.py

"""Cloud depth product.

Difference of cloud top height and cloud base height.
"""
import logging
from xarray import DataArray

LOG = logging.getLogger(__name__)

interface = "algorithms"
family = "xarray_to_xarray"
name = "my_cloud_depth"
# Conventionally matches the name of the plugin definition file, but can be anything
# that does not contain hyphens.

Each module-based plugin is required to have a call function. This is how geoips will interact with the module-based plugins. See below for the call signature of the my_cloud_depth.py plugin. To see a list of required arguments for each algorithm family, see this link.

As for keyword arguments (kwargs), you can create as many as you want provided you include them in your product and are needed for your algorithm.

Copy and paste this code into your algorithm file (feel free to remove the comments).

def call(
    xobj, # Xarray dataset holding xarrays
    variables, # list of required input variables for algorithm.
               # Note: Python lists are ordered, so you can count on
               # your list of variables being in the order in which you
               # define them in your product plugin variables
    product_name,
    output_data_range,  # Range of values that your algorithm will output
    scale_factor,  # Adding a scale factor here for use in converting input meters to output kilometers
    min_outbounds="crop",
    max_outbounds="crop",
    norm=False,
    inverse=False,
):
    """My cloud depth product algorithm manipulation steps."""

This is where the actual data manipulation occurs. Make sure to index the variable list to the order of the variables you defined in your product, then make the following changes.

Add the code block below to your call function. This is how cloud-depth will be calculated.

cth = xobj[variables[0]]
cbh = xobj[variables[1]]

out = (cth - cbh) * scale_factor

from geoips.data_manipulations.corrections import apply_data_range

data = apply_data_range(
    out,
    min_val=output_data_range[0],
    max_val=output_data_range[1],
    min_outbounds=min_outbounds,
    max_outbounds=max_outbounds,
    norm=norm,
    inverse=inverse,
)
xobj[product_name] = DataArray(data)

return xobj

If you have already created a Product defined in the Products section, we should revisit our My-Cloud-Depth product definition to use the algorithm we just created. Note: If you haven’t yet created this product, see the Products section.

If you are using this page as more of a guideline for how to create an algorithm plugin, it should be noted that algorithms are useless on their own. This goes for other plugins too, like colormappers, interpolators, etc. These are just sub-components of a larger plugin, that being a Product, which fully defines the process of how to create a Product via GeoIPS.

In other words, you should implement your product in a fashion similar to what is done in the My-Cloud-Depth product definition.