Map of Relative Floristic Ignorance

Computes a Map of Relative Floristic Ignorance (MRFI) using modern `sf` and `terra` packages for high performance. Aligned with MRFI philosophy: shows all areas where data exists, letting IRFI values indicate sampling quality rather than excluding poorly-sampled areas.

The function automatically generates both quantile and continuous visualizations, providing comprehensive analysis in a standardized 4-page PDF output.

ignorance_map(
  data_flor,
  site,
  year_study = NULL,
  excl_areas = NULL,
  CRS.new = 3035,
  tau,
  cellsize,
  verbose = TRUE,
  check_overlap = TRUE,
  output_dir = file.path(getwd(), "output"),
  output_prefix = "MRFI",
  site_buffer = FALSE,
  buffer_width = NULL,
  mask_method = "touches",
  use_coverage_weighting = TRUE
)

Arguments

data_flor

A data.frame with 5 columns: 'Taxon' (species identity), 'Long' (longitude), 'Lat' (latitude), 'uncertainty' (spatial uncertainty radius in meters), and 'year' (year of occurrence record).

site

An `sf` object (or 'SpatialPolygonsDataFrame') representing the study area. If no CRS is set, assumes EPSG:4326 (WGS84).

year_study

Numeric year of analysis (e.g., 2025). Defaults to current system year if not specified.

excl_areas

Optional `sf` object (or 'SpatialPolygonsDataFrame') to delimit unsuitable areas (e.g., marine surfaces for terrestrial flora) to be excluded from calculations. If no CRS is set, assumes EPSG:4326.

CRS.new

Numeric EPSG code for projected CRS used in calculations (must be in meters). Default = 3035 (ETRS89-LAEA Europe).

tau

Numeric. Percentual value of taxa loss over 100 years (0 <= tau < 100). Represents the temporal decay of floristic records.

cellsize

Numeric. Resolution of output raster in meters.

verbose

Logical. If TRUE (default), prints progress messages during execution.

check_overlap

Logical. If TRUE (default), checks and plots spatial overlap between occurrence points and study area.

output_dir

Character. Directory path for output files. Defaults to working directory.

output_prefix

Character. Prefix for output filenames. Default = "MRFI".

site_buffer

Logical. If TRUE, expands the study area boundary to analyze a larger region beyond the original site. If FALSE (default), analyzes only the original boundary. Note: Edge effects from external records are already handled by the spatial uncertainty mechanism - points outside the site automatically contribute to cells within the study area if their uncertainty buffers reach in. This parameter is for expanding the analysis region itself, not for fixing edge effects. Buffer width controlled by buffer_width parameter.

buffer_width

Numeric. Width of buffer in meters when site_buffer=TRUE. If NULL (default), uses cellsize as buffer distance. If specified, overrides default. Must be > 0. Buffer will NOT extend into exclusion areas.

mask_method

Character. Method for final raster masking. One of:

  • "touches" Include any cell intersecting site boundary (default, MRFI-aligned)

  • "none" Include entire raster extent, no masking (shows all data)

use_coverage_weighting

Logical. If TRUE (default), weights ignorance contribution by fraction of cell covered by each buffer (matches original algorithm, slower but more accurate). If FALSE, uses faster binary approach where any buffer touch contributes full ignorance value (faster but may underestimate ignorance).

Value

A list with 4 objects:

  • MRFI A `terra SpatRaster` of the Map of Relative Floristic Ignorance

  • RICH A `terra SpatRaster` of species richness computed without uncertainties

  • Uncertainties A data.frame of uncertainty and year values for all records used in computation

  • Statistics A data.frame summarizing settings and results

Details

PDF Output Structure (4 pages, A4 landscape):

  • Page 1 Quantile comparison (MRFI + Richness) - Primary analysis figure

  • Page 2 Continuous comparison (MRFI + Richness) - Raw data view

  • Page 3 Data diagnostics (temporal + spatial uncertainty histograms)

  • Page 4 Summary statistics table

Examples

if (FALSE) { # \dontrun{
# Load example data (requires 'ignobioR' package data)
data(floratus)
data(park)
data(unsuitablezone)

# Example 1: Basic usage (recommended - edge effects already handled)
mrfi <- ignorance_map(
  data_flor = floratus,
  site = park,
  excl_areas = unsuitablezone,
  tau = 20,
  cellsize = 2000
)

# Example 2: With buffer to EXPAND analysis area beyond original site
# (defaults to cellsize width expansion)
mrfi_buffered <- ignorance_map(
  data_flor = floratus,
  site = park,
  tau = 20,
  cellsize = 2000,
  site_buffer = TRUE  # Analyzes original site + 2000m buffer zone
)

# Example 3: Custom buffer to analyze larger region (5km beyond site)
mrfi_5km <- ignorance_map(
  data_flor = floratus,
  site = park,
  excl_areas = unsuitablezone,
  tau = 20,
  cellsize = 2000,
  site_buffer = TRUE,
  buffer_width = 5000  # Analyzes original site + 5km buffer zone
)

# Example 4: Fast mode without coverage weighting
mrfi_fast <- ignorance_map(
  data_flor = floratus,
  site = park,
  tau = 20,
  cellsize = 2000,
  use_coverage_weighting = FALSE
)

# View results
terra::plot(mrfi$MRFI)
terra::plot(mrfi$RICH)
print(mrfi$Statistics)
} # }