Package {OpenRange}

Title:	Code to Access Open Access Species Range Maps
Version:	0.0.3
Description:	Allows access to a proof-of-concept database containing Open Access species range models and relevant metadata. Access to the database is via both 'PostgreSQL' connection and API https://github.com/EnquistLab/Biendata-Frontend, allowing diverse use-cases.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0), RPostgreSQL
Imports:	DBI, sf, httr, jsonlite
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), maps, tidyverse, vcr, ggplot2
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-10-28 17:59:13 UTC; bmaitner
Author:	Brian Maitner [aut, cre], Cory Merow [aut], Brad Boyle [aut], Xiao Feng [aut], Rethvick Sriram Yugendra Babu [aut], Brian Enquist [aut]
Maintainer:	Brian Maitner <bmaitner@usf.edu>
Repository:	CRAN
Date/Publication:	2026-10-28 19:30:09 UTC

Query the OpenRange API

Description

Helper function used to query the OpenRange API. If the API cannot be reached, returns an error status, or returns content that cannot be interpreted, NULL is returned along with an informative message rather than throwing an error.

Usage

.api_query(url)

Arguments

Value

The parsed content of the API response, or NULL if the API could not be reached or its response could not be interpreted.

Convert records returned by a remote resource to an sf object

Description

Helper function used to convert the records returned by the OpenRange database or API into an sf object. If the records cannot be interpreted as spatial data (for example because the remote resource has changed), NULL is returned along with an informative message rather than throwing an error.

Usage

.as_sf(df, crs = "epsg:4326", resource = "OpenRange database")

Arguments

Value

An sf object, or NULL if the records could not be converted.

Check that value is character

Description

Helper function to check data format.

Usage

.is_char(x)

Check that value is logical

Description

Helper function to check data format.

Usage

.is_log(x)

Check that value is logical or null

Description

Helper function to check data format.

Usage

.is_log_or_null(x)

Check that value is numeric

Description

Helper function to check data format.

Usage

.is_num(x)

Report that an Internet resource is unavailable

Description

Helper function used to fail gracefully, returning NULL along with an informative message rather than throwing an error, when a remote resource cannot be reached or does not return what was expected.

Usage

.resource_unavailable(resource, details = NULL)

Arguments

Value

NULL, invisibly.

Load range maps for given species using the API.

Description

OpenRange_api_load_species extracts range maps for the specified species.

Usage

OpenRange_api_load_species(species, ...)

Arguments

Value

Range maps for specified species, or NULL if the API is unavailable or no maps are found.

Note

Details on the construction of BIEN range maps is available at http://bien.nceas.ucsb.edu/bien/biendata/bien-3/

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_sf(), OpenRange_species()

Examples

library(maps) #a convenient source of maps
library(sf)

temp_dir <- file.path(tempdir(), "BIEN_temp")

#Download ranges
Abies_poly <- OpenRange_api_load_species(species = "Abies_amabilis")

# OpenRange functions return NULL if the data source is unavailable,
# so check the output before using it.

if(!is.null(Abies_poly)){

 #Plotting files
 plot(Abies_poly[,1])#plots the range, but doesn't mean much without any reference
 map('world', fill = TRUE, col = "grey")#plots a world map (WGS84 projection), in grey
 plot(Abies_poly,col="forest green",add=TRUE) #adds the range to the map

 #Getting data from the files
 Abies_poly |>
   st_drop_geometry()

}

Download range maps for given species using the API.

Description

OpenRange_api_species downloads range maps for the specified species.

Usage

OpenRange_api_species(species, directory, include_id = TRUE, ...)

Arguments

Value

NULL. Called for its side effect of downloading range maps.

Note

Details on the construction of BIEN range maps is available at http://bien.nceas.ucsb.edu/bien/biendata/bien-3/

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_sf(), OpenRange_species()

Examples

library(OpenRange)
library(maps) #a convenient source of maps
library(sf)
library(ggplot2)


# Create temp directory

temp_dir <- file.path(tempdir(), "BIEN_temp")

#Download ranges

OpenRange_api_species(species = "Abies_amabilis",
                      directory = temp_dir,
                      include_id = TRUE) # saves ranges to a temporary directory

# Nothing is saved if the data source is unavailable, so check that the
# file exists before using it.

if(file.exists(file.path(temp_dir, "Abies_amabilis_117684.shp"))){

  #Reading files

  Abies_poly <- st_read(dsn = temp_dir,
                        layer = "Abies_amabilis_117684")

  # Get a map to plot on

  world <- map("world", plot = FALSE, fill = TRUE)|>
    st_as_sf()

  #Plotting files

  ggplot(data = world)+
    geom_sf()+
    geom_sf(data = Abies_poly,
            fill="green")+
    coord_sf(xlim = st_bbox(Abies_poly)[c(1,3)],
             ylim = st_bbox(Abies_poly)[c(2,4)]) +
    theme_bw()

  #Getting data from the files

  Abies_poly |>
    st_drop_geometry()

}

Download license information

Description

OpenRange_get_license provides information on model licenses.

Usage

OpenRange_get_license(...)

Arguments

Value

Data.frame containing information on the license associated with the maps, or NULL if the database is unavailable.

Note

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_sf(), OpenRange_species()

Other metadata functions: OpenRange_get_stats(), OpenRange_list_scenarios()

Examples

range_license_info <- OpenRange_get_license()

# OpenRange functions return NULL if the data source is unavailable,
# so check the output before using it.

if(!is.null(range_license_info)){

  head(range_license_info)

}

Download model performance statistics

Description

OpenRange_get_stats provides information on model performance.

Usage

OpenRange_get_stats(...)

Arguments

Value

List object containing one data.frame for each of the three modeling frameworks, or NULL if the database is unavailable.

Note

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_license(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_sf(), OpenRange_species()

Other metadata functions: OpenRange_get_license(), OpenRange_list_scenarios()

Examples

range_stats <- OpenRange_get_stats()

# OpenRange functions return NULL if the data source is unavailable,
# so check the output before using it.

if(!is.null(range_stats)){

  names(range_stats)

}

Download information on available climate change scenarios

Description

OpenRange_list_scenarios provides information on climate scenarios with range projections available.

Usage

OpenRange_list_scenarios(...)

Arguments

Value

Data.frame containing climate change scenarios available in BIEN, or NULL if the database is unavailable.

Note

Details on the construction of BIEN range maps is available at http://bien.nceas.ucsb.edu/bien/biendata/bien-3/

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_load_species(), OpenRange_sf(), OpenRange_species()

Other metadata functions: OpenRange_get_license(), OpenRange_get_stats()

Examples

## Not run: 

cc_scenarios <- OpenRange_list_scenarios()


## End(Not run)

Load Open Range maps for specified species.

Description

OpenRange_load_species returns spatial data for the specified species.

Usage

OpenRange_load_species(
  species,
  default_only = TRUE,
  projection = 4326,
  scenario = "present",
  ...
)

Arguments

Value

An sf object containing range maps for the specified species, or NULL if the database is unavailable or no maps are found.

Note

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_sf(), OpenRange_species()

Examples

#' 
library(maps)
library(ggplot2)
library(sf)

species_vector <- c("Abies_lasiocarpa","Abies_amabilis")
abies_maps <- OpenRange_load_species(species = species_vector)

# OpenRange functions return NULL if the data source is unavailable,
# so check the output before using it.

if(!is.null(abies_maps)){

  # To get all maps for a species, use "default = FALSE".
  # Here, this returns maps with different thresholds from the same model
  std_all <- OpenRange_load_species(species = "Stellaria debilis",
                                    default_only = FALSE)

  #To just get the default map, use "default = TRUE"
  std_default <- OpenRange_load_species(species = "Stellaria debilis",
                                        default_only = TRUE)

  #get world map

  world <- map("world", plot = FALSE, fill = TRUE)|>
    st_as_sf()

  #Plotting ranges

  ggplot(data = world)+
    geom_sf()+
    geom_sf(data = abies_maps,
            mapping = aes(fill = species),
            alpha=0.5)+
    coord_sf(xlim = st_bbox(abies_maps)[c(1,3)],
             ylim = st_bbox(abies_maps)[c(2,4)]) +
    theme_bw()

}

Download range maps that intersect a user-supplied sf object.

Description

OpenRange_sf extracts range maps that intersect a specified SpatialPolygons or SpatialPolygonsDataFrame object.

Usage

OpenRange_sf(
  sf,
  directory,
  species.names.only = FALSE,
  return.species.list = TRUE,
  crop.ranges = FALSE,
  include.gid = FALSE,
  projection = 4326,
  scenario = "present",
  default_only = TRUE,
  ...
)

Arguments

Value

All range maps that intersect the user-supplied shapefile, or NULL if the database is unavailable.

Note

Details on the construction of BIEN range maps is available at https://bien.nceas.ucsb.edu/bien/biendata/bien-3/

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_species()

Examples

saguaro_poly <- OpenRange_load_species("Carnegiea gigantea")

# OpenRange functions return NULL if the data source is unavailable,
# so check the output before using it.

if(!is.null(saguaro_poly)){

 #Create a temp directory
 temp_dir <- file.path(tempdir(), "BIEN_temp")

 #Get range maps for all species with ranges that overlap the range of saguaros
 OpenRange_sf(sf = saguaro_poly,
              directory = temp_dir)

 #Note that this will save many sfs to the directory (or working directory)

}

Download range maps for given species.

Description

OpenRange_species extracts range maps for the specified species.

Usage

OpenRange_species(
  species,
  directory,
  default_only = TRUE,
  matched = TRUE,
  match_names_only = FALSE,
  include_id = TRUE,
  projection = 4326,
  scenario = "present",
  ...
)

Arguments

Value

Range maps for specified species, or NULL if the database is unavailable.

Note

Details on the construction of BIEN range maps is available at http://bien.nceas.ucsb.edu/bien/biendata/bien-3/

This function relies on an Internet resource. If that resource is unavailable, NULL will be returned along with an informative message.

See Also

Other range functions: OpenRange_api_load_species(), OpenRange_api_species(), OpenRange_get_license(), OpenRange_get_stats(), OpenRange_list_scenarios(), OpenRange_load_species(), OpenRange_sf()

Examples

library(maps) #a convenient source of maps
library(sf)

species_vector <- c("Abies_lasiocarpa","Abies_amabilis")

#check whether the species are available
OpenRange_species(species_vector,match_names_only = TRUE)

#Create a temp directory
temp_dir <- file.path(tempdir(), "BIEN_temp")

#Download ranges
OpenRange_species(species = species_vector,
                 directory = temp_dir)#saves ranges to a temporary directory

# Nothing is saved if the data source is unavailable, so check that the
# file exists before using it.

if(file.exists(file.path(temp_dir, "Abies_amabilis_117684.shp"))){

 #Reading files

 Abies_poly <- st_read(dsn = temp_dir,
                       layer = "Abies_amabilis_117684")

 #Plotting files
 plot(Abies_poly[,1])#plots the range, but doesn't mean much without any reference
 map('world', fill = TRUE, col = "grey")#plots a world map (WGS84 projection), in grey
 plot(Abies_poly,col="forest green",add=TRUE) #adds the range of Abies lasiocarpa to the map

 #Getting data from the files
 Abies_poly |>
   st_drop_geometry()

}

Run an SQL query on the OpenRange database.

Description

ranges_sql is an internal function used to submit SQL queries.

Usage

ranges_sql(
  query,
  user = "public_bien",
  password = "bien_public",
  ranges = NULL,
  limit = NULL,
  return.query = FALSE,
  schema = "analytical_db",
  db_name = "vegbien",
  print.query = FALSE
)

Arguments

Value

A dataframe returned by the query, or NULL (with an informative message) if the database cannot be reached.