EHN: Options to Plot a Terminator

[carleyjmartin]

Scope

This PR adds options to plot a terminator. As discussed in the last pyDARN meeting, it's difficult to plot your own terminator using fill or fill_between due to the Earth being spherical and fill not understanding which side of the terminator needs filling. Due to this, it was decided that we go ahead with only applying the cartopy nightshade option to geographic projected plots, the cartopy function does not return lat/lon as expected so we can't just convert them and then we still have the plotting issue.
I have, however, left in the terminator and peripheral code so that a user might be able to calculate and plot their own terminator if they would like in magnetic coordinates, but they may find that fill doesn't work as expected - this is written up in the documentation changes to explain.
I have also added a warning if someone uses the nightshade key with a polar projection.

The examples below use a height in the ionosphere of 250 km, so you'll notice that it looks a lot further back than when at ground level. Cartopy nightshade and the terminator function use an angle value to denote how far back it is which is calculated by:

angle = -np.degrees(np.arccos(Re / (Re + height_in_ionosphere)))

but due to a difference in how the distance is calculated, then you might see a small difference between the two terminator positions.

issue: to close #50

Approval

Number of approvals: 2

Test

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

import pydarn
import aacgmv2
import datetime as dt
import matplotlib.pyplot as plt
import numpy as np

# Geographic Coordinates
# North Winter
_,_,ax1,ccrs1=pydarn.Fan.plot_fov(66, dt.datetime(2023, 12, 21, 0, 0), lowlat= 10,
    coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO,
    boundary=True, line_color='red', coastline=True, nightshade=250)
plt.show()
# 
# North Summer
_,_,ax1,ccrs1=pydarn.Fan.plot_fov(66, dt.datetime(2023, 6, 21, 0, 0), lowlat= 10,
     coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO,
     boundary=True, line_color='red', coastline=True, nightshade=250)
plt.show()
 
# South Summer
_,_,ax1,ccrs1=pydarn.Fan.plot_fov(24, dt.datetime(2023, 12, 21, 0, 0), lowlat= 10,
     coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO,
     boundary=True, line_color='red', coastline=True, nightshade=250)
plt.show()

# South Winter
_,_,ax1,ccrs1=pydarn.Fan.plot_fov(24, dt.datetime(2023, 6, 21, 0, 0), lowlat= 10,
     coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO,
     boundary=True, line_color='red', coastline=True, nightshade=250)
plt.show()

# Magnetic Coordinates to show warning
# North Winter
_,_,ax1,ccrs1=pydarn.Fan.plot_fov(66, dt.datetime(2023, 12, 21, 0, 0), lowlat= 5,
    boundary=True, line_color='red', coastline=True, nightshade=250)

# test to plot terminator if ever required - plot not fill!
# Get antisolar point in geographic coords and radius of terminator
# at given height
date = dt.datetime(2023, 12, 21, 0, 0)
antisolarpsn, arc, ang = pydarn.terminator(date, 250)
# Convert position to magnetic coordinates
mlat, lon_mag, _ =  aacgmv2.convert_latlon(antisolarpsn[1],
                                                 antisolarpsn[0],
                                                 250,
                                                 date,
                                                 method_code='G2A')
# Shift to MLT
shifted_mlts = lon_mag - (aacgmv2.convert_mlt(lon_mag, date) * 15)
shifted_lons = lon_mag - shifted_mlts
mlon = np.radians(shifted_lons)
# Get positions at a distance from new position to plot terminator
lats = []
lons = []

for b in range(-180,180,1):
    (lat, lon) = pydarn.new_coordinate(mlat, shifted_lons, arc, b, R=pydarn.Re)
    nlon =np.radians(lon)
    lats.append(lat)
    lons.append(nlon)
lats2 = np.zeros(len(lats))
plt.plot(np.squeeze(lons), np.squeeze(lats), color='b', zorder=2.0, linewidth=6.0, linestyle='dashed')

plt.show()

[Shirling-VT]

MacOS Monterey 12.5.1
matplotlib 3.4.2
python 3.8.0
The FOV plots are working fine for me. Also tested the fan plot, it's working good in geo coord:

#Read in fitACF file
cly_file = '/Users/xueling/data/superdarn/2015/fitacf/cly/20150308.1400.03.cly.fitacf.bz2'
fitacf_data = pydarn.SuperDARNRead().read_dmap(cly_file)

# FOV plot
_, _ , ax, ccrs = pydarn.Fan.plot_fov(fitacf_data[0]['stid'], dt.datetime(2015,3,8,14,10), grid=True, fov_color='red',coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO, coastline=True, lowlat=50, nightshade=250)
plt.show()

# Fan plot with specific data in geo
_, _, ax, ccrs = pydarn.Fan.plot_fov(fitacf_data[0]['stid'], dt.datetime(2015,3,8,14,10), coastline=True, lowlat=50, coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO, nightshade=250)
pydarn.Fan.plot_fan(fitacf_data, scan_index=dt.datetime(2015,3,8,14,10), boundary=True,radar_label=True, groundscatter=True, ax=ax, colorbar=False, coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO)
plt.show()

[KhanalKrishna]

Works as aspected.
Matplotlib version: 3.5.3

import matplotlib.pyplot as plt
from datetime import datetime
import pydarn
import aacgmv2
import numpy as np

#Read in fitACF file using SuperDARDRead, then read_fitacf
file = "20130202.2001.00.inv.fitacf"
SDarn_read = pydarn.SuperDARNRead(file)
fitacf_data = SDarn_read.read_fitacf()

_, _ , ax, ccrs = pydarn.Fan.plot_fov(fitacf_data[0]['stid'], datetime(2013,2,2,20,30), grid=True, fov_color='red',coords=pydarn.Coords.GEOGRAPHIC ,projs=pydarn.Projs.GEO, coastline=True, lowlat=50, nightshade=250)
plt.show()

in magnetic coordinates

_, _ , ax, ccrs = pydarn.Fan.plot_fov(fitacf_data[0]['stid'], datetime(2013,2,2,20,30), grid=True, fov_color='red', coastline=True, lowlat=50, nightshade=250)

date = datetime(2013,2,2,20,30)
antisolarpsn, arc, ang = pydarn.terminator(date, 250)
#Convert position to magnetic coordinates
mlat, lon_mag, _ = aacgmv2.convert_latlon(antisolarpsn[1],
antisolarpsn[0],
250,
date,
method_code='G2A')
#Shift to MLT
shifted_mlts = lon_mag - (aacgmv2.convert_mlt(lon_mag, date) * 15)
shifted_lons = lon_mag - shifted_mlts
mlon = np.radians(shifted_lons)
#Get positions at a distance from new position to plot terminator
lats = []
lons = []

for b in range(-180,180,1):
(lat, lon) = pydarn.new_coordinate(mlat, shifted_lons, arc, b, R=pydarn.Re)
nlon =np.radians(lon)
lats.append(lat)
lons.append(nlon)
lats2 = np.zeros(len(lats))
plt.plot(np.squeeze(lons), np.squeeze(lats), color='b', zorder=2.0, linewidth=6.0, linestyle='dashed')

plt.show()

[hiyadutuje]

I am getting this error in the # Magnetic Coordinates to show warning:
File ~/pydarn/test/303.py:64
(lat, lon) = pydarn.new_coordinate(mlat, shifted_lons, arc, b, R=pydarn.Re).

AttributeError: module 'pydarn' has no attribute 'new_coordinate'. The OS is Ubuntu.

---

But # Geographic Coordinates work very were (see the attached files




).