diff --git a/doc/index.rst b/doc/index.rst index ff94cff5..fa9f0da9 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/source/advanced/datatype.rst b/doc/source/advanced/datatype.rst index cabbc08a..49db9cec 100644 --- a/doc/source/advanced/datatype.rst +++ b/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 `_. + + Temporal -------- Temporal data types describe time-related attributes, such as dates and timestamps. diff --git a/doc/source/advanced/map.rst b/doc/source/advanced/map.rst new file mode 100644 index 00000000..94611ed0 --- /dev/null +++ b/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 `_ 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 `_ 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) `_ 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 `_ 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. \ No newline at end of file diff --git a/doc/source/guide/FAQ.rst b/doc/source/guide/FAQ.rst index cd5a0433..b0cf82c3 100644 --- a/doc/source/guide/FAQ.rst +++ b/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 `__. +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 `__. + 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`).