WorldMap
==============================
:Author: Robert Shaffer - rbshaffer@utexas.edu
:Version 1.0:
:Revised: 11/15/2013
.. contents::
Overview
--------
WorldMap helps users to map country-level data. The library supports all years from 1946-2011, with a variety of plotting options. WorldMap is intended for users who are less familiar with Python's visualization capabilities; as a result, the library does as much as possible in the background. Advanced users may find the source code useful as a starting point, but will likely want more customization options than are currently available in this library.
WorldMap is compatible with Python 2.7 - other Python versions have not been tested.
Data and Dependencies
---------------------
WorldMap relies on the following libraries:
- numpy (http://www.scipy.org/scipylib/download.html)
- matplotlib(http://matplotlib.org/users/installing.html)
- Depending on your OS and your installtion method, matplotlib may also require:
- libpng (http://www.libpng.org/pub/png/libpng.html)
- freetype (http://www.freetype.org/)
- dateutil (http://labix.org/python-dateutil)
- basemap(http://matplotlib.org/basemap/users/installing.html)
- PyShp (https://code.google.com/p/pyshp/)
- Included with the base files
All shapefile data are drawn from Nils Weidmann's cshapes library (http://nils.weidmann.ws/projects/cshapes), with a few
polygons edited slightly for better functionality.
Usage
--------
::Data Formatting::
First, you'll need to get your data formatted correctly. WorldMap assumes that your data are formatted as a .CSV file. The first
row in the CSV should be a set of row headers, and each subsequent row should be a country-year observation. Country names should be placed in the first row, years should be placed in the second row, and your data should be in the subsequent rows. For example:
Country,Year,Var_1,Var_2
Australia,1996,5,3
Australia,1997,5,4
United States,1996,2,1
United States,1997,3,4
Data must be numeric, but they can be either categorical or continuous. For categorical data, WorldMap can display up to 9 categories by default.
For country names, WorldMap (and the cshapes library) uses Correlates of War (COW) country names. To see the appropriate names, check the 'GW State Names and Durations.csv' file contained in the Reference Materials folder. For an example dataset, see the 'Example Dataset.csv' file contained in the Reference Materials folder.
::Getting Started::
After your data are properly formatted, you'll need to import the library:
>>> import WorldMap
Next, you'll need to create an instance of the Map class, with the following attributes:
- data_in: STR, which points to CSV file you'll be using
- var_name: INT or STR, which references the variable name you'll be using. If you use an INT, the number should refer to the column number of the variable you'll be using. So, in the following example:
Country,Year,Var_1,Var_2
Australia,1996,5,3
Australia,1997,5,4
United States,1996,2,1
United States,1997,3,4
If you wanted to refer to the first variable, you could either use 'Var_1' as your var_name, or 3 (since Var_1 is in the 3rd column).
- var_type: STR, which refers to the variable type. WorldMap will accept either "discrete" or "continous".
Examples:
>>> m = Map('C:\Users\Robert\Desktop\My Data.csv','Var_1','discrete')
>>> m = Map('/Users/Robert/Desktop/My Data.csv',5,'continuous')
You can change which variable is loaded using the Load_Var() method. This method functions in the same manner as the original variable instantiation above.
Example:
>>> m = Map('C:\Users\Robert\Desktop\My Data.csv','Var_1','discrete')
>>> m.Load_Var('Var_2','continuous')
::Setting the Titles::
Next, you'll need to set up the map title and the key. To do this, use the Set_Titles() method. Set_Titles() takes 2-3 arguments:
- title: STR, sets the title for the plot. Example: 'Figure 1: Country GDP'.
- legend_titles: LIST of STR, describes the names of the legend items in your map. For discrete variables, each list item should refer to a category. List items should be strings, with the category number, then a colon, then the name of that category. For example:
- ['1:Category 1','2:Category 2','3:Category 3']
For continuous variables, you can specify either two or three legend items: -1, 0, and 1. The item with a 0 will label the white color, while -1 and 1 will allow you to label positive and negative values (if applicable). So, for example:
- ['-1:Most Negative','0:No Change','1:Most Positive']
If you have only positive or only negative values, omit the -1 or 1 label as appropriate.
- colors: LIST of STR, describes the colors used for discrete plot. The first color will be used for the first variable in your legend_titles argument, the second color will be used in the second variable in your legend_titles argument, and so forth. Any standard HTML color name is valid here, as are RGB tuples. For example:
- ['blue','green','red','purple','yellow','orange','magenta','white','black']
- [(0,1,0),(1,0,0),(0,0,1)]
If not specified, this argument will default to the colors listed in the first example.
Examples:
>>> m.Set_Titles('Figure 1: Type of Government',['1:Presidentialism','2:Semi-Presidentialism','3:Parliamentarism']
>>> m.Set_Titles('Figure 2: Economic Growth',['-1:Negative','0:No Growth','1:Positive Growth'])
>>> m.Set_Titles('Figure 3: Legal System',['1:Common Law','2:Civil Law'],colors=['red','blue'])
::Drawing a Map::
To create a map, use the Draw_Map() method. Draw_Map() takes 3 arguments:
- view: STR, describes which part of the world you want to visualize. Currently, WorldMap supports the following inputs (not case-sensitive):
- 'world'
- 'north america'
- 'central america'
- 'south america'
- 'europe'
- 'middle east'
- 'africa'
- 'asia'
- 'australia' or 'southeast asia' (same output)
View defaults to 'world'.
- date: INT, describes which year you want to plot. Year should be formatted as YYYY. Any value is valid, but only years from 1946-2011 will be plotted.
- mode: STR, accepts either "most recent" or "listed". In "most recent" mode, WorldMap will plot the most recent available value for every country, regardless of whether that value actually coincides with the year your specified. So, for example, if you specify "1976" and you have data for a given country for 1950, 1960, and 1970, the 1970 data will be plotted.
If this behavior is not desirable (for example, if your data expire after the dates listed in your dataset), you can change the mode to "listed". In "listed" mode, WorldMap will only plot data points that coincide with the actual year you specified. For example, if you specify "1976" and all of your data date from 1975, WorldMap will return a blank plot.
If not specified, Mode defaults to "most recent".
- GA: STR, sets whether Greenland and Antarctica are displayed (only applies to 'world' and 'europe' views). By default, Greenland and Antarctica are hidden. To turn them out, set GA='on'
Examples:
>>> m.Draw_Map('europe',1978)
>>> m.Draw_Map('world',2001,GA='on')
::Usage::
To see some example uses with randomly-generated data, call the Map_Examples() method:
>>> Map_Examples()
This command will bring up three sample plots (all drawn from randomly-generated data). These example data cover all countries and time periods, so you can play with different map views and dates. For example:
>>> Map_Examples('europe',1976)
Will display maps of Europe, with data and national boundaries drawn from 1976.
The commands used to generate each of these plots will be displayed in the Python console, so check there for some example commands.
