Add northness and eastness functions (cos/sin of aspect)

[brendancol]

Author of Proposal: rockout workflow

Reason or Problem

Aspect in degrees (0-360) is circular. A slope facing 1 degree and one facing 359 degrees point almost the same direction, but numerically they're 358 apart. This breaks any model that treats inputs as linear, which includes most regression and clustering methods.

The standard fix is to decompose aspect into two linear components:

• Northness = cos(aspect), ranging from +1 (due north) to -1 (due south)
• Eastness = sin(aspect), ranging from +1 (due east) to -1 (due west)

These two values together capture the same information as the original angle, but in a form that linear models can use directly. GIS textbooks treat this as a routine step (Stage 1976, Hengl 2009), but users currently have to handle the degree-to-radian conversion and flat-cell edge cases themselves.

Proposal

Add two public functions, northness and eastness, to the xrspatial.aspect module.

Design:

Both are thin wrappers around aspect(). They call aspect(agg, ...) with the same parameters (method, z_unit, boundary), convert from compass degrees to radians, apply np.cos or np.sin, and map flat cells (aspect == -1) to NaN.

Since they delegate to aspect(), all four backends and both methods (planar, geodesic) work automatically. No new kernel code.

Usage:

from xrspatial import northness, eastness

north = northness(elevation)
east = eastness(elevation)

# Use in a regression
features = xr.Dataset({'northness': north, 'eastness': east, 'slope': slope_agg})

Value:

Saves users from re-deriving the conversion and handling edge cases (flat cells, NaN propagation) each time they need aspect in a statistical model.

Stakeholders and Impacts

Anyone using aspect in statistical or ML workflows. No impact on existing functions.

Drawbacks

Simple enough that a user could write this in a few lines. But having it in the library makes the decomposition more discoverable, and gets the flat-cell handling right by default.

Alternatives

Users can write the cos/sin conversion inline. It works, but it's easy to forget the -1 flat cell handling or mess up the radian conversion. A combined function returning both components as a Dataset could be added later if there's demand.

Unresolved Questions

None.

Additional Notes or Context

References:

• Stage, A.R. (1976). "An Expression for the Effect of Aspect, Slope, and Habitat Type on Tree Growth." Forest Science 22(4): 457-460.
• Hengl, T. (2009). A Practical Guide to Geostatistical Mapping.