CircularDifference¶

The CircularDifference ObsFunction computes the minimum (shortest-path) difference between two values defined on a circular (cyclic) domain, accounting for wrap around at the circular boundary.

For two values \(A\) (variable start) and \(B\) (variable end) of a circular quantity, the circular difference is \(B - A\) normalised to the range \([-P/2,\, P/2)\) where \(P\) is the circular period. Of the two such possible differences (the shortest path and longest paths around the circle) the shortest path is returned.

If signed is true, the signed difference in the range \([-P/2,\, P/2)\) is returned:

Positive values indicate \(B\) is ahead of \(A\) in the direction of increasing values (clockwise for angles).
Negative values indicate \(B\) is behind \(A\) in the direction of increasing values (counter-clockwise for angles).

If signed is false, the absolute (unsigned) difference is returned, always in the range \([0,\, P/2]\).

Similarly for days in the week, if P = 7 and \(A = 6\) (Saturday) and \(B = 1\) (Monday), the circular difference is \(-2\) if signed is true (indicating that Monday is 2 days before Saturday), and \(2\) if signed is false.

Missing values in either input variable propagate to the output.

Options¶

variable start (required): The start variable \(A\) (the reference value).
variable end (required): The end variable \(B\) (the value being compared).
signed (optional): If true, return the signed difference in \([-P/2,\, P/2)\). If false, return the absolute difference in \([0,\, P/2]\). Defaults to true.
circular period (required): The period \(P\) of the circular quantity (e.g. 360.0 for wind directions in degrees, 6.283185307 for angles in radians, 24 for hours in the day). Must be positive.

Examples¶

The following examples illustrate the sign convention using wind directions (\(P = 360°\)) as a concrete case. Note how the signed difference gives a negative value when \(B\) and \(A\) are on opposite sides of the 0°/360° boundary. The same would happen with hours in the day if the values were separated by 12 hours.

\(A\) (°)	\(B\) (°)	Signed difference (°)	Unsigned difference (°)
10	350	−20	20
350	10	20	20
0	180	-180	180
90	270	-180	180

The following YAML computes both the signed and unsigned circular difference between two wind direction variables, using the Variable Assignment filter:

obs filters:
  # Signed circular difference (windDirectionB - windDirectionA)
  - filter: Variable Assignment
    assignments:
      - name: MetaData/signedWindDirectionCircularDiff
        type: float
        function:
          name: ObsFunction/CircularDifference
          options:
            variable start: ObsValue/windDirectionA
            variable end: ObsValue/windDirectionB
            signed: true
            circular period: 360.0
  # Unsigned (absolute) circular difference |windDirectionB - windDirectionA|
  - filter: Variable Assignment
    assignments:
      - name: MetaData/unsignedWindDirectionCircularDiff
        type: float
        function:
          name: ObsFunction/CircularDifference
          options:
            variable start: ObsValue/windDirectionA
            variable end: ObsValue/windDirectionB
            signed: false
            circular period: 360.0