Merge 6f650fb into 1bc9b6e

Changelog.rst

@@ -10,11 +10,12 @@ Summary of all changes made since the first stable release
 * DEP: Moved OCBoundary class to hidden sub-module, `_boundary`
 * DEP: Moved `ocboundary` functions to new sub-module, `cycle_boundary`
 * DEP: Deprecated kwargs no longer needed to select good IMAGE data
-* DOC: Improved the PEP8 compliance in the documentation examples
-* DOC: Improved the docstring numpydoc compliance
+* DOC: Improved the PEP8 and numpydoc compliance in the documentation examples
+* DOC: Updated citations
 * DOC: Updated cross-referencing and added missing API sections
 * DOC: Added examples for DMSP SSJ boundaries, pysat Instruments, and the
-       DualBoundary class
+       DualBoundary class, updated the README example
+* DOC: Improved documentation configuration
 * ENH: Added a setup configuration file
 * ENH: Changed class `__repr__` to produce a string `eval` can use as input
 * ENH: Updated the IMAGE OCB files and added EAB files

README.md

@@ -11,10 +11,11 @@ Overview </h1>
 
 OCBpy is a Python module that converts between AACGM coordinates and a magnetic
 coordinate system that adjusts latitude and local time relative to the Open
-Closed field line Boundary (OCB).  This is particulary useful for statistical
-studies of the poles, where gridding relative to a fixed magnetic coordinate
-system would cause averaging of different physical regions, such as auroral
-and polar cap measurements.  This coordinate system is described in:
+Closed field line Boundary (OCB), Equatorial Auroral Boundary (EAB), or both.
+This is particulary useful for statistical studies of the poles, where gridding
+relative to a fixed magnetic coordinate system would cause averaging of
+different physical regions, such as auroral and polar cap measurements.  This
+coordinate system is described in:
 
   * Chisham, G. (2017), A new methodology for the development of high‐latitude
     ionospheric climatologies and empirical models, Journal of Geophysical
@@ -23,14 +24,13 @@ and polar cap measurements.  This coordinate system is described in:
 
   * Full [documentation](http://ocbpy.rtfd.io/)
 
-OCBs must be obtained from observations for this coordinate transformation.
-In the British Antarctic Survey's [IMAGE Auroral Boundary data project](https://www.bas.ac.uk/project/image-auroral-boundary-data/)
-from three auroral instruments provide northern hemisphere OCB locations
-for 3 May 2000 03:01:42 UT - 22 Aug 2002 00:01:28, though not all of the times
-included in these files contain high-quality estimations of the OCB.
-Recommended selection criteria are included as defaults in the OCBoundary class.
-OCBpy also supports boundaries provided by AMPERE and DMSP:
+Boundaries must be obtained from observations or models for this coordinate
+transformation. Several boundary data sets are included within this package.
+These include northern hemisphere boundaries from the IMAGE satellite,
+northern and southern hemisphere OCBs from AMPERE, and single-point boundary
+locations from DMSP.
 
+  * [IMAGE Auroral Boundary data](https://www.bas.ac.uk/project/image-auroral-boundary-data/)
   * 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)
@@ -46,18 +46,18 @@ These routines may be used as a guide to write routines for other datasets.
 
 # Python versions
 
-This module currently supports Python version 3.6 - 3.9.
+This module currently supports Python version 3.7 - 3.10.
 
 # Dependencies
 
 The listed dependecies were tested with the following versions:
   * numpy
   * aacgmv2
-  * pysat (2.0.0+)
+  * pysat (3.0.1+)
   * ssj_auroral_boundary
 
 Testing is performed using the python module, unittest.  To limit dependency
-issues, pysat (>=2.0.0) and ssj_auroral_boundary are optional dependencies.
+issues, pysat (>=3.0.1) and ssj_auroral_boundary are optional dependencies.
 
 # Installation
 
@@ -92,57 +92,55 @@ To run the unit tests,
 In iPython, run:
 
 ```
-import numpy as np
+import datetime as dt
 import ocbpy
 ```
 
 Then initialise an OCB class object.  This uses the default IMAGE FUV file and
 will take a few minutes to load.
 
 ```
-ocb = ocbpy.ocboundary.OCBoundary()
+ocb = ocbpy.OCBoundary()
 print(ocb)
 ```
 
 The output should be as follows:
 
 ```
-Open-Closed Boundary file: ~/ocbpy/ocbpy/boundaries/si13_north_circle
+Open-Closed Boundary file: ~/ocbpy/ocbpy/boundaries/image_north_circle.ocb
 Source instrument: IMAGE
-Open-Closed Boundary reference latitude: 74.0 degrees
+Boundary reference latitude: 74.0 degrees
 
-219927 records from 2000-05-05 11:35:27 to 2002-08-22 00:01:28
+305805 records from 2000-05-04 03:03:20 to 2002-10-31 20:05:16
 
 YYYY-MM-DD HH:MM:SS Phi_Centre R_Centre R
------------------------------------------
-2000-05-05 11:35:27 356.93 8.74 9.69
-2000-05-05 11:37:23 202.97 13.23 22.23
-2002-08-21 23:55:20 322.60 5.49 15.36
-2002-08-22 00:01:28 179.02 2.32 19.52
+-----------------------------------------------------------------------------
+2000-05-04 03:03:20 4.64 2.70 21.00
+2000-05-04 03:07:15 147.24 2.63 7.09
+2002-10-31 20:03:16 207.11 5.94 22.86
+2002-10-31 20:05:16 335.47 6.76 11.97
 
 Uses scaling function(s):
-circular(**{})
+ocbpy.ocb_correction.circular(**{})
 ```
 
-Get the first good OCB record, which will be record index 27.
+Get the first good OCB record, which will be record index 0.
 
 ```
 ocb.get_next_good_ocb_ind()
 print(ocb.rec_ind)
-
-27
 ```
 
-To get the OCB record closest to a specified time, use **ocbpy.match_data_ocb**
+To get the good OCB record closest to a specified time (with a maximum of a
+60 sec time difference, as a default), use **ocbpy.match_data_ocb**
 
 ```
-first_good_time = ocb.dtime[ocb.rec_ind]
-test_times = [first_good_time + dt.timedelta(minutes=5 * (i + 1))
-              for i in range(5)]
+test_times = [dt.datetime(otime.year, otime.month, otime.day, otime.hour,
+                          otime.minute, 0) for otime in ocb.dtime[1:10]]
 itest = ocbpy.match_data_ocb(ocb, test_times, idat=0)
 print(itest, ocb.rec_ind, test_times[itest], ocb.dtime[ocb.rec_ind])
 
-0 31 2000-05-05 13:45:30 2000-05-05 13:50:29
+4 5 2000-05-05 11:39:00 2000-05-05 11:39:20
 ```
 
-More examples are available in the documentation.
+More examples are available in the documentation.

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/citing.rst

@@ -59,6 +59,9 @@ boundary retrieval method.
   Mission Data (May 2000 - Oct 2002), Version 1.1, Polar Data Centre, Natural
   Environment Research Council, UK.
   http://doi.org/10.5285/75aa66c1-47b4-4344-ab5d-52ff2913a61e.
+* **OCB**: Chisham, G., et al. (2022) Ionospheric boundaries derived from
+  auroral images. Journal of Geophysical Research: Space Physics, 127,
+  e2022JA030622. https://doi.org/10.1029/2022JA030622.
 
 
 .. _cite-ampere:

docs/conf.py

@@ -83,7 +83,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/examples/ex_pysat_eab.rst

@@ -9,13 +9,13 @@ demonstrating how to use :py:mod:`pysat` with :py:mod:`ocbpy`.
 
 Using Equatorward Auroral Boundaries
 ------------------------------------
- may be loaded on their own using the
-:py:class:`~ocbpy._boundary.EABoundary` class.  This is a wrapper for the
-:py:class:`~ocbpy._boundary.OCBoundary` class with different defaults more
-appropriate for EABs.  Currently, :ref:`bound-data-image` and
-:ref:`bound-data-dmsp-ssj` both have EAB data.  This example uses
-the default file for IMAGE from the Northern hemisphere.  It is very similar
-to :ref:`exinit`, the first example in this section.
+
+EABs may be loaded using the :py:class:`~ocbpy._boundary.EABoundary` class.
+This is a wrapper for the :py:class:`~ocbpy._boundary.OCBoundary` class with
+different defaults more appropriate for EABs.  Currently,
+:ref:`bound-data-image` and :ref:`bound-data-dmsp-ssj` both have EAB data.  This
+example uses the default file for IMAGE from the Northern hemisphere.  It is
+very similar to :ref:`exinit`, the first example in this section.
 
 ::
 
@@ -53,16 +53,17 @@ The expected record index, :py:attr:`eab.rec_ind`, is ``1``.
 
 Load a pysat Instrument (Madrigal TEC)
 --------------------------------------
+
 Total Electron Content (TEC) is one of the most valuable ionospheric data sets.
 `Madrigal <http://cedar.openmadrigal.org/>`_ provides Vertical TEC (VTEC) maps
 from the 1990's onward that specify the median VTEC in 1 degree x 1 degree
 geographic latitude x longitude bins.  The
 `pysat <https://github.com/pysat>`_ package,
 `pysatMadrigal <https://github.com/pysat/pysatMadrigal>`_
 has an instrument for obtaining, managing, and processing this VTEC data. To
-run this example, you must have :py:module:`pysatMadrigal`
+run this example, you must have :py:mod:`pysatMadrigal`
 `installed <https://pysatmadrigal.readthedocs.io/en/latest/installation.html>`_.
-After setting up :py:module:`pysat`, download the file needed for this example
+After setting up :py:mod:`pysat`, download the file needed for this example
 using the following commands.
 
 ::

ocbpy/boundaries/README.md

@@ -17,10 +17,12 @@ A       : Psuedo area of the circle (as in AACGM, not geographic)
 R_ERR   : Root-mean squared error in the radius in degrees
 R_MERIT : Radial distance from the most typical pole location in degrees
 
-There are certain ranges for NB, RCENT, and R that you shouldn’t use that can
-be found (and explained) in Chisham (2017), doi:10.1002/2016JA023235.  These
-ranges are the defaults in OCBoundary.get_next_good_ocb_ind.  When using these
-boundaries, remember to cite Chisham (2017). From ocbpy version 0.3.0 onward,
+Previosly, there are certain ranges for NB, RCENT, and R that were not
+recommended for use (see Chisham (2017), doi:10.1002/2016JA023235).  Currently,
+R_MERIT is used instead, with recommended merit values documented in Chisham
+et al. (2022), doi:10.1029/2022JA030622.  These ranges are the defaults in
+OCBoundary.get_next_good_ocb_ind.  When using these boundaries, remember to cite
+Chisham (2017) or Chisham et al. (2022). From ocbpy version 0.3.0 onward,
 the SI12, SI13, and WIC files contain uncorrected auroral boundary fits, while
 the IMAGE file contains DMSP corrected average boundaries for the OCB and EAB.