View source for OnDraw Google map

[[Category:Google Maps from OnGraphDraw library functions]]
''Requires release [[Analytica 5.2]] and [[Analytica Enterprise]] or better''

Use this function to draw a google map under your plotted data to plot data on a map. You'll need to have the longitude and latitude of each or your data points.

<center>[[image:Power plants on map.png]]</center>

== OnDraw_GoogleMap( canv, info, roles ) ==

This function is included in the '''OnGraphDraw Google Map''' library.  Use it to display a map under your data in a result plot, where the X-axis of your plot is longitude and the y-axis of your plot is latitude.

===Setup before using in your model===
# Select '''Add Library...''' on the '''File''' menu, click on the "<code>Google Maps from OnGraphDraw.ana</code>" library file. You can embed or link, but we recommend linking it.
# Go to the [[Attributes dialog]] by selecting '''Attributes...''' from the '''Object''' menu. With '''Class=Variables''', make sure there is a check before the [[OnGraphDraw]] attribute.

===How to structure your data ===
You'll need to create a plot where the x-axis is longitude (in degrees) and the y-axis is latitude.  There are many ways you might accomplish this, depending on how your data is already structured. Here are two simple ways.

(a) Create separate variables for Latitude, Longitude, and the data you want to depict (e.g., by using color, symbol shape or symbol size). These should all share a common index (your "point" index).

Press the '''[XY]''' button to add in comparison variables. Add in Latitude, Longitude, and any others to be depicted. 

The example model "<code>CSV read and Google Maps plot.ana</code>" uses this data organization.

(b) Organize your data in a 2-D table, where one index corresponds to the individual points, and the other index contains a relative small number of labels that includes <code>'Latitude'</code>, <code>'Longitude'</code>, and any other data you want to depict.

Press the '''[XY]''' button and check "Use comparison index". Select the second index as your comparison index.

===Graph setup ===
Bring up the [[Graph Setup Dialog]] and select the desired line type. The most common use case is a symbol-only plot, with variable symbol size selected. Use this configuration when you want symbol size to vary to depict a continuous quantity such as generation capacity in the example plot above.

On the Style tab, it looks best to set Grid and Frame to None.  This is optional.

Apply Graph Setup changes, the select your main result for Symbol size, and set Horizontal to longitude and Vertical to Latitude.

=== Set the OnGraphDraw attribute ===
Now you are ready to use the function! In the Object window for your result variable, find the [[OnGraphDraw]] variable. Place a check on "''before drawing'" and uncheck the others, and set the [[OnGraphDraw]] expression to:
<code>
:roleChanges := [[OnDraw_Google_map]](canv, info, roles)
</code>

=== Suppressing when pivot is wrong ===
You'll get maps of random locations in the world if your pivot is something other than latitude on the Y-axis and longitude on the X-axis. Since your model end-user might pivot the graph, you might want to configure it to not show a map when the pivot is something else. 

The [[OnDraw_Google_map]] function itself doesn't know where the latitude and longitude dimensions are coming from, so it doesn't do this test.  But two library functions are included to perform this test in the two most common cases.

==== Test_map_pivot_vars(info, roles, latituteVar, longitudeVar) ====

Use this function to test for the correct pivot when the latitude is in its own variable and longitude is in its own variable. In this case, assuming here that your variables are named Target_latitude and Target_longitude, your [[OnGraphDraw]] expression would be
<code>
:[If]] Test_map_pivot_vars( info, roles, Target_latitude, Target_longitude) [[Then]]
::	roleChanges := [[OnDraw_Google_map]](canv,info,roles)
</code>

In the example model "<code>CSV read and Google Maps plot.ana</code>", the variable '''Generation_capacity''' demonstrates this usage.

==== Test_map_pivot_slice(info, roles, latitudeLabel, longitudeLabel) ====

Use this function to test for the correct pivot when the latitude and longitude are in the same table in separate slices. In this case, you'll need to be viewing the result of this table. Some data values might also be in this table, or they might be added as exogenous variables. The latitude and longitude will be slices along an index that we refer to as the ''comparison index''. To get latitude on the vertical and longitude on the horizontal, you'll need to press the '''[XY]''' button to turn on the comparison index and make sure the correct index is selected. Once you've done this, your columns with latitude and longitude data are available as graphing roles. Note that a comparison index is required to be short -- fewer than 30 items.

To use this function, you provide the labels of the latitude and longitude columns. For example, if latitude is in the 'Y' column and longitude is in the 'X' column, then the [[OnGraphDraw]] expression would be:
<code>
:[[If]] Test_map_pivot_slice(info, roles, 'Y', 'X') [[Then]]
::	roleChanges := [[OnDraw_Google_map]](canv,info,roles)
</code>

In the example model "<code>CSV read and Google Maps plot.ana</code>", the variable ''Plant_data_on_map'' in the submodule titled "''When data is in one table...''" demonstrates this usage.

=== Your API Key ===
The very first time you display a map result, you'll be asked for a Google API Key. You need to get this from Google and enter it.  The popups provide instructions for how to obtain it.

Once you obtain your own API key and enter it, you'll never be asked for it again, with this model or other models.

If you ever need to reset it, view the main diagram for the ''Google Maps from OnGraphDraw'' library. You'll find a button there to reset it.

== An example model ==
An example model <code>"CSV read and Google Maps plot.ana"</code>, which is included with Analytica in the <code>Data Analysis</code> folder, demonstrates the use of this library function. 

After loading the model, view the result graph for Generation capacity.  (The screen shot of this appears at the top of this page).  Use the ''Select fuel type(s)'' multi-choice to explore other power plant types in California.

== See Also ==
* [[OnGraphDraw]]