Map View

Nodes in the data can be displayed in a global, geographic map using Map View if geo-coordinates are included in the node file. The map allows you to zoom to the geolocation indicated in the node list. Although latitude and longitude give you the most precise location, zip codes and other geopolitical demarcations (counties, and states) are also rendered on the map if latitude longitude data is unavailable. MicrobeTrace uses CARTO Voyager as our base map provider; the map tiles are based on OpenStreetMap data and are served/managed by CARTO.

IMPORTANT ATTRIBUTION NOTE

If you use a screenshot of your data in Map View for a journal publication, please add the following attribution note "“Basemap © CARTO and © OpenStreetMap contributors; OpenStreetMap data licensed under ODbL. Overlaid MicrobeTrace data © [authors/year]."

---

Map settings

Use the various settings as described below. The settings dialog box has four tabs: Data, Components, Nodes, and Links.

Data

In this example, we would like to visualize node data by zip code. NOTE: The map display is hierarchical, so if your data set has all the data columns listed below, and you select multiple properties, the map displayed will default to the highest available level of geographic precision. Please ensure you select only the variable that works best for your data set, and leave the others as None.

Components tab

Selecting Components will enable making changes to the actual network that will be displayed, including nodes and links. You can also choose whether to would like to use Map View while online or offline. This option will determine which features are displayed. When offline, you can choose to show or hide countries, states and counties. When online, you can choose to display either base map or satellite view layers that are not available offline in MicrobeTrace. If you select these options, MicrobeTrace will download the base map and satellite geographic data (called tiles) from the internet, which are similar to the Google map features.

Nodes tab

Select Nodes to change the appearance of nodes on the map. Nodes can be colored by any variable in your node file. Selecting Color Options opens up the Global Settings menu, and you can customize the Style settings, background, etc. as in other views. If you have colored nodes by a specific variable in the 2D network, those colors (and the key table will transfer over to the Map View as well. You can turn node collapsing on or off. If node collapsing is on, then all nodes sharing the same zip code will be collapsed. Clicking on a collapsed node will show you the component nodes arranged in a spiral (see image)

The transparency and jitter speed of the nodes can be changed using the respective slider bars. *PLEASE NOTE: In many datasets, there can be many nodes that share the same geographic co-ordinates causing a very high node density in the map such that these nodes appear as a single large dot. In order to separate nodes with the same geographic coordinates, use the jitter slider bar to increase the jitter level to separate or jitter the nodes so they are visible. Use Tooltip to change which variables are displayed when the mouse pointer is placed (“hovers”) over a node. For example, if you choose ID from the Tooltip drop-down menu, the node ID will be displayed when the mouse pointer is over that node.

Links tab

Select Links to change the link settings. The features are identical to those in the Node tab. You can adjust color, transparency and tooltip settings.

The image below shows the map with nodes colored by risk factor, and links hidden. When viewing a map, the scroll bar on your mouse can be used to pan around or zoom in and out. By default, the map is zoomed out, and you see a circle with a number that represents the number of nodes. When you zoom in, the nodes pop out to form smaller, more discrete groups. Individual or multiple nodes can be selected or de-selected by using the mouse pointer. These selections will propagate to the Network and Table Views. This enables tracking of particular individuals between multiple visualization windows. As with other views, map images can be exported and saved as .png, .svg, or .jpg image files.

MicrobeTrace contains a small dataset of useful geographic data. This enables it to plot data points on maps, even if the location information is generic and imprecise (e.g. US State).

MicrobeTrace's geospatial data catalog includes:

• Countries (Boundaries and Centroids)
• US States (Boundaries and Centroids)
• US Counties (Boundaries and Centroids)
• Zipcodes (Centroids only)
• Census Tracts (Centroids only)

Custom Maps in Map View / Advanced Settings

⚠️ Feature in development

Everything below is in development as well as the wiki entry

Custom maps are currently under development and are not yet available on the main MicrobeTrace site.

MicrobeTrace can display a user-provided map or floorplan behind a network. Custom maps are useful for non-geographic locations such as hospital floors, clinics, wards, rooms, laboratories, schools, and other outbreak investigation spaces. They can also be used with geographic GeoJSON data.

Choose a workflow

Goal	Recommended method
Match existing nodes to geographic features by ID	Add a GeoJSON location file on the Files screen with the node data
Display a GeoJSON layer without changing node locations	Upload it from Map Settings > Custom Map > Background
Display a floorplan, diagram, or other image	Upload it from Map Settings > Custom Map > Background
Place individual nodes by clicking or dragging	Use Custom Map > Manual Positions
Automatically distribute groups of nodes into labeled areas	Upload an image and use Custom Map > Boundary Labels

Accepted custom-map files

GeoJSON location files added on the Files screen

• File extension: .geojson or .json.
• The top-level GeoJSON object must be a FeatureCollection or Feature. See example json below.
• At least one feature must contain finite coordinates.
• Each feature to be matched must have an identifier in feature.id or in a field under feature.properties.
• Coordinates must use GeoJSON order: [longitude, latitude].

This import method joins GeoJSON features to nodes; it does not create new nodes. A feature identifier must exactly match the _id of an existing node. Features without an ID or coordinates are skipped, as are features whose IDs do not match existing nodes.

For a Point, MicrobeTrace uses the point coordinate. For other geometry types, it uses the center of the geometry's coordinate bounding box. The importer adds these fields to matched nodes:

• GeoJSON Latitude
• GeoJSON Longitude
• GeoJSON Feature ID

When at least one feature matches, MicrobeTrace selects GeoJSON Latitude and GeoJSON Longitude as the Map View coordinate fields. It also retains the GeoJSON as a custom-map layer, initially hidden.

To use this workflow:

1. On the Files screen, add the node file and the GeoJSON file.
2. Confirm that MicrobeTrace identifies the location file as GeoJSON.
3. In the GeoJSON file's ID selector, choose the feature property that matches the node IDs. MicrobeTrace attempts to select a common ID field automatically.
4. Launch the data.
5. Open Map View > Settings > Custom Map and set Layer to Show if you also want to display the GeoJSON geometry behind the nodes.

Add example geoJSON file here

Example GeoJSON location file

This example matches features to nodes using the _id property. This example works with preloaded dataset. After loading switch to files tab, load this file as GeoJSON, push update, and then open Map View.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "_id": "MZ415508"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-83, 40]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "_id": "MZ797703"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-88, 40]
      }
    },
  ]
}

GeoJSON backgrounds uploaded in Map View

• File extension: .geojson or .json.
• The file may contain a FeatureCollection, Feature, GeometryCollection, or another valid GeoJSON geometry object with coordinates.
• A FeatureCollection must contain at least one feature.
• Feature IDs are not required when the file is used only as a background.
• Coordinates must use GeoJSON order: [longitude, latitude].

Uploading GeoJSON through Custom Map > Background displays the geometry but does not join its features to nodes. Use coordinate fields in the node data or the manual-positioning tools to place nodes on it.

For a non-geographic floorplan, treat GeoJSON coordinates as [x, y]: x occupies the longitude position and y occupies the latitude position. The node coordinates and GeoJSON must use the same coordinate plane.

Image backgrounds

The background picker accepts browser-readable image files. Common supported formats include:

• .png
• .jpg or .jpeg
• .gif
• .webp
• .svg

MicrobeTrace preserves the image's aspect ratio and assigns it a normalized coordinate plane beginning at x = 0, y = 0. The longer side is scaled to 80, and the shorter side is scaled proportionally. The loaded-file summary shows the original pixel dimensions and resulting x/y range.

Only one custom background is active at a time. Uploading a GeoJSON background clears the current image background. Uploading an image clears the current GeoJSON background and any existing image boundaries.

Load a background in Map View

1. Load the network data and open Map View.
2. Select the Settings gear.
3. Open the Custom Map tab.
4. Under Background, select a GeoJSON or image file.
5. Leave Layer set to Show.
6. Select Center to fit the visible nodes and background to the screen.

Showing a custom background hides the built-in basemap, satellite, country, state, and county layers. Nodes and links continue to use the normal Map View styling controls.

Use Layer > Hide to temporarily hide the custom background without deleting it. Use Clear to remove it. If the background is an image, Clear also removes its boundary definitions and boundary-generated node positions.

Use coordinates from node data

If a node file already contains coordinates:

1. Open Map Settings > Data.
2. Select the vertical coordinate field under Latitude.
3. Select the horizontal coordinate field under Longitude.

For geographic data, these fields should contain latitude and longitude. For a custom floorplan coordinate plane, use y as Latitude and x as Longitude.

Place nodes manually

Manual positioning works on both custom floorplans and regular geographic maps.

1. Open Map Settings > Custom Map > Manual Positions.
2. Set Positioning to On.
3. Choose a visible node from Node.
4. Click the desired location on the map, or drag an existing node marker.
5. Use Next Unplaced to move to the next visible node without a position.

Selecting a marker while positioning is on selects that node. Selecting the same marker again, choosing None, or turning positioning off stops map clicks from moving it.

The available controls affect visible nodes in the current map mode:

• Clear Selected removes the selected node's manual position.
• Clear All removes manual positions from all currently visible nodes.

When a custom background is shown, positions are stored as floorplan coordinates:

• map_floorplan_x
• map_floorplan_y

When no custom background is shown, positions are stored as geographic map coordinates:

• map_manual_latitude
• map_manual_longitude

Floorplan positions are used only while a custom background is shown. Regular manual map coordinates are used when no custom background is shown and override the selected latitude and longitude fields for those nodes.

Create labeled areas on an image

Boundary labels can automatically distribute nodes into areas such as rooms, wards, buildings, or workspaces. This feature is available for image backgrounds, not GeoJSON backgrounds.

Create a boundary

1. Upload and show an image background.
2. Under Boundary Labels, select a Node Field. For example, select Profession, Ward, or Room.
3. Under Draw, choose one of the following:
   • Polygon: click to add corners, then select Finish. Use Undo to remove the latest corner.
   • Freehand: press and drag to draw an area, then release.
4. Enter a label that matches a value in the selected node field.
5. Select Save.

Boundary matching ignores capitalization and spaces at the beginning or end. For example, a boundary labeled Healthcare matches node values of healthcare and Healthcare. Boundary labels must be unique using the same matching rule.

A valid boundary must:

• Contain at least three distinct points.
• Stay entirely within the uploaded image.
• Have an area greater than zero.
• Not cross or overlap itself.

MicrobeTrace places each matching node at a randomly selected point inside the boundary. The Status line reports how many nodes match a boundary label and how many do not.

Manage boundaries and generated positions

• Show/Hide controls the visibility of saved outlines and labels without removing placements.
• Rename changes the value matched by a boundary.
• Edit lets you drag corners, add a corner by selecting a midpoint, or remove a selected corner.
• Delete removes the boundary and its generated node positions.
• Reposition All selects new random positions inside the matching boundaries.

Generated positions remain stable until the corresponding boundary is changed or Reposition All is selected. A manually assigned floorplan position takes precedence over a boundary-generated position, including after repositioning.

Save and reopen a custom map

Custom-map backgrounds, visibility settings, manual positions, boundary definitions, the selected boundary field, and generated boundary positions are included when the session is saved as a .microbetrace file. Reopening the session restores the custom map without requiring the original background file to be uploaded again.

Troubleshooting

A GeoJSON feature did not match a node

• Confirm that the correct GeoJSON ID field is selected on the Files screen.
• Confirm that the feature ID exactly matches the node _id.
• Confirm that the feature has finite coordinates.
• Remember that unmatched GeoJSON features do not create nodes.

A node is listed as missing map location data

• Select valid coordinate fields under Map Settings > Data.
• Show the correct custom background if the node has saved floorplan coordinates.
• Assign the node a manual position.
• For an image floorplan, confirm that its selected field value matches a boundary label.

Nodes do not appear over a floorplan

• Confirm that Custom Map > Layer is set to Show.
• For GeoJSON, confirm that the node coordinates use the same coordinate system as the background.
• For an image, use manual positioning, matching x/y fields, or labeled boundaries.
• Select Center after loading or showing the background.