further documentation

open-risk · Jun 18, 2019 · 9f57920 · 9f57920
1 parent 92f34b5
commit 9f57920
Show file tree

Hide file tree

Showing 10 changed files with 109 additions and 28 deletions.
diff --git a/description.rst b/description.rst
@@ -10,7 +10,7 @@ models
 * Mathematical Documentation: `Open Risk Manual <https://www.openriskmanual.org/wiki/Transition_Matrix>`_
 * Training: `Open Risk Academy <https://www.openriskacademy.com/login/index.php>`_
 * Development Website: `Github <https://github.com/open-risk/portfolioAnalytics>`_
-* Discussion: `Discord`_
+
 
 Functionality
 -------------
@@ -71,7 +71,7 @@ Dependencies
 -----------------
 
 - portfolioAnalytics requires Python 3
-- the thresholds module depends on the transitionMatrix library
+- the thresholds module depends on the Open Risk transitionMatrix and correlationMatrix libraries
 - It depends on numerical and data processing Python libraries (Numpy, Scipy, Pandas)
 - The Visualization API depends on Matplotlib
 - The precise dependencies are listed in the requirements.txt file.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -11,15 +11,18 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+
+# portfolioAnalytics/docs/source/conf.py
+# portfolioAnalytics/examples
+# portfolioAnalytics/portfolioAnalytics
 
 import sys
 import os
 import matplotlib
 matplotlib.use('agg')
 
 sys.path.insert(0, os.path.abspath('../../'))
-sys.path.insert(0, os.path.abspath('../../thresholds'))
+sys.path.insert(0, os.path.abspath('../../examples/python'))
 
 autodoc_mock_imports = ["transitionMatrix"]
 

diff --git a/docs/source/examples.python.calculate_thresholds.rst b/docs/source/examples.python.calculate_thresholds.rst
@@ -0,0 +1,21 @@
+Examples of calculation thresholds
+====================================
+
+Estimating thresholds given a multi-period transition matrix set. Example of using portfolioAnalytics to compute multi-period transition thresholds
+compatible with a given transition matrix.
+
+
+Rating Transition Thresholds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* calculate_thresholds.py
+* validated_thresholds.py
+* visualize_thresholds.py
+
+ Validate computed thresholds.
+
+The mathematical framework documented in
+`Multi-Period Transition Thresholds <https://www.openriskmanual.org/wiki/Multi-Period_Transition_Thresholds>`_
+
+.. image:: ../../examples/Thresholds.png
+
diff --git a/docs/source/examples.python.calculate_variance.rst b/docs/source/examples.python.calculate_variance.rst
@@ -0,0 +1,6 @@
+Examples of calculating variance
+========================================
+
+Calculating the default rate volatility (variance) of a portfolio requires two inputs:
+* a set of suitable portfolio data
+* an asset correlation matrix
diff --git a/docs/source/examples.python.portfolio_model.rst b/docs/source/examples.python.portfolio_model.rst
@@ -0,0 +1,20 @@
+Examples of calculating portolio models
+========================================
+
+The examples directory includes python scripts and jupyter notebooks to help you get started
+
+- Generating loss distributions analytically
+- Estimating thresholds given a multi-period transition matrix set
+
+Located in examples/python (For testing purposes all examples can be run using the run_examples.py script
+located in the root directory)
+
+
+Portfolio Models
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* portolio_model.py
+
+Using the portfolio model library to calculate default probabilities in finite
+portfolio with N credits
+
diff --git a/docs/source/examples.python.validate_thresholds.rst b/docs/source/examples.python.validate_thresholds.rst
@@ -0,0 +1,21 @@
+Examples of validating transition thresholds
+================================================
+
+The examples directory includes python scripts and jupyter notebooks to help you get started
+
+- Generating loss distributions analytically
+- Estimating thresholds given a multi-period transition matrix set
+
+Located in examples/python (For testing purposes all examples can be run using the run_examples.py script
+located in the root directory)
+
+
+
+Validating Transition Thresholds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* validate_thresholds.py
+
+Example of using portfolioAnalytics to compute multi-period transition thresholds
+compatible with a given transition matrix. Validate computed thresholds.
+
diff --git a/docs/source/examples.python.visualize_thresholds.rst b/docs/source/examples.python.visualize_thresholds.rst
@@ -0,0 +1,24 @@
+Examples of visualizing thresholds
+================================================
+
+The examples directory includes python scripts and jupyter notebooks to help you get started
+
+- Generating loss distributions analytically
+- Estimating thresholds given a multi-period transition matrix set
+
+Located in examples/python (For testing purposes all examples can be run using the run_examples.py script
+located in the root directory)
+
+
+Visualizing Rating Transition Thresholds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* visualize_thresholds.py
+
+Example of using portfolioAnalytics to compute multi-period transition thresholds
+compatible with a given transition matrix. Validate computed thresholds.
+
+The mathematical framework documented in
+`Multi-Period Transition Thresholds <https://www.openriskmanual.org/wiki/Multi-Period_Transition_Thresholds>`_
+
+.. image:: ../../examples/Thresholds.png
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -13,30 +13,17 @@ Python Scripts
 Located in examples/python (For testing purposes all examples can be run using the run_examples.py script
 located in the root directory)
 
+.. automodule:: examples.python
+    :noindex:
 
-Portfolio Models
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* portolio_model.py
+.. toctree::
 
-Using the portfolio model library to calculate default probabilities in finite
-portfolio with N credits
-
-
-Rating Transition Thresholds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* calculate_thresholds.py
-* validated_thresholds.py
-* visualize_thresholds.py
-
-Example of using portfolioAnalytics to compute multi-period transition thresholds
-compatible with a given transition matrix. Validate computed thresholds.
-
-The mathematical framework documented in
-`Multi-Period Transition Thresholds <https://www.openriskmanual.org/wiki/Multi-Period_Transition_Thresholds>`_
-
-.. image:: ../../examples/Thresholds.png
+    examples.python.calculate_variance
+    examples.python.portfolio_model
+    examples.python.calculate_thresholds
+    examples.python.visualize_thresholds
+    examples.python.validate_thresholds
 
 
 

diff --git a/examples/python/calculate_thresholds.py b/examples/python/calculate_thresholds.py
@@ -13,9 +13,7 @@
 # limitations under the License.
 
 
-""" Example of calculating thresholds
-
-"""
+"""Example of calculating thresholds."""
 
 import transitionMatrix as tm
 from transitionMatrix.predefined import Generic

diff --git a/requirements.txt b/requirements.txt
@@ -2,6 +2,7 @@ scipy>=1.0
 sympy>=1.3
 numpy>=1.16.2
 pandas>=0.24.2
+scikit-learn>=0.21.2
 matplotlib>=3.0.3
 requests>=2.21.0
 statsmodels>=0.9.0