Fan plots

---

Fan plots are a way to visualise data from the entire scan of a SuperDARN radar.

All beams and ranges for a given parameter (such as line-of-sight velocity, backscatter power, etc) and a particular scan can be projected onto a polar format plot in AACGMv2 coordinates, or projected onto a geographic plot in geographic coordinates.

The mapping of the range gate corners was based on rbpos in RST that is coded in /pydarn/geo.py. To get the coordinates read hardware docs.

Basic usage

pyDARN and pyplot need to be imported, as well as any FITACF file needs to be read in:

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

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

With the FITACF data loaded as a list of dictionaries (fitacf_data variable in above example), you may now call the plot_fan method. Make sure you tell it which scan (numbered from first recorded scan in file, counting from 1 or give it a datetime object for the scan at that time) you want using scan_index:

fan_rtn = pydarn.Fan.plot_fan(fitacf_data, scan_index=27, 
                              colorbar_label='Velocity [m/s]')
plt.show()

In this example, the 27th scan was plotted with the defaulted parameter being line-of-sight velocity:

You can also provide a datetime object to obtain a scan at a specific time:

pydarn.Fan.plot_fan(fitacf_data, scan_index=datetime(2015, 3, 8, 15, 26),
                     colorbar_label='Velocity [m/s]')
plt.show()

Default plots also do not show groundscatter as grey. Set it to true to colour groundscatter:

fan_rtn = pydarn.Fan.plot_fan(fitacf_data,
                              scan_index=27,
                              groundscatter=True)
plt.show()

You might have noticed that the variable fan_rtn in the examples above actually holds some information. This return value is a dictionary containing data in the plot, ax and ccrs values along with color map and color bar information:

fan_rtn = pydarn.Fan.plot_fan(fitacf_data, scan_index=27)

print(fan_rtn.keys())

>>> dict_keys(['ax', 'ccrs', 'cm', 'cb', 'fig', 'data'])

Parameters Available for Plotting

In addition to line-of-sight velocity, you can choose one of three other data products to plot by setting parameter=String name:

Data product	String name
Line of sight velocity (m/s) [Default]	'v'
Spectral width (m/s)	'w_l'
Elevation angle (degrees)	'elv'
Power (dB)	'p_l'

Ball and Stick Plots

Data on fan plots can also be displayed as a 'ball and stick' plot, where each data point is represented by a ball with a stick showing direction towards or away from the radar, coloured by the magnitude of the parameter plotted. Ball and stick plots can be plotted usng the ball_and_stick with len_factor key words, as follows:

pydarn.Fan.plot_fan(fitacf_data,
                    scan_index=1, lowlat=60, zmin=-1000, zmax=1000,
                    boundary=True, radar_label=True,
                    groundscatter=True, ball_and_stick=True, len_factor=300,
                    coastline=True, parameter="v")
plt.show()

Additional Options

Here is a list of all the current options than can be used with plot_fan

Option	Action
ax=(Axes Object)	Matplotlib axes object than can be used for cartopy additions
scan_index=(int or datetime)	Scan number or datetime, from start of records in file corresponding to channel if given
channel=(int or 'all')	Specify channel number or choose 'all' (default = 'all')
parameter=(string)	See above table for options
groundscatter=(bool)	True or false to showing ground scatter as grey
ranges=(list)	Two element list giving the lower and upper ranges to plot, grabs ranges from hardware file (default []
cmap=string	A matplotlib color map string
grid=(bool)	Boolean to apply the grid lay of the FOV (default: False )
zmin=(int)	Minimum data value for colouring
zmax=(int)	Maximum data value for colouring
colorbar=(bool)	Set true to plot a colorbar (default: True)
colorbar_label=(string)	Label for the colour bar (requires colorbar to be true)
title=(string)	Title for the fan plot, default auto generated one based on input information
boundary=(bool)	Set false to not show the outline of the radar FOV (default: True)
coords=(Coords)	Coordinates for the data to be plotted in
projs=(Projs)	Projections to plot the data on top of
colorbar_label=(string)	Label that appears next to the color bar, requires colorbar to be True
coastline=(bool)	Plots outlines of coastlines below data (Uses Cartopy)
beam=(int)	Only plots data/outline of specified beam (default: None)
kwargs **	Axis Polar settings. See polar axis

plot_fan can concatenate with itself in both polar and geographic projection, here is an example of plotting two different radars with some of the above parameters, remember to pass in the axes object (ax) to any subsequent plots, unlike the FOV plots, fan plots will automatically control the ccrs variable for you:

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

cly_file = 'data/20150308.1400.03.cly.fitacf'
pyk_file = 'data/20150308.1401.00.pyk.fitacf'

pyk_data = pydarn.SuperDARNRead().read_dmap(pyk_file)
cly_data = pydarn.SuperDARNRead().read_dmap(cly_file)

fan_rtn = pydarn.Fan.plot_fan(cly_data, scan_index=datetime(2015, 3, 8, 14, 4),
                    colorbar=False, fov_color='grey', line_color='blue',
                    radar_label=True)

pydarn.Fan.plot_fan(pyk_data, scan_index=datetime(2015, 3, 8, 14, 4), 
                    colorbar_label='Velocity [m/s]', fov_color='grey',
                    line_color='red', radar_label=True, ax=fan_rtn['ax'])

plt.show()

Using cartopy to plot underlaid coastline map using the coastline keyword, this example also shows the use of plotting in geographic coordinates:

pydarn.Fan.plot_fan(data, scan_index=5, radar_label=True,
                    groundscatter=True,
                    coords=pydarn.Coords.GEOGRAPHIC,
                    projs=pydarn.Projs.GEO,
                    colorbar_label="Velocity m/s",
                    coastline=True)
plt.show()