Arithmetic

The Arithmetic ObsFunction can be used to manipulate and combine an arbitrary number of inputs using selected mathematical operations.

Please note that this ObsFunction used to be called LinearCombination. The name has been retained for backwards compatibility, but its use is deprecated.

Operations

The following operations are available:

  • Multiplication,

  • Addition,

  • Exponentiation,

  • Logarithms,

  • Absolute value,

  • Truncation towards an integer.

The operations are combined as follows:

(22)\[y = A F\Big(\sum_i a_i f_i(g_i(x_i))\Big) + C\]

where \(y\) is the output value, \(x_i\) are the variables to combine, \(a_i\) are multiplicative coefficients applied to each variable, \(A\) is a total multiplicative coefficient, \(C\) is an additive constant, \(F(\cdot)\) and \(f_i(\cdot)\) represent the application of one or both of the exponentiation and logarithm functions, and \(g_i(\cdot)\) represents the application of one or both of the absolute value and truncation functions.

The base used in both the exponentiation and logarithm functions is user-defined and can be different for each application of those functions. The truncation function rounds (towards zero) each variable to the nearest integer multiple of a chosen integer. For example, if the chosen integer is 5, the truncation function will round 12 to 10 and -17 to -15.

Parameters

The ObsFunction accepts the following parameters. In each case the correspondence between the parameter and a term in the above equation is shown.

  • variables: Vector of input variables (\(x_i\)).

  • coefs: Vector of multiplicative constants associated with the input variables (\(a_i\)).

  • exponents: Vector of exponents associated with the input variables (\(f_i(\cdot)\)).

  • total exponent: Overall exponent (\(F(\cdot)\)).

  • total coefficient: Overall multiplicative coefficient (\(A\)).

  • intercept: Additive constant (\(C\)).

  • total log base: Overall log base (can be empty string for no logarithm, or e for natural logarithm) (\(f_i(\cdot)\)).

  • log bases: Vector of log bases associated with the input variables (can empty string for no logarithm, or e for natural logarithm) (\(f_i(\cdot)\)).

  • absolute value: Take absolute value of each variable (true/false). If true, the absolute value is taken before any other operation is performed (\(g_i(\cdot)\)).

  • truncate: Truncate (round towards zero) each input variable to the nearest integer multiple of the corresponding entry in this vector. If the value in the vector is zero or negative, no truncation is performed. If the value is positive, truncation is performed before any other operation apart from taking the absolute value. (\(g_i(\cdot)\)).

  • use channel numbers: This option enables channel numbers to be combined if that is desired. If true, the channel number will be used in the calculation instead of the value of each variable. Default false.

The variables parameter must be present. All other parameters are optional. The length of vector parameters such as log bases must be the same length as variables.

If the input variable is equal to the missing value, the output variable is set to the missing value. The same occurs for a missing input channel if use channel numbers is true.

Warnings are emitted in the following situations:

  • The total exponent parameter is larger than 25, or any value in the exponents vector is larger than 10. Such values could cause numerical overflows.

  • A negative value is raised to a non-integer exponent. In this case the output value is set to missing.

Exceptions are thrown in the following situations:

  • The logarithm of a negative number (or zero) is taken.

  • The chosen log base is invalid.

Example 1

obs function:
  name: ObsFunction/Arithmetic
  options:
    variables: [GeoVaLs/representation_error,
                ObsError/waterTemperature]
    coefs: [0.1, 1.0]

Output: 0.1 GeoVaLs/representation_error + ObsError/waterTemperature.

Example 2

obs function:
  name: ObsFunction/Arithmetic
  options:
    variables: [ObsValue/variable1,
                ObsValue/variable2,
                ObsValue/variable3]
    coefficients: [0.1, 0.2, 0.3]
    exponents: [1, 2, 3]
    log bases: ["10", "", e]
    total coefficient: 4
    total exponent: 5
    total log base: 2
    intercept: 6

Output:

4 \(\log_{2}\) \(\Big(\big(\) 0.1 \(\log_{10}\) (ObsValue/variable1\(^1\)) + 0.2 ObsValue/variable2\(^2\) + 0.3 \(\ln\) (ObsValue/variable3\(^3\)) \(\big)^5\) \(\Big)\) + 6.

Example 3

This example shows how calculations can be performed on multi-channel data.

obs function:
  name: ObsFunction/Arithmetic
  channels: &select_chans 6-15, 18-22 # this line may be needed depending on the filter used
  options:
    variables:
    - name: ObsValue/brightnessTemperature
      channels: *select_chans
    - name: ObsError/brightnessTemperature
      channels: *select_chans
    coefs: [1.0, 0.5]

Output for channel k: ObsValue/brightnessTemperature[k] + 0.5 ObsError/brightnessTemperature[k].

Example 4

This example shows how calculations can be performed on multi-channel data, using the channel number instead of the value of each variable.

obs function:
  name: ObsFunction/Arithmetic
  channels: &select_chans 6-15, 18-22 # this line may be needed depending on the filter used
  options:
    variables:
    - name: ObsValue/brightnessTemperature
      channels: *select_chans
    coefs: [0.5]
    intercept: 3.6
    use channel numbers: true

Output for channel k: 3.6 + 0.5 k.

Example 5

obs function:
  name: ObsFunction/Arithmetic
  options:
    variables: [ObsValue/variable1,
                ObsValue/variable2]
    absolute value: [true, false]
    truncate: [0, 3]

Output: |ObsValue/variable1| + trunc(ObsValue/variable2, 3) where trunc(x, y) returns x truncated to the nearest integer multiple of y. Truncation is always performed towards zero, e.g. trunc(17, 3) = 15, trunc(-13, 3) = -12.