Merge pull request #358 from SuperDARN/release/4.0

RELEASE: pyDARN Version 4.0!
SuperDARN · Jan 2, 2024 · 3c70fb8 · 3c70fb8
2 parents 19f903b + c5cd8d2
commit 3c70fb8
Show file tree

Hide file tree

Showing 61 changed files with 16,040 additions and 878 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+# sphinx:
+#   configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#   - requirements: docs/requirements.txt
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,5 +1,5 @@
 {
-    "creators":[
+    "creators": [
         {
             "name": "SuperDARN Data Visualization Working Group"
         },
@@ -8,67 +8,72 @@
             "name": "Martin, C.J.",
             "orcid": "0000-0002-8278-9783"
         },
-        {
-            "affiliation": "Virginia Tech",
-            "name": "Shi, X.",
-            "orcid": "0000-0001-8425-8241"
-        },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Schmidt, M.T.",
-            "orcid": "0000-0002-3265-977X"
+            "name": "Rohel, R.A.",
+            "orcid": "0000-0003-2208-1553"
         },
         {
-            "affiliation": "Lancaster University",
-            "name": "Day, E. K.",
-	    "orcid": "0000-0002-0169-6201"
+            "affiliation": "Virginia Tech",
+            "name": "Kunduri, B.S.R.",
+            "orcid": "0000-0002-7406-7641"
         },
         {
-            "affiliation": "The University Centre in Svalbard",
-            "name": "Bland, E.C.",
-            "orcid": "0000-0002-0252-0400"
+            "affiliation": "Virginia Tech",
+            "name": "Pitzer, P."
         },
         {
             "affiliation": "University of Alabama",
             "name": "Khanal, K.",
-            "orcid": "0000-0003-3927-7501" 
+            "orcid": "0000-0003-3927-7501"
         },
         {
-            "affiliation": "University of Saskatchewan",
-            "name": "Billett, D.D.",
-            "orcid": "0000-0002-8905-8609"
+            "affiliation": "Virginia Tech",
+            "name": "Shi, X.",
+            "orcid": "0000-0001-8425-8241"
+        },
+        {
+            "affiliation": "University of Scranton",
+            "name": "Frissell, N.",
+            "orcid": "0000-0002-8398-4222"
+        },
+        {
+            "affiliation": "SANSA",
+            "name": "Hiyadutuje, A.",
+            "orcid": "0000-0002-3391-8737"
         },
         {
             "affiliation": "Virginia Tech",
-            "name": "Kunduri, B.S.R.",
-            "orcid": "0000-0002-7406-7641"
+            "name": "Chakraborty, S.",
+            "orcid": "0000-0001-6792-0037"
         },
-        {   "affiliation": "University of Scranton",
-            "name":  "Tholley, F."
+        {
+            "affiliation": "Dartmouth College",
+            "name": "Thomas, E. G.",
+            "orcid": "0000-0001-8036-8793"
         },
         {
-            "affiliation": "University of Scranton",
-            "name":  "Frissell, N.",
-            "orcid": "0000-0002-8398-4222" 
+            "affiliation": "University of Newcastle",
+            "name": "Waters, C. L.",
+            "orcid": "0000-0003-2121-6962"
         },
         {
-            "affiliation": "Virginia Tech",
-            "name": "Coyle, S.",
-            "orcid": "0000-0003-1730-2753"
+            "affiliation": "University of Saskatchewan",
+            "name": "Billett, D.D.",
+            "orcid": "0000-0002-8905-8609"
         },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Rohel, R.A.",
-            "orcid": "0000-0003-2208-1553"
+            "name": "Galeshuck, D."
         },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Kolkman, T.J.",
-            "orcid": "0000-0001-9759-9045"
+            "name": "Detwiller, M."
         },
         {
             "affiliation": "University of Saskatchewan",
-            "name": "Krieger, K.J.",
-            "orcid": "0000-0002-3678-4201"
-        }]
-}
+            "name": "Schmidt, M.T.",
+            "orcid": "0000-0002-3265-977X"
+        }
+    ]
+}
diff --git a/README.md b/README.md
@@ -9,23 +9,24 @@ Python data visualization library for the Super Dual Auroral Radar Network (Supe
 
 ## Changelog
 
-## Version 3.1.1 - Patch Release!
-
-This patch release includes:
-- **Bug fix** `hdw` repository installation issues resolved
-- Inclusion of ICE and ICW in `hdw` repository and superdarn_radars module
-
-Most recent minor release (3.1.0) changes listed below:
-- 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!
+## Version 4.0 - Major Release!
+
+This major release includes: 
+- **NEW** IQ level data plotting
+- **NEW** Latitude and longitude y-axis in RTP
+- **NEW** Ball and stick plots
+- **NEW** Map file variable time series plotting
+- **NEW** Terminator plotting
+- Coastlines available in magnetic coordinate spatial plots without Cartopy
+- More flexibility in fan plots - single beams/ range gate range options
+- TDiff correction for elevation data available
+- Boxcar filtering available for data before plotting
+- Corrections to geolocation algorithms
+- Standardized plot return values across all plots
+- **Bug fix** Radar position labels no longer overlap
+- **Bug fix** Warning use refactored
+- **Bug fix** Multiple bug fixes for data handling and plotting in grid plots
+- **Bug fix** Multiple bug fixes for the aesthetics of convection maps
 
 
 ## Documentation
@@ -61,7 +62,9 @@ plt.show()
 
 [summary plot](docs/imgs/summary_clyb2.png)
 
-For more information and tutorials on pyDARN please see the [tutorial section](https://pydarn.readthedocs.io/en/latest/index.html)
+For more information and tutorials on pyDARN please see the [tutorial section](https://pydarn.readthedocs.io/en/latest/index.html).
+
+We also have a [Jupyter notebook](https://zenodo.org/record/7005203) with many examples to support our recent [publication](https://doi.org/10.3389/fspas.2022.1022690).
 
 ## Getting involved
 

diff --git a/docs/dev/developing.md b/docs/dev/developing.md
@@ -0,0 +1,70 @@
+<!--Copyright (C) 2023 SuperDARN Canada, University of Saskatchewan 
+Author(s): Carley Martin 
+Modifications:
+
+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.
+-->
+
+# Quick Guide to Developing
+
+Once you have decided on an issue that you would like to develop, or have decided to develop your own feature, you can follow the rough guidelines below to develop your feature.
+Each developer has different preferences on how they develop, text editors, OS and style. All are valid and you can use whatever method you wish to achieve the development of a new feature. Below is a quick run-through of how I (Carley) develop a new feature using a basic text editor and command line directly as a branch of the main repository.
+It is not required, but probably useful if you have a relatively good knowledge and some experience of writing code in python - however, any style or efficiency issues can be picked up by the testers and fixed then!
+
+Firstly, if you don't have the repository cloned, find a suitable location where you would like the repo and clone:
+```
+git clone https://github.com/SuperDARN/pydarn.git
+```
+The default branch is `develop` so your repository will already be showing the development branch. If you have the repository clones already, make sure to pull any new changes to the develop branch:
+```
+cd pydarn
+git pull origin develop
+```
+Now, we want to make a new 'branch' of the repository where only the changes you are making will be present and it won't interfere with anyone else developing. 
+```
+git checkout -b ehn/new-feature-name
+```
+This command will create a new branch with the name 'ehn/new-feature-name' and move to that new branch.
+
+You can now change any code in the new branch and it will not effect the development branch. You can add a whole new module - make sure you add anything you wish to call using pyDARN to the `__init__.py` file.
+
+I suggest that you install and run the code frequently during development to check that everything is running as expected.
+To do this make a virtual environment, install the branch of pyDARN and run some testing code you have developed. 
+```
+python3 -m virtualenv (or venv if 3.10+) venv-feature-name
+source venv-feature-name/bin/activate
+cd pydarn (make sure you are in the pydarn git repository)
+pip3 install .
+python3 your_testing_code.py
+```
+
+!!! Note
+    If repeatedly testing, make sure to uninstall pydarn before reinstalling to pick up the changes.
+    `pip3 uninstall pydarn`
+
+If you wish to push finished or partially finished code to the repository on GitHub so others can see and test:
+```
+git status
+git add .
+git commit -m 'commint message here - what did you change, what's new ect.'
+git push origin ehn/new-feature-branch
+```
+
+You can then continue developing, or if you have completed the feature, make a [pull request](dev/PR.md)!
+
+# Tips to Keep in Mind
+
+ - If making a whole new module, read up on how to structure and have the module accessible to the rest of the code: [library structure](https://docs.python-guide.org/writing/structure/)
+ - Make a short piece of code that tests your feature - this is helpful for you to test as you develop but also helpful to show testers how they can use your new feature.
+ - Make sure that the code does not interfere with, change or break another part of the code base - this means you need to test anything peripheral to the code you have added too.
+ - Write up some documentation! Documentation can be found in the docs directory and is written in markdown.
+ - [Kwargs](https://realpython.com/python-kwargs-and-args/) - very useful to pass keyword arguments through various methods.
+ - [Enum](https://realpython.com/python-kwargs-and-args/) is extremely helpful for when a keyword has multiple options to choose from (not just True, False).
+ - pyDARN has implemented a standard return dictionary, so make sure that if you develop a new plot that you format your plot return the same as all others.
diff --git a/docs/imgs/CTP_1.png b/docs/imgs/CTP_1.png
diff --git a/docs/imgs/ball_and_stick.png b/docs/imgs/ball_and_stick.png
diff --git a/docs/imgs/ctp_equator.png b/docs/imgs/ctp_equator.png
diff --git a/docs/imgs/ctp_pole.png b/docs/imgs/ctp_pole.png
diff --git a/docs/imgs/filtered.png b/docs/imgs/filtered.png
diff --git a/docs/imgs/iq1.png b/docs/imgs/iq1.png
diff --git a/docs/imgs/iq2.png b/docs/imgs/iq2.png
diff --git a/docs/imgs/iq3.png b/docs/imgs/iq3.png
diff --git a/docs/imgs/iq4.png b/docs/imgs/iq4.png
diff --git a/docs/imgs/map_ts.png b/docs/imgs/map_ts.png
diff --git a/docs/imgs/unfiltered.png b/docs/imgs/unfiltered.png
diff --git a/docs/index.md b/docs/index.md
@@ -22,6 +22,7 @@ If you have any questions or concerns please submit an **Issue** on the SuperDAR
     - [Axes Setup](user/axis.md)
     - [Ranges, Coords and Projs](user/coordinates.md)
     - [Range-Time plots](user/range_time.md)
+    - [Coordinate-Time plots](user/coord_time.md)
     - [Time-Series plots](user/time_series.md)
     - [Summary plots](user/summary.md)
     - [FOV plots](user/fov.md)
@@ -30,14 +31,16 @@ If you have any questions or concerns please submit an **Issue** on the SuperDAR
     - [Convection Map Potential plots](user/map.md)
     - [Power plots](user/power.md)
     - [ACF plotting](user/acf.md)
+    - [IQ Plotting](user/iq.md)
+    - [Filtering data](user/filters.md)
     - [Logging](user/logging.md)
  - [pyDARN Team](dev/team.md)
     - [Communication Guidelines](dev/communication.md)
     - [Copyrighting and Licensing](dev/copyright_license.md)
     - Workflow
-        - [Projects](dev/projects.md)
         - [Issues](dev/issues.md)
         - [Branches](dev/branching.md)
+        - [Developing](dev/developing.md)
         - [Unit Testing](dev/pytest.md)
         - [Pull Requests](dev/PR.md) 
         - [Testing](dev/testing.md)

diff --git a/docs/user/axis.md b/docs/user/axis.md
@@ -1,32 +1,34 @@
 # Axes Setup 
 
-For spatial plots (FOV, Fan, Grid), pyDARN allows users to choose between Polar and
+For some 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.
+Convection maps do not allow for geographic projections due to lack of interest.
 
 ## 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)             |
-| coastline=(bool)             | Uses Cartopy to add outlines fo the coastlines below data         |
+| 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 to the coastlines below data                           |
+| nightshade=(int)               | Uses the value given to calculate and show where on the plot the Earth is in shadow |
 
 
-This choice will return an `ax` object and a value of None for `ccrs`.
+This choice will return an `ax` object and a value of None for the Cartopy `ccrs` (coordinate reference system).
 
 ## 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                                   |
+| 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                                                     |
+| nightshade=(int)               | Uses the value given to calculate and show where on the plot the Earth is in shadow |
 
-This choice will return an `ax` object and a Cartopy `ccrs` object.
+This choice will return an `ax` object and a Cartopy `ccrs` object (coordinate reference system).
 
 ## Custom Axes
 pyDARN does not currently support use of custom axes to read in and plot on. This means