Skip to contents

Run the v10 share family on a scoring connection

Source: R/share.R
share_run.Rd

Executes share_sql() in order and returns the results. Writes only share_* temporary tables: share_base (the one pass over model_cell x zone_cell) is kept and reused by a later call with the same cats, floor_strip, er_sql, val_col and taxa_where (its signature is stored in share_base_sig), so the three denominators cost one heavy pass, not three; the other temporaries are dropped before returning.

Usage

share_run(
  con,
  cats = c("bird", "coral", "fish", "invertebrate", "mammal", "primary_producer",
    "turtle"),
  denom = c("global", "usa", "pooled"),
  kappa = 0.05,
  floor_strip = FALSE,
  er_sql =
    "(CASE t.er_mode WHEN 'premultiplied' THEN 100 WHEN 'cell' THEN e.er ELSE t.er_score END)",
  val_col = "val",
  taxa_where = "t.is_valid_usa AND t.is_marine",
  nation_sql = "SELECT cell_id, 100.0 AS pct_covered FROM cell WHERE in_usa",
  primprod = "primprod_cell" %in% DBI::dbListTables(con),
  reuse_base = TRUE
)

Arguments

con

a DBI connection holding the relations share_sql() documents.

cats

character; the scored categories (taxon.sp_cat values), default the seven of v8+.

denom

one of "global", "usa", "pooled".

kappa

numeric; the reportability floor on coverage (default 0.05), applied with coverage_floor()'s tolerance.

floor_strip

logical; TRUE drops the floored cells (val <= 1) of premultiplied taxa from every sum (numerator, US total, coverage, species counts) and takes total_global_strip as their denominator (page §9b, the sensitivity column; the default keeps the surface continuous, plan D4).

er_sql

character; the SQL expression of the per-(taxon, cell) risk weight over aliases t (taxon) and e (model_cell_er): the CASE score_cell_metrics.qmd uses. Its species-level counterpart for the percent of the world, w_s, is er_score for the taxon and cell modes and 100 for premultiplied.

val_col

character; the value column of model_cell (sdm_val_col(con, "model_cell")).

taxa_where

character; SQL over alias t selecting the scored species.

nation_sql

character; SQL yielding (cell_id, pct_covered) for the national reference.

primprod

logical; also compute $primprod from primprod_cell (default: when that table exists).

reuse_base

logical; reuse an existing share_base built with the same arguments (default TRUE); FALSE rebuilds it.

Value

a list: taxon (the share_taxon table), nation (per category: share_usa, area_usa, n_cells of the national reference), zone (per zone x category: share, n_species, mean_share, area_km2, coverage, reportable, pct_nation, pct_world, v10 – NA where not reportable, the row kept so the caller can publish coverage and counts), zone_taxon (per zone x species), cell (per category x cell: share, n_species, v10), primprod (per zone, or NULL), composite (per zone: the equal-weight mean of the reportable components' v10, n_components), and denom, floor_strip, kappa.

Details

Hard stops (the rule's own assertions): under global, every scored species must have a positive denominator from an accepted source (merged_global, aquamaps, fallback:*; a national_only_unresolved, cell_er_unsupported or none row is refused – curate data/us_share_fallback.csv or fix the totals) and f_us <= 1; every scored species must have a positive US total; every scored cell must lie in the national reference; every scored cell of a cell-mode taxon must have its per-cell ER and model_cell_er no duplicate row; a species may appear once in share_taxon. Under the global denominator the percent of the world divides by er_score for a cell-mode species while its integrated contribution is its suitability-weighted mean ER (<= er_score), so that companion is an upper-bound convention for such taxa; none exists in v10, and denom_sql() flags them until v11 settles their global ER.