ENH: Option to return full array of data including NaNs from geo calcs

[carleyjmartin]

Scope

This PR adds an option to return a full array of lat/lon data from the GEOGRAPHIC and AACGM functions in coordinates.
Often a user does not want to plot the data, but compare the positions in two range estimates (i.e. GSMR and slant range)
Using this new key word, the user can return a complete lat lon array including NaN values (as inner range gates for GSMR often end up with NaN values due to /0).

Note that this is NOT designed to be used when plotting, including an array with NaNs for position will result in unexpected behavior. You can still plot normally as the default is to remove the NaN values and this hasn't changed.

issue: to close #439

Approval

Number of approvals: 2 - minor change

Test

matplotlib version: 3.10.8
Note testers: please indicate what version of matplotlib you are using

import pydarn
import matplotlib.pyplot as plt
import datetime as dt

data, _ = pydarn.read_fitacf('/home/carleyjm/data/fitacf/20250101.0600.00.sas.a.fitacf')

GSMR_lats, GSMR_lons = pydarn.Coords.GEOGRAPHIC(stid=pydarn.RadarID(data[0]['stid']),
                           rsep = 45,
                           frang=data[0]['frang'],
                           gates=[0,75],
                           date=dt.datetime(2025,1,1,12,0),
                           range_estimation=pydarn.RangeEstimation.GSMR,
                           include_invalid=False)

GSMR_full_lats, GSMR_full_lons = pydarn.Coords.GEOGRAPHIC(stid=pydarn.RadarID(data[0]['stid']),
                           rsep = 45,
                           frang=data[0]['frang'],
                           gates=[0,75],
                           date=dt.datetime(2025,1,1,12,0),
                           range_estimation=pydarn.RangeEstimation.GSMR,
                           include_invalid=True)

SLANT_lats, SLANT_lons = pydarn.Coords.GEOGRAPHIC(stid=pydarn.RadarID(data[0]['stid']),
                           rsep = 45,
                           frang=data[0]['frang'],
                           gates=[0,75],
                           date=dt.datetime(2025,1,1,12,0),
                           range_estimation=pydarn.RangeEstimation.SLANT_RANGE,
                           include_invalid=False)

print('==== GSMR ====')
print(GSMR_lats.shape)
print(GSMR_lons.shape)

print('==== GSMR All ====')
print(GSMR_full_lats.shape)
print(GSMR_full_lons.shape)

print('=== SLANT RANGE ===')
print(SLANT_lats.shape)
print(SLANT_lons.shape)

plt.scatter(SLANT_lats, SLANT_lons, c='r', marker='x')
plt.scatter(GSMR_lats, GSMR_lons, c='b', marker='+')
plt.show()

Output:

==== GSMR ====
(68, 17)
(68, 17)
==== GSMR All ====
(76, 17)
(76, 17)
=== SLANT RANGE ===
(76, 17)
(76, 17)

If the user would like to use range_estimation to calculate positions, this already returns unmodified array of data, including NaNs, plotting removes these in RTP.py but the function can be called to give range estimate values (not lat and lon).

E.G.

range_estimation = pydarn.RangeEstimation.GSMR

rxrise = pydarn.SuperDARNRadars.radars[pydarn.RadarID(data[0]['stid'])].hardware_info.rx_rise_time
y = range_estimation(frang = int(data[0]['frang']),
                     rxrise = rxrise,
                     rsep = int(data[0]['rsep']),
                     nrang=75)
print(y)

[Prof-CW]

Hi Carley,
Thanks for adding the information about NaN in the ground scatter lat,lons.
The NaNs come from the calculation of acos() of a number > 1 rather than a divide by 0, i.e.

ground_scatter_mapped_ranges = (hop/0.5) * Re * np.arccos(-num/den)
return ground_scatter_mapped_ranges

.