0.6.0 PyPI release

open-risk · Feb 21, 2022 · 266cdc5 · 266cdc5
1 parent 9f606b8
commit 266cdc5
Show file tree

Hide file tree

Showing 30 changed files with 271 additions and 1,408 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -3,6 +3,12 @@ Change Log
 
 PLEASE NOTE THAT THE API IS STILL UNSTABLE AS MORE USE CASES / FEATURES ARE ADDED REGULARLY
 
+v0.6.0 (21-02-2022)
+-------------------
+* Installation:
+    * PyPI release update
+
+
 v0.5.1 (14-06-2020)
 -------------------
 * Added Hall-Tideman Index
@@ -13,7 +19,7 @@ v0.5.0 (05-04-2020)
 -------------------
 * Added script that produces cross-check calculations from corresponding R packages
 * Expanded functionality to process dataframes
-* PyPI installation
+* First PyPI installation
 
 v0.4.2 (08-03-2019)
 -------------------

diff --git a/DESCRIPTION.rst b/DESCRIPTION.rst
diff --git a/concentrationMetrics/__init__.py b/concentrationMetrics/__init__.py
@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-# (c) 2017-2021 Open Risk (www.openriskmanagement.com), all rights reserved
+# (c) 2017-2022 Open Risk (www.openriskmanagement.com), all rights reserved
 #
 # ConcentrationMetrics is licensed under the MIT license a copy of which is included
 # in the source distribution of concentrationMetrics. This is notwithstanding any licenses of

diff --git a/concentrationMetrics/model.py b/concentrationMetrics/model.py
@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-# (c) 2017-2021 Open Risk (www.openriskmanagement.com), all rights reserved
+# (c) 2017-2022 Open Risk (www.openriskmanagement.com), all rights reserved
 #
 # ConcentrationMetrics is licensed under the MIT license a copy of which is included
 # in the source distribution of concentrationMetrics. This is notwithstanding any licenses of
@@ -144,9 +144,11 @@ def hhi(self, data, normalized=True, ci=None, samples=None):
         :type normalized: bool
         :param data: Positive numerical data
         :type data: numpy array
+        :param ci: confidence interval
+        :type ci: float
         :return: HHI (Float)
 
-        `Open Risk Manual Entry for Hirschman-Herfindahl Index <https://www.openriskmanual.org/wiki/Herfindahl-Hirschman_Index>`_
+        `Open Risk Manual Entry for the Hirschman-Herfindahl Index <https://www.openriskmanual.org/wiki/Herfindahl-Hirschman_Index>`_
         """
         # Normalize the data
         weights = self.get_weights(data)
@@ -236,7 +238,7 @@ def hti(self, data):
         :type data: numpy array
         :return: HTI (Float)
 
-        `Open Risk Manual Entry for Gini Index <https://www.openriskmanual.org/wiki/Hall-Tideman_Index>`_
+        `Open Risk Manual Entry for Hall-Tideman Index <https://www.openriskmanual.org/wiki/Hall-Tideman_Index>`_
         """
         data = np.array(sorted(data, reverse=True))
         weights = self.get_weights(data)
@@ -514,7 +516,7 @@ def margalev(self, data):
         :type data: list
         :return: D (Float)
 
-        `Open Risk Manual Entry for Gini Index <https://www.openriskmanual.org/wiki/Margalef_Index>`_
+        `Open Risk Manual Entry for Margalev Index <https://www.openriskmanual.org/wiki/Margalef_Index>`_
         """
         n = len(data)
         s = len(list(set(data)))
@@ -567,7 +569,6 @@ def global_clustering(self, adjacency_matrix):
         """
         pass
 
-
     def average_clustering(self, adjacency_matrix):
         """Calculate the Average Clustering Coefficient of an Adjacency Matrix.
 

diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,14 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from
+       overriding this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+  }
+
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+
+}
diff --git a/docs/source/concentrationMetrics.rst b/docs/source/concentrationMetrics.rst
@@ -1,7 +1,7 @@
-concentrationMetrics module
+concentrationMetrics Package
 =============================
 
 .. automodule:: concentrationMetrics.model
     :members:
     :undoc-members:
-    :show-inheritance:
+    :show-inheritance:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,23 +14,22 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../'))
 
+sys.path.insert(0, os.path.abspath('../../'))
 
 # -- Project information -----------------------------------------------------
 
 __version__ = '0.5.0'
 
 project = 'concentrationMetrics'
-copyright = '2018-2020, Open Risk'
+copyright = '2017-2022, Open Risk'
 author = 'Open Risk'
 
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
 release = __version__
 
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -79,7 +78,6 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -92,14 +90,13 @@
 # documentation.
 #
 # html_theme_options = {}
-# html_theme_options = {}
+
 html_theme_options = {
-    'canonical_url': '',
     'analytics_id': '',
-    'logo_only': False,
+    'logo_only': True,
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
+    'style_external_links': True,
     # Toc options
     'collapse_navigation': True,
     'sticky_navigation': True,
@@ -123,13 +120,13 @@
 #
 # html_sidebars = {}
 
+html_css_files = ['custom.css']
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'concentrationMetricsdoc'
 
-
 # -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
@@ -158,7 +155,6 @@
      'Open Risk', 'manual'),
 ]
 
-
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -168,7 +164,6 @@
      [author], 1)
 ]
 
-
 # -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
@@ -180,7 +175,6 @@
      'Miscellaneous'),
 ]
 
-
 # -- Extension configuration -------------------------------------------------
 
 extensions.append('sphinx.ext.todo')

diff --git a/docs/source/data_preparation.rst b/docs/source/data_preparation.rst
@@ -11,9 +11,7 @@ The data need not be normalized, this is done automatically with the :meth:`conc
 
 Tabular Data and Dataframes
 ---------------------------
-For convenience, when the data are in tabular or dataframe format (e.g. observation counts for different types
-of entities) the library offers built-in functionality to calculate metrics across the data set. So for example if we
-have the distribution of counts per Attribute (rows) for three distinct categories (Columns Group 1 to 3) the calculation will produce the desired index for each one of the Groups
+For convenience, when the data are in tabular or dataframe format (e.g. observation counts for different types of entities) the library offers built-in functionality to calculate metrics across the data set. So for example if we have the distribution of counts per Attribute (rows) for three distinct categories (Columns Group 1 to 3) the calculation will produce the desired index for each one of the Groups
 
 
 +-----------+------------+------------+

diff --git a/docs/source/description.rst b/docs/source/description.rst
@@ -1 +1,81 @@
-.. include:: ../../DESCRIPTION.rst
+The concentrationMetrics Library
+================================
+
+concentrationMetrics is an MIT-licensed `Python <http://www.python.org>`_ package aimed at becoming a reference implementation of indexes used in the analysis of concentration, inequality and diversity measures.
+
+Overview of Main Features
+=========================
+
+* exhaustive collection of concentration and inequality indexes and metrics
+* supports file input/output in both json and csv formats
+* detailed mathematical documentation
+* computation of confidence intervals via bootstraping
+* visualization using matplotlib
+
+
+Usage
+===============================
+
+Using the library is quite straightforward. For example calculating the Gini and the HHI indexes
+on randomly generated portfolio data:
+
+.. code:: python
+
+    import numpy as np
+    from concentrationMetrics import Index
+    
+    # Create some data
+    a = 1.7
+    portfolio = np.random.zipf(a, 100)
+
+    # Calculate the desired indexes
+    indices = Index()
+    hhi = indices.hhi(portfolio)
+    gini = indices.gini(portfolio)
+
+    # Compute the confidence interval around the HHI index value
+    lower_bound, val, upper_bound = indices.compute(portfolio, index='hhi', ci=0.95, samples=10000)
+
+    # Calculate indexes on a dataframe
+    BCI = pd.read_json(dataset_path + "BCI.json")
+    y = BCI.values
+    myGroupIndex = cm.Index(data=y, index='simpson')
+    myGroupIndex.print(6)
+
+
+Many more examples and tests are available in the examples and test directories.
+
+
+File structure
+==============
+
+* `concentrationMetrics/model.py` The library module
+* `datasets/` Contains a variety of datasets useful for getting started with the ConcentrationMetrics
+* `examples/` Variety of usage examples
+* `docs/` Sphinx generated documentation
+* `tests/` testing the implementation
+
+All indexes are currently implemented in concentrationMetrics/model.py as methods of the Index object.
+
+Dependencies
+============
+The main dependencies are the standard python datascience stack (numpy, pandas etc) and networkx. The full list is in requirements.txt
+
+- matplotlib
+- numpy
+- pandas
+- scipy
+- networkx
+
+Datasets
+========
+Version 0.5.0 includes datasets used primarily for testing and comparison with R implementations:
+
+- hhbudget.csv
+- Ilocos.csv
+- BCI.json
+
+
+Comparison with R packages
+=================================
+-   atkinson\_test.py compares the Atkinson function with the IC2/Atk function
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,23 @@
+Usage Examples
+======================
+
+The examples directory includes both **standalone python scripts** and **jupyter notebooks** to help you get started. (NB: Currently there are only scripts and no notebooks TODO).
+
+
+Python Scripts
+-------------------------------------------
+
+The scripts are located in examples/python. For testing purposes all examples can be run using the run_examples.py script located in the root directory. Some scripts have an example flag that selects alternative input data or estimators.
+
+
+Jupyter Notebooks
+-------------------------------------------
+
+
+
+Open Risk Academy Scripts
+-------------------------------------------
+
+Further examples available in an Open Risk Academy CrashProgram in the use of python for risk modelling purposes, in particular credit concentration measurement: `Concentration Measurement Using Python	<https://www.openriskacademy.com/course/management.php?categoryid=26&courseid=13>`_
+
+