Skip to main content

Using Maps in Analyses

Prerequisites​

The Qarbine Administrator must define a Mapbox token to use the map custom cell. Instructions to do this are within the Tools;Administration Tool area of http://doc.qarbine.com.

Overview​

A custom cell supporting embedded maps may be available depending on the Qarbine edition and release level. The Mapbox allows developers to integrate geographic maps into their applications. Qarbine has a custom cell to support embedding maps into your templates and subsequent analysis results. Below is an example map.

  

Complementing the map custom cell is the “Map View Button” custom cell which opens up Google maps on a geographical location.

Geospatial Prompts​

Qarbine prompts may include geospatial proxity in what their runtime dialog. This can be used as part of a query to retrieve the data being analyzed. See the Tools;Prompt Designer documentation for details on using this widget.

Sample Data Source​

As an example a data source can be defined as shown below.

  

with the query specification of

db.theaters.aggregate( [
{$match: { "location.address.state" : "CA"} },
{$project: {where: "$location.geo"} },
{$limit: 20} 
] )

Below is some of the resulting answer set.

  

Selecting a row shows its details on the right hand side.

  

This map related data is in the longitude and latitude values within the “coordinates” embedded array of the embedded “where” field document.

Saving the Data Source​

To save the data source click

  

Navigate to the catalog folder of interest.

In the Catalog dialog, fill in the name, description and other fields.

Click

  

The data source is saved in the catalog and is remembered as a recent data source as well.

This particular data source example can be found at “example/Custom cells/Theatres in California”.

Template Definition Steps​

Specifying the Data​

This example is in the catalog as “example/Custom cells/Theatres in California along with map with circles and no details”.

Open the Template Designer for a new template.

Access the properties dialog by clicking

  

In the dialog enter a name and description.

  

Specify the main data by choosing the drop down option highlighted below

  

Choose

  

Click

  

The reference is filled in within the properties dialog.

  

Close the property dialog by clicking

  

The right hand side of the Template Deisgner displays information on the general structure of the main data.

  

The coordinates array has the longitude and latitude values.

Defining the Basic Map Cell​

The map custom cell requires how to determinant he center of the map and a list of geographic points. Usually the cell is placed on a summary line.

Select a position on the group summary line.

  

On the right hand side choose

  

Select the custom cell highlighted below.

  

Click

  

The custom cell is added to the template with its default properties.

  

Custom cell summary information is shown on the right hand side.

  

Its default formula is

  

You can adjust the width of the output map as shown below.

  

On the right hand side you can adjust the height as well.

  

You can adjust the initial zoom level using the slider shown below.

  

Defining the Map Markers​

The custom cell requires a list of markers for what to show. As noted on the right hand side,

  

Recall the data being processed has the following general shape.

  

The mapping point data is the longitude and latitude numbers in the coordinates field. Qarbine has several macro functions supporting geographic points. You can access the integrated Macro Function Help content by clicking the image highlighted below to the right of the formula entry field.

  

Choose the Help tab and the highlighted section below.

  

The section scrolls into view.

  

The primary functions of interest for points are shown below.

  

In this case the pointFromGeoJsonHolder function will be used to create a point object on the BODY line.

The first body line cell has the formula

pt = pointFromGeoJsonHolder(#location.geo, #theaterId)

Its width is 3

  

and formatting is

  

The second body list cell shows the formatted address information as

concat(#location.address.street1, ' ', #location.address.street2, ', ', #location.address.city)

Select the map custom cell again. While processing the body the points are added to the marker list using the formula shown below.

  

That list populates the map in the result with a marker for each location.

Sample output from this custom cell is shown below.

  

The marker tooltips are the theatre identifiers as used in the body formula

pt = pointFromGeoJsonHolder (#location.geo, #theaterId)

Your data likely has a better choice for a tooltip label.

Adding a report header and a group header can generate the following result.

  

Saving the Data Source​

To save the template click

  

Navigate to the catalog folder of interest.

In the Catalog dialog, fill in the name, description and other fields.

Click

  

The template is saved in the catalog and is remembered as a recent template as well.

This example is in the catalog as “example/Custom cells/Theatres in California along with map”.

Just Displaying the Map in the Result​

There are cases when all you want is the map as the result. This may be the case for a dashboard for example. To accomplish this select the body line.

  

On the right, enter the line process condition shown below.

  

Uncheck the checkbox below.

  

Shown below is the resulting output. The “Address” group heading line has been removed.

  

This example is in the catalog as “example/Custom cells/Theatres in California along with map and no details”.

Displaying Shapes Instead of Pin Markers
Rather than pins set the pt variable using the following formula

pt = mapCircle(pointFromGeoJsonHolder(#location.geo, #theaterId), 2)

In the map custom cell then use the following formulas.

  

Below is the result of these changes.

  

Other Macro Functions of Interest​

locateStreetAddress​

Qarbine provides an endpoint to lookup the geographic coordinates (latitude and longitude) given a place name or street address. The Google Maps services can be used to look up the geographic coordinates. Also, the Azure Maps Search service has a set of RESTful APIs designed to search addresses, places, and business listings by name, category, and other geographic information. The return value is a Geo JSON object as depicted below.

{
"type": "Feature",
"properties": { "name": the long address string" },
"geometry": {
   "type": "Point",
   "coordinates": [longitude, latitude ]
   }
}