NRL pub release

.github/workflows/main.yml

@@ -14,12 +14,7 @@ jobs:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
-        install-extras: [0, 1, 2]  # TODO(#129): update to replace extra flag
-        exclude:
-          - os: "windows-latest"  # TODO(#135): remove exclusion
-            install-extras: 2
-          - os: "macos-latest"  # TODO(#135): remove exclusion
-            install-extras: 2
+        install-extras: [0, 1]  # TODO(#129): update to replace extra flag
 
     name: Python ${{ matrix.python-version }} on ${{ matrix.os }} with extras ${{ matrix.install-extras }}
     runs-on: ${{ matrix.os }}

AUTHORS.rst

@@ -9,3 +9,9 @@ Contributors
 ------------
 
 * Dominic Jodoin - https://github.com/cotsog
+
+Acknowledgements
+----------------
+ * Angeline G. Burrell is supported by the Office of Naval Research
+   (2018-Present)
+

CONTRIBUTING.rst

@@ -9,7 +9,8 @@ to respond in a timely manner.
 Short version
 =============
 
-* Submit bug reports and feature requests at `GitHub <https://github.com/aburrell/ocbpy/issues>`_
+* Submit bug reports and feature requests at
+  `GitHub <https://github.com/aburrell/ocbpy/issues>`_
 * Make pull requests to the ``develop`` branch
 
 Bug reports
@@ -82,8 +83,8 @@ Tips
 
 To run a subset of tests from the test directory for a specific environment::
 
-    python test_name.py
+    python -m unittest test_name.py
 
 To run all the tests for a specific environment::
 
-    python setup.py test
+    python -m unittest discover

Changelog.rst

@@ -16,8 +16,7 @@ Summary of all changes made since the first stable release
 * ENH: Added AMPERE EABs, using the Heppner-Maynard boundary as a valid EAB
 * ENH: Changed default directory ID to use `pathlib`
 * ENH: Allow data padding in `pysat_instrument` functions
-* ENH: Created separate vector transformation functions to support multiple
-       coordinate systems
+* ENH: Separated vector transformations to support multiple coordinate systems
 * ENH: Updated VectorData and pysat_instruments to allow geographic inputs
 * BUG: Fixed a typo in the documentation's pysat example
 * BUG: Added an error catch for badly formatted SuperMAG file reading

README.md

@@ -21,7 +21,7 @@ coordinate system is described in:
     Research: Space Physics,
     [doi:10.1002/2016JA023235.](https://doi.org/10.1002/2016JA023235)
 
-  * Full [documentation](http://ocbpy.rtfd.io/)
+  * Full [documentation](https://ocbpy.readthedocs.io/en/latest/)
 
 Boundaries must be obtained from observations or models for this coordinate
 transformation. Several boundary data sets are included within this package.
@@ -33,7 +33,7 @@ locations from DMSP.
   * Burrell, A. G. et al. (2020): AMPERE Polar Cap Boundaries, Ann. Geophys.,
     38, 481-490,
     [doi:10.5194/angeo-38-481-2020](https://doi.org/10.5194/angeo-38-481-2020)
-  * [ssj_auroral_boundary](https://github.com/lkilcommons/ssj_auroral_boundary)
+  * [DMSP SSJ Boundaries](https://zenodo.org/records/3373812)
 
 Currently, support is included for files from the following datasets:
 
@@ -53,10 +53,12 @@ The listed dependecies were tested with the following versions:
   * numpy
   * aacgmv2
   * pysat (3.0.1+)
-  * ssj_auroral_boundary
+  * ssj_auroral_boundary (deprecated)
+  * zenodo_get
 
 Testing is performed using the python module, unittest.  To limit dependency
-issues, pysat (>=3.0.1) and ssj_auroral_boundary are optional dependencies.
+issues, the pysat, ssj_auroral_boundary, and zenodo_get dependencies are
+optional.
 
 # Installation
 
@@ -73,11 +75,12 @@ You may also checkout the repository and install it yourself:
 ```
 
 Change directories into the repository folder and run the setup.py file.  For
-a local install use the "--user" flag after "install".
+a local install use the "--user" flag after "install". For development, add
+the "-e" flag.
 
 ```
     $ cd ocbpy/
-    $ python setup.py install
+    $ pip install .
 ```
 
 To run the unit tests,

docs/citing.rst

@@ -91,6 +91,11 @@ The DMSP SSJ boundaries are retrieved using
 Please follow the citation guidelines on their page.  The general reference
 for the DMSP SSJ boundary data set is provided below.
 
+* **SSJ Auroral Boundaries**: Kilcommons, L. M., R. J. Redmon, and D. J. Knipp
+  (2017), A new DMSP magnetometer and auroral boundary data set and estimates
+  of field-aligned currents in dynamic auroral boundary coordinates, J. Geophys.
+  Res. Space Physics, 122, 9068–9079, doi:10.1002/2016JA023342.
+
 * **SSJ Auroral Boundaries (2010-2014)**: Kilcommons, L., et al. (2019).
   Defense Meteorology Satellite Program (DMSP) Electron Precipitation (SSJ)
   Auroral Boundaries, 2010-2014 (Version 1.0.0) [Data set]. Zenodo.

docs/conf.py

@@ -21,6 +21,7 @@
 import datetime as dt
 import json
 import os
+from pyproject_parser import PyProject
 import sys
 
 sys.path.insert(0, os.path.abspath('.'))
@@ -61,20 +62,21 @@
 master_doc = 'index'
 
 # General information about the project.
+info = PyProject.load("../pyproject.toml")
 zenodo = json.loads(open('../.zenodo.json').read())
 project = 'ocbpy'
 author = '; '.join([auth['name'] for auth in zenodo['creators']])
 copyright = '{:d}, {:s}'.format(dt.datetime.utcnow().year, author)
 title = 'ocbpy Documentation'
-desc = ''.join(['Coordinate transformation to and from an open-closed ',
-                'field line boundary system'])
+desc = ''.join(['Coordinate transformation to and from high-latitude ',
+                'boundary systems'])
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.3.0'
+version = info.project['version'].base_version
 # The full version, including alpha/beta/rc tags.
 release = '{:s}-beta'.format(version)
 
@@ -180,4 +182,4 @@
 epub_exclude_files = ['search.html']
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3': None}
+intersphinx_mapping = {'<name>': ('https://docs.python.org/3', None)}

docs/examples/ex_pysat_eab.rst

@@ -90,8 +90,8 @@ prodedures while loading the desired data.  The
 be applied using the :py:mod:`pysat` `custom interface
 <https://pysat.readthedocs.io/en/latest/tutorial/tutorial_custom.html>`_.  The
 EAB conversion can handle magnetic, geodetic, or geocentric coordinates for
-scalar or vector data types using the :py:var:`loc_coord` and
-:py:var:`vect_coord` keyword arguments, respectively. We do need to calculate
+scalar or vector data types using the :py:attr:`loc_coord` and
+:py:attr:`vect_coord` keyword arguments, respectively. We do need to calculate
 local time before calculating the EAB coordinates, though.
 
 ::

docs/index.rst

@@ -22,7 +22,6 @@ process and provides examples for usage.
    contributing.rst
 
 
-
 Indices and tables
 ==================
 

docs/ocb_gridding.rst

@@ -33,6 +33,7 @@ the :py:mod:`ocbpy.ocb_scaling` module.
 Boundary Classes
 ----------------
 .. automodule:: ocbpy._boundary
+    :noindex:
     :members:
 
 
@@ -50,3 +51,12 @@ OCB Scaling Module
 ------------------
 .. automodule:: ocbpy.ocb_scaling
     :members:
+
+
+.. _ocbgrid-vector:
+
+Vector Functions
+----------------
+.. automodule:: ocbpy.vectors
+    :members:
+

ocbpy/__init__.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2019, AGB & GC
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Auroral oval and polar cap normalised location calculation tools."""
 

ocbpy/_boundary.py

@@ -1,6 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Hold, manipulate, and load the OCB and EAB data.
 
@@ -471,7 +475,7 @@ def get_next_good_ocb_ind(self, min_merit=None, max_merit=None, **kwargs):
 
         AMPERE/DMSP-SSJ and new IMAGE FUV checks that:
         - the Figure of Merit is greater than or equal to the specified minimum
-          (`min_fom`) or less than or equal to the specified maximum (`max_fom`)
+        (`min_fom`) or less than or equal to the specified maximum (`max_fom`)
 
         """
 

ocbpy/boundaries/README.md

@@ -1,3 +1,9 @@
+# DOI: 10.5281/zenodo.1179230
+# Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 This directory contains files with Open Closed field line Boundaries obtained
 from different instruments
 

ocbpy/boundaries/__init__.py

@@ -1,6 +1,10 @@
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2019, AGB * GC
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in LICENSE.txt
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Boundary file utilities."""
 

ocbpy/boundaries/dmsp_ssj_files.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2019, AGB & GC
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # -----------------------------------------------------------------------------
 """Download and format DMSP SSJ boundary files.
 
@@ -15,6 +18,10 @@
    boundary coordinates, J. Geophys. Res.: Space Phys., 122, pp 9068-9079,
    doi:10.1002/2016ja023342.
 
+.. [7] Kilcommons, L., Redmon, R., & Knipp, D. (2019). Defense Meteorology
+   Satellite Program (DMSP) Electron Precipitation (SSJ) Auroral Boundaries,
+   2010-2014 (1.0.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.3373812
+
 """
 
 import datetime as dt
@@ -279,7 +286,7 @@ def fetch_ssj_boundary_files(stime=None, etime=None, out_dir=None,
     sat_nums : list or NoneType
         Satellite numbers or None for all satellites (default=None)
     doi : str
-        DOI for the DMSP SSJ boundary file Zenodo archive
+        DOI for the DMSP SSJ boundary file Zenodo archive [7]_
         (default='10.5281/zenodo.3373811')
     rm_temp : bool
         Remove all files that are not the final boundary files (default=True)
@@ -492,7 +499,7 @@ def format_ssj_boundary_files(csv_files, ref_alt=830.0,
     times, a circle that intersects the two boundary pass points is defined and
     the boundary location saved.  The DMSP SSJ boundary correction function
     will use this information to only return values within a small distance of
-    the boundary locations [5]_.
+    the boundary locations [5]_, [7]_.
 
     Separate files are created for each boundary and hemisphere, dates and
     spacecraft are combined.

ocbpy/boundaries/files.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2019, AGB & GC
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Functions that support boundary file selection."""
 

ocbpy/cycle_boundary.py

@@ -1,6 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Routines to match and cycle through the OCboundary class records."""
 

ocbpy/instruments/__init__.py

@@ -1,6 +1,10 @@
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2017 AGB
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in LICENSE.txt
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
 """Instrument specific Boundary support."""
 

ocbpy/instruments/general.py

@@ -1,6 +1,10 @@
 #!/usr/bin/env python
-# Copyright (C) 2017 AGB
-# Full license can be found in LICENSE.txt
+# -*- coding: utf-8 -*-
+# DOI: 10.5281/zenodo.1179230
+# Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ---------------------------------------------------------------------------
 """General loading routines for data files."""
 

ocbpy/instruments/pysat_instruments.py

@@ -1,6 +1,10 @@
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2017 AGB
-# Full license can be found in LICENSE.txt
+# DOI: 10.5281/zenodo.1179230
+# Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ---------------------------------------------------------------------------
 """Perform OCB gridding for appropriate instrument data loaded in pysat.
 

ocbpy/instruments/supermag.py

@@ -1,6 +1,10 @@
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2017 AGB
-# Full license can be found in LICENSE.txt
+# DOI: 10.5281/zenodo.1179230
+# Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ---------------------------------------------------------------------------
 """Perform OCB gridding for SuperMAG data.
 

ocbpy/instruments/vort.py

@@ -1,6 +1,10 @@
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2017 AGB
-# Full license can be found in LICENSE.txt
+# DOI: 10.5281/zenodo.1179230
+# Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ---------------------------------------------------------------------------
 """Perform OCB gridding for SuperDARN vorticity data.
 

ocbpy/ocb_correction.py

@@ -1,16 +1,19 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright (C) 2017, AGB & GC
+# DOI: 10.5281/zenodo.1179230
 # Full license can be found in License.md
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
 # ----------------------------------------------------------------------------
-""" Functions that specify the boundary location as a function of MLT
+"""Functions that specify the boundary location as a function of MLT.
 
 References
 ----------
 .. [4] Burrell, A. G. et al.: AMPERE Polar Cap Boundaries, Ann. Geophys., 38,
    481-490, doi:10.5194/angeo-38-481-2020, 2020.
-.. [6] Chisham, G. et al.: Ionospheric Boundaries Derived from Auroral Images,
-    in prep, 2022.
+.. [6] Chisham, G. et al. (2022) Ionospheric Boundaries Derived from Auroral
+   Images. JGR Space Physics, 127, 7, e2022JA030622, doi:10.1029/2022JA030622.
 
 """