EHN: Standard Plot Return Values

[carleyjmartin]

Scope

This pull request makes each plotting function return a dictionary with standard return values. For each plotting function a dictionary with the following keys will be returned:

return {'ax': ax, # axes
    'ccrs': ccrs, # cartopy projection
    'cm': cmap, # colormaps
    'cb': cb, # color bar
    'fig': plt.gcf(), # figure
    'data': {'beam_corners_lats': beam_corners_lats,
        'beam_corners_lons': beam_corners_lons,
        'scan_data': scan,
        'ground_scatter': grndsct}
    }

This is an example of the return values for plot_fan, this allows the user to use a return dictionary much easier, knowing where 'ax' is to overpot features and being able to add extra data if they like. This makes it easier than the current system when trying to plot multipl fov plots and things like that, you don't have to automatically know which return value in the list is the axes. The data section will be different for each plot, but you can easily see the different keys by return_value['data'].keys() and choose which values you want. If a return value doesn't exist, like ccrs in range time plots, it is given as None.

These were all the return values we generally used, let me know if there is something that you might also like to have in this list.

issue: No issue

Approval

Number of approvals: 2 at least

Test

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

This is a change to every plotting function so please throw whatever plotting code you have at it, lots of different keyword combos. But make sure that you are amending any return values from the original. E.G:

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

stids = [209,208,33,207,206,66,205,204,1,10,40,41,64,50,3,16,7,90,9,6,65,5,8,32]
plt.figure(figsize=(8, 8))
rtn=pydarn.Fan.plot_fov(stids[0], datetime(2021, 2, 5, 12, 5),
                        fov_color= 'grey',radar_location=True,
                        radar_label=True, coastline=True,
                        coords=pydarn.Coords.GEOGRAPHIC,
                        projs=pydarn.Projs.GEO)
print(rtn.keys())

for stid in stids[1:-1]:
    rtn=pydarn.Fan.plot_fov(stid, datetime(2021, 2, 5, 12, 5), ax=rtn['ax'],
                            ccrs=rtn['ccrs'], fov_color= 'grey',
                            radar_location=True, radar_label=True,
                            coastline=True,
                            coords=pydarn.Coords.GEOGRAPHIC,
                            projs=pydarn.Projs.GEO)
plt.show()

NOTE: THIS WILL NEED TO ALSO BE DONE FOR CURRENT PRS THAT ARE NOT MERGED INTO DEVELOP FOR NEW PLOTTING FUNCTIONS

[KhanalKrishna]

Matplotlib version: 3.8.0
Tested for fan and map plots. Looks good.

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

#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()
fan_return_values = pydarn.Fan.plot_fan(fitacf_data, scan_index=27,
colorbar_label='Velocity [m/s]')
plt.show()
print(fan_return_values.keys())
print(fan_return_values['data']['beam_corners_lats'])

#Read map file
file = "20150419.north.map2"
SDarn_read = pydarn.SuperDARNRead(file)
map_data = SDarn_read.read_map()
map_return_values = pydarn.Maps.plot_mapdata(map_data, record=150)
map_return_values['ax'].set_title('My Own Title')
plt.show()
print(map_return_values.keys())

[Shirling-VT]

@carleyjmartin Can we also return the cross polar cap potential (cpcp), number of vectors, fitting model and order for the map plot? These are information showed at the bottom left of the convection map which I think lots of people are interested in, particularly the cpcp and number of vector parameters. I guess the reason None is returned for the data key in the power.py plot is probably because it's a bit complicated to return multiple plotted parameters/panels? Just finished the code review and haven't tested anything yet, will do that in the next day or two.

[carleyjmartin]

@Shirling-VT
All added in now!

I don't know why I returned None for the stats power plots: it was likely I looked at the code and decided that I didn't know what was happening in there at the time.