Improvements, Rework, Documentation, & Release v2 (#20)

* testing commits from colab * testing changing files from colab * fixed typo * added dataset file * added more data files * fixed where file points to * allowed the use of either k or Bend during sampling * testing new model: regularization but with fixed alpha * tweak to fix graphing * adjusted step order to match paper * incorporating info from the model into the trace object * testing new plotting * new plots for just P and V + improvements to existing plots * updates to readme and some cleanup * updates to V and P plotting functions * added ability to plot confidence intervals for V, B, and P * update plotV for better inclusion of default values * update plotcorrelations for better customization * normalize P in gaussian model * updates to plotting for V and P * created a rudimentary pyproject.toml (unfinished) * finished pyproject.toml and updated README * cleaned up and added documentation for dive.model() * cleaned up and added documentation for remaining functions in model.py * cleaned up and added documentation for models.py and samplers.py * cleaned up and added documentation for models.py and saving.py * quick fix to dive.load_trace() * added documentation to most of plotting.py * finished documentation for plotting.py and minor updates * bugfixes * documentation for utils.py * documentation for deer.py * removed extraneous comments * removed no-longer-useful notebook * added documentation for deerload.py * added documentation for test_data.py * fixed typo * bugfix for sampling * bugfix for saving * bugfix for saving pt2 * bugfix for saving pt3 * bugfix for saving pt4 * bugfix for plot_correlations * bugfix for running traces * removed include_amplitude, include_background, and include_mod_depth * temporary (nonworking) rudimentary test folder * update dependencies * fixed pytests * updates to test_data.py * update readme * added rudimentary documentation * Create sphinx.yml * added furo as requirement * added furo as requirement in conf.py * try sphinx_rtd_theme * make sphinx.yml install dependencies * try alabaster theme * remove link to dive-scripts * make sphinx.yml update if run on /docs branch * autogenerated docs for functions * added usage guide * fixed usage guide * try numpydoc in extensions * update conf.py to import modules * update conf.py to import modules pt2 * update conf.py to import modules pt3 * update conf.py to import modules pt4 * update conf.py to import modules pt5 * attempt to support numpydoc * attempt to use sphinx.ext.napoleon * attempt to use sphinx.ext.napoleon * attempt to use sphinx_rtd_theme * update sphinx.yml to install sphinx-rtd-theme * attempt to use sphinx_rtd_theme pt2 * attempt to use sphinx_rtd_theme pt3 * attempt to use sphinx_rtd_theme pt4 * attempt to use sphinx_rtd_theme pt5 * reattempt to use napoleon for numpy documentation * reattempt to use napoleon for numpy documentation pt2 * reattempt to use napoleon for numpy documentation pt3 * reattempt to use napoleon for numpy documentation pt4 * reattempt to use napoleon for numpy documentation pt5 * try fixing autodoc * try fixing autodoc pt2 * try fixing autodoc pt3 * remove bad pages * try mocking all imports * try mocking all imports pt2 * update sphinx.yml to install more packages * try changing filepath * try changing filepath pt2 * try adjusting spacing * fix docstring errors and unmock dive * include numpy * update sphinx.yml to use python 3.10 * update sphinx.yml to no longer use outdated library * Update sphinx.yml to install ipython * Update README with updated documentation link * Update sphinx.yml to only update only on pushes to `docs` * Update README.md for more detailed install instructions * Added numpy as requirement + link to docu * Update index.rst slightly * Create publish-test.yml to publish to TestPyPI * Update index.rst and upload documentation * fix bug in models.py when r not given * fix bug in models.py when r not provided * Added howtoguide.ipynb * move howtoguide * Remove metadata from setup.py Metadata is already present at pyproject.toml * Update LICENSE * Remove mock imports * Try sphinx-rtd-theme * use sphinx-rtd-theme * import ArrayLike and ColorType * Update conf.py to include ArrayLike and ColorType * fix typo * reattempt for ArrayLike and ColorType
StollLab · Aug 12, 2024 · 0655a7d · 0655a7d
1 parent 3611900
commit 0655a7d
Show file tree

Hide file tree

Showing 42 changed files with 4,809 additions and 1,228 deletions.
diff --git a/.github/workflows/publish-test.yml b/.github/workflows/publish-test.yml
@@ -0,0 +1,95 @@
+name : Publish to TestPyPI
+
+on : push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-testpypi:
+    name: >-
+      Publish to TestPyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/dive-MCMC
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+
+  github-release:
+    name: >-
+      Sign the distribution with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-testpypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/[email protected]
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'
diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml
@@ -0,0 +1,43 @@
+name: "Sphinx: Render docs"
+
+on:
+  push:
+    branches: [docs]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.10' 
+    - name: Install dependencies
+      run: |
+           python -m pip install --upgrade pip
+           python -m pip install sphinx
+           python -m pip install sphinx-rtd-theme  
+           python -m pip install sphinx_mdinclude
+           python -m pip install pymc
+           python -m pip install deerlab
+           python -m pip install scipy
+           python -m pip install matplotlib
+           python -m pip install pandas
+           python -m pip install ipython
+           python -m pip install sphinx-rtd-theme
+    - name: Build HTML
+      run: |
+           sphinx-build -E -b html docs/source docs/build/html
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/docs'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Stephan Pribitzer, Sarah Sweger, Stefan Stoll
+Copyright (c) 2024 Sarah Sweger, Julian Cheung, Lukas Zha, Stephan Pribitzer, Stefan Stoll
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,33 +1,47 @@
 # dive
 
 ### About
-`dive` is a Python package for Bayesian analysis of dipolar EPR (electron paramagnetic resonance) spectroscopy data.
+`dive` is a Python package for Bayesian analysis of dipolar EPR (electron paramagnetic resonance) spectroscopy data through Markov chain Monte Carlo (MCMC) sampling with the Python package [PyMC](https://www.pymc.io).
 
 ### Requirements
 
-`dive` is available for Windows, Mac and Linux systems and requires **Python 3.8** or later and **PyMC 4.0** or later.
+`dive` is available for Windows, Mac and Linux systems and requires **Python 3.9** or later and **PyMC 5.0** or later.
 
+### Features
+
+`dive`'s features include:
+- An output InferenceData object containing many random posterior samples for each parameter
+- Full uncertainty quantification for all model parameters, including the distance distribution
+- Visualizations for ensembles of fitted signals and residuals
+- Visualizations for ensembles of fitted distance distributions
+- Histograms for margnialized posteriors of other parameters such as modulation depth and background decay rate
+
 ### Setup
 
-As long as `dive` is in a development state, use the following installation procedure:
+You can install `dive` using `pip`. Please note that the installation name is `dive-MCMC`.
 
-If using `conda`, install the following packages to the environment of your choice:
+    pip install dive-MCMC
+
+You can also directly clone the `dive` directory. Please make sure to also import the necessary packages.
 
-    conda install mkl-service libpython m2w64-toolchain scipy matplotlib pandas
+    pip install pymc deerlab scipy matplotlib numpy pandas mkl-service h5netcdf pytest
+    git clone https://github.com/StollLab/dive
 
-In order to get the newest version of `pymc`, it is necessary to run
+`dive` can then be used by importing the package as usual.
 
-    pip install pymc 
+    import dive
 
-Unfortunately, the `conda-forge` version is usually deprecated.
+<!-- As long as `dive` is in a development state, use the following installation procedure:
 
-After successful installation of `pymc`, navigate to the directory that contains the `dive` source code and run
+If using `conda`, install the following packages to the environment of your choice:
+
+    conda install pymc deerlab scipy matplotlib pandas mkl-service h5netcdf pytest
 
-    python setup.py develop
+You can also use `pip`.
 
-For drawing graphs of the models, you will need `python-graphviz`, which can be installed with
+After successful installation of dependencies, navigate to the directory that contains the `dive` source code and run
 
-    conda install -c conda-forge python-graphviz
+    python setup.py develop -->
 
 <!-- A pre-built distribution can be installed using `pip`.
 
@@ -39,6 +53,10 @@ Next, install dive with
 
     python -m pip install dive -->
 
+### Documentation
+
+See the [documentation](https://stolllab.github.io/dive) for a detailed guide on how to use `dive`. An IPython Notebook guide on using `dive` can also be found under the `examples/` directory.
+
 ### Citation
 
 When you use `dive` in your work, please cite the following publication:
@@ -53,4 +71,4 @@ Sarah R. Sweger, Stephan Pribitzer, and Stefan Stoll <br>
 
 `dive` is licensed under the [MIT License](LICENSE).
 
-Copyright © 2021: Stephan Pribitzer, Sarah Sweger, Stefan Stoll
+Copyright © 2024:  Sarah Sweger, Julian Cheung, Lukas Zha, Stephan Pribitzer, Stefan Stoll
diff --git a/data/3992_test_trace.nc b/data/3992_test_trace.nc
diff --git a/dive-scripts b/dive-scripts