Documentation Improvements regarding JOSS Reviews (#13)

* Improvements to documentation * Pinned dependencies to avoid test errors * Add matplotlib dependency * Move demos back to parent directory * Switch to setup.cfg for package description * Changes for JOSS review --------- Co-authored-by: Joe Ranalli <[email protected]>
jranalli · Sep 13, 2024 · 7f1f965 · 7f1f965
1 parent 31588d3
commit 7f1f965
Show file tree

Hide file tree

Showing 42 changed files with 129 additions and 75 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -21,21 +21,6 @@ jobs:
         python -m pip install --upgrade pip
         pip install -e .[tests]
 
-    - name: Test cmv
+    - name: Run All Tests
       working-directory: ./tests
-      run: pytest test_cmv.py
-    - name: Test field
-      working-directory: ./tests
-      run: pytest test_field.py
-    - name: Test irradiance
-      working-directory: ./tests
-      run: pytest test_irradiance.py
-    - name: Test signalproc
-      working-directory: ./tests
-      run: pytest test_signalproc.py
-    - name: Test spatial
-      working-directory: ./tests
-      run: pytest test_spatial.py
-    - name: Test stats
-      working-directory: ./tests
-      run: pytest test_stats.py
+      run: pytest
diff --git a/Changelog.md b/Changelog.md
@@ -12,35 +12,35 @@ the primary impact being on my individual use. Beginning with version 0.4.0,
 the package will adopt a consistent approach and will strive to maintain 
 backwards compatibility for releases within the same minor version (0.X.X). 
 
-# Version 0.2
+# Version 0.2 - Jun 15, 2022
 First public release of the package via PyPi
-# Version 0.2.1
+# Version 0.2.1 - Jul 17, 2022
 - Add wrapper for `pvlib.clearsky_index` to handle pandas type
-# Version 0.2.2
+# Version 0.2.2 - July 27, 2022
 - Change input to camfilter to handle references that don't coincide with the 
 site itself. 
 - ** Breaks backwards compatibility **
 # Version 0.2.3
 - Add methods for calculating delay between signals to `signalproc`
-# Version 0.2.4
+# Version 0.2.4 - Oct 19, 2023
 - Add some additional options to `cmv` for qc and filtering of the data
 # Version 0.2.5
 - Add location analysis in `field` package
-# Version 0.3.1
+# Version 0.3.1 - Nov 8, 2023
 - Expands `field` analysis capability
 - Add comprehensive testing
 - ** Breaks backwards compatibility **
-# Version 0.3.2
+# Version 0.3.2 - Nov 14, 2023
 - Major speed improvements via vectorization of CMV 
 - ** Breaks backwards compatibility due to function signature changes **
-# Version 0.3.3
+# Version 0.3.3 - Nov 17, 2023
 - Major speed improvements to field analysis (vectorization of transfer function delays)
 - ** Breaks backwards compatibility **
-# Version 0.3.4
+# Version 0.3.4 - Nov 21, 2023
 - Bug fix for handling and excluding NaN within `field`
-# Version 0.3.5
+# Version 0.3.5 - Dec 18, 2023
 - Add multi-column support to several functions in `stats`. Thanks to Scott Sheppard for the suggestion.
-# Version 0.4.0
+# Version 0.4.0 - Apr 10, 2024
 - Added some functions to `field` to support automated remapping.
     - See `field_reassignment_demo` for details.
 - Added a function to `cmv` for identifying an optimum subset of CMV pairs. 
@@ -54,10 +54,17 @@ site itself.
     - `field_demo_full_process` - Overview of the full field processing workflow 
     - `field_demo_full_process_multithread` - Same as previous but including multithreading support for speed
 - Added tests of these new functions for more completeness.
-# Version 0.4.1
+# Version 0.4.1 - Aug 8, 2024
 - Bug fix for `cmv` so that `jamaly` r_corr is always positive. 
 - Demo for digitizing a plant equipment layout added by @williamhobbs
 - Improve comments in `cmv_demo`
 - Add sphinx documentation for entire library
-# Version 0.4.2
-- Rename the library to solarspatialtools
+# Version 0.4.2 - Aug 8 - 2024
+- Rename the library to solarspatialtools
+# Version 0.4.3 & 0.4.4 - Aug 8, 2024
+- Fixes to GitHub deployment issues, no functional changes
+# Version 0.4.5 - Sept 13, 2024
+- Improvements to documentation
+- Simplification of github actions
+- Added matplotlib dependency
+- Move demos back to the parent directory using nblink
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021-2024, Joe Ranalli
+Copyright (c) 2021, Joe Ranalli
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/README.md b/README.md
@@ -7,13 +7,27 @@ Two examples of what are believed to be the most generally useful techniques thi
 - Processing the cloud motion vector from a distributed sensor network. 
 - Verifying the locations of field components (e.g. combiners) within a distributed network of measurements
 
+[![ReadTheDocs status](https://readthedocs.org/projects/solarspatialtools/badge/?version=stable)](https://solarspatialtools.readthedocs.io/en/stable/?badge=stable)
+[![test status](https://github.com/jranalli/solarspatialtools/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jranalli/solarspatialtools/actions/workflows/tests.yml/badge.svg?branch=main)
+
+[![joss status](https://joss.theoj.org/papers/04aaa860013faf055d69b673d44f5fab/status.svg)](https://joss.theoj.org/papers/04aaa860013faf055d69b673d44f5fab)
+
+
+
 # Installation
-The package can be most easily installed via [PyPi](https://pypi.org/project/solartoolbox/) 
+The package can be most easily installed via [PyPi](https://pypi.org/project/solarspatialtools/) 
 with the following command:
 ```bash
 pip install solarspatialtools
 ```
 
+If you wish to run the demo jupyter notebooks locally, you can specify that the additional dependencies should also be installed when you install the package:
+```bash
+pip install solarspatialtools[demos]
+```
+
+Alternatively, you could manually install `jupyter` in your environment.
+
 # Getting Started
 A number of example codes are available in the demos folder. These are meant to demonstrate what are believed to be the most useful functions in the package and applications of the functions to real sample data included with the library.
 
@@ -31,6 +45,8 @@ The codes are organized into a few subpackages and several function libraries.
 The subpackages are meant to contain tools that are related to a specific
 task. 
 
+Full API documentation is available at ReadTheDocs: [https://solarspatialtools.readthedocs.io/en/stable/](https://solarspatialtools.readthedocs.io/en/stable/)
+
 ### Packages
 ```dataio```  
 A package with codes for accessing a couple of distributed irradiance datasets 
@@ -120,20 +136,22 @@ of each hour of the day over a 30 day window)
 ```field```
 Functions for predicting the position of field components on the basis of cloud
 motion. 
+- [Ranalli and Hobbs (2024)](https://doi.org/10.1109/JPHOTOV.2024.3366666)
+- Ranalli and Hobbs (2024, IEEE PVSC, forthcoming)
 
 
 # Contributing
 This is an open source project and appreciates participation, engagement and contribution from community members. Development on the library is active and the project seeks to provide a useful tool for the research community. The project is currently maintained by an individual researcher, and the process for contributions is not as formalized as it might be for larger projects.     
 
-If you've found a bug or have an idea for a new feature, please open an [issue](https://github.com/jranalli/solartoolbox/issues) 
-on GitHub. Questions can be asked in the GitHub [discussions](https://github.com/jranalli/solartoolbox/discussions).
+If you've found a bug or have an idea for a new feature, please open an [issue](https://github.com/jranalli/solarspatialtools/issues) 
+on GitHub. Questions can be asked in the GitHub [discussions](https://github.com/jranalli/solarspatialtools/discussions).
 
 Code contributions are also welcome! Please follow the instructions in GitHub's [getting started guide](https://docs.github.com/en/get-started/start-your-journey/hello-world) to open a pull request. 
 
 Changes to the contribution guidelines and policies may be made in the future in response to growth of the project and community.
 
 # License
-This project is licensed under the BSD 3-Clause License - see the [LICENSE](https://github.com/jranalli/solartoolbox/blob/main/LICENSE) file for full details. 
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](https://github.com/jranalli/solarspatialtools/blob/main/LICENSE) file for full details. 
 
 # History
 SolarSpatialTools began as a library of tools developed to support my own 

diff --git a/...hinx/source/demos/automate_cmv_demo.ipynb → demos/automate_cmv_demo.ipynb b/...hinx/source/demos/automate_cmv_demo.ipynb → demos/automate_cmv_demo.ipynb
diff --git a/.../sphinx/source/demos/automate_cmv_demo.py → demos/automate_cmv_demo.py b/.../sphinx/source/demos/automate_cmv_demo.py → demos/automate_cmv_demo.py
diff --git a/docs/sphinx/source/demos/cmv_demo.ipynb → demos/cmv_demo.ipynb b/docs/sphinx/source/demos/cmv_demo.ipynb → demos/cmv_demo.ipynb
diff --git a/docs/sphinx/source/demos/cmv_demo.py → demos/cmv_demo.py b/docs/sphinx/source/demos/cmv_demo.py → demos/cmv_demo.py
diff --git a/...source/demos/data/digitized_plant.geojson → demos/data/digitized_plant.geojson b/...source/demos/data/digitized_plant.geojson → demos/data/digitized_plant.geojson
diff --git a/.../demos/data/digitized_plant_centroids.csv → demos/data/digitized_plant_centroids.csv b/.../demos/data/digitized_plant_centroids.csv → demos/data/digitized_plant_centroids.csv
diff --git a/...e/demos/data/digitized_plant_centroids.h5 → demos/data/digitized_plant_centroids.h5 b/...e/demos/data/digitized_plant_centroids.h5 → demos/data/digitized_plant_centroids.h5
diff --git a/...demos/data/digitized_plant_meters.geojson → demos/data/digitized_plant_meters.geojson b/...demos/data/digitized_plant_meters.geojson → demos/data/digitized_plant_meters.geojson
diff --git a/...inx/source/demos/data/hope_melpitz_10s.h5 → demos/data/hope_melpitz_10s.h5 b/...inx/source/demos/data/hope_melpitz_10s.h5 → demos/data/hope_melpitz_10s.h5
diff --git a/...hinx/source/demos/data/hope_melpitz_1s.h5 → demos/data/hope_melpitz_1s.h5 b/...hinx/source/demos/data/hope_melpitz_1s.h5 → demos/data/hope_melpitz_1s.h5
diff --git a/...phinx/source/demos/data/sample_plant_1.h5 → demos/data/sample_plant_1.h5 b/...phinx/source/demos/data/sample_plant_1.h5 → demos/data/sample_plant_1.h5
diff --git a/...phinx/source/demos/data/sample_plant_2.h5 → demos/data/sample_plant_2.h5 b/...phinx/source/demos/data/sample_plant_2.h5 → demos/data/sample_plant_2.h5
diff --git a/docs/sphinx/source/demos/field_demo.ipynb → demos/field_demo.ipynb b/docs/sphinx/source/demos/field_demo.ipynb → demos/field_demo.ipynb
@@ -593,7 +593,11 @@
   },
   {
    "cell_type": "markdown",
-   "source": "It's necessary to provide the CMV for each time period. These precomputed values for the time periods in the data file are provided here. It's also possible to compute them directly using methods in `solarspatialtools.cmv`. Note that it's necessary for the CMVs to be roughly perpendicular, because the matrix calculation associated with triangulating the predicted position becomes singular for CMVs that are too close to parallel (or anti-parallel).",
+   "source": [
+    "It's necessary to provide the CMV for each time period. These precomputed values for the time periods in the data file are provided here. It's also possible to compute them directly using methods in `solarspatialtools.cmv`. Note that it's necessary for the CMVs to be roughly perpendicular, because the matrix calculation associated with triangulating the predicted position becomes singular for CMVs that are too close to parallel (or anti-parallel).\n",
+    "\n",
+    "One other potential issue with CMVs is that the `spatialsolartools.cmv` module is also based on accurate knowledge of the combiner positions. In our experience, even plants with small numbers of scrambled combiners can still produce useful CMVs, because the position errors are averaged out when including all the combiners in the entire plant. A completely scrambled plant with no confidence in any of the combiner positions would likely require special handling, or CMVs from an independent source. But users should be aware of this as a potential limitation of the technique for very low confidence plant maps.  "
+   ],
    "metadata": {
     "collapsed": false
    },

diff --git a/docs/sphinx/source/demos/field_demo.py → demos/field_demo.py b/docs/sphinx/source/demos/field_demo.py → demos/field_demo.py
@@ -13,7 +13,13 @@
 # two time periods A) and B) that represent two different CMV periods
 datafile = "data/sample_plant_2.h5"
 
-# Input the CMVs, see cmv_demo.py for examples of how to calculate these
+# Input the CMVs, see cmv_demo.py for examples of how to calculate these. It's
+# important to note that the CMVs as calculated using the CMV module would be
+# dependant on accurate field positions. So it's important in this step that
+# the CMVs either come from an independent source, or that the errors in the
+# field positions are isolated incidents, and the location data for the plant
+# as a whole is somewhat accurate. Plants that were completely scrambled would
+# likely require special treatment that we haven't tested the method on.
 cmv_a = spatial.pol2rect(9.52, 0.62)
 cmv_b = spatial.pol2rect(8.47, 2.17)
 

diff --git a/...nx/source/demos/field_demo_detailed.ipynb → demos/field_demo_detailed.ipynb b/...nx/source/demos/field_demo_detailed.ipynb → demos/field_demo_detailed.ipynb
diff --git a/...x/source/demos/field_demo_full_process.py → demos/field_demo_full_process.py b/...x/source/demos/field_demo_full_process.py → demos/field_demo_full_process.py
diff --git a/...os/field_demo_full_process_multithread.py → demos/field_demo_full_process_multithread.py b/...os/field_demo_full_process_multithread.py → demos/field_demo_full_process_multithread.py
diff --git a/...ource/demos/field_reassignment_demo.ipynb → demos/field_reassignment_demo.ipynb b/...ource/demos/field_reassignment_demo.ipynb → demos/field_reassignment_demo.ipynb
diff --git a/...x/source/demos/field_reassignment_demo.py → demos/field_reassignment_demo.py b/...x/source/demos/field_reassignment_demo.py → demos/field_reassignment_demo.py
diff --git a/docs/sphinx/source/demos/images/qgis_01.png → demos/images/qgis_01.png b/docs/sphinx/source/demos/images/qgis_01.png → demos/images/qgis_01.png
diff --git a/docs/sphinx/source/demos/images/qgis_02.png → demos/images/qgis_02.png b/docs/sphinx/source/demos/images/qgis_02.png → demos/images/qgis_02.png
diff --git a/docs/sphinx/source/demos/images/qgis_03.png → demos/images/qgis_03.png b/docs/sphinx/source/demos/images/qgis_03.png → demos/images/qgis_03.png
diff --git a/docs/sphinx/source/demos/images/qgis_04.png → demos/images/qgis_04.png b/docs/sphinx/source/demos/images/qgis_04.png → demos/images/qgis_04.png
diff --git a/docs/sphinx/source/demos/images/qgis_05.png → demos/images/qgis_05.png b/docs/sphinx/source/demos/images/qgis_05.png → demos/images/qgis_05.png
diff --git a/docs/sphinx/source/demos/images/qgis_06.png → demos/images/qgis_06.png b/docs/sphinx/source/demos/images/qgis_06.png → demos/images/qgis_06.png
diff --git a/...ce/demos/plant_digitization_example.ipynb → demos/plant_digitization_example.ipynb b/...ce/demos/plant_digitization_example.ipynb → demos/plant_digitization_example.ipynb
diff --git a/docs/sphinx/source/demos/signalproc_demo.py → demos/signalproc_demo.py b/docs/sphinx/source/demos/signalproc_demo.py → demos/signalproc_demo.py
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -11,7 +11,7 @@
 author = 'Joe Ranalli'
 
 release = '0.4'
-version = '0.4.4'
+version = '0.4.5'
 
 import os
 import sys
@@ -26,6 +26,7 @@
               'sphinx.ext.autosummary',
               'sphinx.ext.intersphinx',
               'nbsphinx',
+              'nbsphinx_link',
               ]
 
 intersphinx_mapping = {
@@ -49,3 +50,6 @@
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
 
+# Hide warning per sphinx #12300, appears to come from nbsphinx or nbsphinx_link
+suppress_warnings = ["config.cache"]
+
diff --git a/docs/sphinx/source/demos/automate_cmv_demo.nblink b/docs/sphinx/source/demos/automate_cmv_demo.nblink
@@ -0,0 +1,3 @@
+{
+  "path":"../../../../demos/automate_cmv_demo.ipynb"
+}
diff --git a/docs/sphinx/source/demos/cmv_demo.nblink b/docs/sphinx/source/demos/cmv_demo.nblink
@@ -0,0 +1,3 @@
+{
+  "path":"../../../../demos/cmv_demo.ipynb"
+}
diff --git a/docs/sphinx/source/demos/field_demo.nblink b/docs/sphinx/source/demos/field_demo.nblink
@@ -0,0 +1,3 @@
+{
+  "path":"../../../../demos/field_demo.ipynb"
+}
diff --git a/docs/sphinx/source/demos/field_demo_detailed.nblink b/docs/sphinx/source/demos/field_demo_detailed.nblink
@@ -0,0 +1,3 @@
+{
+  "path":"../../../../demos/field_demo_detailed.ipynb"
+}
diff --git a/docs/sphinx/source/demos/field_reassignment_demo.nblink b/docs/sphinx/source/demos/field_reassignment_demo.nblink
@@ -0,0 +1,3 @@
+{
+  "path":"../../../../demos/field_reassignment_demo.ipynb"
+}
diff --git a/docs/sphinx/source/demos/plant_digitization_example.nblink b/docs/sphinx/source/demos/plant_digitization_example.nblink
@@ -0,0 +1,6 @@
+{
+  "path":"../../../../demos/plant_digitization_example.ipynb",
+  "extra-media":[
+    "../../../../demos/images"
+  ]
+}
diff --git a/setup.cfg b/setup.cfg
@@ -1,2 +1,43 @@
 [metadata]
-description_file = README.md
+name = solarspatialtools
+version = 0.4.5
+author = 'Joe Ranalli'
+author_email = [email protected]
+description = A package for spatial analysis of solar energy and solar irradiance
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/jranalli/solarspatialtools
+project_urls =
+    Bug Tracker = https://github.com/jranalli/solarspatialtools/issues
+    Documentation = https://solarspatialtools.readthedocs.io
+classifiers =
+    Programming Language :: Python :: 3
+    License :: OSI Approved :: BSD (3 Clause)
+    Operating System :: OS Independent
+    Topic :: Scientific/Engineering
+    Intended Audience :: Science/Research
+
+[options]
+install_requires =
+    numpy<2
+    pandas<=2.2.2
+    tables<=3.9.2
+    pyproj<=3.6.1
+    pvlib<=0.11.0
+    netcdf4<1.7.2
+    scipy<=1.14.0
+    matplotlib<=3.9.2
+
+[options.extras_require]
+tests =
+    pytest
+
+demos =
+    jupyter
+
+docs =
+    sphinx
+    sphinx_rtd_theme
+    nbsphinx
+    ipython
+    nbsphinx-link
diff --git a/setup.py b/setup.py
diff --git a/tests/test_cmv.py b/tests/test_cmv.py
@@ -97,7 +97,7 @@ def test_cmv_artificial(theta_deg, velocity, mode):
 
 
 def test_cmv_gagne_data():
-    datafile = "../docs/sphinx/source/demos/data/sample_plant_1.h5"
+    datafile = "../demos/data/sample_plant_1.h5"
     pos_utm = pd.read_hdf(datafile, mode="r", key="utm")
     df = pd.read_hdf(datafile, mode="r", key="data_a")
 
@@ -115,7 +115,7 @@ def test_cmv_gagne_data():
 
 
 def test_cmv_jamaly_data():
-    datafile = "../docs/sphinx/source/demos/data/sample_plant_1.h5"
+    datafile = "../demos/data/sample_plant_1.h5"
     pos_utm = pd.read_hdf(datafile, mode="r", key="utm")
     df = pd.read_hdf(datafile, mode="r", key="data_a")
 
@@ -133,7 +133,7 @@ def test_cmv_jamaly_data():
 def test_cmv_jamaly_data_ref():
     # A test using a reference when we calculate the CMV
 
-    datafile = "../docs/sphinx/source/demos/data/sample_plant_1.h5"
+    datafile = "../demos/data/sample_plant_1.h5"
     pos_utm = pd.read_hdf(datafile, mode="r", key="utm")
     df = pd.read_hdf(datafile, mode="r", key="data_a")
 

diff --git a/tests/test_field.py b/tests/test_field.py
@@ -88,7 +88,7 @@ def test_compute_predicted_position_static(refdat):
     ref = refdat[2][0]
     expect = refdat[2][1]
 
-    datafile = "../docs/sphinx/source/demos/data/sample_plant_2.h5"
+    datafile = "../demos/data/sample_plant_2.h5"
     cmv_a = spatial.pol2rect(9.52, 0.62)
     cmv_b = spatial.pol2rect(8.47, 2.17)