Merge branch 'spedas:master' into master

.github/workflows/pythonpackage.yml

@@ -198,6 +198,8 @@ jobs:
         coverage run -a -m pyspedas.analysis.tests.tests
         echo Starting analysis wavpol tests at `date`
         coverage run -a -m pyspedas.analysis.tests.test_twavpol
+        echo Starting analysis magnetic nulls tests at `date`
+        coverage run -a -m pyspedas.analysis.tests.test_magnetic_nulls
         echo Starting fast tests at `date`
         coverage run -a -m pyspedas.fast.tests.tests
         echo Starting omni tests at `date`

docs/source/getting_started.rst

@@ -5,7 +5,7 @@ pySPEDAS supports Windows, macOS and Linux.
 
 Requirements
 --------------
-Python 3.7 or later is required.
+Python 3.8 or later is required.
 
 We recommend Anaconda, which comes with a suite of packages useful for scientific data analysis. Step-by-step instructions for installing Anaconda can be found at: `Windows <https://docs.anaconda.com/anaconda/install/windows/>`_, `macOS <https://docs.anaconda.com/anaconda/install/mac-os/>`_, `Linux <https://docs.anaconda.com/anaconda/install/linux/>`_
 

pyspedas/__init__.py

@@ -11,7 +11,7 @@
 from .analysis.tinterpol import tinterpol
 from .analysis.yclip import yclip
 from .analysis.twavpol import twavpol
-from .analysis.find_magnetic_nulls import find_magnetic_nulls_fote
+from .analysis.find_magnetic_nulls import find_magnetic_nulls_fote, classify_null_type
 from .cdagui.cdagui import cdagui
 from .cotrans.cotrans import cotrans
 from .cotrans.cotrans_get_coord import cotrans_get_coord
@@ -73,6 +73,7 @@
 from .mms.particles.mms_part_slice2d import mms_part_slice2d
 from .maven import maven_load
 from .sosmag.load import sosmag_load
+from .noaa import noaa_load_kp
 
 # Make mission-specific namespaces available under pyspedas
 from . import ace

pyspedas/analysis/README.md

@@ -0,0 +1,63 @@
+## PySPEDAS Analysis Tools
+
+The routines in this module can be used to perform various analysis tasks on spacecraft or ground data.
+
+### Linear Gradient Estimation (lingradest)
+
+This routine is used to estimate the gradients and other properties of the magnetic field, using positions and field measurements from four spacecraft in a roughly
+tetrahedral formation (e.g. MMS or Cluster).
+
+### Magnetic Null Finding via First Order Taylor Expansion (find_magnetic_nulls_fote)
+
+This routine finds locations and toplogical properties of magnetic null points near a
+tetrahedral formation of spacecraft (e.g. MMS or Cluster)
+
+Example:
+```python
+import pyspedas
+from pytplot import tplot
+
+data = pyspedas.mms.fgm(probe=[1, 2, 3, 4], trange=['2015-09-19/07:40', '2015-09-19/07:45'], data_rate='srvy', time_clip=True, varformat='*_gse_*', get_fgm_ephemeris=True)
+fields = ['mms'+prb+'_fgm_b_gse_srvy_l2' for prb in ['1', '2', '3', '4']]
+positions = ['mms'+prb+'_fgm_r_gse_srvy_l2' for prb in ['1', '2', '3', '4']]
+null_vars = pyspedas.find_magnetic_nulls_fote(fields=fields, positions=positions, smooth_fields=True,smooth_npts=10,smooth_median=True)
+tplot(null_vars)
+```
+
+### Magnetic Null Classification (classify_null_types)
+
+This routine takes three complex values (eigenvalues of a Jacobian matrix) and uses
+them to classify the corresponding magnetic null point (2-D types X or O, or 3-D types
+A (radial), B (radial), A (spiral) or B (spiral)).
+
+Example:
+```python
+import pyspedas
+
+l1 = complex(-.25,0.0)
+l2 = complex(-.25, 0.0)
+l3 = complex(0.5,0.0)
+lambdas = [l1,l2,l3]
+tc = pyspedas.classify_null_type(lambdas)
+# tc == 3, indicating a type A (radial) null
+```
+
+### Neutral Sheet Models (neutral_sheet)
+
+This routine takes a list of times and positions, some additional model parameters, and
+a model name, and computes the GSM-Z coordinate of the neutral sheet at those
+times and positions, or optionally the difference along Z between the NS and the input position.
+
+### Time Domain Filtering (time_domain_filter)
+
+TBD
+
+### Wave Polarization Analysis (twavpol)
+
+This routine takes a variable containing field data (preferably in a minimum variance coordinate system), and some processing parameters, and calculates
+several wave polarization properties of the input field versus time and frequency: wave power, degree of polarization, wave normal angle, helicity, ellipticity,
+
+### Wavelet analysis (wavelet)
+
+TBD
+