Creating Spatial Lens Boundaries for Region Mapping

Site Administrators can create custom choropleth maps for use in 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 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 and the boundary file must be public before you start.  

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".  If your boundary dataset is not listed, check whether it has been made viewable as Public first.

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.

Note: A small subset of datasets and filtered views currently have visible computed region columns. To remove these columns in Exploration Canvas, edit the asset and remove the column from the select statement. Removing a computed region column from a select statement will make it no longer visible in Exploration Canvas and still usable in Visualizations Canvas.

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. When it is disabled, it does not show in the list of available boundaries for users to choose from.

• Enable Quick-Add - Choosing this option saves you time and effort. If there is a boundary that your users will want on most of their maps, 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. These changes will automatically go into effect on already created maps.

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 an 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 Map

Once the Spatial Lens Boundary is set up, you’ll want to make it available for use on datasets.  To do this a site administrator, dataset owner, or anyone that can edit the source dataset must initialize the Spatial Lens Boundary on a dataset with geo-referenced data.

Anytime a new dataset is added to your site, unless “quick ads” was enabled when it was uploaded, you’ll need to initialize each custom Spatial Lens Boundary.

To initialize the Spatial Lens boundary for a dataset with a point column, click on 'Create-Visualization' to open the new visualization canvas and follow the steps below:

1. Select 'Map'

2. Select the point column in the Geo column section

3. Select 'Region map' under point aggregation

4. Select the boundary that needs processing.

NOTE: 'quick add' spatial lenses will be readily available to select.  spatial lenses that are not set to be automatically added to new datasets will take a few seconds to process.

Once processed, the boundary will be available to users to use on that dataset. The map draft created in the process described above DOES NOT need to be published for the processed boundary to be available. After processing the map draft can be deleted if not needed.