0.5.0 Release (Extended API, BCI examples and tests)

Author: open-risk

CHANGELOG.rst

@@ -1,28 +1,29 @@
-ConcentrationMetrics Change Log
+Change Log
 ================================
 
-v0.5.0 (16-10-2019)
-===================
-* Added first set of spatial concentration indexes
-* Added first set of network concentration indexes
-* Added methods for semantic self-documentation of models
-* Adding functionality to calculate metrics on graph data
+PLEASE NOTE THAT THE API IS STILL UNSTABLE AS MORE USE CASES / FEATURES ARE ADDED REGULARLY
+
+v0.5.0 (05-04-2020)
+-------------------
+* Added script that produces cross-check calculations from corresponding R packages
+* Expanded functionality to process dataframes
+* PiPy installation
 
 v0.4.2 (08-03-2019)
-===================
+-------------------
 
 * Renamed library to concentrationMetrics to emphasize the nature of the library and follow the naming conventions of other Open Risk projects (transitionMatrix, correlationMatrix etc)
 * Added readthedocs documentation
 
 v0.4.1 (18-02-2019)
-===================
+-------------------
 
 * Provide confidence intervals via bootstraping
 * Improved test documentation
 * Fixed documentation links
 
 v0.4 (17-08-2018)
-===================
+-------------------
 * Added new one-dimensional indexes: Hoover
 * New multi-dimensional index family: Ellison-Glaeser
 * Added normalized version flag (ranging in 0,1) for HHI, Shannon
@@ -32,13 +33,13 @@ v0.4 (17-08-2018)
 * More formal testing framework, added tests for the EG index
 
 v0.3.1 (09-05-2018)
-===================
+-------------------
 
 * Code documentation via sphinx
 * Improved alignment with Open Risk Manual pages
 
 v0.3.0 (27-12-2017)
-===================
+-------------------
 
 * Exhaustive collection of indexes
 * Direct documentation using Open Risk Manual URL's
@@ -47,6 +48,6 @@ v0.3.0 (27-12-2017)
 * Examples directory
 
 v0.2.0 (23-11-2016)
-===================
+-------------------
 
 * First public release of the package

DESCRIPTION.rst

@@ -1,16 +1,15 @@
-====================
-ConcentrationMetrics
-====================
+The concentrationMetrics Library
+================================
 
-ConcentrationMetrics is an MIT-licensed `Python <http://www.python.org>`_
-package aimed at becoming a reference implementation of indicators used in the analysis of concentration,
-inequality and diversity measures.
+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
 
@@ -30,22 +29,28 @@ on randomly generated portfolio data:
     a = 1.7
     portfolio = np.random.zipf(a, 100)
 
-    # Calculate some indexes
+    # Calculate the desired indexes
     indices = Index()
     hhi = indices.hhi(portfolio)
     gini = indices.gini(portfolio)
 
-    # Compute the confidence interval
+    # 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 in the examples directory.
+
+Many more examples and tests are available in the examples and test directories.
 
 
 File structure
 ==============
 
-* `concentrationMetrics.py` The library module
+* `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
@@ -55,27 +60,27 @@ All indexes are currently implemented in concentrationMetrics.py as methods of t
 
 Dependencies
 ============
+The main dependencies are the standard python datascience stack and networkx. The full list is in requirements.txt
 
--   matplotlib
--   networkx
--   numpy
--   pandas
--   scipy
+- matplotlib
+- numpy
+- pandas
+- scipy
+- networkx
 
 Datasets
 ========
+Version 0.5.0 includes datasets used primarily for testing and comparison with R implementations:
 
-Version 0.3.1 includes two real datasets currently used primarily for testing and comparison with R implementations:
-
--   hhbudget.csv
--   Ilocos.csv
+- hhbudget.csv
+- Ilocos.csv
+- BCI.json
 
 Testing
 =======
 
 Run python test.py
 
-Comparison with R implementations
+Comparison with R packages
 =================================
-
 -   atkinson\_test.py compares the Atkinson function with the IC2/Atk function

LICENSE renamed to LICENSE.txt

@@ -7,12 +7,11 @@ concentrationMetrics is a python library for the computation of various concentr
 
 You can use concentrationMetrics to
 
-- access an exhaustive collection of concentration and inequality indexes and metrics
+- access an exhaustive collection of concentration, inequality and diversity indexes and metrics
 - perform file input/output in both json and csv formats
-- computate indices with confidence intervals via bootstraping
+- compute indexes with confidence intervals via bootstraping
 - visualize using matplotlib
 
-
 Key Information
 ================
 
@@ -24,22 +23,15 @@ Key Information
 * General Discussions: [Gitter Lobby](https://gitter.im/open-risk/Lobby)
 * Package Specific Chat: [Gitter Project](https://gitter.im/open-risk/concentrationMetrics)
 
+**NB: concentrationMetrics is still in active development. If you encounter issues please raise them in our github repository**
 
-**NB: concentrationMetrics is still in active development. If you encounter issues please raise them in our
-github repository**
-
-Support and Training
-=========================
-
-The Open Risk Academy has free courses demonstrating the use of the library: [Open Risk Academy](https://www.openriskacademy.com)
-
+[Full Description](DESCRIPTION.rst)
 
 List of Implemented Indexes
 ===============================
+An overview of the implemented metrics (indexes) and their relationships is available at the [Open Risk Manual](https://www.openriskmanual.org/wiki/Concentration_Index)
 
-An overview of the implemented metrics is available at the [Open Risk Manual](https://www.openriskmanual.org/wiki/Concentration_Index)
-
-The below list provides specific documentation URL's for each one of the implement indexes
+The below list provides more specific documentation URL's for each one of the implement indexes:
 
 * [Atkinson Index](https://www.openriskmanual.org/wiki/Atkinson_Index)
 * [Berger-Parker Index](https://www.openriskmanual.org/wiki/Berger-Parker_Index)
@@ -49,17 +41,18 @@ The below list provides specific documentation URL's for each one of the impleme
 * [Theil Index](https://www.openriskmanual.org/wiki/Theil_Index)
 * [Hannah-Kay Index](https://www.openriskmanual.org/wiki/Hannah_Kay_Index)
 * [Hoover Index](https://www.openriskmanual.org/wiki/Hoover_Index)
-* [Herfindahl-Hirschman Index](https://www.openriskmanual.org/wiki/Herfindahl-Hirschman_Index)
+* [Herfindahl-Hirschman Index](https://www.openriskmanual.org/wiki/Herfindahl-Hirschman_Index) and related indexes such as Simpson and Inverse Simpson
 * [Shannon Index](https://www.openriskmanual.org/wiki/Shannon_Index)
 * [Generalized Entropy Index (Renyi)](https://www.openriskmanual.org/wiki/Generalized_Entropy_Index)
 * [Kolm Index](https://www.openriskmanual.org/wiki/Kolm_Index)
 
+Support and Training
+=========================
+The Open Risk Academy has free courses demonstrating the use of the library: [Open Risk Academy](https://www.openriskacademy.com)
 
-[Full Description](DESCRIPTION.rst)
 
 Examples
 ========
-
 Comparing two indexes across a range of input portfolio data 
 
 ![image](examples/hhi_vs_gini.png)
@@ -71,5 +64,5 @@ Calculating industrial and geographic concentrations
 
 Contributions
 =============
-
-Check the [TODO list](TODO.rst) for ideas of where to take this library next
+* Check the [TODO list](docs/source/todo.rst) for immediate TODO items
+* Check the [Roadmap](docs/source/roadmap.rst) for the bigger picture

README.md

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+# (c) 2020 Open Risk (https://www.openriskmanagement.com)
+#
+# ConcentrationMetrics is licensed under the MIT license a copy of which is included
+# in the source distribution of TransitionMatrix. This is notwithstanding any licenses of
+# third-party software included in this distribution. You may not use this file except in
+# compliance with the License.
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+""" concentrationMetrics - Python package aimed at becoming a reference implementation of indicators used in the
+analysis of concentration, inequality and diversity measures. """
+
+from .model import *
+
+__version__ = '0.5.0'
+
+package_name = 'concentrationMetrics'
+module_path = os.path.dirname(__file__)
+source_path = module_path[:-len(package_name)]
+dataset_path = os.path.join(source_path, 'datasets/')