Distribution maps with mapregions

The mapregions is the most powerful data type in NaturaList. It encodes geographic distribution as a set of region / status / note tuples and produces two complementary outputs simultaneously: a dynamic, color-coded SVG choropleth map in the Details pane, and an annotated inline text list of region names in the taxon card. These can be used independently or together.

The three moving parts

Before entering any data, it helps to understand what the system is assembled from.

1. Your data - stored in the data sheet. Each cell records which regions a taxon occurs in, with an optional status value per region and optional footnote notes. The data contains no color or display information; it is purely factual.

2. Region names (Map regions information table) - a dictionary that translates short region codes into the human-readable names shown to users: fr → "France", de → "Germany", and so on. One row per region code, shared across all map columns in the project so you can reuse region names if you present the same map filled with different data (e.g. map of a country with occurrence counts per province in one data column and another data column containing population changes in the same provinces).

3. Color and legend rules (Map regions legend table) - a rules table that tells the engine what color to paint each region on the SVG map and what label text to show. Rules are matched against the status values in your data.

These three parts are completely independent. You can revise your color scheme without touching a single data cell, add new regions without rewriting legend rules, and rename the human-readable region labels without changing your SVG map.

Minimal working example

The fastest path to a working mapregions map is to go through the three moving parts one by one. Here we will create the most simple present/absent-style map, read Map regions legend to see how to encode more complex status data. mapregions reference will also show you how to include occurrence status notes including bibliography references.

Step 1 - data sheet. Add a column and encode which regions each taxon occurs in, separated by |:

Species	distribution
Dryopteris filix-mas	fr | de | gb | pl
Asplenium trichomanes	fr | es | it

Step 2 - declare the column. In Custom data definition:

Column name	Title	Data type	Template	Placement
distribution	Distribution	mapregions	maps/world.svg	bottom|details

The Template field is the path to your SVG file inside usercontent/. Without it, no SVG map is drawn - only the inline text list appears. Note we use the world.svg shipped with the app, but you can use your own map. The placement value bottom|details renders the inline text list in the full-width bottom row of the taxon card, and the SVG map in the Details pane when the user clicks the taxon.

Step 3 - define region names. In Map regions information:

Region code	Region name
fr	France
de	Germany
gb	United Kingdom
es	Spain
it	Italy
pl	Poland

Step 4 - add at least one color rule. In Map regions legend, a single fallback row (empty Status code) paints every present region in one color:

Column name	Status code	Fill color	Legend	Appended legend	Legend type
		#2ecc71	Present

That is sufficient for a functional presence/absence map. Dryopteris filix-mas will show France, Germany, UK, and Poland highlighted green; Asplenium trichomanes will show France, Spain, and Italy.

Data entry formats

Two formats are available. Both produce identical output and can be used in different columns of the same project.

Inline format (single cell)

All regions for a taxon go in one cell, separated by |. Each entry follows this pattern:

regioncode:status#note1#note2

Only the region code is required; status and notes are optional. Whitespace around | and : is ignored.

fr:native#Verified 2022 | de:introduced | gb

This encodes: France as native with a note, Germany as introduced, Great Britain present with no status and no notes.

To include a literal # character inside a note, escape it as \#.

Per-column format (multi-column)

Each region gets its own column, named columnname.regioncode. The cell content is the status and any notes, without the region code prefix:

distribution.fr	distribution.de	distribution.gb
native	introduced#2015
native		native

An empty cell means no data for that region. The format is auto-detected: if the app finds sub-columns (distribution.fr, distribution.de…), it uses per-column mode; if it finds only the root column, it uses inline mode.

Which format to choose. The Inline format is compact and well suited to projects where most taxa have only a handful of regions, or if your distribution data is generated from an external database. Per-column format gives you direct spreadsheet filtering on each region's status and is more convenient for hand-editing or when different contributors manage different regional columns.

Status values

The status (text after :) is what the color engine reads. It can be:

• Empty - the region is present with no status distinction. Matched by the fallback row (empty Status code) in the Map regions legend table.
• A named string - e.g. native, introduced, c, p, v. Matched exactly against category rows in the Map regions legend table.
• A number - e.g. 312, 8.12, 47. Drives gradient or stepped coloring. See The color engine below.

Notes

Text after # becomes a superscript footnote in the inline text list. Multiple notes per region are separated by additional # characters. Notes support Markdown and bibliography @citekey references - useful for attributing regional records to vouchers, collectors, or publications.

What users see: the two render modes

Inline text list

When placement includes any value other than details alone (e.g. bottom, left, bottom|details), the taxon card shows an inline list of all regions where the taxon is present:

France (native), Germany¹ (introduced), United Kingdom

¹ see Smith et al., 2026 and a single specimen in NHM:546

• Region names are bold, resolved from the Map regions information table.
• The italicised annotation in parentheses is the Appended legend from the matching Map regions legend row. If that cell is empty, nothing is appended.
• Superscript numbers are footnote references. Full note text renders below the list.

For numeric status columns, the raw value or its bin label appears in parentheses rather than an appended legend string.

SVG map in the Details pane

When the column has a Template value and the user opens the Details pane, the app loads the SVG and colors it at runtime by finding SVG elements whose CSS class attribute matches a region code and setting their fill to the color determined by the Map regions legend table. Elements with no matching class are left untouched.

Below the map, the app renders:

• A legend with color swatches and their labels.
• A collapsible data table listing every present region, its status label, and any notes.

Clicking the map toggles fullscreen. The SVG map renders in the Map tab of the Details pane.

Using both together

placement = bottom|details is the most common setup for species-level distribution data: users get a quick text summary while scrolling, and can click through to the full interactive map. Use placement = details alone when even the text list would be too long for the card.

SVG map authoring

The app colors regions by finding SVG elements whose class attribute matches a region code:

<path class="fr" d="…" />
<path class="de" d="…" />

Key requirements:

• Every path or polygon you want colorable must have its class set to the region's lowercase code.
• Region codes must be all-lowercase letters a–z only - no digits, no hyphens, no underscores.
• The SVG must have a viewBox attribute (e.g. viewBox="0 0 1200 800") for correct scaling.
• Elements with no matching class (coastlines, graticules, labels) are displayed but never colored.
• Export as Plain SVG, not Inkscape SVG. In Inkscape, use Object → Object Properties to set or confirm class values.

The world map special case. When the SVG filename ends with world.svg (case-insensitive), the app automatically remaps three codes to handle overseas territories: fr → frx, nl → nlx, cn → cnx. SVG elements for metropolitan France, the Netherlands, and China should carry class frx, nlx, cnx on the world map, while your data sheet and Map Regions Information table continue to use fr, nl, cn normally. This remapping applies only to filenames ending in world.svg.

Free SVG map sources. among other online resource, sites like Wikimedia Commons, SimpleMaps or MapChart provides permissivly licensed vector maps at multiple scales. Many pre-made country-level world SVGs using ISO 3166-1 alpha-2 codes are freely available and need only minor class normalisation to work with NaturaList.

The color engine

The Map regions legend table controls how region status values become colors. Three modes are available and can be combined within the same column.

Category mode (default)

The Status code is matched exactly as a plain string. Each matching region receives the specified fill color directly. This covers:

• Presence/absence - one row with an empty Status code (the global fallback). Every present region gets the same color.
• Named statuses - one row per distinct status string (native, introduced, extirpated…). Each maps to its own color.
• Categorical exceptions inside a numeric column - string values like ND (no data ... alongside otherwise numeric presence data) are picked up as exact-match categories before any numeric interpolation runs.

A row with an empty Status code is the global fallback: any region whose value matches no other row receives this color. If no fallback exists, unmatched regions are left at the SVG's own default (uncolored).

Gradient mode

The Status code is an anchor position (see Anchor value notation below). At least two gradient rows are required (denoting color on two extremities). Colors are smoothly interpolated in perceptual CIE Lab space between adjacent anchors based on where each numeric value falls. Use for continuous data - population density, temperature, index scores - where a seamless transition communicates the full range.

Values below the lowest anchor clamp to that anchor's color; values above the highest clamp to the highest.

Stepped mode

Identical to gradient in how anchors are declared, but color assignment is discrete: each value snaps to the color of the highest anchor whose resolved threshold does not exceed it - histogram binning. Use for crisp color bands at defined thresholds: abundance classes, IUCN criterion scores, custom bins.

Combining modes

Category rows and numeric rows coexist freely. The engine always tries an exact string match first; numeric interpolation or binning is the fallback. This lets you mix genuine numeric data with exception codes like ND (no data) or E (extirpated) that have no numeric meaning.

Anchor value notation

Anchor notation is used in the Status code column of gradient and stepped rows to define where on the data scale a color control point sits. Five notations are available and may be freely mixed within the same column, though in most practical cases sticking to a single one per-column will be sufficient.

Per-taxon color scales

For notations that reference dataset statistics (other than raw value), the "dataset" is the numeric status values in the current taxon's or current occurrence data for that column. Each taxon/occurrence therefore has its own independent color scale: 50% always means "the midpoint of this taxon's value range", not a global midpoint. This is usually the correct behaviour for biological data. The Regional distribution analysis tool uses a separate aggregate scale.

Raw value

A plain integer or decimal. The anchor sits at that exact absolute value regardless of what the dataset looks like.

7.6    14.5    0    -5    100

Use when absolute thresholds have fixed biological or ecological meaning (seawater pH, temperature in °C, chemical concentration breakpoints).

Percentage of data range

A number followed by %. Resolves linearly between the taxon's dataset minimum (0%) and maximum (100%).

0%    25%    50%    75%    100%

Use when relative position within the current data range matters more than absolute values - for example when voucher counts will grow over time and you want the color scale to recalibrate automatically.

Percentile

A number followed by p. Resolves to that percentile of the taxon's data distribution.

0p    25p    50p    75p    100p    2.5p

Use to set breakpoints at natural distributional boundaries regardless of absolute scale - always highlighting the top quartile of species richness, for instance, regardless of the study area's absolute richness.

Standard deviation (z-score)

A number followed by s. Resolves to that many standard deviations from the dataset mean. 0s is the mean; negative values are below the mean.

-2s    -1s    0s    1s    2s

Use to visualise statistical outliers: body-size anomalies in monitored populations, collection effort extremes, or any measurement that reads most naturally relative to its population's variability.

Centered / diverging

Syntax: [±magnitude][modifier]c[centerValue]

Creates a scale diverging symmetrically from a declared absolute center point, preventing the visual bias that occurs when data is skewed to one side of a meaningful neutral value.

Part	Meaning
magnitude	A number (may be negative or decimal)
modifier	% = percentage of max distance from center to any data point; s = σ units; absent = raw units
c	Literal separator character
centerValue	The absolute center of the diverging scale

-100%c0    → 100% of max dataset distance below center 0
100%c0     → 100% of max dataset distance above center 0
0c28       → the baseline 28 (self-documenting equivalent of A1 value 28)
-2sc28     → 2 standard deviations below a target baseline of 28

Use when the neutral midpoint is a known external reference - zero change, a conservation management target, a historical baseline - rather than the data's own mean or midpoint.

Practical configurations

These cover the most common authoring patterns. For a full library of worked examples covering every anchor mode and mix, see Examples.

Presence/absence only

One fallback row. No status values needed in the data.

Data sheet

fr | de | gb | pl

Map regions legend

Status code	Fill color	Legend
	#2ecc71	Present

Named qualitative statuses

One row per status. Appended legend annotates the inline text list.

Data sheet

fr:native | de:introduced | at:extirpated | gb

Map regions legend

Status code	Fill color	Legend	Appended legend
native	#1a9641	Native	native
introduced	#d7191c	Introduced	introduced
extirpated	#636363	Extirpated	extirpated
	#ffffbf	Unclassified

Breeding atlas evidence codes

Short codes; the Appended legend shows the full label in the inline text list.

Data sheet

fr:c | de:p | gb:c | es:s | pl:v

Map regions legend

Status code	Fill color	Legend	Appended legend
c	#1a9641	Confirmed breeding	confirmed breeding
p	#a6d96a	Probable breeding	probable breeding
s	#fdae61	Seasonal / passage	seasonal
v	#636363	Vagrant / irregular	vagrant

Numeric counts with adaptive gradient

Percentual anchors recalibrate silently as the dataset grows; no absolute thresholds needed.

Data sheet

fr:347 | de:512 | gb:198 | pl:89

Map regions legend

Status code	Fill color	Legend	Legend type
0%	#ffffd4	Rare in collections	gradient
33%	#fe9929	Moderately documented	gradient
100%	#662506	Well documented	gradient

Numeric data with categorical exceptions (mixed mode)

Categorical rows are evaluated first; strings that match are never passed to the gradient calculation.

Data sheet

fr:0.62 | es:0.71 | pt:0.58 | it:FL | gb:ND

Map regions legend

Status code	Fill color	Legend	Appended legend	Legend type
0%	#d7191c	Sparse vegetation		gradient
100%	#1a9641	Dense vegetation		gradient
ND	#aaaaaa	No satellite data
FL	#000000	Fire loss	destroyed by fire

The region filter

When a mapregions column has a Search category title set in Custom data definition, it becomes filterable. The filter shows a searchable list of region names as checkboxes, with ANY and EXCLUDE match modes.

When the Map regions legend table defines categorical status codes for the column, the filter automatically gains a status sub-filter alongside the region checkboxes - categorical for named statuses, a numeric range control for numeric status data. Users can combine region and status in one operation (e.g. "Introduced in France or Germany") with no extra column needed. The sub-filter appears automatically; no additional configuration is required.

Multiple map columns

A project can have any number of mapregions columns, each pointing to a different (or the same) SVG via its Template value and carrying independent data. Color rules in the Map regions legend table are isolated per column using the Column name scoping field.

Tips and common mistakes

Every code in the data must have a row in the Map regions information table. Missing codes are logged as errors during compilation.

The Template field is required for the SVG map to appear. Its value is the path to the SVG inside usercontent/ - e.g. maps/europe.svg. Without it, only the inline text list renders.

Legend and Appended legend serve different purposes. The Legend column labels the swatch in the map legend below the SVG. The Appended legend column annotates the region name in the inline text list. They are independent - one can be empty while the other is filled.

Gradient and stepped modes require at least two anchor rows. A single anchor row is not enough; the engine needs a range to interpolate or bin across. For a single-color numeric column, use a category fallback row instead.

Notes support Markdown and bibliography references. A note like #@bonnet2014 p. 42 renders as a formatted citation footnote when bibliography entries are configured - particularly useful for museum collections where each regional record needs a voucher citation.