Add local incidence angles, validation summary, and tile tailored views on the ellipsoid

CHANGELOG.md

@@ -33,8 +33,10 @@ Added:
  - Utility methods `compute_view_tangents`, `compute_view_angles`, `compute_along_track_field_of_view`, `compute_argument_of_latitude`, `geodesic_destination`, `pressure_to_altitude`, and `altitude_to_pressure`, radar geometry methods (`compute_radar_beam_height`, `compute_radar_ground_range`, `compute_radar_ground_range_bounds`, `compute_radar_slant_range`, `compute_terrain_elevation_angle`, `compute_radar_footprint`, and `compute_radar_footprint_profile`), and method `PointedInstrument.is_in_field_of_view`.
  - Utility methods for the WGS 84 ellipsoid (module `tatc.utils.ellipsoid`): `geodetic_to_rectangular`, `rectangular_to_geodetic`, `compute_ellipsoid_intersection` (intersections of rays with the ellipsoid), and `compute_tangent_point` (the point of minimum geodetic altitude on a line), utility method `compute_vnb_frame` (a satellite's velocity, normal, and binormal frame), and utility method `hash_geometry` (a compact hash identifying a geometry).
  - Runtime configurations `footprint_points_radar_azimuthal`, `repeat_cycle_delta_semimajor_axis_m`, and `nutation_interpolation_minutes` (the step of a cached table from which nutation angles are interpolated, or `null` to compute them for every time), and constants `EFFECTIVE_EARTH_RADIUS_FACTOR`, `EARTH_ROTATION_RATE`, and `TROPICAL_YEAR_S`.
- - Validation notebooks in `docs/validation` comparing TAT-C with data from operational missions.
+ - Utility method `compute_local_incidence_angle`, the angle between the line of sight to a satellite and the normal to sloped terrain at a target, and preprocessing methods `compute_terrain_slope_aspect` (the slope and aspect of a DEM, by central differences of bilinearly interpolated elevations, across the seams of adjacent tiles) and `add_local_incidence_angles` (the terrain slope, aspect, and local incidence angle at the targets of ground pixels or observations with satellite angles), to constrain observations of mountainous terrain, as by side-looking instruments.
+ - Validation notebooks in `docs/validation` comparing TAT-C with data from operational missions, with a summary of their results by capability, modeling guidance, and the limits of what TAT-C models (`docs/validation/summary.rst`).
  - Example notebook `docs/examples/RunOSSEMonsoon.ipynb`, an observing system simulation experiment (OSSE) that samples cold cloud top features of the 7-km GEOS-5 Nature Run over the American Southwest with the swaths of current (ATMS, CrIS) and notional future sounders, compares their horizontal resolution, and trades the number of satellites and orbit planes of the constellation.
+ - A section of example notebook `docs/examples/CollectOrbitGroundTrack.ipynb` comparing the nadir field of regard model of NOAA-20 VIIRS with a detailed model from its validation (a `PointedInstrument` with the measured scan extent, scan view geometry, an along-track field of view tailored to the scan period, and the inertial velocity frame): their footprints, scans at nadir and the swath edge, and swaths over a pass.
  - Example notebook `docs/examples/RunOSSEHurricane.ipynb`, an OSSE of a simulated North Atlantic hurricane in the GEOS-5 Nature Run (located with its coarsened 0.5 degree collection), which samples its cold cloud tops and heavy precipitation with the same sensors.
  - Optional dependencies `preprocess` and `validation`, and development dependency `pytest-xdist` to run tests in parallel (e.g. `pytest -n 8`).
 
@@ -60,6 +62,9 @@ Changed:
  - Generating points and cells is about 3 to 15 times faster (vectorized geometry construction, hashing, and clipping). Points and cells clipped to a mask keep the grid or lattice order rather than the arbitrary order of `geopandas.clip`.
  - Analysis methods that accept satellites raise a `TypeError` for a constellation (use its `generate_members` method).
  - Deprecated utility method `buffer_target`.
+ - `collect_observations` accepts a GeoDataFrame or GeoSeries of points (for example, generated points), as the list of its geometries.
+ - Moved `joblib`, used only by the example and validation notebooks, from the required to the `examples` optional dependencies.
+ - Replaced the deprecated `shapely.ops.transform` with `shapely.transform` in `buffer_footprint` and `buffer_target`.
  - Fixed `SunSynchronousOrbit` to place the ascending node in local mean solar time and to keep the local time of its equator crossings constant as propagated.
  - Fixed `TrainConstellation` for long intervals between members, and `MolniyaOrbit` and `TundraOrbit` periods to repeat the ground track as propagated.
  - Fixed rectangular footprints of wide, elongated views.
@@ -72,6 +77,7 @@ Changed:
  - Fixed `collect_ro_observations` labeling some occultations of transmitters nearly abeam of the receiver (yaw angles near 90 degrees) as setting rather than rising: `is_rising` follows the direction of the tangent point through `sample_elevation`. `collect_ro_observations` also splits a grazing occultation, whose tangent point descends and rises again, into a setting and a rising observation where the tangent point turns, so that each observation crosses `sample_elevation` at most once.
  - Fixed `compute_latencies` for observations and downlinks whose times have different units (for example, microseconds and nanoseconds).
  - Fixed `split_polygon` for longitudes beyond 180 degrees, for polygons spanning -180 to 180 degrees of longitude, and for holes across the anti-meridian or around a pole (holes are now split like exteriors), and to drop degenerate (zero-area) parts left by repairing invalid polygons.
+ - Fixed `compute_along_track_field_of_view` to subtend the ground track's advance from the satellite's height above the WGS 84 ellipsoid rather than its mean altitude above the mean Earth radius: at low latitudes, where a satellite is about 7 km lower above the ellipsoid, consecutive footprints left gaps of up to about 0.7% of their length (83 m per scan for NOAA-20 VIIRS). Tailored fields of view are about 1% larger in low Earth orbit.
  - Fixed cached orbit computations for copies with changed fields, and orbits and satellites to be picklable after propagation.
  - Fixed numba-compiled utility methods (in `tatc.utils.orbital`, `observation`, `radar`, `atmosphere`, and `surface`) returning `nan` for integer inputs, which overflowed in compiled integer arithmetic (for example, `semimajor_axis_to_mean_motion(7000000)`): inputs are now converted to floats.
  - Improved the performance of footprints (rays projected together from one view frame, vectorized ray and limb intersections, polygon assembly, splitting along the anti-meridian, and `split_polygon`), masked ground tracks, multi-element orbit propagation, `collect_ro_observations` (observation periods of all transmitters searched and sampled together, with sample times and profiles built at once), `collect_limb_observations` (all scans sampled together, with sample times built at once), radar footprints (terrain masks interpolated at all azimuths at once, and a closed-form local projection instead of PROJ transformers for each station), `collect_observations` (linear-time pairing of rise and set events, and validity checks of all epochs at once), `collect_region_observations` (validity checks and swaths of all periods at once), `collect_orbit_track` (masks tested and points built for all times at once), observations of several points, regions, or satellites (Earth orientation computed together at each step of their searches), rise and set times (each bracketed near Skyfield's estimate and bisected only until it is narrower than a millisecond), orbit propagation (IAU 2000A nutation angles interpolated from a cached table, to within about a microarcsecond, rather than computed for every time), instrument validity checks (without iterating over Skyfield times), and the searches that refine observation periods (times built from offsets without `datetime` objects). `to_datetime64_ns` and `GeneralPerturbationsOrbit.get_closest_element_index` accept Skyfield `Time` objects.

README.md

@@ -45,14 +45,26 @@ Development tools are applicable when working with the source code.
 
 ### Unit Tests
 
-Run unit tests with:
+Run unit tests with pytest (installed with the `dev` optional dependencies):
 ```shell
-python -m unittest
+pytest
 ```
 
+Tests can run in parallel with `pytest-xdist` (e.g., with 8 workers):
+```shell
+pytest -n 8
+```
+
+Run a subset of tests by file, or by a keyword expression with `-k`:
+```shell
+pytest tests/analysis/test_point_sampling.py -k "geodataframe"
+```
+
+The tests are written with `unittest`, so `python -m unittest` also runs them without pytest.
+
 Unit tests run numba-compiled functions (see below) compiled, which coverage cannot trace. To include them in a test coverage report, run the tests with the environment variable `NUMBA_DISABLE_JIT=1` (e.g., in bash):
 ```shell
-NUMBA_DISABLE_JIT=1 coverage run -m unittest
+NUMBA_DISABLE_JIT=1 coverage run -m pytest
 ```
 including html output:
 ```shell

docs/api_reference/preprocess/index.rst

@@ -38,6 +38,24 @@ Compute Terrain Mask for Platform
 
 .. autofunction:: tatc.preprocess.compute_terrain_mask_for_platform
 
+Terrain Slopes and Incidence Angles
+===================================
+
+The terrain slope and aspect at observed targets, from a DEM, give the local
+incidence angle of observations on sloped terrain (see
+:func:`tatc.utils.compute_local_incidence_angle`), for example, to constrain
+side-looking observations of mountainous regions.
+
+Compute Terrain Slope and Aspect
+--------------------------------
+
+.. autofunction:: tatc.preprocess.compute_terrain_slope_aspect
+
+Add Local Incidence Angles
+--------------------------
+
+.. autofunction:: tatc.preprocess.add_local_incidence_angles
+
 Rasters
 =======
 

docs/api_reference/utils/index.rst

@@ -53,6 +53,8 @@ Utility Functions
 
 .. autofunction:: tatc.utils.compute_min_elevation_angle
 
+.. autofunction:: tatc.utils.compute_local_incidence_angle
+
 .. autofunction:: tatc.utils.semimajor_axis_to_orbit_period
 
 .. autofunction:: tatc.utils.semimajor_axis_to_mean_motion