Enrich SAS VA Geo Maps with pinned locations loaded from a CSV file

1 Like

In a previous article, Enrich VA Geo Maps using a custom ESRI map with pinned locations, I explained how you can load data from a CSV file to an ESRI map and use that map within a SAS Visual Analytics report. This time, I will explain how you can load pinpoints information from a CSV directly into a SAS VA Geo Map. This article will make use of REST API's to access the report content and update it. Even though, it will use Python code to extract and update the information, you don't need to be a Python expert. There will be no need to write a lot of Python code if you want to reproduce because I will use a Python repository called viyaRestPy to assist in calling REST API from Python.

Let me first show the resulting geo map.

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

This map is based on the MegaCorp table represented by the small teal coordinate points and the pinned location are the SAS offices. The offices locations are coming from a CSV file and the data will be inserted in the report. The logic might look simplistic and it is as you will discover!

Introduction to viyaRestPy

For different projects and workshops, I had to write Python code to call the SAS Viya REST API's. The API's are well documented on developer.sas.com and are easy to use but I felt like I was often rewriting the same code to authenticate and call the REST API's. This is not unique code but it can be time consuming. I finally decided to write some functions that I could reuse to ease the development process. And thus, the viyaRestPy project is born from this.

The logic behind is simple: a main function called callRest that takes care of the authentication and calling the REST API. Besides that a few "Lego" functions that used to achieve some specific tasks that require calls to multiple endpoints. At this point in time, the number of "Lego" functions is pretty small but it can grow quickly as the foundation is there.

The how-to install the tool is available from the GitHub repository: viyaRestPy’s ReadMe.

What you should remember is that the callRest function requires information about the endpoint and authentication information. After execution, it will return a JSON object containing the headers and a JSON representation of the answer to the REST API call.

A simple example calling a "Lego" function called getFolder:

# Import module(s)
from viyaRestPy.Folders import getFolder

# Collect information needed for authentication
authInfo = {}
authInfo["user"] = "gatedemo003"
authInfo['pw'] = "lnxsas"
authInfo["serverName"] = "http://sasviya01.race.sas.com:80"
authInfo["appName"] = "app"
authInfo["appSecret"] = "appsecret"

# Call the getFolder
folder = getFolder(path="/Users", auth=authInfo)

# Display name and description of the extracted folder
print(folder["json"])["name"]
print(folder["json"])["description"]

The getFolder is defined as:

def getFolder(path, auth={}):
    endpoint = "/folders/folders/@item"
    params = {"path": path}
    folder = callRest(
        endpoint,
        "get",
        params=params,
        auth=auth)
    return folder

As you can see the callRest requires some specific information but this information comes directly from the developer.sas.com website as you can see below:

Now, that you have been introduced to viyaRestPy, it is time to dive into the code needed to load the pinned locations into your report.

The report

In order to import the SAS office locations into the report, we first need to have the report. Our report is using MegaCorp table as input and contains a Geo Coordinate object.

When the table is loaded into CAS and added to the report, the first step is to create a geography data item. From the Data pane, select the Facility State, click on the chevrons and change Classification to Geography.

When prompted to edit the geography item, fill in the following information. In this case our Facility State data item uses the US state abbreviations.

You can now add the item to the report canvas. When done, a map is displayed and you can assign the data item roles in the Roles pane as depicted below. To get the exact same map as in this article, you can also switch from the Options pane for the geo map object the Data layer render type from Scatter to Bubble.

We know have a report with some geographic data displayed in it. It is now time to save it and integrate the SAS office locations data.

Integrate SAS office location data

Here is the SAS offices data. You should save the CSV file on the machine where the Python code executes.

The Python code that should be executed to load SAS Office locations into the report can be found in the viyaRestPy package under /Examples/Non-DevOps/loadPinPoints.py.

The code can be executed from the command line after following the instructions to install the package in the README.md file. Here is an example:

In this example, the following options are used:

u - the username
p - the password
sn - the server name
an - the application name that was set when configuring access to REST API
as - the application secret that was set when configuring access to REST API
rl - the report location
rn - the report name
b - the backup location where the report will be copied
i - the input file containing the pinpoint information

After running the code, the report will be updated and look like this picture.

The Code

You might wonder what the loadPinpoints.py does behind the scene. I will try to explain it step by step.

The code first imports the Python modules that are required for the execution.

Then the parameters that will be passed to the command line are defined:

When the parameters are defined, we should retrieve the parameters when the code is called.

Now that we have collected information from the command line, it is time to extract the report information. This is actually the first line of code that is calling the viyaRestPy package. In this case, we call the getReportContent which is a "Lego" function. As you can see, we are just passing the name of the report, the path location and the information needed for authentication.

The next step will be to save a copy of the report content. In case there is a problem during the load of the pinpoints, it can be used to restore the report to his original state.

We are now done with extracting the report. We will now read the data from the input file and transform those data into something that can be inserted into the report. You might wonder how I could get the correct structure for the GraphState_Property. In fact, I have added a pinpoint on the geo map object. After exporting the report, I could use the information in the JSON file as a template. As soon as you have the template, it is easy to use the format function in Python to fill the information in the template. You can see the template on line 137.

After this process, we have an object containing all the information about the pinpoints in a representation that can be used within the VA report. So, we have on one side the report and on the other side the additional information. It is now time to merge them.

Finally, we will load the data back into the SAS Visual Analytics and overwrite the existing report.

This last piece of code is the second "Lego" function from viyaRestPy that we are using. We are passing the content of the report that should be written back to VA. To do this, we need to pass the report name, the path location, and the authentication information.

Next steps

With a little bit of Python code, we have been able to update report content based on information coming from an external source of data. At first, you might think that it is a complex task and that building the "Lego" functions represents a lot of hard work. Of course some of the functions are more complex than others, it would be misleading for me to say otherwise. As you can see, some functions can also be pretty simple as the getFolder function. If you take the time to build a "Lego" function, then it is really easy to use it and to make it available to other users and hiding the complexity of the tasks. If you feel like some "Lego" functions should be added to the viyaRestPy, feel free to contribute. Your work can benefit to others!