Geographic types documentation (#358)

* Use altair/Choropleth.py in MatpltlibRenderer.py to render choropleths; include warning

* Documentation for geographical attributes / entities

* writing changes

Co-authored-by: Doris Lee <[email protected]>

doc/index.rst

@@ -39,6 +39,7 @@ This website contains pages that overview of the basic and advanced functionalit
    :maxdepth: 1
    :caption: Advanced Topics
 
+   source/advanced/map
    source/advanced/date
    source/advanced/indexgroup
    source/advanced/custom

doc/source/advanced/datatype.rst

@@ -60,6 +60,26 @@ Below: Lux displays the occurence counts of nominal variables under the :code:`O
   :align: center
   :alt: Displays bar chart for nominal variables.
 
+Geographic
+-----------
+Geographic data types describe location-based attributes, such as US states and world countries. 
+Lux infers that an attribute is geographical if it's column name is :code:`state` or :code:`country` and if the data content contain state or country information. For example, the :code:`Country` column is detected as a geographic data type in this example:
+
+.. code-block:: python
+
+  df = pd.read_csv("https://raw.githubusercontent.com/lux-org/lux-datasets/master/data/hpi.csv")
+  df
+
+Here, the :code:`Geographical` tab shows different choropleth maps of how different measures vary by country.
+
+.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/map-2.png?raw=true
+  :width: 600
+  :align: center
+  :alt: Geographic tab of HPI dataset
+
+.. note:: For more information on geographic attributes in Lux, see `this tutorial <https://lux-api.readthedocs.io/en/latest/source/advanced/map.html>`_.
+
+
 Temporal
 --------
 Temporal data types describe time-related attributes, such as dates and timestamps. 

doc/source/advanced/map.rst

@@ -0,0 +1,52 @@
+********************************
+Working with Geographic Data
+********************************
+
+This tutorial describes how geographic attributes can be visualized automatically with Lux. 
+Lux recognizes any columns named :code:`state` and :code:`country` that contains US States or worldwide countries as geographic attributes.
+Geographic attributes are automatically plotted against other attributes in the dataset as `choropleths maps <https://en.wikipedia.org/wiki/Choropleth_map.html>`_ in Lux. 
+
+
+Map of US States
+--------------------------------------
+
+Below we look at an example COVID-19 dataset that has a :code:`state` column, with each row representing data for a state in the US. 
+
+.. code-block:: python
+  
+  df = pd.read_csv("https://github.com/covidvis/covid19-vis/blob/master/data/interventionFootprintByState.csv?raw=True",index_col=0)
+  df
+
+Under the :code:`Geographical` tab on the Lux widget, we immediately see a list of choropleths map demonstrating how different attributes vary by state.
+
+.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/map-1.png?raw=true
+  :width: 600
+  :align: center
+  :alt: Geographic tab of COVID-19 dataset
+
+:code:`state` is a special keyword that allows Lux to identify columns containing US states. If your dataframe contains a column with state information and the geographical visualization is not being displayed, you may have to rename the column as :code:`state`. 
+
+Lux uses the `python-us package <https://github.com/unitedstates/python-us/blob/master/us/states.py>`_ to define the naming conventions for US states.
+The :code:`state` column can either contain the full state name (e.g. "California"), abbreviation (e.g. "CA"), or FIPS code (e.g. 06) as values.
+
+Map of World Countries
+--------------------------
+
+Below we look at the `Happy Planet Index (HPI) <http://happyplanetindex.org/>`_ dataset that has a :code:`country` column with each row representing data for a country in the world.
+
+.. code-block:: python
+
+  df = pd.read_csv("https://raw.githubusercontent.com/lux-org/lux-datasets/master/data/hpi.csv")
+  df
+
+Under the "Geographical" tab on the Lux widget, we immediately see a list of choropleths maps demonstrating how attributes vary by country.
+
+.. image:: https://github.com/lux-org/lux-resources/blob/master/doc_img/map-2.png?raw=true
+  :width: 600
+  :align: center
+  :alt: Geographic tab of HPI dataset
+
+:code:`country` is a special keyword that allows Lux to identify columns containing world countries. If your dataframe contains a column with country information and the geographical visualization is not being displayed, you may have to rename the column as :code:`country`. 
+
+Lux uses the `iso3166 package <https://github.com/deactivated/python-iso3166/blob/master/iso3166/__init__.py>`_ to define the naming conventions for world countries.
+The :code:`country` column can either contain full country name (e.g. "Afghanistan"), abbreviations (e.g. "AF" or "AFG"), or ISO code (e.g. 004) as values.

doc/source/guide/FAQ.rst

@@ -18,6 +18,10 @@ What do I do with date-related attributes in my dataset?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
   Lux supports a variety of temporal data types in Pandas. For more information on how to handle temporal data in Lux, refer to `the datetime guide <https://lux-api.readthedocs.io/en/latest/source/advanced/date.html>`__.
 
+What do I do with geographical attributes in my dataset?
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+  Lux supports a variety of geographical data types in Pandas. For more information on how to handle temporal data in Lux, refer to `the geographic entity tutorial <https://lux-api.readthedocs.io/en/latest/source/advanced/map.html>`__.
+
 How do I access all of the current recommendations shown in my widget?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
   The recommendations for Lux can be accessed via the :code:`recommendation` property of the dataframe (e.g., :code:`df.recommendation`).