Add documentation

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Deploy Sphinx documentation to Pages
+# See: https://github.com/marketplace/actions/sphinx-to-github-pages
+on:
+  push:
+    branches:
+    - main
+
+jobs:
+  pages:
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - id: deployment
+      uses: sphinx-notes/pages@v3

.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_static/
+docs/_templates/
 
 # PyBuilder
 target/

README.md

@@ -1,7 +1,19 @@
-# UADAPy
+# UADAPy - Uncertainty-aware Data Analysis with Python
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+![Alt text](image.png)
+
 UADAPy is a Python library to support an easy analysis of uncertain data.
 
+The library provides:
+- uncertainty-aware algorithms for different visualization algorithms, including UAMDS
+- easy-to-use visualizations for uncertain data
+
+## Installation
 So far the library is very much work in progress, but you can already use it via pip:
 ```
-pip install git+https://github.com/hageldave/uadapy
+pip install git+https://github.com/UniStuttgart-VISUS/uadapy
 ```
+
+## Documentation
+You can find the documentation here: https://unistuttgart-visus.github.io/uadapy/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/changelog.rst

@@ -0,0 +1,14 @@
+=========
+Changelog
+=========
+
+0.1
+---
+Features in first version:
+
+* Uncertainty-aware Principle Component Analysis
+* Uncertainty-aware Multi-dimensional Scaling
+* Basic visualizations:
+
+    * N-dimensional distributions: scatterplot matrices, iso-lines of probability distribution
+    * 1D distributions: box plots, violin plots, dot plots

docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sphinx_rtd_theme
+
+project = 'UADAPy'
+copyright = '2024, Ruben Bauer, Marina Evers, David Hägele, Patrick Paetzold'
+author = 'Ruben Bauer, Marina Evers, David Hägele, Patrick Paetzold'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+  "sphinx_rtd_theme",
+  "sphinx.ext.autodoc",
+  "sphinx.ext.napoleon"
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/examples.rst

@@ -0,0 +1,20 @@
+========
+Examples
+========
+
+The following jupyter notebooks contain examples on how to use the library.
+
+Uncertainty-aware multidimensional scaling
+------------------------------------------
+
+`Load data, reduce the dimensionality with UAMDS, visualize the output <https://github.com/UniStuttgart-VISUS/uadapy/blob/main/examples/uamds.ipynb>`_
+
+Uncertainty-aware principal component analysis
+------------------------------------------
+
+`Load data, reduce the dimensionality with UAPCA, visualize the output <https://github.com/UniStuttgart-VISUS/uadapy/blob/main/examples/uapca.ipynb>`_
+
+Working with own data
+------------------------------------------
+
+`Load data, create a distribution, visualize it <https://github.com/UniStuttgart-VISUS/uadapy/blob/main/examples/ownData.ipynb>`_

docs/index.rst

@@ -0,0 +1,16 @@
+==================================================
+UADAPy - Uncertainty-aware Data Analysis in Python
+==================================================
+UADAPy is a Python library to support an easy analysis of uncertain data. Here you find the most important information to get started.
+
+.. toctree::
+   :maxdepth: 1
+
+   changelog.rst
+   installation.rst
+   examples.rst
+
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`modindex`

docs/installation.rst

@@ -0,0 +1,12 @@
+Installation
+============
+Installation via pip
+--------------------
+
+You can install the library by typing:
+
+.. code-block:: console
+
+    pip install git+https://github.com/UniStuttgart-VISUS/uadapy
+
+The library was tested under Windows.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules.rst

@@ -0,0 +1,7 @@
+uadapy
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   uadapy

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx_rtd_theme

docs/uadapy.dr.rst

@@ -0,0 +1,29 @@
+uadapy.dr package
+=================
+
+Submodules
+----------
+
+uadapy.dr.uamds module
+----------------------
+
+.. automodule:: uadapy.dr.uamds
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.dr.uapca module
+----------------------
+
+.. automodule:: uadapy.dr.uapca
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: uadapy.dr
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/uadapy.plotting.rst

@@ -0,0 +1,53 @@
+uadapy.plotting package
+=======================
+
+Submodules
+----------
+
+uadapy.plotting.distribution\_plot module
+-----------------------------------------
+
+.. automodule:: uadapy.plotting.distribution_plot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.plotting.interactive\_splom module
+-----------------------------------------
+
+.. automodule:: uadapy.plotting.interactive_splom
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.plotting.plots2D module
+------------------------------
+
+.. automodule:: uadapy.plotting.plots2D
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.plotting.plotsND module
+------------------------------
+
+.. automodule:: uadapy.plotting.plotsND
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.plotting.utils module
+----------------------------
+
+.. automodule:: uadapy.plotting.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: uadapy.plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/uadapy.rst

@@ -0,0 +1,46 @@
+uadapy package
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   uadapy.dr
+   uadapy.plotting
+
+Submodules
+----------
+
+uadapy.data module
+------------------
+
+.. automodule:: uadapy.data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.distribution module
+--------------------------
+
+.. automodule:: uadapy.distribution
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+uadapy.test\_distrib module
+---------------------------
+
+.. automodule:: uadapy.test_distrib
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: uadapy
+   :members:
+   :undoc-members:
+   :show-inheritance:

example.py

@@ -19,7 +19,7 @@ def example_uamds():
     #plotsND.plot_contour_samples(distribs_lo, 10000, 128, None, [5, 25, 50, 75, 95])
 
 def example_kde():
-    samples = np.random.randn(1000,2)
+    samples = np.random.randn(1000, 2)
     distr = ua.distribution.distribution(samples)
     plots2D.plot_contour(distr)