8 Model Merging
A taxon may have distribution data in several source datasets. Merging combines them into one surface per taxon, applying the taxon’s governing extinction risk and constraining the result to where experts say the species actually occurs.
TipInteractive walkthrough
The Scoring Walkthrough animates this — maximum merge, range masking and the regulatory floors, step by step from input rasters.
8.1 The rule, in one place
The merge rules are msens::merge_sql() and msens::turtle_sql() — SQL held in the package rather than inside a notebook. The merge notebook executes them and the unit tests assert them against synthetic fixtures, one per taxon category, so the pipeline and its tests cannot drift apart. Changing a rule in a way that breaks a documented case fails the tests.
8.2 Pipeline
8.2.1 Step 1 — gather the taxon’s models
Every model resolving to the same taxon is collected: an AquaMaps suitability surface, any regulatory habitat or range designation (NMFS, FWS), a BirdLife or IUCN range map, and for sea turtles a SWOT+DPS range.
8.2.2 Step 2 — the expert range constrains AquaMaps
This is the heart of the merge, and it is not a plain maximum.
Where a taxon has an expert range, the merged surface is the range footprint, valued at the maximum of the taxon’s governing er_score and the AquaMaps value at those cells:
\[ v_{c} = \max\!\big(\text{er\_score},\; v_{am,c}\big) \qquad c \in \text{range} \tag{8.1}\]
AquaMaps values beyond the range are masked away. An environmental-envelope model will happily predict suitable habitat far outside where a species is known to occur; the expert range is what stops that prediction becoming an assertion of presence.
Where a taxon has no expert range anywhere, there is nothing to constrain it against, so its raw AquaMaps footprint is kept as-is.
Important“Has a range” is a global question, not a local one
Whether a taxon counts as range-constrained is decided on its range anywhere in the world, not on whether that range reaches the study area.
That distinction is the entire mechanism for excluding species whose expert range lies wholly outside US waters. Such a species has an expert range, so it takes the range-constrained path; its range ∩ US is empty, so it contributes no US cells. Deciding instead on “has a range in the US” would push those same species onto the unconstrained AquaMaps path and re-admit roughly 750 of them — river dolphins such as Sotalia guianensis among them — on the strength of edge-of-range model artifacts that expert assessment places nowhere near the US.
This was a v6 fix, lost in the v8 rewrite and since restored. It is now a named regression test.
8.2.3 Step 3 — two surfaces, not one
8.2.4 Step 4 — sea turtles multiply instead of taking a maximum
For the six sea turtle species, extinction risk varies across the range: NOAA Fisheries lists Distinct Population Segments separately, so the same species can be Endangered in one region and Threatened in another. A single scalar weight cannot express that.
So the turtle merge multiplies the DPS extinction-risk surface by the suitability surface:
\[ v_{c} = \max\!\Big(1,\; \mathrm{round}\Big(\frac{v_{er,c} \times v_{suit,c}}{100}\Big)\Big) \tag{8.2}\]
Critical-habitat designations then override with a maximum, so a designated cell is never scored below its designation.
Because risk is already inside the merged values, turtles receive er_score = 100 at scoring time as a pass-through multiplier (flagged is_er_spatial), which cancels in the division by 100 rather than double-counting.
NoteTwo merge strategies
- Most taxa — range-constrained maximum, then a scalar extinction-risk weight at scoring time.
- Sea turtles — an extinction-risk raster multiplied into the merged model, so risk varies spatially within the species.
8.3 Where extinction risk enters
The governing er_score (Chapter 7) is applied at merge time, valuing the range cells — the point at which a species’ presence in a cell should carry its governing risk rather than whatever code the contributing dataset happened to record. Applying it later, at scoring, would lose that: the merged surface would carry source-specific codes that may be stale or out of jurisdiction.
8.4 The statutory floors
The MMPA (20) and MBTA (10) floors are part of the governing er_score, not a separate pass over the cells. A marine mammal’s range cells therefore carry at least 20 wherever it is present, and a CFR 50 §10.13 migratory bird at least 10 — see Chapter 7 for how each flag is assigned, and why the MBTA one is a species list rather than “all birds”.
8.5 Persisted output
The merged result is stored as:
model— one row per merged model, keyed bymdl_seq.model_cell— one row per model × cell, holding the merged value inval.
8.6 Validity after merging
A taxon is flagged valid once merging has run, on the criteria in Chapter 6 — chiefly that it resolved to a taxon, is marine and not extinct, and has at least one merged cell in the study area. Program-Area overlap is not among them from v7 onward; it is a spatial question answered later.
In v7 this yields 16,153 valid species across the study area, of which 9,230 contribute to scores within the 20 BOEM Program Areas of the current program cycle.
8.7 Guarding the rules
Every merge category has a synthetic fixture in the msens test suite asserting its exact expected output: range-only, both-masked, range-outside-the-US excluded, AquaMaps-only single-model, AquaMaps-only multi-model (which must not deduplicate), and the multiplicative turtle case.
This is deliberate. Whole-pipeline checks — the version-equivalence gate on Program-Area scores, and the content-hash checkpoints — catch aggregate drift, but they hide rule-level breakage: the ~750 wrongly-included species above moved aggregate scores almost not at all while being scientifically wrong. A category with no fixture is a category that can break silently.