Merge pull request pysat#1116 from pysat/rc_3_1_0

Release Candidate 3.1.0

.github/workflows/stats.yml

@@ -17,9 +17,9 @@ jobs:
 
     name: Summary of instrument libraries
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
 

CHANGELOG.md

@@ -3,6 +3,80 @@ Change Log
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+[3.1.0] - 2023-06-02
+--------------------
+* New Features
+  * Added a utility to ensure two xarray Datasets can be concatonated, and
+    incorporated this utility into the Instrument file loading
+  * Added unit tests for different file cadences in the Instrument class
+  * Added `to_inst` method to the Constellation class
+  * Added `export_pysat_info` kwarg to `to_netcdf` routines to select whether
+    pysat instrument info is written to files
+  * Added Constellation class examples to the docs tutorial
+  * Added links to the project standards repository to the docs
+  * Improved formatting of custom kwargs when running `print` on an instrument
+  * Added a core utility to update fill values consistently in the data and
+    metadata
+  * Adapted `check_and_make_path` to treat an empty path as the current dir
+  * Added `meta_kwargs` attribute and kwarg to Instrument, allowing full custom
+    specification of the Meta class on instantiation
+  * Expanded MetaLabels type defaults for 'max_val', 'min_val', and 'fill_val'
+    to include more common data types
+  * Added `data_types` input to Meta and certain MetaLabels methods, allowing
+    the default values to be set to the specified data type when multiple types
+    are allowed, ensure these are updated when adding new data to an Instrument
+  * Added `_update_label_types` to MetaLabels, expanding the Python float/int
+    types to include all numpy float/int types
+  * Added `strict_dim_check` for loading xarray Datasets through netCDF
+  * Added `combine_by_coords` kwarg to `io.load_netcdf` for use on multi-file
+    xarray Datasets
+* Deprecations
+  * Deprecated the Instrument kwarg `labels` in favor of `meta_kwargs` and
+    replaced the `meta_labels` attribute with the `meta_kwargs` attribute
+  * Deprecated the `labels` keyword arg in favor of `meta_kwargs` in the
+    netCDF I/O functions and Instrument sub-module
+  * Deprecated the `malformed_index` kwarg in the test instruments.  This is
+    replaced by `non_monotonic_index` and `non_unique_index`
+* Bug Fix
+  * Allow `pysat.instruments.methods.general.list_files` to handle file
+    cadences other than daily or monthly
+  * Allow equality assessments if optional kwargs are used in Instrument
+  * Fixed an issue with setting single variables in xarray coords (#988)
+  * Fixed `pysat.Instrument.bounds` to handle all input types for `step`
+    and `width` regardless of `start` and `stop` time. Also fixed
+    seasonal bounds specified using file names.
+  * Fixed `pysat.utils.io.apply_table_translation_to_file` check for duplicates
+    in the meta translation table
+  * Fixed an issue when passing dates through load_remote_files (#1022)
+  * Fixed a bug where data may not have any times, but still not be empty
+  * Fixed a bug where metadata with values of None are assigned as useful
+    attributes when attaching metadata to xarray objects
+  * Fixed a bug where a multi_file_day non-monotonic xarray index failed to
+    merge datasets (#1005)
+  * Fixed a bug in testing for setting multiple optional load kwargs (#1097)
+  * Fixed a bug when setting xarray data as a tuple
+  * Fixed a bug when loading constellations for partially empty instrument lists
+  * Fixed a bug when cleaning up temporary directories on windows during testing
+  * Fixed a bug in Instrument loading with a pad, where RangeIndex slicing no
+    longer works on an empty series
+* Maintenance
+  * Added roadmap to readthedocs
+  * Improved the documentation in `pysat.utils.files`
+  * Clarified documentation and tests for name slicing support in pandas
+  * Clarified documentation for adding new instruments
+  * Fixed broken links in docs
+  * Updated docstring header underline lengths and addressed documentation
+    build errors and warnings
+  * Additional unit tests for data padding when a data index is non-monotonic.
+  * Deprecated the `malformed_index` kwarg in the test instruments.  This is
+    replaced by `non_monotonic_index` and `non_unique_index`
+  * Set the `instruments.pysat_testing` tag='no_download' to return an empty
+    pandas DataFrame for `load`
+  * Added `constellations.testing_partial`, which loads a partially empty
+    constellation dataset
+  * Reduced default num_samples for constellation test objects
+  * Improved consistency in metadata for test instruments
+
 [3.0.6] - 2022-12-21
 --------------------
 * Bug Fix
@@ -226,6 +300,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
    * Cleaned up excess variables upon import
    * Removed `data_path` check from `pysat.instruments.methods.general.list_files`
    * Compatible with netCDF v1.6.0
+   * Updated default labels in load_netcdf routines to match core pysat metadata
 
 [3.0.1] - 2021-07-28
 --------------------

CONTRIBUTING.md

@@ -13,7 +13,8 @@ are generally held fortnightly.
 Short version
 -------------
 
-* Submit bug reports and feature requests at [GitHub](https://github.com/pysat/pysat/issues)
+* Submit bug reports and feature requests at
+  [GitHub](https://github.com/pysat/pysat/issues)
 
 * Make pull requests to the ``develop`` branch
 
@@ -160,3 +161,14 @@ These include:
   final period
 * When casting is necessary, use `np.int64` and `np.float64` to ensure operating
   system agnosticism
+
+
+Ecosystem Style Guidelines
+--------------------------
+
+If you are creating a new project that you wish to incorporate into the pysat
+ecosystem: welcome!  We have a
+[template repository](https://github.com/pysat/pysatEcosystem_Template) that
+contains many of the common documents needed for a new project that you can use
+to get started. You may find this helpful when getting started, though this
+repository is under active development.

docs/api.rst

@@ -39,6 +39,7 @@ Meta
 
 .. autoclass:: pysat.Meta
    :members:
+   :noindex:
 
 
 .. _api-metalabels:
@@ -57,6 +58,7 @@ MetaHeader
 
 .. autoclass:: pysat.MetaHeader
    :members:
+   :noindex:
 
 
 .. _api-orbits:

docs/citing.rst

@@ -2,10 +2,13 @@ Citations in the pysat ecosystem
 ================================
 
 When referring to this software package, please cite the original paper by
-Stoneback et al [2018] `<https://doi.org/10.1029/2018JA025297>`_ as well as the
-package `<https://doi.org/10.5281/zenodo.1199703>`_. Note that this DOI will
-always point to the latest version of the code.  A list of DOIs for all
-versions can be found at the Zenodo page above.
+Stoneback et al [2018] `<https://ntrs.nasa.gov/citations/20190002337>`_
+as well as the package `<https://doi.org/10.5281/zenodo.1199703>`_. Note that
+this DOI will always point to the latest version of the code.  A list of DOIs
+for all versions can be found at the Zenodo page above. Depending on
+usage, citation of the full ecosystem paper by Stoneback et al [2023] 
+`<https://www.frontiersin.org/articles/10.3389/fspas.2023.1119775/full>`_
+may also be appropriate.
 
 Example for citation in BibTex for a generalized version:
 

docs/conf.py

@@ -85,7 +85,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/devel/pysatEcosystem_Template.rst

@@ -0,0 +1,10 @@
+.. _devel-ecotemp:
+
+pysatEcosystem_Template
+-----------------------
+
+`pysatEcosystem_Template <https://github.com/pysat/pysatEcosystem_Template>`_
+is a repository holding common files contained in all pysat ecosystem
+repositories. This makes it easier to start a new pysat ecosystem package or
+maintain an existing package, as the current project standards will be recorded
+here for ease of reference. These standards are currently under development.

docs/devel/pysatTutorials.rst

@@ -0,0 +1,8 @@
+.. _devel-tut:
+
+pysatTutorials
+--------------
+
+`pysatTutorials <https://github.com/pysat/pysatTutorials>`_ acts as a repository
+for different Jupyter notebooks with tutorials and examples for scientific
+processing and analysis using pysat ecosystem packages.

docs/ecosystem.rst

@@ -50,3 +50,19 @@ The packages listed below provide useful tools for data analysis.
    analysis/pysatModels.rst
    analysis/pysatSeasons.rst
    analysis/pysatSpaceWeather.rst
+
+
+.. _eco_devel:
+
+Development Tools
+=================
+
+The packages listed below are repositories for pysat ecosystem tutorials, as
+well as development standards and tools.
+
+.. toctree::
+   :maxdepth: 2
+
+   devel/pysatEcosystem_Template.rst
+   devel/pysatTutorials.rst
+

docs/examples.rst

@@ -6,9 +6,11 @@ Examples
 The pysat framework reduces the steps needed when performing certain science
 data investigations. It allows you to focus on developing routines that make
 your investigation unique, and creating the output data or visualizations you
-require. This section provides examples, with the full code for each example
-made available in the
-`pysatTutorials <https://github.com/pysat/pysatTutorials>`_ repository.
+require. This section provides examples, with the full code for each example,
+as well as additional examples, made available in the
+`pysatTutorials <https://github.com/pysat/pysatTutorials>`_ repository, as 
+well as the recent `PyHC Summer School tutorials 
+<https://github.com/pysat/summer-school/tree/main/pysat-tutorial>`_.
 
 .. toctree::
    :maxdepth: 2

docs/index.rst

@@ -20,5 +20,6 @@ Welcome to pysat's documentation!
    dependency.rst
    api.rst
    contributing.rst
+   roadmap.rst
    faq.rst
    release_notes.rst