Time and Place User Guide

Overview

Time and Place is an application which reads a table of values organized by time and place and displays the values as a bar chart with a slider to sequence through the times. The values are also shown on a prism map if the support exists. It's focus is on annual geopolitical series. To help visualize the geographic relationships, places can be grouped into regions. Here is an example:

The data here is percentage Republican vote. The date on the near left of the slider represents the position of the slider while the date on the far left of the slider represents the latest date where a sample value exists. In this case, the latest sample is 1920 since the next election is 1924.

On the bar chart, the interiors of the bars are interpolations of the vote in 1920 and 1924 for the current date of 1923, so the republicans gain in Vermont and Maine, but break even or lose elsewhere. The black outlines and the values are those from the sample date, in this case the 1920 election. Mississippi has been selected so it's bar is highlighted. The Plains and Rocky Mountain regions have been closed so their entries are not shown.

On the prism map, the height of each state is proportional to the vote in that state. The map can be rotated, centered, zoomed, and the heights scaled by use of the mouse. Mississippi is again highlighted, and the regions which are closed or the states that are hidden are not shown. Regions having undefined values are also not shown.

The prism map capability requires a system with a version of Java of 1.4.2 and will not be shown otherwise.

Each region or place entry is displayed as a bar in the chart and a shape on the map. Entries can be sorted by name or value, selected to allow them to be tracked easier or to hide them, just high or low regions displayed, and scales chosen for the values and the chart.

In order to view important portions of data with many entries, regions can be collapsed or expanded, selected entries can be hidden, all hidden entries re-displayed, and a set of entries with the largest or smallest values can displayed.

A series can be saved as a file compatible with most spreadsheet programs, and any file in this format may be read in and displayed. Only a few hints may be necessary to identify the rows and columns.

Several series can be combined over a common range of times and regions by creating a new series and providing formulas to compute its values from selected input series. Links can be added in a spreadsheet program to allow web pages to be brought up which are relevent to a specific time or place. Here is an example formed by adding the percentage Republican and Democratic votes. It is sorted by Value.

Clicking on the Sample date of 1948 brings up a web page about the election in 1948 so you can answer the obvious question: Who was the third party candidate in 1948? Clicking on a state brings up the home page of the state goverment. Some files have footnotes for names instead of links. When such a name is selected, the footnote will be displayed over the slider rather than the URL. World statistics will have date and place links to the Wikipedia by default.

The application is executed by opening a Java Web Start file. Since it uses a native library (Jogl) for rendering the 3D scenes, the application requires full access to the local system. The application also has access to local files and locations on the internet.


Controls

Use the slider to vary the date, click on a the triangle to the left of a region to open or close it, or click on the sample date or a region or place name which is shown colored as a link to follow the link in your default browser or to display a footnote.

Selections of entries may be made by clicking within a bar's interior, dragging through a group of bars, or using Shift+click to extend a contiguous selection. Using the modifier key for menu shortcuts (Control or Meta/Command), you can toggle entries without effecting those entries previously selected. Otherwise, the previous selections are first cleared.

A single click on a region on the map will toggle it's selection. Also, on the map the left mouse rotates, the middle mouse moves, and the right mouse zooms the map. Pressing both the middle and right mouse allows the height of the regions to be scaled.

The Edit menu aguments the selection choices with Select All and Unselect All. It also includes entries to Hide Selected entries, Hide all but Selected, and Unhide All. These may be used to display just the interesting entries. Hiding a region will hide not only it, but everything grouped below it. Hidden entries and entries within a closed region will be not be shown on the map and the map will be rescaled when entries are hidden/shown or regions opened/closed. If you hide an entry which is always much taller than everything else, the rescaling of height helps you see the differences in the remaining entries.

The File menu's Open/Close/Save selections are used for operations to the local file system. The files they deal with are described in detail below and contain a tabular form of the series data. Location allows you to open a file on the web. Save As Grouping may be used to create a grouping file which can then be made availble through the Add a Grouping menu.

There are also menus to access a number of files that have been gathered for time series of US and World data. They are just shortcuts for opening those files. These menus can be customized for your own files - see the Customization section below. The New and Properties (or Get Info) menus are described below.

The View menu contains controls for the display of the series. It does not change any of the values, just they way they are shown. Show/Hide Grouping controls the display of the regions. This is useful in conjunction with the Sort selections to display all the places sorted independently of the regions. If the Grouping is being shown, the places are sorted within the regions. Grouping is also used when writing a series to determine if the regions will be written out as well as the places.

Show Subseries is useful for displaying the subseries added together to create a series and is described in the Computational Details section.

Chart Scale plots the values on a linear or log scale that is useful for data like population which has a very wide range of values. Sorting can be Unsorted (the original order in the file), by Name, or by Value (the default). Scale Values changes they way values are shown but not the values themselves. Identity shows the underlying data, Thousands divides the original data by 1000 and adds "in thousands" to the title. Hundreths multiples the data by 100 (to convert a ratio to a percentage, for example) and shows "in hundreths" in the title.

The View menu also contains a Display menu that allows you to show just the entries with the Top or Bottom 30 or 75 values, or All of the entries which are not hidden or closed. Note that the set of entries which are displayed may change as the slider selects different dates since the values change with the dates. Regions are always displayed unless hidden.

Most statistics use modern place names even though the geographic area for that place may have changed over time, so you may see statistics about Russia that also include entries for Russia prior to the breakup of the USSR in 1991. Other statistics may include both historical and modern places, typically with 0 or invalid data for the years when a place was subsumed by another or was not in existence. Although this usually causes no confusion on the bar chart, it may create confusion on the prism map since, by default, both places will be displayed and usually one will hide the other. In particular, clicking on a region with both places displayed may select the one which is hidden and thus not be visible, but the name of the region will be displayed just above the slider.

This should usually be sufficient, but in some cases the values are given just for dates when the country was in existence. The Show all Places/Hide obsolete Places menu controls the suppression of the display of places on the prism map during the years the places were not in existence. Hence the USSR will only be displayed between 1922 and 1991 and Russia will be displayed only up to 1922 or during or after 1991. This currently effects only the recent changes to Germany, the USSR, Yugoslavia, and Czechoslovakia.

The Window menu allows you to select among the currently opened series. Use this menu to view a series you've opened using one of the File menu selections.

The Help gives access to this User Guide and program acknowledgments. Tips for using the various menu or dialog fields are shown as the mouse rolls over the items. The About menu gives information about the version of the application. The Quit menu item is in the Application menu rather than the File menu on the Mac.


Computational Details

New is used to compute a new series from your selection of the currently opened series selected from the list shown. Properties (or Get Info) will display those properties for the current window.

The title and citations fields provide information that is saved with the series to identify it. Use of URL's (Web locations) to locate the source of the data is strongly encouraged to allow others to verify your information.

The Grouping File allows you to select among known files that group places into regions. Adding a file to the set can be done using the Add a Grouping menu on the File menu.

The Namespace option resolves the names and locations of places against a US or World gazetteer, None, or arranges the entries in a Grid. The Grid namespace is useful when showing the subseries that make up an additive series or when the "places" have no geographic reference. More detail on this is given in the description of Show Subseries near the end of this section.

The selected subseries are combined into a new series using the compute and combine formulas.

When computing a new series, note that different input series may have different spans of times and different sets of places. Only the common range of times is used, with linear interpolation used to compute values where not directly available for a series. So if one series has samples in 1930, 1960, 1990, and 2000 while another has samples in 1960, 1995, and 2001 then the common range is 1960, 1990, 1995, and 2000 where interpolation is used for the first series in 1995 and for the second series in 2000.

Only the set of places common to all input series is used. Warning dialogs describe the ones ommitted.

The compute formula describes how to compute the value of the new series for a specific time and place from the corresponding values of each of the subseries. The variable d represents the current sample date and the variables s1, s2, ... represent the values of the input series. A per capita computation might be s1/s2 where s1 represents something like Total Income and s2 represents Population.The sum of Republican and Democratic vote can be expressed as s1+s2 where s1 is the Republican Vote subseries and s2 is the Democratic Vote subseries.

The operators available are '+', '-', '*', '/', log, ln, abs, sqrt, mod, angle, sin[h], cos[h], tan[h], asin[h], acos[h], atan[h], rand, sum, and cpi. cpi is the US Consumer Price Index normalized for the years 1982-1984. To convert s1 in 1982-1984 dollars to dollars in the year xxxx, use s1*cpi(xxxx); conversely to convert dollars to constant 1982-1984 dollars, use s1/cpi(d). So to convert s1 in dollars to constant year yyyy dollars, use s1*cpi(yyyy)/cpi(d).

The combine formula describes how to accumulate values of several places into an appropriate value for a region. In this case the variables s1, s2, ... represent vectors of the values of places within a region, and s represents the vector of values resulting from the compute operation. So an appropriate formula to compute per capita income for a region is sum(s1)/sum(s2) which is quite different from sum(s1/s2) where the vector division is done element by element. If there are places a, b, and c in a region, in the first formula we have (s1.a+s1.b+s1.c)/(s2.a+s2.b+s2.c) where the second formula would give (s1.a/s2.a + s1.b/s2.b + s1.c/s2.c).

To compute an appropriate percentage total vote, information about the total number of people voting in each state is necessary to weigh the percentages properly. Without that information, setting the combine formula to 0 is about all you can do. If s3 is a subseries with the number of number of people voting, then sum((s1/100)*s3+(s2/100)*s3)/sum(s3) might be an appropriate combine formula. NOTE: At present, vector arithmetic works properly for sum and for the operators '+', '-', '*', and '/'.

Here is an example which computes the total income per state from the per capita income and the population. Note that the combine formula, sum(s), could also be written sum(s1*s2), but not sum(s1)*sum(s2).

Use the Properties (or Get Info) menus to inspect some of the demo examples for more ideas. The computed series are shown in the US/World Series menus with the notation [=].

Show Subseries from the View Menu may be selected to help see the larger picture when a series comprises a number of subseries added together with a compute formula of s1+s2+.... This displays the labels s1, s2, etc within the bar and there is a division noted between them. If the namespace parameter is grid, the cylinders displayed in a grid on the map will have pie charts on their tops showing the proportion of each subseries to the current value. The height of the cylinder is the current value. The Show Subseries capability is restricted to ungrouped series, so you must first Hide Grouping if it is present. Here is a simple example of a subseries:

The following example shows the grid namespace used with a series which has a place for various grade levels of education in Canada:

In order that the combine formula is useful when some of the data being combined are not finite values (i.e., NaN or NegativeInfinity or PositiveInfinity) the sum() operator will treat non-finite data as 0. In order to make this consistent for all subseries, if a place has a non-finite value for any subseries, then the values of that place in all subseries will be treated as NaN for the purpose of computation. Thus if place is NaN in s1 but finite in s2, then it will effectively be ignored in both sum(s1) and sum(s2).


File Format

You can create your own input data to the program by using a spreadsheet or plain text editor to create a Comma Separated Value (CSV) file with places down and times across. The minimal form looks something like this:

This is a title,1940,1980,2020
New York,10.7,14.8,22.76
New Jersey,11.5,45,13.001

In more familiar form as a spreadsheet it would look like this:

            A          B      C         D
1   This is a title  1940   1980      2020
2   New York         10.7   14.8     22.76
3   New Jersey       11.5     45    13.001

The columns holding values are usually determined by the first row with three or more consecutive dates. If the column of places is not the last column before the table of values, then a column heading of areaName is necessary. A column with the label areaLink will be taken as the web link fields for each area (place or region) or a footnote if it is not a URL. If there are regions grouping the places, a column with the heading areaLevel holds a code starting with either r for region or p for place followed by the level numbers with 1 for the highest level, 2 for the next, etc. This column is created when a grouped series is written.

Several row headings can be placed in the first column. They are namespace, which must preceed all place or region entries and specifies a world or us gazetteer to use in resolving names in the series or grid to create an array of cylinders on the map; date, to indicate the dates are in this row; dataLink, to indicate links for dates are in the value columns of this row; title, which overrides a title found in the row containing the dates; citations, which is followed by one field for each reference or citation; groupFile, which gives the name of the Grouping File; compute, which is followed by the formula and then the file names of each subseries used in the computation of this series values; and finally combine, which is followed by the formula for combining place values into a region. The tabular values are expected to be present - no computation is done from the compute or combine formula when a file is read, they are there to document the computation.

Inspect the output of writing one of the demo series to see an example with most headings supplied.


Executing the Application

Time and Place is an application designed to run under Java Web Start to provide immediate updates to new releases. Java Web Start is a part of any browsers Java Plugin installed within the last year or so. If you need to, you can download Sun's Java plugin (the JRE - Java Runtime Environment) on your computer. It is available for most systems (except for Mac's prior to OS 10) from http://www.java.com:

The prism map capabilities require Java 1.4.2 or later and a video card with OpenGL support. It will not be shown if the Java support is not available. The Jogl library used to create this map is in development, so problems may still exist. A garbled display can usually be cleared by resizing the window or moving the divider between the two panes. Please report any problems which occur, especially those where things stop responding.

The application requires access to the local system to allow it to load the native Jogl library and to access files on the internet other that those on the home site of the application. This also allows the application to be customized to access your own statistics files.


Customizing the Time and Place Application

If you have a group of files which you would like to make available, you can modify a template JNLP file which invokes Time And Place to supply menus for your files to replace the US and World menus.

Create a text file with the menu structure you would like using leading tabs to build the menu hierarchy. Then, for the lowest level menu items that should open a file, add a tab and the URL of the '.csv' file to be opened. Here is an example:

Production
	Crackers	http://yourdomain/crackerProduction.csv
	Antacids	http://yourdomain/whatever/antacidProduction.csv
Consumption
	Crackers	http://yourdomain/crackerConsumption.csv
	Antacids	http://yourdomain/whatever/antacidConsumption.csv	

Place this file on your site, say in a file called http://yourdomain/yourMenu. Then get the template TimeAndPlace.jnlp file (right click on the link to download it without executing it) and replace the line between the <application-desc> and </application-desc> elements toward the bottom which reads:

    <argument>menu=http://agileimage.com/html/statistics/DataMenu</argument>

to be:

    <argument>menu=http://yourdomain/yourMenu</argument>

You can then put the customized JNLP file on your web site, and use it to bring up the Time and Place application customized for your data. If you would like to incorporate some of the US or World Series, you can modify a template of the normal DataMenu (again, right click on the link to download it without executing it).


License.

This Time and Place Software is currently a proof of concept demonstration. It can be used freely, but no guarantee is made of the correctness of results. The Time and Place Software is provided on an "as is" basis. Agile Image Movers makes no warranty, express or implied, with regard to the use of the Software. Agile Image Movers does not represent or warrant that the Software will operate error free or that defects in the Software will be corrected. Agile Image Movers shall not have any liability for claims, losses, damages or injuries arising from the use of the Software

Acknowlegments.

This program uses several useful libraries. The details are here.

Agile Image Movers home page