NEW: Map Potential Time Series at Given MLON/MLAT

[carleyjmartin]

Scope

This PR includes the addition of a time series plot option for plotting the potential calculated at a specific mlon, mlat in a map potential.

issue: to close #368

Approval

Number of approvals: 2

Test

matplotlib version: 3.9.1

NOTE THERE IS A NUMPY BUG IN PYDARNIO, DOWNGRADE NUMPY TO 1.26.4 OR BELOW, PLEASE TEST IN A VIRTUAL ENVIRONMENT. This is out of scope for pyDARN and will be fixed in pyDARNio later.

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

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

mapfile = '/Users/carley/Documents/data/maps/20220101.n.map'

SDarn_read = pydarn.SuperDARNRead(mapfile)
map_data = SDarn_read.read_map()

# Coordinates of interest, as mlat/mlon pairs. 
#This example keeps mlon the same but changes mlat, like a keogram
mlats = 75
mlons = 110

# Map parameters from the mapfile, first record
fit_coefficient = map_data[0]['N+2']
fit_order = map_data[0]['fit.order']
lat_shift = map_data[0]['lat.shft']
lon_shift = map_data[0]['lon.shft']
lat_min = map_data[0]['latmin']
hemisphere = pydarn.Hemisphere(map_data[0]['hemisphere'])

# Get the potential for my coordinates
pots = pydarn.Maps.calculate_potentials_pos(mlats, mlons, fit_coefficient,
                                            lat_min, lat_shift, lon_shift,
                                            fit_order, hemisphere)

print(pots)

# Test plotting
pydarn.Maps.plot_time_series(map_data,
                         parameter = pydarn.TimeSeriesParams.POT,
                         start_time = dt.datetime(2022,1,1,0,0),
                         end_time = dt.datetime(2022,1,1,6,0),
                         potential_position = [mlons, mlats])
plt.show()

# Test warning messages
pydarn.Maps.plot_time_series(map_data,
                         parameter = pydarn.TimeSeriesParams.POT,
                         start_time = dt.datetime(2022,1,1,0,0),
                         end_time = dt.datetime(2022,1,1,6,0),
                         potential_position = [])
plt.show()
pydarn.Maps.plot_time_series(map_data,
                         parameter = pydarn.TimeSeriesParams.POT,
                         start_time = dt.datetime(2022,1,1,0,0),
                         end_time = dt.datetime(2022,1,1,6,0),
                         potential_position = [-10000, 6])
plt.show()

# Test fix for partial records
pydarn.Maps.plot_time_series(map_data,
                             parameter=pydarn.TimeSeriesParams.NUM_VECTORS,
                             start_record=0, end_record=100)
plt.show()

You should get two plots:

and a console output of:

[13.60432699]
/Users/carley/Documents/testing/venv-map-pot-time-series/lib/python3.9/site-packages/pydarn/plotting/maps.py: 1390: UserWarning: A valid magnetic position with format [mlon, mlat] is required to plot the potential at a given location. E.G. potential_position = [-110, 78]
/Users/carley/Documents/testing/venv-map-pot-time-series/lib/python3.9/site-packages/pydarn/plotting/maps.py: 1399: UserWarning: A valid magnetic position with format [mlon, mlat] is required to plot the potential at a given location. E.G. potential_position = [-110, 78]

[PrestonXPitzer]

Should this be working for mapex or map2 files? NUM_VECTORS is working for me when I use map2 data but the potential plot is blank (might be a data issue).

[carleyjmartin]

Should this be working for mapex or map2 files? NUM_VECTORS is working for me when I use map2 data but the potential plot is blank (might be a data issue).

I'm not sure, it should work for map2 files as I use them too, but I've never used or tested (or heard of) mapx files, but they should all be of the same format. There was a quick bug that I tried to fix where if the first record was a partial record and didn't have any vector fields then it broke, but now it just doesn't plot that record, it could be that the vector.mlat value or the values needed to calculate potential aren't in those files/ called something else? But I think they should all be of the same format and field names if they're in use in the community. Could you email me or zip up a mapx file to check out on here?

[Doreban]

Tested with the provided test code and data on Windows 10 with matplotlib 3.9.1

Testing an empty or incorrect potential_position both returned the following user warning: `UserWarning: A valid magnetic position with format [mlon, mlat] is required to plot the potential at a given location. E.G. potential_position = [-110, 78]'

Plots that were made look like the ones expected. I didn't play around with it much since I don't have an eye for this data and what it should look like.