Merge 6827ace into 830c951

.github/workflows/main.yml

@@ -36,7 +36,7 @@ jobs:
         python -c "import pysat; pysat.params['data_dirs'] = 'pysatData'"
 
     - name: Test PEP8 compliance
-      run: flake8 . --count --select=E,F,W --show-source --statistics
+      run: flake8 . --count --select=D,E,F,W --show-source --statistics
 
     - name: Evaluate complexity
       run: flake8 . --count --exit-zero --max-complexity=10 --statistics

CHANGELOG.md

@@ -2,6 +2,12 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - XXXX-XX-XX
+* Documentation
+  * Improve docstrings throughout
+* Testing
+  * Add style check for docstrings
+
 ## [0.2.2] - 2021-06-18
 * Migrate pyglow interface to pysatIncubator
 * Style updates for consistency with pysat 3.0

docs/conf.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# https://www.sphinx-doc.org/en/master/config
+
+"""Configuration file for the Sphinx documentation builder.
+
+Note
+----
+For a full list see the documentation:
+https://www.sphinx-doc.org/en/master/config
+
+"""
 
 # -- Path setup --------------------------------------------------------------
 

pysatMissions/__init__.py

@@ -1,5 +1,19 @@
-from __future__ import print_function
-from __future__ import absolute_import
+"""
+Core library for pysatMissions.
+
+pysatMissions allows users to run build simulated satellites for Two-Line
+Elements (TLE) and add empirical data.  It includes the `missions_ephem` and
+`mission_sgp4` instrument modules which can be imported into pysat.
+
+Main Features
+-------------
+- Simulate satellite orbits from TLEs and add data from empirical models
+- Import ionosphere and thermosphere model values through pyglow
+- Import magnetic coordinates through apexpy and aacgmv2
+- Import geomagnetic basis vectors through OMMBV
+
+"""
+
 import logging
 import os
 

pysatMissions/instruments/__init__.py

@@ -1,6 +1,5 @@
 """
-pysatMissions.instruments is a pysat module that provides
-the instrument modules to be used with pysat
+Provides the instrument modules to be used with pysat.
 """
 
 from pysatMissions.instruments import missions_ephem, missions_sgp4

pysatMissions/instruments/_core.py

@@ -1,10 +1,15 @@
 """
-Handles the default pysat functions for simulated instruments
+Handles the default pysat functions for simulated instruments.
 """
 
 
 def _clean(self):
-    """Cleaning function.  Simple pass since data is generated locally.
+    """Pass through since cleaning is not needed.
+
+    Note
+    ----
+    Required for pysat standards compliance.
+
     """
 
     return

pysatMissions/instruments/missions_ephem.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
 """
-Produces satellite orbit data. Orbit is simulated using
-Two Line Elements (TLEs) and ephem. Satellite position is coupled
-to several space science models to simulate the atmosphere the
+Produce satellite orbit data.
+
+Orbit is simulated using Two Line Elements (TLEs) and ephem. Satellite position
+is coupled to several space science models to simulate the atmosphere the
 satellite is in.
 
 Properties
@@ -48,9 +49,9 @@
 
 def init(self):
     """
-    Adds custom calculations to orbit simulation.
-    This routine is run once, and only once, upon instantiation.
+    Add custom calculations to orbit simulation.
 
+    This routine is run once, and only once, upon instantiation.
     Adds custom routines for quasi-dipole coordinates, velocity calculation in
     ECEF coords, and attitude vectors of spacecraft (assuming x is ram pointing
     and z is generally nadir).
@@ -68,7 +69,7 @@ def init(self):
 
 def preprocess(self):
     """
-    Add modeled magnetic field values and attitude vectors to spacecraft
+    Add modeled magnetic field values and attitude vectors to spacecraft.
 
     Runs after load is invoked.
 
@@ -89,9 +90,10 @@ def preprocess(self):
 def load(fnames, tag=None, inst_id=None, obs_long=0., obs_lat=0., obs_alt=0.,
          TLE1=None, TLE2=None, num_samples=None, cadence='1S'):
     """
-    Returns data and metadata in the format required by pysat. Generates
-    position of satellite in both geographic and ECEF co-ordinates.
+    Generate position of satellite in both geographic and ECEF co-ordinates.
 
+    Note
+    ----
     Routine is directly called by pysat and not the user.
 
     Parameters

pysatMissions/instruments/missions_sgp4.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
-Produces satellite orbit data. Orbit is simulated using
-Two Line Elements (TLEs) and SGP4.
+Produce satellite orbit data.
+
+Orbit is simulated using Two Line Elements (TLEs) and SGP4.
 
 Properties
 ----------
@@ -40,7 +41,7 @@
 
 def init(self):
     """
-    Initializes the Instrument object with required values.
+    Initialize the Instrument object with required values.
 
     Runs once upon instantiation.
 
@@ -66,9 +67,10 @@ def init(self):
 def load(fnames, tag=None, inst_id=None, obs_long=0., obs_lat=0., obs_alt=0.,
          TLE1=None, TLE2=None, num_samples=None, cadence='1S'):
     """
-    Returns data and metadata in the format required by pysat. Generates
-    position of satellite in ECI co-ordinates.
+    Generate position of satellite in ECI co-ordinates.
 
+    Note
+    ----
     Routine is directly called by pysat and not the user.
 
     Parameters

pysatMissions/methods/__init__.py

@@ -1,6 +1,5 @@
 """
-pysatMissions.methods is a module that provides
-the methods to interface with numerous empirical model packages
+Provides the methods to interface with numerous empirical model packages.
 """
 
 from pysatMissions.methods import magcoord

pysatMissions/methods/magcoord.py

@@ -1,6 +1,5 @@
-"""Provides default routines for projecting aacgmv2 and apexpy model values onto
-locations from pysat instruments.
-
+"""
+Routines for projecting aacgmv2 and apexpy model values onto pysat instruments.
 """
 
 import aacgmv2
@@ -10,7 +9,7 @@
 def add_aacgm_coordinates(inst, glat_label='glat', glong_label='glong',
                           alt_label='alt'):
     """
-    Uses AACGMV2 package to add AACGM coordinates to instrument object.
+    Add AACGM coordinates to instrument object via AACGMV2 package.
 
     The Altitude Adjusted Corrected Geomagnetic Coordinates library is used
     to calculate the latitude, longitude, and local time
@@ -71,7 +70,7 @@ def add_aacgm_coordinates(inst, glat_label='glat', glong_label='glong',
 def add_quasi_dipole_coordinates(inst, glat_label='glat', glong_label='glong',
                                  alt_label='alt'):
     """
-    Uses Apexpy package to add quasi-dipole coordinates to instrument object.
+    Add quasi-dipole coordinates to instrument object using Apexpy package.
 
     The Quasi-Dipole coordinate system includes both the tilt and offset of the
     geomagnetic field to calculate the latitude, longitude, and local time

pysatMissions/methods/spacecraft.py

@@ -1,5 +1,4 @@
-"""Provides default routines for projecting values onto vectors
-for pysat instruments.
+"""Default routines for projecting values onto vectors for pysat instruments.
 
 """
 
@@ -136,7 +135,7 @@ def add_ram_pointing_sc_attitude_vectors(inst):
 
 def calculate_ecef_velocity(inst):
     """
-    Calculates spacecraft velocity in ECEF frame.
+    Calculate spacecraft velocity in ECEF frame.
 
     Presumes that the spacecraft velocity in ECEF is in
     the input instrument object as position_ecef_*. Uses a symmetric
@@ -187,7 +186,7 @@ def get_vel_from_pos(x):
 def project_ecef_vector_onto_sc(inst, x_label, y_label, z_label,
                                 new_x_label, new_y_label, new_z_label,
                                 meta=None):
-    """Express input vector using s/c attitude directions
+    """Express input vector using s/c attitude directions.
 
     x - ram pointing
     y - generally southward

pysatMissions/tests/__init__.py

@@ -0,0 +1 @@
+"""Unit and Integration tests for pysatMissions."""

pysatMissions/tests/test_instruments.py

@@ -1,3 +1,12 @@
+"""
+Unit and Integration Tests for each instrument module.
+
+Note
+----
+Imports test methods from pysat.tests.instrument_test_class
+
+"""
+
 import datetime as dt
 import numpy as np
 import tempfile
@@ -46,13 +55,18 @@
 
 
 class TestInstruments(InstTestClass):
-    """Uses class level setup and teardown so that all tests use the same
+    """Main class for instrument tests.
+
+    Note
+    ----
+    Uses class level setup and teardown so that all tests use the same
     temporary directory. We do not want to geneate a new tempdir for each test,
     as the load tests need to be the same as the download tests.
+
     """
 
     def setup_class(self):
-        """Runs once before the tests to initialize the testing setup."""
+        """Initialize the testing setup once before all tests are run."""
         # Make sure to use a temporary directory so that the user's setup is not
         # altered
         self.tempdir = tempfile.TemporaryDirectory()
@@ -64,7 +78,7 @@ def setup_class(self):
         self.inst_loc = pysatMissions.instruments
 
     def teardown_class(self):
-        """Runs once to clean up testing from this class."""
+        """Clean up downloaded files and parameters from tests."""
         pysat.params.data['data_dirs'] = self.saved_path
         self.tempdir.cleanup()
         del self.inst_loc, self.saved_path, self.tempdir
@@ -74,7 +88,7 @@ def teardown_class(self):
     @pytest.mark.parametrize("inst_dict", [x for x in instruments['download']])
     @pytest.mark.parametrize("kwarg,output", [(None, 1), ('10s', 10)])
     def test_inst_cadence(self, inst_dict, kwarg, output):
-        """Test operation of cadence keyword, including default behavior"""
+        """Test operation of cadence keyword, including default behavior."""
 
         if kwarg:
             self.test_inst = pysat.Instrument(

pysatMissions/tests/test_methods_magcoord.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Test some of the aacgmv2 method functions
+"""Test some of the aacgmv2 method functions."""
 
 import datetime as dt
 import numpy as np
@@ -8,17 +8,19 @@
 
 
 class TestBasics():
+    """Main testing class for aacgmv2."""
+
     def setup(self):
-        """Runs before every method to create a clean testing setup."""
+        """Create a clean testing setup before each method."""
         self.testInst = pysat.Instrument(platform='pysat', name='testing',
                                          num_samples=100, clean_level='clean')
 
     def teardown(self):
-        """Clean up test environment after tests"""
+        """Clean up test environment after each method."""
         del self
 
     def test_add_aacgm_coordinates(self):
-        """Test adding thermal plasma data to test inst"""
+        """Test adding thermal plasma data to test inst."""
         self.testInst.custom_attach(mm_magcoord.add_aacgm_coordinates,
                                     kwargs={'glat_label': 'latitude',
                                             'glong_label': 'longitude',
@@ -33,7 +35,7 @@ def test_add_aacgm_coordinates(self):
             assert target in self.testInst.meta.data.index
 
     def test_add_quasi_dipole_coordinates(self):
-        """Test adding thermal plasma data to test inst"""
+        """Test adding thermal plasma data to test inst."""
         self.testInst.custom_attach(mm_magcoord.add_quasi_dipole_coordinates,
                                     kwargs={'glat_label': 'latitude',
                                             'glong_label': 'longitude',