Merge pull request #287 from SuperDARN/release/3.1

Release pyDARN v3.1
SuperDARN · Dec 21, 2022 · ec503d8 · ec503d8
2 parents 8299522 + 1cee5a5
commit ec503d8
Show file tree

Hide file tree

Showing 36 changed files with 1,026 additions and 366 deletions.
diff --git a/.gitignore b/.gitignore
@@ -133,3 +133,7 @@ site/
 *.iqdat
 *.hdf5
 hdw.dat* 
+
+# mac
+**/.DS_Store
+
diff --git a/.zenodo.json b/.zenodo.json
@@ -3,11 +3,6 @@
         {
             "name": "SuperDARN Data Visualization Working Group"
         },
-        {
-            "affiliation": "University of Saskatchewan",
-            "name": "Schmidt, M.T.",
-            "orcid": "0000-0002-3265-977X"
-        },
         {
             "affiliation": "University of Saskatchewan",
             "name": "Martin, C.J.",
@@ -18,42 +13,62 @@
             "name": "Shi, X.",
             "orcid": "0000-0001-8425-8241"
         },
-        {   "affiliation": "University of Scranton",
-            "name":  "Tholley, F."
-        },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Billett, D.D.",
-            "orcid": "0000-0002-8905-8609"
+            "name": "Schmidt, M.T.",
+            "orcid": "0000-0002-3265-977X"
+        },
+        {
+            "affiliation": "Lancaster University",
+            "name": "Day, E. K.",
+	    "orcid": "0000-0002-0169-6201"
         },
         {
             "affiliation": "The University Centre in Svalbard",
             "name": "Bland, E.C.",
             "orcid": "0000-0002-0252-0400"
         },
+        {
+            "affiliation": "University of Alabama",
+            "name": "Khanal, K.",
+            "orcid": "0000-0003-3927-7501" 
+        },
+        {
+            "affiliation": "University of Saskatchewan",
+            "name": "Billett, D.D.",
+            "orcid": "0000-0002-8905-8609"
+        },
         {
             "affiliation": "Virginia Tech",
-            "name": "Coyle, S.",
-            "orcid": "0000-0003-1730-2753"
+            "name": "Kunduri, B.S.R.",
+            "orcid": "0000-0002-7406-7641"
+        },
+        {   "affiliation": "University of Scranton",
+            "name":  "Tholley, F."
         },
         {
             "affiliation": "University of Scranton",
             "name":  "Frissell, N.",
             "orcid": "0000-0002-8398-4222" 
         },
+        {
+            "affiliation": "Virginia Tech",
+            "name": "Coyle, S.",
+            "orcid": "0000-0003-1730-2753"
+        },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Huyghebaert, D.",
-            "orcid": "0000-0002-4257-4235"
+            "name": "Rohel, R.A.",
+            "orcid": "0000-0003-2208-1553"
         },
         {
-            "affiliation": "University of Alabama",
-            "name": "Khanal, K.",
-            "orcid": "0000-0003-3927-7501" 
+            "affiliation": "University of Saskatchewan",
+            "name": "Kolkman, T.J.",
+            "orcid": "0000-0001-9759-9045"
         },
         {
-            "affiliation": "University of Bergen",
-            "name": "Reistad, J.P.",
-            "orcid": "0000-0003-3509-5479" 
+            "affiliation": "University of Saskatchewan",
+            "name": "Krieger, K.J.",
+            "orcid": "0000-0002-3678-4201"
         }]
 }
diff --git a/README.md b/README.md
@@ -9,13 +9,20 @@ Python data visualization library for the Super Dual Auroral Radar Network (Supe
 
 ## Changelog
 
-## Version 3.0 - Release!
+## Version 3.1 - Release!
+
+pyDARN release v3.1 includes the following features:
+- Full Cartopy coastline plotting options for all spatial plots
+  - **NEW** `coastline` keyword in method calls
+- Full Cartopy integration for plotting in geographic coordinates for grid and fan plots
+- Completed polar coordinate convection maps including reference vector and many customization options
+- Improved ACF plotting
+- New `HALF_SLANT` range estimation for RTP
+- **Bug fix** Multiple fan plots now available on one axis
+- **Bug fix** `lowlat` keyword now available for geographic coordinate plots
+- **Bug fix** Colorbars now extend/don't extend as required
+along with many other minor improvements and bug fixes!
 
-**New Requirement**: pyDARN 3.0 requires minimum matplotlib version of 3.3.4
-
-pyDARN release v3.0 includes the following features:
-- **New** optional cartopy dependency 
-- **New** convection map plotting
 
 ## Documentation
 

diff --git a/docs/imgs/acf_plot1.png b/docs/imgs/acf_plot1.png
diff --git a/docs/imgs/fov_8.png b/docs/imgs/fov_8.png
diff --git a/docs/imgs/subplots.png b/docs/imgs/subplots.png
diff --git a/docs/index.md b/docs/index.md
@@ -17,11 +17,11 @@ If you have any questions or concerns please submit an **Issue** on the SuperDAR
   - Tutorials 
     - [Reading a SuperDARN File](user/io.md)
     - [Radar and Hardware Information](user/hardware.md)
-    - [Coordinate Systems](user/coordinates.md)
+    - [Axes Setup](user/axis.md)
+    - [Ranges, Coords and Projs](user/coordinates.md)
     - [Range-Time plots](user/range_time.md)
     - [Time-Series plots](user/time_series.md)
     - [Summary plots](user/summary.md)
-    - [Axis](user/axis.md)
     - [FOV plots](user/fov.md)
     - [Fan plots](user/fan.md)
     - [Grid plots](user/grid.md)

diff --git a/docs/user/acf.md b/docs/user/acf.md
@@ -14,19 +14,19 @@ the additional permissions listed below.
 
 ### Auto-Correlation Function Plots
 
-`plot_acfs` simply plots the Auto-Correlation Function (ACF) of the imaginary and real parts in the selected RAWACF file. 
+`plot_acfs` plots the imaginary and real parts of the Auto-Correlation Function (ACF), along with the power and phase of the ACF in the selected RAWACF file. 
 
 Basic code to plot ACFs from a RAWACF file would look like:
 ```python
-import matplotlib.pyplot as plt
 import pydarn
+import matplotlib.pyplot as plt 
+from datetime import datetime
 
-
-file = "20180101.0000.01.rkn.rawacf"
-sdarn_read = pydarn.SuperDARNRead(file)
-rawacf_data = sdarn_read.read_rawacf()
-
-pydarn.ACF.plot_acfs(rawacf_data)
+reader = pydarn.SuperDARNRead("data/20140105.1208.03.rkn.rawacf")
+rawacf_data = reader.read_rawacf()
+plt.figure(figsize=(12, 7))
+pydarn.ACF.plot_acfs(rawacf_data, beam_num=7, gate_num=44,
+                start_time=datetime(2014, 1, 5, 12, 8))
 plt.show()
 ```  
 
@@ -37,19 +37,19 @@ You also have access to numerous plotting options:
 
 | Parameter              | Action                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------- |
-| beam_num=0             | beam number to plot                                                             |
-| gate_num=0             | gate number to plot                                                             |
-| parameter='acfd'       | parameter to pick between acfd or xcfd plotting                                 |
-| scan_num=0             | the scan number to plot                                                         |
+| beam_num=(int)             | beam number to plot                                                             |
+| gate_num=(int)             | gate number to plot                                                             |
+| parameter=(string)       | parameter to pick between acfd or xcfd plotting                                 |
+| scan_num=(int)             | the scan number to plot                                                         |
 | start_time=None        | plot the closest beam scan to the given start time (overrides the scan number if set) |
-| ax                     | matplotlib axes object                                                          |
-| normalized=True        | normalizes the parameter data with the associated power 0 value                 |
-| real_color='red'       | Real part of the parameter line color                                           |
-| imaginary_color='blue' | Imaginary part of the parameter line color                                      |
-| plot_blank=False       | Determine if blanked lags should be plotted                                     |
-| blank_marker='o'       | Choice of marker to indicate blanked lags are a dot (general python markers accepted)             |
-| legend=True            | plot a legend                                                                   |
-| kwargs                 | arguments passed in matplotlib line_plot for real and imaginary plots           |
+| normalized=(bool)      | normalizes the parameter data with the associated power 0 value                 |
+| real_color=(str)       | Real part of the parameter line color                                           |
+| imaginary_color=(str)  | Imaginary part of the parameter line color                                      |
+| plot_blank=(bool)        | Determine if blanked lags should be plotted                                     |
+| blank_marker=(str)       | Choice of marker to indicate blanked lags are a dot (general python markers accepted)             |
+| legend=(bool)          | plot a legend                                                                   |
+| pwr_and_phs=(bool)     | Plots subplots of power and phase of the ACF                                    |
+| kwargs**               | arguments passed in matplotlib line_plot for real and imaginary plots           |
 
 
 If blank lags are present in the data, it will look similar to the following: 
@@ -61,7 +61,7 @@ from datetime import datetime
 
 rawacf_file = '20140105.1200.03.cly.rawacf'
 rawacf_data = pydarn.SuperDARNRead(rawacf_file).read_rawacf()
-pydarn.ACF.plot_acfs(rawacf_data, beam_num=15, gate_num=16, start_time=datetime(2014, 1, 5, 13, 30))
+pydarn.ACF.plot_acfs(rawacf_data, beam_num=15, gate_num=16, start_time=datetime(2014, 1, 5, 13, 30), pwr_and_phs=False)
 plt.show()
 ```    
 

diff --git a/docs/user/axis.md b/docs/user/axis.md
@@ -1,12 +1,72 @@
-# Axis 
+# Axes Setup 
 
-For plots using geographical coordinates, a wide selection of axis representation is possible. Currently pyDARN only offers polar coordinate axis for fan, fov, and grid plots. 
+For spatial plots (FOV, Fan, Grid), pyDARN allows users to choose between Polar and
+Geographic axes using the `projs` keyword and `Projs` module.
+Convection maps do not allow for geographic projects due to lack of interest.
 
-## Polar 
+## Projs.POLAR 
 
 | Option                       | Action                                                            |
 | ---------------------------- | ----------------------------------------------------------------- |
 | lowlat=(int)                 | Lower Latitude boundary for the polar plot (degree) (default: 30) |
-| hemisphere=(pydarn.Hemisphere) | Hemisphere of the radar (default: Hemisphere.North)               |
+| hemisphere=(pydarn.Hemisphere) | Hemisphere of the radar (default: Hemisphere.North)             |
+| coastline=(bool)             | Uses Cartopy to add outlines fo the coastlines below data         |
 
 
+This choice will return an `ax` object and a value of None for `ccrs`.
+
+## Projs.GEO
+
+**REQUIRES CARTOPY INSTALLATION**
+
+| Option                       | Action                                                            |
+| ---------------------------- | ----------------------------------------------------------------- |
+| lowlat=(int)                 | Lower Latitude boundary for the polar plot (degree) (default: 30) |
+| hemisphere=(pydarn.Hemisphere) | Hemisphere of the radar (default: Hemisphere.North)             |
+| coastline=(bool)             | Uses Cartopy to add outlines fo the coastlines below data         |
+| grid_lines=(bool)            | Uses Cartopy to plot grid lines                                   |
+
+This choice will return an `ax` object and a Cartopy `ccrs` object.
+
+## Custom Axes
+pyDARN does not currently support use of custom axes to read in and plot on. This means
+that use of subplots is not supported. There are ways to get around this if a custom axis
+that has the same setup as either axes above is read into the subplot. For example, a polar
+and a geographic plots can be positioned using subplots as follows:
+
+```python
+import pydarn
+import datetime as dt
+import numpy as np
+import matplotlib.pyplot as plt 
+import cartopy.crs as ccrs
+
+# Polar plot
+date=dt.datetime(2022, 1, 8, 14, 5)
+fig = plt.figure(figsize=(6, 6)) 
+ax1 = fig.add_subplot(121, projection='polar')
+ax1.set_ylim(90, 30)
+ax1.set_yticks(np.arange(30, 90, 10))
+ax1.set_xticks([0, np.radians(45), np.radians(90), np.radians(135),
+                       np.radians(180), np.radians(225), np.radians(270),
+                       np.radians(315)])
+ax1.set_xticklabels(['00', '', '06', '', '12', '', '18', ''])
+ax1.set_theta_zero_location("S")
+pydarn.Fan.plot_fov(stid=65, date=date, ax=ax1)
+
+# Geo plot
+deg_from_midnight = (date.hour + date.minute / 60) / 24 * 360
+pole_lat = 90
+noon = -deg_from_midnight
+ylocations = -5
+proj = ccrs.Orthographic(noon, pole_lat)
+ax2 = fig.add_subplot(122, projection=proj, aspect='auto')
+ax2.gridlines(draw_labels=True)
+extent = min(45e5,(abs(proj.transform_point(noon, 30, ccrs.PlateCarree())[1])))
+ax2.set_extent(extents=(-extent, extent, -extent, extent), crs=proj)
+pydarn.Fan.plot_fov(stid=65, date=date, ax=ax2, ccrs=ccrs, coords=pydarn.Coords.GEOGRAPHIC, projs=pydarn.Projs.GEO)
+plt.tight_layout()
+plt.show()
+```
+
+![](../imgs/subplots.png)
diff --git a/docs/user/coordinates.md b/docs/user/coordinates.md
@@ -12,18 +12,23 @@ and conditions of version 3 of the GNU General Public License, supplemented by
 the additional permissions listed below.
 -->
 
-# Coordinate Systems 
+# Ranges, Coords and Projs
 ---
 
-pyDARN offers several different measurement systems for various types of plotting: 
+pyDARN uses several different measurement and plotting systems to easily allow the user to customise their plots, this page aims to describe their uses: 
 - Range Estimation: the estimate of how far the target (echo) is from the radar
-- Coordinate systems: Generic geographic coordinate system with conversions to AACGM and AACGM MLT 
+- Coordinate systems: determines the unique position using a set of points - primarily we use geographic and magnetic coordinate systems for Earth
+- Projections: used primarily on spatial plots (FOV, Fan, Grid...) projection choices allow the user to choose what type of projection the plot appears in
 
-## Range-Time Plots 
+## RangeEstimation
 
 **Range Gates**: `RangeEstimation.RANGE_GATE` a rectangle section determined by beam width and set distance for each range (nominally 45 km). RAWACF and FITACF data give their parameter values with respect to range gates. Range gates are a unit-less measure of estimating distance.
 
-**Slant Range**: `RangeEstimation.SLANT_RANGE` is a conversion from range gates to km units.  Slant range estimates the distance of ionospheric echos from the radar, using the time it takes for the radio wave to travel to the ionosphere and return, assuming the radio wave is travelling at the speed of light.
+**Slant Range**: `RangeEstimation.SLANT_RANGE` is a conversion from range gates to km units.  Slant range estimates the distance of ionospheric echos from the radar, using the time it takes for the radio wave to travel to the ionosphere and return, assuming the radio wave is travelling at the speed of light. Measured in km.
+
+**Half Slant**: `RangeEstimation.HALF_SLANT` is slant range divided by two, measured in km.
+
+**Ground Scatter Mapped Range**: `RangeEstimation.GSMR` uses echos from ground scatter to adjust slant range coordinates to be more accurate based on [Dr. Bill Bristow's paper](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/93JA01470). Implemented by Dr. Nathaniel Frissell and Francis Tholley from University of Scranton. Measured in km.
 
 !!! Note
     Slant range is calculated from the value of `frang`, the distance to the first range gate. In pyDARN, we assume 
@@ -33,25 +38,37 @@ pyDARN offers several different measurement systems for various types of plottin
     due to discussion *outside of pyDARN's remit* the value of `rxrise` is adjusted in FITACF files and may not match 
     the value given in hardware files. Currently, pyDARN has decided to use the values for `rxrise` given in the 
     hardware files. We will amend or reconsider this approach as and when a solution to the differing values is found.
+    In some plots, the user can change the `frang` value to fit their needs.
 
-**Ground Scatter Mapped Range**: `RangeEstimation.GSMR` uses echos from ground scatter to adjust slant-range coordinates to be more accurate based on [Dr. Bill Bristow's paper](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/93JA01470). Implemented by Dr. Nathaniel Frissell and Francis Tholley from University of Scranton. Measured in km.
+## Coords
 
-**Geographic Latitude** (Coming Soon)
+Used to determine the position of data in spatial plots: fan, grid and convection map plots
+Range time plots now allow for `Coords` use. The y-axis can be converted to latitude, longitude or MLT using a the `coords` keyword.
+E.G. using `coords=Coords.Geographic` and `lat_or_lon='lon'` in the method call will convert the chosen range estimate (see above) into Geographic Longitudes.
 
-**AACGM Latitude** (Coming Soon)
+**Geographic**: `Coords.GEOGRAPHIC` is the standard geographical coordinate system for latitude and longitude (degrees)
 
-## Geographic Plots
+**AACGM**: `Coords.AACGM` is [Altitude Adjusted Corrected Geogmagnetic Coordinates developed by Dr. Simon Shepherd](http://superdarn.thayer.dartmouth.edu/aacgm.html) are an extension of corrected geomagnetic (CGM) coordinates that more accurately represent the actual magnetic field. In AACGM coordinates points along a given magnetic field line are given the same coordinates and thus are a better reflection of magnetic conjugacy. pyDARN uses AACGM-V2 from the [aacgmv2 python library](https://pypi.org/project/aacgmv2/).
 
-Geographic plots include: fan, grid and convection map (coming soon) plots
+**AACGM_MLT**: `Coords.AACGM_MLT` is `Coords.AACGM` with the geomagnetic longitude converted to magnetic local time.
 
-**Geographic**: `Coords.GEOGRAPHIC` is the standard geographical coordinate system for latitude and longitude (degree) (coming soon)
+`RangeEstimation` methods can be used with a `Coords` calculation. For example, using `Coords.GEOGRAPHIC` and `RangeEstimation.GSMR` together, will give a plot of ionospheric echoes at a distance from the radar calculated in ground scatter mapped range, in geographic coordinates. 
 
-**AACGM**: `Coords.AACGM` is [Altitude Adjusted Corrected Geogmagnetic Coordinates developed by Dr. Simon Shepherd](http://superdarn.thayer.dartmouth.edu/aacgm.html) are an extension of corrected geomagnetic (CGM) coordinates that more accurately represent the actual magnetic field. In AACGM coordinates points along a given magnetic field line are given the same coordinates and thus are a better reflection of magnetic conjugacy. pyDARN uses AACGM-V2 from the [aacgmv2 python library](https://pypi.org/project/aacgmv2/). Implemented by Dr. Daniel Billett from University of Saskatchewan. 
+## Projs
 
-**AACGM_MLT**: `Coords.AACGM_MLT` is `Coords.AACGM` with the geomagnetic longitude converted to magnetic local time
+Spatial plots have two options for projections. 
 
-`RangeEstimation` methods can be used with a `Coords` calculation. For example, using `Coords.GEOGRAPHIC` and `RangeEstimation.GSMR` together, will give a plot of ionospheric echoes at a distance from the radar calculated in ground scatter mapped range, in geographic coordinates. 
+**Polar**: `Projs.POLAR` sets up the axis of the spatial plot in polar coordinates common in studies that show data over the poles.
 
-!!! Warning
-    You cannot use `RangeEstimation.RANGE_GATES` with any `Coords`, the default is `RangeEstimation.SLANT_RANGE`
+**Geographic**: `Projs.GEO` sets up the axes of the spatial plots in geographic coordinates using Cartopy.
 
+!!! Note
+    The 'look-direction' of the two projections are different for the Southern hemisphere. 
+    Polar projections show a view of the south pole as if looking down through the planet from above the north pole, 
+    geographic projections show a view of the south pole as if looking from above the south pole.
+
+!!! Note
+    Some combinations of Projs/Coords/RangeEstimates are not designed to work. 
+    For example, you cannot plot a fan plot using range gates, spatial plots require a value in kilometers. 
+    At the moment, AACGM Coordinates do not plot on Geographic projections as it has not been developed yet. 
+    Convection maps only support polar projections due to lack of interest in requiring geographic projections.