Dots Help center

Here you'll find a collection of How-To articles and guides to help you get started with the products built and supported by the team at Hikaya. (opens new window)

Not finding what you need? Get in touch with our team directly at: support@hikaya.io

Dots is a modern visualization and reporting tool to help nonprofits connect their data from multiple sources to visualize and make results reporting easier.

Some of the key features of Dots are:

• Import data sets from external sources.
• Perform cleaning and scheduling operations to keep your data up to date.
• Visualize your data in map layers using our interactive mapping portal.
• Create charts and tables to save them on a dashboard to share with others.
• Author narrative reports with data generated from your data sets.

Have a use case that you'd like to see if Dots can help with? Contact us at: info@hikaya.io

Account setup

Register new account

Setting up an account with Dots is simple. Go to https://dots.hikaya.app/register/ (opens new window) To register, you'll need to complete the following fields:

• first name
• last name
• username
• email address
• password

After successfully registering your account, a verification email will be sent to your registered email address. Open the verification email and click Confirm email or click on the provided link in your email to complete the verification process.

Once you have confirmed your email address, you will see a message that your email address has been verified. Next, you can navigate to the log in page to get started.

Didn't receive a verification email?

If you do not see the verification email in your Inbox, please check your email's spam folder. Alternatively, go to the log in page and log in with your credentials. If your email hasn't been verified, you will see an option to Resend email.

Forgot password

If you have forgotten your password you can click on ‘Forgot password’ on the Log In page or go to: https://dots.hikaya.app/forgot-password/ (opens new window)

Getting started

Create a workspace

After logging in to your account the first thing to do is to create your Workspace. Click on Create workspace to create a workspace where all your work can be saved and shared. A workspace is used to control who has access to your data and visuals and will be used as a space to collaborate with others on your team.

You will need to create a workspace before you can use the main features of Dots.

When creating a workspace, start by giving your workspace a name. Next, choose a custom URL for your workspace. It is recommended that it resembles the workspace name. Both the workspace name and the workspace URL needs to be unique. You will see a green check mark that confirms if your workspace URL is unique.

Import table

After the workspace is created you are ready to start! To begin, import a data table that you want to visualize. Choose a dataset that has GPS data or administrative boundary information which will help to build your maps.

Currently you can import data from spreadsheet files or from third-party data collection tools like KoBoToolbox (opens new window).

To import a data table go to the Data menu from the Navigation bar. You can then click on the Import table button. You can then either choose to import a spreadsheet file from your local computer or log in to your KoBoToolbox account to import data from there. For more details, see Import spreadsheet (opens new window) and Import from KoBoToolbox (opens new window).

Spreadsheet files supported are: .xlsx, .xls, and .csv formats. Currently, we only support importing from the Kobo server (opens new window) for Humanitarian organizations (hosted by the UN OCHA).

Create map layers

Now that you have a data table imported, you are ready to create a map layer. Creating map layers will allow you to visualize data from your imported tables using one of the various map layers Dots supports (see Supported map layers (opens new window)). To create a map layer, select a data table and click on the Add new layer button on the bottom of the Layers panel.

To create a map layer, choose a name for your layer and select the map layer that you want to create.

Next, the process will walk you through the following steps to:

1. Select a map layer that you want to create.
2. Select a location column from the data table that will set location points or areas of your map layer.
3. Select a value column will determine the data you would like to visualize and help to color the map layer.
4. Select columns to display in a tooltip. When viewing the map layer, the columns you select will display when you hover over any data points on your map layer.

View your map

After creating your layer, you can now see your data visualized in a map.

Account profile

Update account information

To view your profile information, look to the top navigation and click on your profile icon located in the top-right corner. Then select your profile from the side bar, this will bring you to your profile information.

Change password

On your profile, select the Security tab. This is where you are able to update and change your password.

Personal access tokens

On the Security tab, you can also find your personal access token. This can be used to create auto-updates with mobile data collection tools like KoBoToolbox.

How to generate a personal access token

To create a personal access token, click the Generate button.

Workspace

Update workspace information

To get to your workspace settings, look to the top navigation and select profile icon located in the top-right corner of the application. Then select ‘Settings’ to access your workspace settings.

Upload workspace logo

Navigate to the Details tab of your workspace settings. Under the Details tab you will be able to see your workspace information including an option to upload a logo image that will set update the logo across your workspace. Select the current logo to upload a new workspace logo from your computer.

Invite new member

To manage members of your workspace, click on your profile icon in the top-right corner and under the menu, click on Members or from the Settings page, you can click on the Members tab. From here you can invite new members by clicking + Invite member button. Next, enter their First Name, Last Name, and Email Address. You can invite multiple members by clicking the + Add member button. Once you have entered your members, click the Invite button and an email will be sent to the email address provided.

Completing account registration

Every invited member will receive an email inviting them to join your workspace. They will need to register and create a **Dots** account in order to join your workspace.

Data

Import from a spreadsheet

To import a data table, click on Data menu from the navigation bar. Next, click on Import table and select Spreadsheet. This will launch a window where you can 1) drag and drop a file from your computer or 2) locate and select a file from your computer's file directory.

Once you have selected a file to import, Dots will provide a preview of file where you can review the column headers and glance at the first and last 5 rows of data so you can be sure it's in right format before importing.

To complete the import process, click on the + Import button.

Supported spreadsheet formats

- `.csv` - `.xlsx`, `.xls`

For spreadsheets with multiple sheets, Dots will only import the first sheet found in the workbook.

Import from KoBoToolBox

To import a data table, click on Data menu from the navigation bar. Next, click on Import table and select KoBoToolbox. This will launch a window where you can sign in to your KoboToolbox account (Humanitarian server only). Once signed in, Dots will display your list of forms. Select the form and click Preview.

Next, Dots will provide a preview of file where you can review the column headers and glance at the first and last 5 rows of data so you can be sure it's in right format before importing.

To complete the import process, click on the + Import button.

Tables settings

Each data table you have imported will have its own table settings menu. To access a table's settings, view the table and click on the ellipsis icon found on the top-right corner on the table view. This will expand the table settings menu where you can 1) rename table, 2) export table, and 3) delete table.

For tables imported from KoBoToolbox, the table settings will provide you with additional configuration options:

• Change column header language. Select the language to display the column headers in when viewing your table.
• Enable/disable auto-updates. This feature allows Dots to automatically import new submissions from KoBoToolbox and update its data table with an additional row for each submission.
• Metadata summary. This provides reference information about each table and includes: table name, owner, source, Kobo account/CSV file, URL, number of questions/columns of data, and if it has location data.

Map layers

Map layers are visualizations that are made from data tables that are imported into Dots.

Supported map layers

Dots currently supports the follow map layers that can be visualized on a map.

• Point: If you have GPS coordinates, you can place these points on a map layer.
• Choropleth: If you have location information such as the administrative boundary names, you can map them to official admin boundaries Data service.
• Polygon: If you have a series of GPS coordinates, you can create a polygon layer.
• Bubble: If you have GPS coordinates and would like to weight each point based on a given value from your data you can use the bubble map.
• Heat (coming soon): If you have GPS coordinates and would like to weight each point based on a given value from your data you can use the heat map.

Creating a map layer

Now that you have imported a data table, you are ready to create a map layer. To create a map layer, select a data table and click on the Add new layer button at the bottom of the Layers panel.

Next, the process will walk you through the following steps to:

1. Select a map layer that you want to create.
2. Select a location column from the data table that will set location points or areas of your map layer.
3. Select a value column will determine the data you would like to visualize and help to color the map layer.
4. Select columns to display in a tooltip. When viewing the map layer, the columns you select will display when you hover over any data points on your map layer.

Location

The location step of the map layer is the most important yet complex step in the process to create a map layer. This step will define what column(s) of data are used to position your data points on the map.

Based on which map layer was selected, the location step will prompted you to select column of data that contains the location information used to visualize data on the map. Using the location column, Dots will place markers on the map layer.

Point, bubble, and heat maps

When selecting point maps, bubble maps, or heat maps, the map layer will use latitude and longitude or a single column consisting of GPS coordinates to place data on a map layer.

Latitude and Longitude When using latitude and longitude, select the column of data for each. Both latitude and longitude must be expressed in decimal degrees (opens new window).

GPS Coordinates When using GPS coordinates, the latitude and longitude values should be space separated. The format for GPS coordinates can look like:

[latitude] [longitude] [altitude] [accuracy]

If you are using a mobile data collection tool such as KoBoToolbox, it will automatically capture and save GPS coordinates in the appropriate format. In many instances GPS coordinates come with additional information such as altitude or accuracy since it follows ISO 6709 (opens new window). For the purposes of creating the map layer in Dots, these fields will be ignored.

Capturing GPD Coordinates

For more information on capturing GPS coordinates with mobile data collection tools, read more on the geopoint question type (opens new window).

Polygon maps

For Polygon maps, Dots uses the polygon or multipolygon type in .geojson format to define a polygon on a map layer. According to RFC document (opens new window), a polygon should be an array of GPS coordinates with each separated by a semi-colon.

The following is an example of how the column of data should be formatted and appear in a spreadsheet. For polygons, you will notice that the first and last GPS coordinates are the same denoting when the lines of a polygon are closed.

35 10; 45 45; 15 40; 10 20; 35 10

To learn more about the GeoJSON format

The .geojson format is used to visualize map layers, see this blog post (opens new window) for an introduction into GeoJSON. Here is a snippet of .geojson for point and polygon maps.

Point map

{ "type": "MultiPoint", 
    "coordinates": [
        [10, 40], [40, 30], [20, 20], [30, 10]
    ]
}

Polygon map

{ "type": "MultiPolygon", 
    "coordinates": [
        [
            [[30, 20], [45, 40], [10, 40], [30, 20]]
        ], 
        [
            [[15, 5], [40, 10], [10, 20], [5, 10], [15, 5]]
        ]
    ]
}

Choropleth maps

For Choropleth maps, Dots will use available administrative boundary data to determine location that the map layer will use. In the location step, you are provided with the left source and right source. For the left source, select the country and administrative boundary that you want use. Next, under the left field, you can select the column that you would like to match to your data table in order to link your data with the location data. For the right source, this is your data table that you selected to create a map layer from. The right field is used to match the column of data in your data table with the one provided under the left field.

Preparing your data

Creating choropleth maps requires you to prepare your data tables with a column of data that can be matched with a country administrative boundary found in Dots. See Country Administrative Bouundaries (opens new window) for a complete list supported by Dots. In the repository, click on the Data folder and search by the 3-digit ISO 3166 code. Once you find your country of interest, select the country folder and click one of the available administrative boundaries (e.g. ADM0-ADM4). When you navigate to the administrative boundary of interest, click on the file ending in .geojson.

EXAMPLE: Exploring available country administrative boundaries

For example, Afghanistan's Administrative Boundary Level 1 can be found here (opens new window) and navigating through the file path as such: /data/AFG/ADM1/AFG-ADM1.geojson.

Value

The value step helps you apply a value or weight to each data point or area that is visualized in the map layer.

For Bubble maps and Heat maps, the value column you select will determine size of the data point shown on the map layer.

For Choropleth maps, the value column will be used to style the map layer using a color gradient with darker areas associated to a larger value and lighter areas with a smaller value.

EXAMPLE: Choropleth map with values

This example examines the average income level by district in Yemen. The use of color gradients in styling the Choropleth map shows that the dark green areas represent a larger income value compared to the light green areas that have a smaller income value.

Tooltip

Tooltips in Dots are used to display key information when viewing a specific data point or area on a map layer. When a user is viewing a map layer and finds a data point or area that is of interest, they can click on the data point or area to have the tooltip display more related information. By default, the tooltip will display source of data for the location and value columns.

The tooltip step is used to select columns of data that you want to be displayed in a tooltip description. By selecting the columns of data to include in the tooltip, it can provide your map viewers with more detailed information about each data point or area.

EXAMPLE: Tooltip description

This example depicts a tooltip description with the default location (b_location/gps) and value (c_registration/hh_age) alongside two additional fields: household age (c_registration/hh_age) and region (b_location/region).

Maps

The Maps menu is a place where all your published map layers are visualized. Clicking on the Maps menu found in the navigation bar, you will find a full screen map with your map layers available through a layer panel found on the left side of the app.

Map settings

In Maps you can set the default zoom so that every time you go to Maps, it will automatically zoom to your region of interest. If you have country(s) of interest, you can select them and begin to explore its administrative level boundaries on the map even before you create any map layers!

To access the Map settings, click on your profile icon in the top-right corner and under Workspace, click Map Settings (Only accessible by members who have Admin or Owner roles).

Map placement and default zoom level

Under Map settings, you have the ability to set the default zoom and map placement. To do so, scroll down to the map found at the bottom of the page and begin to move the map itself into the position and zoom level that you prefer. By doing so, you will change the fields found under the Map placement section. Once done, click Save and you will have fixed the map to your region.

Set country administrative levels

Under the Map settings, you can select country(s) of interest and any of its available administrative levels. By doing so, you will enable these country administrative levels to be viewable on the Maps menu. This can be a helpful way to add more context to your visualizations.

If you would like to add multiple administrative levels for a single country, click + Add Country button and a new row will be available for you to select the country and its administrative level.

EXAMPLE: Adding multiple admin levels for a country

Here is an example of Map settings with 3 administrative levels for a single country.

Publishing map layers

Publishing map layers allows your map layers to be viewed on the Maps menu found in the navigation bar. This means map layers can be viewed by members in your workspace. Viewing maps will allow members to toggle on and off multiple map layers for analysis and comparison.

In order for your map layer to be viewable on the Maps menu, your map layer needs to be published first. By default, all map layers are published by default after the map layer is created. Members have the ability to review map layers and decide to publish and un-publish them from the Maps menu.

How to publish map layers

To review which map layers are published, click on the Data menu, select the table in which you have map layers created from and on the layer panel you will see a list of map layers with a toggle switch. The toggle switch is used to publish and un-publish map layers. Once you have finished publishing or un-publishing map layers, you can now click on the Maps menu and see your latest changes reflected in the map view.

View map by layers

After creating multiple maps layers, you can now view them together in the Maps menu. In order to view the map layers, map layers must be published first (see Publishing map layers (opens new window).

On the Maps menu, you can click on the arrow icon to expand the layer panel. Here, you will find two sections:

1. Country: Under Country, you will find a list of administrative level boundaries that have been enabled on your workspace - see Map settings (opens new window) for more details.
2. A list of data tables: Under each data tables you have imported, you will find all the map layers you have created.

As you explore your map layers, you can click on the checkbox next to each map layer to hide or display the map layer. For map layers such as Choropleth maps, you'll notice an additional legend that will appear when this type of map layer is selected.

Have fun exploring your maps! 🗺 🤓