From 369c99bc9cb3673daef9d116d01e1d21c79d578a Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:36:18 -0400 Subject: [PATCH 01/11] DOC: updated zenodo name order Updated the order of the first and last names in the .zenodo.json creators list. --- .zenodo.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.zenodo.json b/.zenodo.json index 19a67cb..b70bcc6 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -16,22 +16,22 @@ "creators": [ { "affiliation": "U.S. Naval Research Laboratory", - "name": "Angeline G. Burrell", + "name": "Burrell, Angeline G.", "orcid": "0000-0001-8875-9326" }, { "affiliation": "Goddard Space Flight Center", - "name": "Jeff Klenzing", + "name": "Klenzing, Jeff", "orcid": "0000-0001-8321-6074" }, { "affiliation": "The University of Texas at Dallas", - "name": "Russell Stoneback", + "name": "Stoneback, Russell", "orcid": "0000-0001-7216-4336" }, { "affiliation": "Predictive Science", - "name": "Asher Pembroke" + "name": "Pembroke, Asher" } ] } From 75a1d978b558d4da39c0aea071ec292962f4c323 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:37:59 -0400 Subject: [PATCH 02/11] STY: updated doc configuration Updated the document configuration by: - adding common variables to reduce duplication, - fixing PEP8 style violations, - linking the authors to the zenodo.json file, and - adding a logo display to the docs sidebar. --- docs/conf.py | 100 ++++++++++++++++++++------------------------------- 1 file changed, 39 insertions(+), 61 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4bff398..9c581aa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # +import json import os import sys sys.path.insert(0, os.path.abspath('..')) @@ -38,8 +39,7 @@ 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'numpydoc', - 'm2r2' -] + 'm2r2'] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] @@ -54,18 +54,21 @@ master_doc = 'index' # General information about the project. -project = u'pysatMadrigal' -copyright = u'2020, Angeline G Burrell, Jeffrey Klenzing, Russell Stoneback' -author = u'Angeline G Burrell, Jeffrey Klenzing, Russell Stoneback, Asher Pembroke' +project = 'pysatMadrigal' +title = '{:s} Documentation'.format(project) +zenodo = json.loads(open('../.zenodo.json').read()) +author = ', '.join([creator['name'] for creator in zenodo['creators']]) +description = ''.join(['Tools for accessing and analyzing data from the ', + 'Madrigal database']) +copyright = ', '.join(['2021', author]) # 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 = u'0.0.2' -# The full version, including alpha/beta/rc tags. -release = u'0.0.2-alpha' +doc_dir = os.path.abspath(os.path.dirname(__file__)) +with open(os.path.join(doc_dir, "..", project, "version.txt"), "r") as fin: + version = fin.read().strip() +release = '{:s}-alpha'.format(version) # Include alpha/beta/rc tags. # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -85,84 +88,61 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True - # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' +html_theme_path = ["_themes", ] + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = os.path.join(os.path.abspath('.'), 'figures', 'pysatMadrigal.png') # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['.static'] - +html_theme_options = {'logo_only': True} # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'pysatMadrigaldoc' - +htmlhelp_basename = '{:s}doc'.format(project) # -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} +# +# The paper size ('letterpaper' or 'a4paper'). +# 'papersize': 'letterpaper', +# +# The font size ('10pt', '11pt' or '12pt'). +# 'pointsize': '10pt', +# +# Additional stuff for the LaTeX preamble. +# 'preamble': '', +# +# Latex figure (float) alignment +# 'figure_align': 'htbp', +latex_elements = {} # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'pysatMadrigal.tex', u'pysatMadrigal Documentation', - u'Angeline G Burrell, Jeffrey Klenzing, and Russell Stoneback', 'manual'), -] - +latex_documents = [(master_doc, '{:s}.tex'.format(project), title, author, + 'manual')] # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'pysatMadrigal', u'pysatMadrigal Documentation', - [author], 1) -] - +man_pages = [(master_doc, project, title, [author], 1)] # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'pysatMadrigal', u'pysatMadrigal Documentation', - author, 'pysatMadrigal', - 'Tools for accessing and analyzing data from the Madrigal database', - 'Space Physics'), -] - - +texinfo_documents = [(master_doc, project, title, author, project, + description, 'Space Physics')] # -- Options for Epub output ---------------------------------------------- @@ -184,7 +164,5 @@ # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] - - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/': None} From 533244e98e7a2ead1db375c1a9c01160d3a3dea2 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:38:31 -0400 Subject: [PATCH 03/11] DOC: fixed docstring style violations Fixed docstring style violations flagged by sphinx. --- pysatMadrigal/instruments/methods/general.py | 32 +++++++++----------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/pysatMadrigal/instruments/methods/general.py b/pysatMadrigal/instruments/methods/general.py index 17c115f..808a3cd 100644 --- a/pysatMadrigal/instruments/methods/general.py +++ b/pysatMadrigal/instruments/methods/general.py @@ -1,8 +1,7 @@ # -*- coding: utf-8 -*-. -"""Provides default routines for integrating CEDAR Madrigal instruments into -pysat, reducing the amount of user intervention. +"""General routines for integrating CEDAR Madrigal instruments into pysat. - """ +""" import datetime as dt import numpy as np @@ -21,36 +20,33 @@ def cedar_rules(): - """ General acknowledgement statement for Madrigal data. + """General acknowledgement statement for Madrigal data. Returns ------- - ackn : string + ackn : str String with general acknowledgement for all CEDAR Madrigal data """ - ackn = "Contact the PI when using this data, in accordance with the CEDAR" - ackn += " 'Rules of the Road'" + ackn = "".join(["Contact the PI when using this data, in accordance ", + "with the CEDAR 'Rules of the Road'"]) return ackn def load(fnames, tag=None, inst_id=None, xarray_coords=[], file_type='hdf5'): """Loads data from Madrigal into Pandas or XArray - This routine is called as needed by pysat. It is not intended - for direct user interaction. - Parameters ---------- fnames : array-like iterable of filename strings, full path, to data files to be loaded. This input is nominally provided by pysat itself. - tag : string + tag : str tag name used to identify particular data set to be loaded. This input is nominally provided by pysat itself. While tag defaults to None here, pysat provides '' as the default tag unless specified by user at Instrument instantiation. (default='') - inst_id : string + inst_id : str Satellite ID used to identify particular data set to be loaded. This input is nominally provided by pysat itself. (default='') xarray_coords : list @@ -61,23 +57,25 @@ def load(fnames, tag=None, inst_id=None, xarray_coords=[], file_type='hdf5'): will have a tuple of coordinates as the key and a list of variable strings as the value. For example, xarray_coords=[{('time',): ['year', 'doy'], - ('time', 'gdalt'): ['data1', 'data2']}]. (default=[]) - file_type : string + ('time', 'gdalt'): ['data1', 'data2']}]. (default=[]) + file_type : strö File format for Madrigal data. Currently only accept 'netCDF4' and 'hdf5'. (default='hdf5') Returns ------- data : pds.DataFrame or xr.Dataset - A pandas DataFrame or xarray Dataset holding the data from the HDF5 - file + A pandas DataFrame or xarray Dataset holding the data from the file meta : pysat.Meta - Metadata from the HDF5 file, as well as default values from pysat + Metadata from the file, as well as default values from pysat Note ---- Currently HDF5 reading breaks if a different file type was used previously + This routine is called as needed by pysat. It is not intended + for direct user interaction. + """ # Test the file format if file_type not in ['netCDF4', 'hdf5']: From 8c2a7ffe8fd5ba5fdda6f151a87496650d500f42 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:38:57 -0400 Subject: [PATCH 04/11] ENH: updated README Updated the README to reflect the conditions of the next release. --- README.md | 49 +++++++++++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index a96922c..b142032 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
- pysatMadrigal + pysatMadrigal
# pysatMadrigal @@ -16,11 +16,28 @@ pysat ([pysat documentation](http://pysat.readthedocs.io/en/latest/)). # Installation -pysatMadrigal may be installed through pip or by cloning the git repository +The following instructions provide a guide for installing pysatSpaceWeather and +give some examples on how to use the routines. + +## Prerequisites + +pysatMadrigal uses common Python modules, as well as modules developed by and +for the Space Physics community. This module officially supports Python 3.7+. + +| Common modules | Community modules | +| -------------- | ----------------- | +| h5py | madrigalWeb | +| numpy | pysat >= 3.0.0 | +| pandas | | +| xarray | | + + +## PyPi Installation ``` pip install pysatMadrigal ``` +## GitHub Installation ``` git clone https://github.com/pysat/pysatMadrigal.git ``` @@ -35,22 +52,10 @@ python setup.py install Note: pre-0.1.0 version ----------------------- -pysatMadrigal is currently provided as an alpha pre-release. Much of the API is -being built off of the upcoming pysat 3.0.0 software in order to streamline the -usage and test coverage. This version of pysat is planned for release later -this year. Currently, you can access the develop version of this through -github: +pysatMadrigal is currently provided as an alpha pre-release. Feedback and +contributions are appreciated. -``` -git clone https://github.com/pysat/pysat.git -cd pysat -git checkout develop-3 -python setup.py install -``` - -It should be noted that this is a working branch and is subject to change. - -# Using with pysat +# Examples The instrument modules are portable and designed to be run like any pysat instrument. @@ -58,6 +63,14 @@ instrument. ``` import pysat from pysatMadrigal.instruments import dmsp_ivm - ivm = pysat.Instrument(inst_module=dmsp_ivm, tag='utd', inst_id='f15') ``` + +Another way to use the instruments in an external repository is to register the +instruments. This only needs to be done the first time you load an instrument. +Afterward, pysat will identify them using the `platform` and `name` keywords. + +``` +pysat.utils.registry.register('pysatMadrigal.instruments.dmsp_ivm') +dst = pysat.Instrument('dmsp', 'ivm', tag='utd', inst_id='f15') +``` From 483a9c670749af3533e3eb489bb709abb28ecef4 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:40:02 -0400 Subject: [PATCH 05/11] MAINT: cycled python versions Cycled the supported python versions and removed the pytest-flake8 options. --- setup.cfg | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/setup.cfg b/setup.cfg index 4ffee39..94e2506 100644 --- a/setup.cfg +++ b/setup.cfg @@ -26,7 +26,6 @@ classifiers = License :: OSI Approved :: BSD License Natural Language :: English Programming Language :: Python :: 3 :: Only - Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 Operating System :: MacOS :: MacOS X @@ -53,6 +52,7 @@ omit = */instruments/templates/ [flake8] max-line-length = 80 +ignore = W503 [tool:pytest] markers = @@ -60,7 +60,4 @@ markers = download: tests for downloadable instruments no_download: tests for instruments without download support first: first tests to run - second: second tests to run -flake8-ignore = - *.py W503 - docs/conf.py ALL + second: second tests to run \ No newline at end of file From 1102461f89c98a162b45a88c8c429955fd6db798 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:40:27 -0400 Subject: [PATCH 06/11] MAINT: added flake8 Switched linter from pytest-flake8 to flake8. --- test_requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test_requirements.txt b/test_requirements.txt index 02dae12..03aca35 100644 --- a/test_requirements.txt +++ b/test_requirements.txt @@ -1,8 +1,8 @@ coveralls +flake8 m2r2 numpydoc pytest-cov pytest-ordering -pytest-flake8 sphinx sphinx_rtd_theme From eb5436146e02d3458b563793b6e96a2a0ad314b3 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:40:54 -0400 Subject: [PATCH 07/11] MAINT: cycled supported python versions Cycled the supported python versions and removed the pytest-flake8 call, replacing it with flake8. --- .travis.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 5b4711a..0c200fd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,13 +2,15 @@ language: python dist: xenial jobs: include: - - python: '3.6' - script: pytest --cov=pysatMadrigal/ - name: '3.7 with flake8' python: '3.7' - script: pytest --flake8 --cov=pysatMadrigal/ + script: + - flake8 + - pytest --cov=pysatMadrigal/ - python: '3.8' script: pytest --cov=pysatMadrigal/ + - python: '3.9' + script: pytest --cov=pysatMadrigal/ services: xvfb cache: pip From ca8df17a6280ede94fa502e249ba8f54db15ea60 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:44:48 -0400 Subject: [PATCH 08/11] DOC: added summary changes to log Updated the CHANGELOG with the changes made on this branch. --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a3adef..7af3755 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,10 +7,15 @@ This project adheres to [Semantic Versioning](http://semver.org/). - Deprecations - Restructed Instrument methods, moving `madrigal` to `general` and extracting local methods from the instrument modules to platform-specific method files + - Cycled testing support to cover Python 3.7-3.9 - Enhancements - Added coords from pysat.utils - Added Vertical TEC Instrument - Added documentation + - Updated documentation configuration to improve maintainability + - Updated documentation style, displaying logo on sidebar in html format + - Changed zenodo author name format for better BibTeX compliance + - Updated README information - Bug Fix - Updated Madrigal methods to simplify compound data types and enable creation of netCDF4 files using `Instrument.to_netcdf4()` From f547c53dd71232743d9eddb44624b6a290ae1d64 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:53:57 -0400 Subject: [PATCH 09/11] BUG: fixed image link Fixed the full-path image link to point to the correct repository. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b142032..0dd924a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
- pysatMadrigal + pysatMadrigal
# pysatMadrigal From b45dabf7c4f50b8ffa7fec72033336da7b690077 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Wed, 26 May 2021 08:55:38 -0400 Subject: [PATCH 10/11] MAINT: added newline to end of file Added a newline to end of setup.cfg. --- setup.cfg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 94e2506..10682bf 100644 --- a/setup.cfg +++ b/setup.cfg @@ -60,4 +60,5 @@ markers = download: tests for downloadable instruments no_download: tests for instruments without download support first: first tests to run - second: second tests to run \ No newline at end of file + second: second tests to run + From 81b311309863b7778e2a6bbe635ac13f8adc5d52 Mon Sep 17 00:00:00 2001 From: Angeline Burrell Date: Fri, 28 May 2021 08:53:39 -0400 Subject: [PATCH 11/11] TST: updated flake8 testing command Updated the flake8 testing command, since flake8 will error on warnings by default. Co-authored-by: Jeff Klenzing --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 0c200fd..f40fda5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,7 +5,7 @@ jobs: - name: '3.7 with flake8' python: '3.7' script: - - flake8 + - flake8 . --count --select=E,F,W - pytest --cov=pysatMadrigal/ - python: '3.8' script: pytest --cov=pysatMadrigal/