Skip to content

Map Locations

Map raw rows from an uploaded file into the scenario's locations table: every facility, supplier, hub and customer your network refers to.

When to use this

  • You're assembling a scenario from raw data and need to declare the places in your network
  • Downstream analysis needs a name to attach demand, supply, lanes or flows to
  • A map view or Center of Gravity needs coordinates

What you need

  • An upstream Import Data node (or operation node) carrying one row per location
  • At minimum, a column that uniquely identifies each location, a name or a code
  • Latitude and longitude columns if you will run map-based analyses
  • Optionally, tags for each location, such as Germany or Export: as a Tags column, or as a second table wired into Tags

Field mapping

Fields are matched by name unless you set them. When the workflow runs, every field you have not set a column for is matched against the headers listed below, case-insensitively and ignoring spaces around the header, and a space inside your header reads as an underscore, so Site Name matches site_name. Setting a column for one field fixes that field only; the others keep following your file's headers, so a renamed column is still found. A required field that no column supplies — no header matched, or you set none or one your table lacks — is reported once, with the headers your table does have.

Set mappings in the node's panel. Connect an upstream table and select the mapping node. A field matched by name is marked Matched by name; pick a column to set it yourself, and Match by name puts it back. Match all by name clears every field you set. Required fields without a match are marked in the panel.

Reshape rows in a Script first. A mapping node only says which column is which field. To drop rows, recode values, or split or combine columns, connect a Script node before it and map the columns the Script returns.

Field Type Required Example What it is Auto-detected headers
Location text Yes Warehouse A Location name (unique identifier) location, loc, name, id, location_id, loc_id
Address text No 123 Main St, City, State Physical address address, addr, street, full_address
Latitude number No 40.7128 Latitude coordinate latitude, lat, y
Longitude number No -74.006 Longitude coordinate longitude, lng, lon, long, x
Type text No warehouse Location type (warehouse, supplier, customer, etc.) type, location_type, node_type, category
Tags text No Germany; Export The location's tags, separated by semicolons, such as Germany; Export. A filter tests one with "Export" in source.tags. tags, tag, labels, location_tags

Tags field mapping

The table wired into Tags is mapped in its own section of the panel, below the node's own fields and in the same way: a field you have not set a column for is matched by name against that table's headers.

Field Type Required Example What it is Auto-detected headers
Tag text Yes Export The tag, such as Germany or Export. A filter tests it with "Export" in source.tags. tag, tags, label, region, cluster
Location text Yes DC Hamburg The location the tag is on. Every location must be one of Map Locations' own. location, member, location_name, location_id, site, facility

How it works

Each upstream row produces one location record. The records flow to a downstream Create Scenario node, which collects everything and writes the scenario.

Every other table refers to a location by its name, and only to a name listed here: a lane, flow, policy, state or demand history row naming a location that is not there stops Create Scenario, which names the table, the rows and the unknown names. A location is never made up to match a name, so a scenario whose rows name places needs this node even when nothing else about those places is known.

Coordinates are decimal degrees: latitude between -90 and 90, longitude between -180 and 180. A location whose latitude or longitude lies outside those, is infinite, or is not a number stops Create Scenario, which names the rows and the values — usually projected metres, or the two columns swapped. A location may have no coordinates at all; when the other locations have theirs, Create Scenario stores it and warns that it will be left off the map.

Tags

A tag is a word you put on a location to say what it is part of, such as Germany, Export or Key Customer. An Add Constraint rule then selects by tag, as in "Export" in source.tags, so a site you tag later is covered by the rule on its next run. A location may carry any number of tags.

Tags come in one of two ways, or both:

  • A Tags column on the locations table, mapped to the Tags field. Each cell holds the location's tags separated by semicolons, such as Germany; Export. Spaces around each tag are ignored. A cell with an empty piece, such as Germany;;Export or a trailing ;, is refused rather than read as fewer tags. A blank cell means no tags.
  • A Tags table wired into the node's second input, Tags, in long form: one row per tag and location, a tag in one column and a location in the other. Its rows are added to the Tags column of the location each row names. Left unwired, the node maps locations only, exactly as without it.

Either way the scenario stores each location's tags once, in its Tags column, so every node that reads the scenario sees the same ones. Tags are compared exactly as written, capitalisation included: Export and export are two tags.

A Tags table is refused, with the rows and the fix named, when:

  • a row lacks its tag or its location
  • a row names a location this node does not map, usually a typo

Workflow wiring

flowchart LR
    n1["Import Data (locations.csv)"] --> n2["Map Locations"]
    n3["Import Data (shipments.csv)"] --> n4["Map Transport"]
    n4 --> n5["Create Scenario"]
    n7["Import Data (lanes.csv)"] --> n8["Map Lanes"]
    n2 --> n5
    n8 --> n5
    n9["Import Data (products.csv)"] --> n10["Map Products"]
    n10 --> n5

To add tags in long form, connect a second Import Data node carrying the Tags table to the Tags input of Map Locations. The first table you connect is the data to map; the Tags table goes to the Tags input.

Common mistakes

  • Two columns claim to be the location. Pick one canonical column, a code or a name, and use it across every Map node. New York, new york and NY are three different locations, and a row naming one that this node does not hold is refused.
  • Missing coordinates when a downstream analysis needs them. Center of Gravity and any map view need latitude and longitude. Geocode addresses before uploading rather than inside the workflow.
  • Wiring the Tags table into the first input. It is then read as locations. The Tags table goes into Tags.
  • Separating tags with commas. Germany, Export is one tag with a comma in it. Separate tags with semicolons: Germany; Export.
  • Tagging what a column already says. A location's Type is already there to filter on, as in source.type == "Plant"; a Plant tag repeats it and can drift from it.
  • Wiring Map Locations straight into an analysis node. It has to flow through Create Scenario first. The scenario is what analyses read from.

Messages this node can show

The table this node makes is checked again with the rest of the scenario when Create Scenario assembles it: see messages about the scenario.

A run gives this node 5 minutes. A node that takes longer stops with Time limit reached.

Like every node, it can also stop on the checks before a run and the run's limits.