Merge pull request #253 from SuperDARN/release/v3.0

Release/v3.0
SuperDARN · Apr 20, 2022 · 101ce6c · 101ce6c
2 parents 2271791 + 7f8bc69
commit 101ce6c
Show file tree

Hide file tree

Showing 43 changed files with 2,578 additions and 839 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,4 @@
 [submodule "hdw"]
 	path = pydarn/utils/hdw
 	url = https://github.com/superdarn/hdw
+	branch = main
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,21 +1,26 @@
 {
     "creators":[
         {
-            "name": "SuperDARN Data Analysis Working Group"
+            "name": "SuperDARN Data Visualization Working Group"
         },
         {
             "affiliation": "University of Saskatchewan",
             "name": "Schmidt, M.T.",
             "orcid": "0000-0002-3265-977X"
         },
-        {   "affiliation": "University of Scranton",
-            "name":  "Tholley, F."
-        },
         {
             "affiliation": "University of Saskatchewan",
             "name": "Martin, C.J.",
             "orcid": "0000-0002-8278-9783"
         },
+        {
+            "affiliation": "Virginia Tech",
+            "name": "Shi, X.",
+            "orcid": "0000-0001-8425-8241"
+        },
+        {   "affiliation": "University of Scranton",
+            "name":  "Tholley, F."
+        },
         {
             "affiliation": "University of Saskatchewan",
             "name": "Billett, D.D.",
@@ -31,32 +36,24 @@
             "name": "Coyle, S.",
             "orcid": "0000-0003-1730-2753"
         },
-        {
-            "affiliation": "University of Saskatchewan",
-            "name": "Detwiller, M.H."
-        },
         {
             "affiliation": "University of Scranton",
             "name":  "Frissell, N.",
             "orcid": "0000-0002-8398-4222" 
         },
-        {
-            "affiliation": "The University Centre in Svalbard",
-            "name": "Herlingshaw, K.",
-            "orcid": "0000-0001-6861-1914"
-        },
         {
             "affiliation": "University of Saskatchewan",
             "name": "Huyghebaert, D.",
             "orcid": "0000-0002-4257-4235"
         },
+        {
+            "affiliation": "University of Alabama",
+            "name": "Khanal, K.",
+            "orcid": "" 
+        },
         {
             "affiliation": "University of Bergen",
             "name": "Reistad, J.P.",
             "orcid": "0000-0003-3509-5479" 
-        },
-        {
-            "affiliation": "University of Saskatchewan",
-            "name": "Roberston, C.R."
         }]
 }
diff --git a/README.md b/README.md
@@ -9,18 +9,13 @@ Python data visualization library for the Super Dual Auroral Radar Network (Supe
 
 ## Changelog
 
-## Version 2.2.1 - Release!
+## Version 3.0 - Release!
 
-**New Requirement**: pyDARN 2.2.1 requires minimum matplotlib version of 3.3.4
+**New Requirement**: pyDARN 3.0 requires minimum matplotlib version of 3.3.4
 
-pyDARN release v2.2.1 includes the following features:
-* Bug fix: fixed but in Summary plot not rendering 
-* Bug fix: fixed axes object not being properly handled in plot_fan
-* Enhancement: Added `__version__` ability in pydarn 
-* Updated: citing warning printing on `import` instead of plotting 
-* Updated: pyDARNio 1.1.0 is requirement 
-
-**Deprecation**: `slant` option in `plot_range-time` and `plot_summary` is deprecated now uses `coords` 
+pyDARN release v3.0 includes the following features:
+- **New** optional cartopy dependency 
+- **New** convection map plotting
 
 ## Documentation
 

diff --git a/docs/imgs/fan_4.png b/docs/imgs/fan_4.png
diff --git a/docs/imgs/fov_5.png b/docs/imgs/fov_5.png
diff --git a/docs/imgs/fov_6.png b/docs/imgs/fov_6.png
diff --git a/docs/imgs/fov_7.png b/docs/imgs/fov_7.png
diff --git a/docs/imgs/map_1.png b/docs/imgs/map_1.png
diff --git a/docs/imgs/map_2.png b/docs/imgs/map_2.png
diff --git a/docs/index.md b/docs/index.md
@@ -25,6 +25,7 @@ If you have any questions or concerns please submit an **Issue** on the SuperDAR
     - [FOV plots](user/fov.md)
     - [Fan plots](user/fan.md)
     - [Grid plots](user/grid.md)
+    - [Convection Map Potential plots](user/map.md)
     - [Power plots](user/power.md)
     - [ACF plotting](user/acf.md)
     - [Logging](user/logging.md)

diff --git a/docs/user/coordinates.md b/docs/user/coordinates.md
@@ -15,13 +15,15 @@ the additional permissions listed below.
 # Coordinate Systems 
 ---
 
-pyDARN offers several different coordinate systems and units for plotting: 
+pyDARN offers several different measurement systems for various types of plotting: 
+- 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 
 
 ## Range-Time Plots 
 
-**Range Gates**: `Coords.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.
+**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**: `Coords.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.
 
 !!! Note
     Slant range is calculated from the value of `frang`, the distance to the first range gate. In pyDARN, we assume 
@@ -32,7 +34,7 @@ pyDARN offers several different coordinate systems and units for plotting:
     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.
 
-**Ground Scatter Mapped Range**: `Coords.GROUND_SCATTER_MAPPED_RANGE` 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.
+**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.
 
 **Geographic Latitude** (Coming Soon)
 
@@ -46,6 +48,10 @@ Geographic plots include: fan, grid and convection map (coming soon) 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/). Implemented by Dr. Daniel Billett from University of Saskatchewan. 
 
-**Ground Scatter Mapped Geographic** (Coming Soon)
+**AACGM_MLT**: `Coords.AACGM_MLT` is `Coords.AACGM` with the geomagnetic longitude converted to magnetic local time
+
+`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. 
+
+!!! Warning
+    You cannot use `RangeEstimation.RANGE_GATES` with any `Coords`, the default is `RangeEstimation.SLANT_RANGE`
 
-**Ground Scatter Mapped Geomagnetic** (Coming Soon)
diff --git a/docs/user/fan.md b/docs/user/fan.md
@@ -18,10 +18,13 @@ the additional permissions listed below.
 
 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 are projected onto a polar format plot in [AACGMv2](http://superdarn.thayer.dartmouth.edu/aacgm.html) coordinates.
+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](http://superdarn.thayer.dartmouth.edu/aacgm.html) coordinates, or projected onto a geographic plot in geographic coordinates.
 
-Currently, fan plots in pyDARN get the geographic positions of a radar's range gates by reading in pre-generated files (found in the `/pydarn/radar_fov_files` folder), and then [converts](https://pypi.org/project/aacgmv2/) them to AACGMv2 coordinates. In the future, pyDARN will generate the geographical position, which will bring support for not standard range/beam layouts.
-The mapping of the range gate corners was based on [rbpos in RST](https://github.com/SuperDARN/rst/blob/0aa1fffed4cc48c1eb6372dfc9effa688af95624/codebase/superdarn/src.idl/lib/legacy.1.6/rbposlib.pro).
+!!! Warning 
+    At present, AACGM coordinates cannot be plotted on a geographic projection.
+
+
+The mapping of the range gate corners was based on [rbpos in RST](https://github.com/SuperDARN/rst/blob/0aa1fffed4cc48c1eb6372dfc9effa688af95624/codebase/superdarn/src.idl/lib/legacy.1.6/rbposlib.pro) that is coded in `/pydarn/geo.py`. To get the coordinates read [hardware docs](hardware.md).
 
 ### Basic usage
 pyDARN and pyplot need to be imported, as well as any FITACF file needs to be [read in](https://pydarn.readthedocs.io/en/latest/user/SDarnRead/):
@@ -56,17 +59,21 @@ pydarn.Fan.plot_fan(cly_data, scan_index=datetime(2015, 3, 8, 15, 26),
 !!! Warning
     Do not include seconds, typically scans are 1 minute long so seconds may end in a error with no data. 
 
-Default plots also do not show groundscatter as grey. Set it to true to colour groundscatter this way:
+Default plots also do not show groundscatter as grey. Set it to true to colour groundscatter:
+
 ```python
-fanplot = pydarn.Fan.plot_fan(fitacf_data, scan_index=27, groundscatter=1)
+fanplot = pydarn.Fan.plot_fan(fitacf_data,
+                              scan_index=27,
+                              groundscatter=True)
 plt.show()
 
 ```
 ![](../imgs/fan_2.png)
 
 You might have noticed that the variable `fanplot` in the examples above actually holds some information. This contains the AACGM latitude and longitude of the fan just plotted, as well as the data, ground scatter information, and datetime object. If you instead change `fanplot` to 5 separate variables, it will return the latitude, longitude, data, groundscatter and datetime info into seperate variables:
 ```python
-lats,lons,data,grndsct,datetime=pydarn.Fan.plot_fan(fitacf_data, scan_index=27)
+ax, lats, lons, data, grndsct, datetime = pydarn.Fan.plot_fan(fitacf_data,
+                                                              scan_index=27)
 
 lats.shape
 
@@ -90,21 +97,21 @@ 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=matplotlib.cm            | A matplotlib color map object. Will override the pyDARN defaults for chosen parameter                   |
+| cmap=string                   | A matplotlib color map string                                                                           |
 | 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)                                      |
-| fov_color=(string)            | Sets the fill in color for the fov plot (default: transparency)                                         |
-| line_color=(string)           | Sets the boundary line and radar location dot color (default: black)                                    |
-| alpha=(int)                   | Sets the transparency of the fill color (default: 0.5)                                                  |
-| radar_location=(bool)         | Places a dot in the plot representing the radar location (default: True)                                |
-| radar_label=(bool)            | Places the radar 3-letter abbreviation next to the radar location                                       |
+| coords=(Coords)               | [Coordinates](coordinates.md) for the data to be plotted in                                             |
+| projs=(Projs)                 | Projections to plot the data on top of                                                                  |
 | kwargs **                     | Axis Polar settings. See [polar axis](axis.md)                                                          |
 
 
@@ -139,3 +146,16 @@ plt.show()
 ```
 
 ![](../imgs/fan_3.png)
+
+Using *cartopy* to plot underlaid coastline map:
+
+!!! Warning
+    The *cartopy* coastlines mapping feature is currently only available for geographic projections in geographic coordinates. Expansion of this feature is coming soon!
+
+```python
+ax, _, _, _, _ = 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")
+ax.coastlines()
+plt.show()
+``` 
+
+![](../imgs/fan_4.png)
diff --git a/docs/user/fov.md b/docs/user/fov.md
@@ -1,3 +1,18 @@
+<!--Copyright (C) SuperDARN Canada, University of Saskatchewan 
+Author(s): Marina Schmidt 
+Modifications:
+2022-03-31 MTS updating documentation with the new coordinate/cartopy system 
+
+Disclaimer:
+pyDARN is under the LGPL v3 license found in the root directory LICENSE.md 
+Everyone is permitted to copy and distribute verbatim copies of this license 
+document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the terms
+and conditions of version 3 of the GNU General Public License, supplemented by
+the additional permissions listed below.
+-->
+
 # Field Of View Plots
 ---
 
@@ -14,10 +29,7 @@ plt.show()
 
 ![](../imgs/fov_1.png)
 
-A `datetime` object of the date is required to convert to AACGM MLT coordinates (see [coordinates](coordinates.md)). 
-
-!!! Note
-    This will not be required for other coordinates once implemented. 
+A `datetime` object of the date is required to convert to `Coords.AACGM_MLT` (default) or `Coords.AACGM`.   
 
 ### Additional options
 
@@ -26,9 +38,15 @@ Here is a list of all the current options than can be used with `plot_fov`
 | Option                  | Action                                                                                                  |
 | ----------------------- | ------------------------------------------------------------------------------------------------------- |
 | stid=(int)              | Station id of the radar. Can be found using [SuperDARNRadars](hardware.md)                              |
-| date=(datetime)         | `datetime` object to determine the position the radar fov is in MLT
+| date=(datetime)         | `datetime` object to determine the position the radar fov AACGM or AACGM MLT coordinates                |
 | ranges=(list)           | Two element list giving the lower and upper ranges to plot, grabs ranges from hardware file (default [] |
-| colorbar=(bool)             | Set true to plot a colorbar (default: True)                                                                      |
+| ccrs=(object)           | Cartopy axes object for plotting using Cartopy                                                          |
+| rsep=(int)              | Range Seperation (km) (default: 45 km)                                                                  |
+| frang=(int)             | Frequency Range (km) (default: 180 km)                                                                  |
+| projs=(Projs)           | Projection for the plot to be plotted on Polar and Geographic (GEO) (default: Projs.POLAR)              |
+| coords=(Coords)         | Coorindates Geographic, AACGM, or AACGM MLT (default: Coords.AACGM_MLT)                                 |
+| grid=(bool)             | Boolean to apply the grid lay of the FOV (default: False )                                              |
+| colorbar=(bool)         | Set true to plot a colorbar (default: True)                                                             |
 | colorbar_label=(string) | Label for the colour bar (requires colorbar to be true)                                                 |
 | boundary=(bool)         | Set false to not show the outline of the radar FOV (default: True)                                      |
 | grid=(bool)             | Set true to show the outline of the range gates inside the FOV (default: False)                         |
@@ -74,6 +92,25 @@ plt.show()
 
 ![](../imgs/fov_3.png)
 
+
+This example shows the use of *cartopy* and plotting in geographic coordinates. 
+
+```python
+_ , _, ax, ccrs = pydarn.Fan.plot_fov(stid=65,
+                                      date=dt.datetime(2022, 1, 8, 14, 5),
+                                      fov_color='red',
+                                      coords=pydarn.Coords.GEOGRAPHIC,
+                                      projs=pydarn.Projs.GEO)
+ax.coastlines()
+plt.show()
+```
+
+![](../imgs/fov_7.png)
+
+!!! Warning
+    Currently you cannot plot AACGM coordinates on a geographic plot as its not correctly transformed. Currently in development. 
+
+
 `plot_fov` use two other plotting methods `plot_radar_position` and `plot_radar_label`, these methods have the following parameters: 
 
 | Option              | Action                                                                     |
@@ -95,4 +132,6 @@ pydarn.Fan.plot_fov(66, datetime(2021, 2, 5, 12, 5), boundary=False,
 ![](../imgs/fov_4.png)
 
 !!! Note
-    The radar labels will appear at the same longitude, but at -5 degrees of latitude to the position of the radar station. This may cause some to overlap. Users can plot their own labels using `plt.text(*lon psn in radians*, *lat psn in degrees*, *text string*)` 
+    The radar labels will appear at the same longitude, but at -5 degrees of latitude to the position of the radar station. This may cause some to overlap. Users can plot their own labels using `plt.text(*lon psn in radians*, *lat psn in degrees*, *text string*)`
+
+