diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..188a2df --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt + +sphinx: + configuration: docs/source/conf.py \ No newline at end of file diff --git a/README.md b/README.md index 119c3cf..a724507 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ MIT license   - build   here. +- We are continuing to expand our library, and are open to suggestions for new models to implement. If you have a model you would like to see implemented, please open an issue on our GitHub page. ## Testing All tests are written using pytest and cover all user accessible code. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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 = source +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/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=source +set BUILDDIR=build + +if "%1" == "" goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..53fc1f3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx==7.1.2 +sphinx-rtd-theme==1.3.0rc1 diff --git a/docs/source/Copulas.rst b/docs/source/Copulas.rst new file mode 100644 index 0000000..81619a3 --- /dev/null +++ b/docs/source/Copulas.rst @@ -0,0 +1,5 @@ +.. _copulas: + +############## +Copula Models +############## diff --git a/docs/source/Installation.rst b/docs/source/Installation.rst new file mode 100644 index 0000000..2d551e9 --- /dev/null +++ b/docs/source/Installation.rst @@ -0,0 +1,19 @@ +.. _installation: + +Installation +------------ + +To use SklarPy, first install it using pip: + +.. code-block:: text + + pip install sklarpy + +For Developers +-------------- + +If you wish to add your own significant modifications to SklarPy, you can can clone the current repository using: + +.. code-block:: text + + git clone https://github.com/tfm000/sklarpy diff --git a/docs/source/Misc.rst b/docs/source/Misc.rst new file mode 100644 index 0000000..5089f38 --- /dev/null +++ b/docs/source/Misc.rst @@ -0,0 +1,5 @@ +.. _misc: + +#################### +Miscellaneous Tools +#################### diff --git a/docs/source/Multivariate.rst b/docs/source/Multivariate.rst new file mode 100644 index 0000000..372e116 --- /dev/null +++ b/docs/source/Multivariate.rst @@ -0,0 +1,5 @@ +.. _multivariate: + +############################ +Multivariate Distributions +############################ diff --git a/docs/source/Univariate.rst b/docs/source/Univariate.rst new file mode 100644 index 0000000..03bd91c --- /dev/null +++ b/docs/source/Univariate.rst @@ -0,0 +1,6 @@ +.. _univariate: + +######################### +Univariate Distributions +######################### + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..4ab9d24 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,39 @@ +# Configuration file for the Sphinx documentation builder. +import os +import sys + +sys.path.insert(0, os.path.abspath("...")) + +# -- Project information + +project = 'SklarPy' +copyright = '2023, Tyler Mitchell' +author = 'Tyler Mitchell' + +release = '1.0.0' +version = '1.0.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..782d8d7 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,117 @@ +.. image:: https://github.com/tfm000/sklarpy/blob/main/media/logo.png?raw=true + :alt: SklarPy logo + :scale: 60% + :align: center + +.. raw:: html + + + + + + +

+ + MIT license   + + build   + + downloads   + + maintained +

+ +

+ + mac os + + windows +

+ + +SklarPy (pronounced 'Sky-Lar-Pee' or 'Sky-La-Pie') is an open-source software for probability distribution fitting. +It contains useful tools for fitting Copula, Multivariate and Univariate probability distributions. +In addition to over 100 univariate distributions, we implement many multivariate normal mixture distributions and their copulas, including Gaussian, Student-T, Skewed-T and Generalized Hyperbolic distributions. +Named after Sklar's theorem and Abe Sklar, the American mathematician who proved that multivariate cumulative distribution functions can be expressed in terms of copulas and their marginals. + +This library has many different possible use cases, ranging from machine learning to finance. + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + Installation + Univariate + Multivariate + Copulas + Misc + +Why we are better +----------------- +- Unlike other Python implementations of copulas, we implement more than the Gaussian and Archimedean copulas. A full list of our implementated copula models can be found in the documentation, though it includes many normal mean-variance mixture models as well as Archimedean and non-parametric models. +- We allow for easy parameter fitting of both the univariate marginals and the multivariate copula distribution. +- We allow for easy plotting of all our distributions, allowing you to visualize your models. +- We use scipy.stats as a backend for all our univariate models, meaning as scipy expands and improves their model selection, so will ours! +- We provide multivariate and univariate distributions, in addition to our copula models, meaning SklarPy can act as a one-stop-shop for all probability distribution fitting. A full list of our implemented multivariate distributions can be found in the documentation. +- We are continuing to expand our library, and are open to suggestions for new models to implement. If you have a model you would like to see implemented, please open an issue on our GitHub page. + +Example +-------- + +Here we show a quick example of working with SklarPy. +For more information, see the specific documentaion.:: + + import numpy as np + import pandas as pd + import matplotlib.pyplot as plt + from sklarpy.copulas import gh_copula + + # generating random data + n: int = 1000 + obs: np.ndarray = np.full((n, 2), np.nan) + obs[:, 0] = np.random.normal(3,4, size=(n,)) + obs[:, 1] = obs[:, 0] + 0.5 * np.random.normal(3, 5, size=(n,)) + obvs_df: pd.DataFrame = pd.DataFrame(obs, columns=['Process A', 'Process B']) + + # fitting our copula model + fitted_copula = gh_copula.fit(obvs_df) + + # printing our fitted copula parameters + print(fitted_copula.copula_params.to_dict) + + # printing our fitted marginal distributions + print(fitted_copula.mdists) + + # plotting our fit + fitted_copula.pdf_plot(show=False) + fitted_copula.copula_pdf_plot(show=False) + plt.show() + +This outputs: + +.. code-block:: text + + {'lamb': -10.0, 'chi': 4.227038325195731, 'psi': 10.0, + 'loc': array([[0.], [0.]]), + 'shape': array([[1. , 0.84273015], + [0.84273015, 1.]]), + 'gamma': array([[0.99696041], [0.99913161]])} + + {0: lognorm(0.02, -203.22, 206.18), 1: lognorm(0.04, -110.89, 115.4)} + +.. image:: https://github.com/tfm000/sklarpy/blob/main/media/PDF_Gh_PDF_Plot_Plot.png?raw=true + :alt: GH PDF + :scale: 60% + :align: center + +.. image:: https://github.com/tfm000/sklarpy/blob/main/media/Copula_PDF_Gh_Copula_PDF_Plot_Plot.png?raw=true + :alt: GH Copula PDF + :scale: 60% + :align: center diff --git a/pyproject.toml b/pyproject.toml index 20fe848..406b08d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,6 +66,9 @@ dev = [ "pytest==7.1.2", "tox==3.25.1", ] +docs = [ + "sphinx~=4.2.0", +] [project.urls] # Optional "Homepage" = "https://github.com/tfm000/sklarpy"