added narrative to theil nb

README.md

@@ -36,6 +36,8 @@ Contribute
 
 PySAL-inequality is under active development and contributors are welcome.
 
+Please see the [Contributing](contributing.md) instructions.
+
 If you have any suggestion, feature request, or bug report, please open a new [issue](https://github.com/pysal/inequality/issues) on GitHub. To submit patches, please follow the PySAL development [guidelines](http://pysal.org/docs/devs/) and open a [pull request](https://github.com/pysal/inequality). Once your changes get merged, you’ll automatically be added to the [Contributors List](https://github.com/pysal/inequality/graphs/contributors).
 
 Support

contributing.md

@@ -0,0 +1,84 @@
+# Contributing to inequality
+
+Contributions to inequality are much appreciated.
+
+## Steps to Contribute
+
+1. Fork the inequality git repository
+2. Create a development environment
+3. Activate the new environment
+4. Install project dependencies
+5. Verify installation and run tests
+6. Build documentation
+7. Submitting a Pull Request
+
+## 1. Fork the inequality git repository
+
+- On github, fork the repository at: <https://github.com/pysal/inequality>
+- From your new fork, grab the clone url:
+```
+git clone git@github.com:your-user-name/inequality.git inequality-yourname
+cd inequality-yourname
+git remote add upstream git://github.com/pysal/inequality.git
+```
+
+## 2. Create a development environment
+
+- Install either [Anaconda](http://docs.continuum.io/anaconda/)  or [miniconda](http://conda.pydata.org/miniconda.html)
+- `cd` into the `inequality-yourname` source directory that you cloned in step 1
+
+```
+conda create --name inequality python=3.10
+```
+
+## 3. Activate the new environment
+```
+conda activate inequality
+```
+## 4. Install project dependencies
+```
+pip install .[dev,docs,tests]
+```
+
+Note, if you are on zsh use:
+
+```
+pip install '.[dev,docs,tests]'
+```
+If this fails on MacOS you have to have `proj` installed:
+```
+brew install proj
+```
+
+Set this variable in your shell configuration (e.g., ~/.zshrc or ~/.bashrc):
+```
+export PROJ_DIR="/opt/homebrew/opt/proj"
+```
+Then, reload your shell configuration:
+```
+source ~/.zshrc
+```
+and check that `proj` is correctly installed:
+```
+proj
+```
+
+## 5. Verify installation and run tests
+```
+python -c "import libpysal; print('libpysal version:', libpysal.__version__)"
+pytest inequality
+```
+
+
+## 6. Build documentation
+```
+cd docs
+make html
+```
+
+## 7. Submitting a Pull Request
+
+If you have made changes that you have pushed to your forked repository, you can
+submit a pull request to have them integrated into the `inequality` code base.
+
+See the [GitHUB tutorial](https://help.github.com/articles/using-pull-requests/).

docs/_static/references.bib

@@ -1,3 +1,33 @@
+
+@misc{hoffmann2024MeasuringMismeasuring,
+  title = {Measuring and {{Mismeasuring Income Polarization}}},
+  author = {Hoffmann, Rodolfo and Kassouf, Ana Lucia},
+  year = {2024},
+  month = mar,
+  doi = {10.21203/rs.3.rs-4139220/v1},
+  urldate = {2024-08-12},
+  abstract = {The main contribution of this paper is to clarify some of the misconceptions about income polarization indices observed in the existing literature. Our analysis explores the domain of measures of polarization of the income distribution, with a specific emphasis on elucidating the importance of distinguishing between bipolarization and multipolarization measures. Additionally, we assert that a valid polarization metric must adhere to the principle of scale-invariance. Furthermore, in cases where the income distribution is categorized into relatively poor and relatively rich, a valid bipolarization measure should consistently increase when regressive transfers occur from poorer to richer individuals and when progressive transfers occur between two poorer or two richer individuals. The study identifies instances where bipolarization measures that fail to adhere to these criteria have been employed in previous research, leading to erroneous conclusions. The research also provides a succinct analysis of the challenges faced by scholars in employing Esteban and Ray's multipolarization measure and its adapted versions. Artificial numerical examples are used to illustrate the application of different polarization measures in various scenarios. Additionally, a real-world illustration is presented that depicts a declining trend of the bipolarization of income distribution in Brazil from 2001 to 2015, coinciding with a decrease in inequality during this period. The study concludes by pinpointing errors in previously published works.},
+  copyright = {https://creativecommons.org/licenses/by/4.0/},
+  langid = {english},
+  file = {/home/serge/Zotero/storage/WM4696MT/Hoffmann and Kassouf - 2024 - Measuring and Mismeasuring Income Polarization.pdf}
+}
+
+@article{wolfson1994WhenInequalities,
+  title = {When {{Inequalities Diverge}}},
+  author = {Wolfson, Michael C.},
+  year = {1994},
+  journal = {The American Economic Review},
+  volume = {84},
+  number = {2},
+  eprint = {2117858},
+  eprinttype = {jstor},
+  pages = {353--358},
+  publisher = {American Economic Association},
+  issn = {0002-8282},
+  urldate = {2024-08-12},
+  file = {/home/serge/Zotero/storage/8JYHLHTW/Wolfson - 1994 - When Inequalities Diverge.pdf}
+}
+
 @article{schutz1951MeasurementIncome,
   title = {On the {{Measurement}} of {{Income Inequality}}},
   author = {Schutz, Robert R.},

docs/api.rst

@@ -7,15 +7,15 @@ API reference
 
 .. _inequality_api:
 
-
 Atkinson Inequality Measures
 ----------------------------
 
 .. autosummary::
    :toctree: generated/
 
     inequality.atkinson.Atkinson
-
+
+
 Gini Inequality Measures
 ------------------------
 
@@ -32,8 +32,7 @@ Schutz Inequality Measures
    :toctree: generated/
 
     inequality.schutz.Schutz
-
-
+
 Theil Inequality Measures
 -------------------------
 
@@ -44,7 +43,14 @@ Theil Inequality Measures
     inequality.theil.TheilD
     inequality.theil.TheilDSim
 
+Wolfson Bipolarization Measure
+------------------------------
+.. autosummary::
+   :toctree: generated/
 
+    inequality.wolfson.wolfson
+
+
 Pengram
 -------
 

docs/conf.py

@@ -17,11 +17,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 
-import sphinx_bootstrap_theme
-
+from datetime import datetime
 
 # import your package to obtain the version info to display on the docs website
 import inequality
+import sphinx_bootstrap_theme
 
 # -- General configuration ------------------------------------------------
 
@@ -31,7 +31,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [  #'sphinx_gallery.gen_gallery',
+extensions = [  # 'sphinx_gallery.gen_gallery',
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
@@ -60,7 +60,7 @@
 
 # General information about the project.
 project = "inequality"  # string of your project name, for example, 'giddy'
-copyright = "2018, pysal developers"
+copyright = f"2018 - {datetime.now().year}, pysal developers (BSD License)"
 author = "pysal developers"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -95,8 +95,9 @@
 # a list of builtin themes.
 #
 # html_theme = 'alabaster'
-html_theme = "bootstrap"
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+# html_theme = "bootstrap"
+html_theme = "pydata_sphinx_theme"
+# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 html_title = "%s v%s Manual" % (project, version)
 
 # (Optional) Logo of your package. Should be small enough to fit the navbar (ideally 24x24).
@@ -105,7 +106,8 @@
 
 # (Optional) PySAL favicon
 html_favicon = "_static/images/pysal_favicon.ico"
-
+html_logo = '_static/images/pysal_logo.png'
+icon_links_label = 'inequality'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -117,12 +119,12 @@
     # Render the next and previous page links in navbar. (Default: true)
     "navbar_sidebarrel": False,
     # Render the current pages TOC in the navbar. (Default: true)
-    #'navbar_pagenav': True,
-    #'navbar_pagenav': False,
+    # 'navbar_pagenav': True,
+    # 'navbar_pagenav': False,
     # No sidebar
     "nosidebar": True,
     # Tab name for the current pages TOC. (Default: "Page")
-    #'navbar_pagenav_name': "Page",
+    # 'navbar_pagenav_name': "Page",
     # Global TOC depth for "site" navbar tab. (Default: 1)
     # Switching to -1 shows all levels.
     "globaltoc_depth": 2,
@@ -136,7 +138,7 @@
     "globaltoc_includehidden": "true",
     # HTML navbar class (Default: "navbar") to attach to <div> element.
     # For black navbar, do "navbar navbar-inverse"
-    #'navbar_class': "navbar navbar-inverse",
+    # 'navbar_class': "navbar navbar-inverse",
     # Fix navigation bar to top of page?
     # Values: "true" (default) or "false"
     "navbar_fixed_top": "true",
@@ -154,7 +156,7 @@
     # Navigation bar menu
     "navbar_links": [
         ("Installation", "installation"),
-        ("Tutorials", "tutorials"),
+        ("User Guide", "user-guide/intro"),
         ("API", "api"),
         ("References", "references"),
     ],

docs/index.rst

@@ -108,14 +108,19 @@ software, terms & conditions for usage, and a DISCLAIMER OF ALL
 WARRANTIES.
 
 
+inequality
+==========
+
+Documentation contents
+----------------------
+
 .. toctree::
-   :hidden:
-   :maxdepth: 4
-   :caption: Contents:
+   :maxdepth: 1
 
+   Home <self>
    Installation <installation>
-   Tutorials <tutorials>
-   API <api>
+   API reference <api>
+   user-guide/intro
    References <references>
 
 .. _PySAL: https://github.com/pysal/pysal

docs/tutorials.rst

@@ -9,3 +9,4 @@ Tutorials
     :caption: Gini
 
     notebooks/gini.ipynb
+    notebooks/pengram.ipynb

docs/user-guide/intro.rst

@@ -0,0 +1,12 @@
+==========
+User Guide
+==========
+
+This user guide covers essential features of pysal-inequality, mostly in the form of interactive Jupyter notebooks. Reading this guide, you will learn:
+
+- how to :ref:`visualize <viz>` spatial inequality
+- how to :ref:`measure <measure>` spatial inequality
+
+Notebooks cover just a small selection of functions as an illustration of
+principles. For a full overview of pysal-inequality capabilities, head to the `API <../api.rst>`_.
+