Site Administrators can create custom choropleth maps for use in Data Lens, the New Visualization tool, and Citizen Connect, called Spatial Lens boundaries! These custom choropleth maps allow users to view and interact with the data through a localized lens.
There are a few steps to adding a custom choropleth map to Data Lens pages on your domain:
1. A site administrator must configure the new Custom Boundary to be available for all pages on the site.
Uploading the Geospatial File for Your Spatial Lens Boundary
Site administrators have the option to upload a geospatial file or create a spatial lens boundary based on an existing geospatial map on the platform. Upload the geospatial file via "Import Geospatial Data" through the create a new dataset button. The geospatial file must meet the following criteria:
- Must be a KML, KMZ, Shapefile or GeoJSON file type
- Must be a single layer map that contains polygons or multipolygons
- Should contain a label for each boundary in the map
- Should NOT have a row ID column selected
- Must be published to a public audience and approved by an administrator before creating the spatial lens
Note: The label for each boundary is needed so that users can identify the area that they are looking at on the map. For example, a USA States boundary map would have labels such as Alabama, Alaska, Arizona, etc. These labels must be contained within a column in the geospatial file. You can find the label column in the attribute table for your geospatial file. Once uploaded to Data & Insights, this table can be viewed by selecting the “table view” on the map.
If you are having trouble uploading/creating a spatial lens boundary, please refer to the limitations here.
Adding the Spatial Lens Boundary
Once the geospatial file has been uploaded to your Data & Insights site, you are ready to start configuring it for Spatial Lens. You’ll need an Administrator role to use the Spatial Lens configuration Panel.
1. Navigate to Spatial Lens from the Admin panel on your domain.
2. Click "Add New Boundary" to open the Spatial Lens picker. In this dialog box, find the boundary map and click "Choose".
3. Give your Spatial Lens boundary a name and pick the column that should represent the label for the shapes. By default the Boundary Name is the Dataset Title, this can be edited.
Note: The Boundary Name is in the title of the Choropleth when added to a Data Lens page, so it is important that this name is human readable and will allow users to identify area and regions that the map represents.
If needed, this Boundary name & the label column that you choose can be changed later. A Boundary Name can only be used one time on a domain, and Boundaries cannot be otherwise edited.
Your new Spatial Lens should now appear in the Custom Boundaries list. You’ll see a few different options next to your Boundary name:
- Enable/Disable - When a Spatial Lens Boundary is enabled it is available to use to make a choropleth map on your site’s Data Lens pages. When it is disabled, it does not show in the list of available boundaries for Data Lens publishers to choose from.
- Enable Quick-Add - Choosing this option saves you time and effort. If there is a choropleth that your users will want on most of their Data Lens pages, then choose this option. This means that the Spatial Lens Boundary will automatically be available on every new dataset that is uploaded to your site while this box is checked. You can add up to 5 auto-encoded spatial lenses per domain.
- Edit - Once configured you can edit the boundary configuration and change the Boundary Name and/or pick a different column to be the label on the choropleth map. This changes will automatically go into effect on already created Data Lens pages.
Note: If your Spatial Lens doesn’t appear on the list or you see an error message that “Something went wrong…,” please contact Data & Insights Support with error message code, and/or a screenshot of the error, along with your domain url and the link to the boundary map that you were trying to configure. You may also follow this link for common reasons behind failed spatial lens boundaries.
Adding the new Boundary to a Data Lens page
Once the Spatial Lens Boundary is set up, you’ll want to make it available to all Data Lens page publishers. To do this a site administrator, dataset owner, or anyone that is able to edit the source dataset must initialize the Spatial Lens Boundary on 1 Data Lens page for each dataset.
Anytime a new dataset is added to your site, unless “auto encode on ingress” was enabled when it was uploaded, you’ll need to initialize each custom Spatial Lens Boundary.
*Remember* Map cards, including this new Boundary, only show on Data Lens pages that have a geocoded location column in their source dataset. If the dataset does not have a location column, you will not see the option to create a map of the data in Data Lens.
To initialize the Spatial Lens boundary for a dataset, enter “customize mode” on a Data Lens page for that dataset.
- Add a new card and choose the location column from the drop down list
- Choose Choropleth card type
From the list of boundaries, choose the newly added boundary.
You’ll see a message “Add this card to the page to begin computing this visualization.”
- Add the card to the Data Lens page to initialize it and make it available to publish for every Data Lens page made from that same source dataset.
- The card will show in customize mode on Data Lens page with message “This visualization is being computed. Check back in a few minutes.” This means that the process has started.
You can stay on the page and the choropleth will show when ready, usually, just a few moments or you can save the page, close the tab and the computing will continue. The choropleth will render as expected on the next page reload as long as it is done computing.
Now, whenever any users add a choropleth card to Data Lens pages created from this source dataset, they’ll have the option to use this boundary.