Add horizontal_tilt_angle function and tests

[ErosKerouak]

This pull request adds the horizontal_tilt_angle function to harmonica._transformations.

The horizontal tilt angle is a enhancement filter used in gravity and magnetic interpretation. It computes the arctangent of the horizontal gradient magnitude over the absolute value of the upward derivative.

Summary of changes:

• Implemented horizontal_tilt_angle function with full docstring and LaTeX formula
• Added unit tests based on a synthetic model
• Input validation for grids with invalid dimensions and NaN values

Relevant issues/PRs:
Closes #559
Related to #560, #561

[gaoflow]

The Actions logs for the failing code-style jobs have expired, but I was able to reproduce the style issues locally on the PR checkout using this branch's older Makefile layout (harmonica doc, not current src/harmonica test doc).

The failures are concentrated around the new horizontal_tilt_angle code and tests: import ordering, blank-line spacing, docstring line length, one trailing whitespace, and Black formatting.

A minimal patch is:

diff --git a/harmonica/_transformations.py b/harmonica/_transformations.py
@@
 """
 Apply transformations to regular grids of potential fields
 """
+
 import numpy as np
@@
     Compute the amplitude of the horizontal gradient of a regular gridded
     potential field `M`. This is a measure of the rate of change in the x and y
-    (horizontal) directions. . The horizontal derivatives are calculated though 
+    (horizontal) directions. The horizontal derivatives are calculated though
     finite-differences.
@@
-        order: *northing*, *easting*. The coordinates must be defined in the same units.
+        order: *northing*, *easting*. The coordinates must be defined in the
+        same units.
@@
-        A :class:`xarray.DataArray` containing the total horizontal derivative of
-        the input ``grid``.
+        A :class:`xarray.DataArray` containing the total horizontal derivative
+        of the input ``grid``.
@@
     horizontal_gradient = (
         derivative_easting(grid, order=1),
-        derivative_northing(grid, order=1)
+        derivative_northing(grid, order=1),
     )
@@
     horiz_deriv = np.sqrt(gradient[0] ** 2 + gradient[1] ** 2)
     return np.arctan2(horiz_deriv, total_gradient)
 
+
 def horizontal_tilt_angle(grid):
@@
-    horizontal gradient magnitude and the absolute value of the upward derivative.
+    horizontal gradient magnitude and the absolute value of the upward
+    derivative.
@@
-
-
 def _get_dataarray_coordinate(grid, dimension_index):
diff --git a/harmonica/tests/test_transformations.py b/harmonica/tests/test_transformations.py
@@
 """
 Test functions for regular grid transformations
 """
+
 from pathlib import Path
@@
     derivative_upward,
     gaussian_highpass,
     gaussian_lowpass,
+    horizontal_tilt_angle,
     reduction_to_pole,
-    tilt_angle,
     theta_map,
-    horizontal_tilt_angle,
+    tilt_angle,
@@
-    def test_against_synthetic(
-        self, sample_potential, sample_g_n, sample_g_e
-    ):
+    def test_against_synthetic(self, sample_potential, sample_g_n, sample_g_e):
@@
         with pytest.raises(ValueError, match="Found nan"):
             theta_map(sample_potential)
 
+
 class TestHorizontalTiltAngle:
@@
-        Check if horizontal_tilt_angle raises error on grid with single dimension
+        Check if horizontal_tilt_angle raises error on grid with single
+        dimension
@@
-        Check if horizontal_tilt_angle raises error on grid with three dimensions
+        Check if horizontal_tilt_angle raises error on grid with three
+        dimensions
@@
-
 class Testfilter:

Verified locally on the changed files:

isort --check harmonica/_transformations.py harmonica/tests/test_transformations.py
flake8 harmonica/_transformations.py harmonica/tests/test_transformations.py
black --check harmonica/_transformations.py harmonica/tests/test_transformations.py
git diff --check

I couldn't run the new tests in this local environment because verde is not installed, and a full install of the old style requirements hit local disk limits. So this is scoped to the style failures only.

[santisoler]

Hi @gaoflow. Your last sentence makes me think you pasted the output of a generative AI directly into the Pull Request.

We value human-human interaction over discussing contributions with bots. We'll delete comments and contributions that goes against the Policy on the usage of AI in Fatiando we are drafting. Please avoid heavy usage of generative AI when interacting with the Fatiando a Terra community.