Package {orange}

Type:	Package
Title:	Spherical Descriptors of Geographic Distributions
Version:	0.1.0
Maintainer:	Adam T. Kocsis <adam.t.kocsis@gmail.com>
Description:	Characterization of distribution data on the surface of a sphere. The primary group of these metrics describe the extent of a distribution, geographic ranges. The calculation of geographic descriptors can be executed using point coordinate data, vector polygons, as well as cells on a discretized sphere. Besides using spherical implementations, the package offers the exploration of partial results for visual diagnostics.
License:	GPL-3
Date:	2026-08-23
BugReports:	https://github.com/adamkocsis/orange/issues
Encoding:	UTF-8
LazyData:	false
URL:	https://adamtkocsis.com/orange/
Depends:	R (≥ 4.0.0), icosa (≥ 0.12.0)
Imports:	igraph, methods
NeedsCompilation:	no
Suggests:	sf, knitr, rmarkdown, vegan
Config/roxygen2/version:	8.0.0
RoxygenNote:	7.3.2
Packaged:	2026-09-05 18:18:47 UTC; adam
Author:	Adam T. Kocsis [cre, aut], Elizabeth M. Dowding [ctb], FAU GeoZentrum Nordbayern [fnd]
Repository:	CRAN
Date/Publication:	2026-09-15 10:50:14 UTC

Orange

Description

Spherical Ranges and Parametrization of Geographic Shapes

Details

A collation of tools and metrics to characterize distribution data on the surface of a sphere or an ellipsoid. The primary group of these metrics is those that describe the extent of a distribution (geographic ranges). The calculation of geographic ranges can be executed using point coordinates data, vector polygons, as well as cells on a discretized sphere. Besides ensuring the use a geometrically correct implementations, the package offers the exploration of partial results for visual diagnostics. This is still the pre-alpha version. Notes about found bugs and suggestions are more than welcome!

Author(s)

Adam T. Kocsis (adam.t.kocsis@gmail.com)

See Also

Useful links:

• https://adamtkocsis.com/orange/

• Report bugs at https://github.com/adamkocsis/orange/issues

Occurrences of Bradypus variegatus from GBIF

Description

This is an example occurrence record data.frame of a single terrestrial species. GBIF.org (30 June 2026) GBIF Occurrence Download https://doi.org/10.15468/dl.s7zhvp

Usage

data(bradypus)

Format

A data.frame with 1466 observations and 6 variables:

scientificName

Taxon name.

basisOfRecord

The basis of the record.

elevation

Elevation of recors

decimalLongitude

Longitude in decimal degrees.

decimalLatitude

Latitude in decimal degrees.

Calculate centroid of a point cloud

Description

Calculate centroid of a point cloud

Usage

centroid(x, ...)

## S4 method for signature 'matrix'
centroid(
  x,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL
)

## S4 method for signature 'data.frame'
centroid(
  x,
  tax = NULL,
  long = "long",
  lat = "lat",
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL
)

Arguments

Value

Either a single numeric or a list with an estimate and other information.

Examples

# Records
data(pinna)
nobilis <- pinna[pinna$species=="Pinna nobilis", ]
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66")

# Number of unique coordinate pairs
cent <- centroid(nobilis, long="decimalLongitude", lat="decimalLatitude")

points(cent[1], cent[2], col="darkred", pch=3, lwd=4, cex=4)

Empty world map (Plate Carée)

Description

Empty world map (Plate Carée)

Usage

emptymap(
  xlim = c(-180, 180),
  ylim = c(-90, 90),
  grat = c(30, 30),
  col = "#DDDDFE",
  grat.col = "#FFFFFF",
  lwd = 2,
  thick = lwd * 2,
  border = grat.col
)

Arguments

Value

The function has no return value.

Examples

data(kentsamples)
emptymap()
points(kentsamples$central_s, pch=16, col=1)
points(kentsamples$arctic_m, pch=16, col=2)
points(kentsamples$antarctic_l, pch=16, col=3)
points(kentsamples$dateline_l, pch=16, col=4)

The gappiness a of shape

Description

Proportion of gap cells in an icosahedral grid.

Usage

gappiness(x, s, ...)

## S4 method for signature 'character,trigrid'
gappiness(x, s, exclude = NULL, full = FALSE)

## S4 method for signature 'matrix,trigrid'
gappiness(
  x,
  s,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  exclude = NULL
)

Arguments

Details

Gappiness refers to proporion of area that are covered by the internal gaps that defined by a set of discretized cells or a point set that covers some cells in a discretization structre.

Value

A proportion that gives the ratio of hole-cells compared to all occupied cells.

Examples

# 1. Only cells
# create a grid
hex <- hexagrid(2, sf=TRUE)

# an example shape
shape <- paste0("F", c(4, 5, 11, 13, 15, 21, 24, 26, 32, 33, 34, 35, 36))
plot(hex, border="gray80")
plot(hex, shape, col="red", add=TRUE)

# the gappiness
gap <- gappiness(shape, hex, full=TRUE)
gap
# plot the first gap
plot(hex, names(gap$holes[gap$holes==1]), col="#00555577", add=TRUE)

# points
set.seed(7)
rand <- icosa::rpsphere(20, output="polar")
occ <- locate(hex, rand)
plot(hex, border="gray80")
plot(hex, occ, col="red", add=TRUE)
points(rand, col="green", pch=3, cex=2)

# gappiness
gap <- gappiness(occ, hex, full=TRUE)
plot(hex, names(gap$holes), col="orange", add=TRUE)

Samples generated from various Kent distributions

Description

Geographic test and demonstration sample set

Usage

data(kentsamples)

Format

A liest with 16 matrices (1000 x 2) with columns being equal to longitudes and latitudes.

scientificname

Taxon name.

central_s

Central position, small spread.

central_m

Central position, medium spread.

central_l

Central position, large spread.

central_xl

Central position, extra large spread.

arctic_s

Arctic position, small spread.

arctic_m

Arctic position, medium spread.

arctic_l

Arctic position, large spread.

arctic_xl

Arctic position, extra large spread.

antarctic_s

Antarctic position, small spread.

antarctic_m

Antarctic position, medium spread.

antarctic_l

Antarctic position, large spread.

antarctic_xl

Antarctic position, extra large spread.

dateline_s

Dateline position, small spread.

dateline_m

Dateline position, medium spread.

dateline_l

Dateline position, large spread.

dateline_xl

Dateline position, extra large spread.

Details

A set of coordinates generated from Kent distributions with the sample number n = 1000. The samples are elements of a list, 16 in total with the combination of location and spread (i.e. the kappa parameter or the Kent distribution). There are four locations: central (0°N 0°E), arctic (85°N 5°E), antarctic (85°S 5°E) and dateline (170°E 5°N), and there are four sizes: small (s, kappa = 50), medium (m, kappa = 15), large (l, kappa = 5), and extra-large (xl, kappa = 2).

Calculate latitudinal ranges

Description

Calculate latitudinal ranges

Usage

latrange(x, ...)

## S4 method for signature 'matrix'
latrange(
  x,
  long = NULL,
  lat = NULL,
  q = 1,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE
)

## S4 method for signature 'data.frame'
latrange(
  x,
  tax = NULL,
  q = 1,
  long = "long",
  lat = "lat",
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE
)

Arguments

Value

Either a single numeric or a list with an estimate and other information. If iterated using 'tax', then either a named vector or list of lists.

Examples

# 1. Records
data(pinna)
# Subset to Pinna nobilis
nobilis <- pinna[pinna$species=="Pinna nobilis", ]
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66")

# Number of unique coordinate pairs
lr <- latrange(nobilis, long="decimalLongitude", lat="decimalLatitude", full=TRUE)

abline(h=lr$range, col="darkred", lty=3, lwd=4)

Calculate ranges with the maximum distance method

Description

This family of metrics rely on the maximum distance within a point cloud

Usage

maxdist(x, s, ...)

mgcd(x, ...)

## S4 method for signature 'matrix,missing'
maxdist(
  x,
  dm = NULL,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  q = 1
)

## S4 method for signature 'data.frame,missing'
maxdist(
  x,
  long = "long",
  lat = "lat",
  tax = NULL,
  dm = NULL,
  duplicates = FALSE,
  q = 1,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE
)

Arguments

Details

This metrics includes maximum great circle distance and similar methods.

Value

A list with an estimate an two indices the rows of the input matrix that represent the longest great circle (or one of them).

Examples

# 1. Records
data(pinna)
# Subset to Pinna nobilis
nobilis <- pinna[pinna$species=="Pinna nobilis", ]
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66")

# 2. calculate and visualize
mgcd <- maxdist(nobilis, long="decimalLongitude", lat="decimalLatitude", plot=TRUE, full=TRUE)

Calculate ranges with the minimum spanning tree length method

Description

This family of metrics rely on constructing a minimum spanning tree from the distances between the points, and use its length to describe spreading.

Usage

mstlength(x, s, ...)

## S4 method for signature 'matrix,missing'
mstlength(
  x,
  dm = NULL,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  q = 1
)

## S4 method for signature 'data.frame,missing'
mstlength(
  x,
  long = "long",
  lat = "lat",
  tax = NULL,
  dm = NULL,
  duplicates = FALSE,
  q = 1,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE
)

Arguments

Details

This metrics includes maximum great circle distance and similar methods.

Value

A list with an estimate an two indices the rows of the input matrix that represent the length of the tree (or one of them).

Examples

# 1. Records
data(pinna)
# Subset to Pinna nobilis
nobilis <- pinna[pinna$species=="Pinna nobilis", ]
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66")

# 2. calculate and visualize
mst <- mstlength(nobilis, long="decimalLongitude", lat="decimalLatitude", plot=TRUE, full=TRUE)
mst$estimate

Calculate ranges with the occupancy method

Description

High-level, abstract function to calculate how many or what proporotion of components in a pre-specified spatial structure is occupied by a distribution dataset

Usage

occupancy(x, s, ...)

## S4 method for signature 'matrix,missing'
occupancy(x, long = NULL, lat = NULL, full = FALSE, prop = NULL)

## S4 method for signature 'data.frame,missing'
occupancy(
  x,
  tax = NULL,
  long = "long",
  lat = "lat",
  full = FALSE,
  listarray = TRUE,
  prop = NULL
)

## S4 method for signature 'data.frame,character'
occupancy(x, s, tax = NULL, full = FALSE, prop = NULL, listarray = TRUE)

## S4 method for signature 'matrix,trigrid'
occupancy(
  x,
  s,
  long = NULL,
  lat = NULL,
  q = 1,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  prop = NULL
)

## S4 method for signature 'data.frame,trigrid'
occupancy(
  x,
  s,
  long = "long",
  lat = "lat",
  tax = NULL,
  q = 1,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  prop = NULL
)

Arguments

Details

The function by default returns counts (i.e. natural numbers) of how many discrete units are occupied. However, there are many cases, when proportions are much more useful, which can be set with the prop argument. Proportions are either global (prop="global") or relative (prop="relative"). Global proportions express how much of the overall spatial structure (s) is occupied; for example, what is the proportion of cells in a grid that are occupied. This method is only applicable, when s is defined as a spatial structure that is independent from x. In contrast, relative proportional occupancies express proportions in the sampled set, i.e. what proportion of the overall sampled grid cells or localities are occupied by a taxon. This is particularly useful when tax!=NULL.

Value

For single subsets (tax=NULL) either a single numeric or an orange list with an estimate and other information. Iterations for multiple taxa result in a named numeric vector or a list.

Examples

# I. Single taxon: Pinna nobils
# 1. Records
data(pinna)
# Subset to Pinna nobilis
nobilis <- pinna[pinna$species=="Pinna nobilis", ]

# Number of unique coordinate pairs
cpairs <- occupancy(nobilis, long="decimalLongitude", lat="decimalLatitude")

# 2. Occupancy in icosahedral grid 
hex <- hexagrid(deg=5, sf=TRUE)
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66",
	xlim=c(-20,45), ylim=c(20,60))
plot(hex, border="gray70", add=TRUE)

# calculate occupancy
occ <- occupancy(nobilis, s=hex, plot=TRUE,
	long="decimalLongitude", lat="decimalLatitude", full=TRUE)

# manual coloring from full output
plot(hex, occ$occupied, add=TRUE, col="#00BB0088")

Occurrences of the genus Pinna from OBIS

Description

This is an example occurrence record data.frame with multiple taxa. Occurrence records downloaded from OBIS on 2026-07-01.

Usage

data(pinna)

Format

A data.frame with 1466 observations and 6 variables:

scientificName

Taxon name.

species

Species name.

basisOfRecord

The basis of the record.

year

Year.

depth

Depth in meters.

decimalLongitude

Longitude in decimal degrees.

decimalLatitude

Latitude in decimal degrees.

Plotting of spherical hulls

Description

Plotting of spherical hulls

Usage

## S3 method for class 'shull'
plot(x, add = FALSE, ...)

Arguments

Value

The function has no return value.

Calculate ranges with the radius-group of methods

Description

This family of metrics rely on estimating the distance of an extent from a fixed point.

Usage

radius(x, s, ...)

## S4 method for signature 'matrix,missing'
radius(
  x,
  p = NULL,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE,
  q = 1
)

## S4 method for signature 'data.frame,missing'
radius(
  x,
  p = NULL,
  long = "long",
  lat = "lat",
  tax = NULL,
  duplicates = FALSE,
  q = 1,
  plot = FALSE,
  plot.args = NULL,
  full = FALSE
)

Arguments

Details

This group of methods rely on calculating single distances.

Value

A list with an estimate an two indices the rows of the input matrix that represent the length of the tree (or one of them).

Examples

# 1. Records
data(pinna)
# Subset to Pinna nobilis
nobilis <- pinna[pinna$species=="Pinna nobilis", ]
plot(nobilis[c("decimalLongitude", "decimalLatitude")], pch=16, col="#00BBAA66")

# 2. calculate and visualize
rad <- radius(nobilis, long="decimalLongitude", lat="decimalLatitude", plot=TRUE, full=TRUE)

Identify the center of a small circle based on three points of a sphere

Description

Identify the center of a small circle based on three points of a sphere

Usage

sc_center(x, origin = c(0, 0, 0), output = "polar")

Arguments

Value

A list with two elements, the center o the small circle and the surface radius of the small circle.

Examples

# generate 3 points on a sphere
set.seed(2)
ps <- icosa::rpsphere(3, output="polar")
small <- sc_center(x=ps)
circle<- sc_shape(x=small$center, r=small$r, output="polar")

plot(NULL, NULL, xlim=c(-180, 180), ylim=c(-90, 90))
points(ps, col="red", pch=3, cex=4)
points(small$center, col="blue", pch=16)
points(circle, col="green", pch=16)

Identify whether a given set of points is in, on or out of a small circle

Description

This method calculates the plane of the small circle and uses the normal to evaluate whether points are in or outside the small circle.

Usage

sc_in(x, center, r, origin = c(0, 0, 0))

Arguments

Value

A numeric vector indicating whether the points are in (1), on (0) or outside of the small circle.

Examples

# set.seed(1)
# generate a random small circle
set.seed(1)
pol <- icosa::rpsphere(1000, output="polar")
# use the first as a small circle's center
center <- pol[1, , drop=FALSE]
radius <- 5000 # define radius in km

# draw a small circle
circle <- sc_shape(x=center, r=radius, breaks=200)

# visualize
plot(NULL, NULL, xlim=c(-180, 180), ylim=c(-90, 90))
points(pol, col="red", pch=3, cex=2)
arcs(circle, col="blue", lwd=2)

# find points in small circle (about 10x faster than distance evaluation)
inside <- sc_in(x=pol, center=center, r=radius)
points(pol[inside==1, ], col="green", pch=3, cex=2)

Generate coordinates of small circles

Description

Creating points along small circles

Usage

sc_shape(
  x = "random",
  r = NULL,
  r.ex = NULL,
  r.rad = NULL,
  r.deg = NULL,
  n = NULL,
  breaks = 100,
  radius = 6371.007,
  origin = c(0, 0, 0),
  output = "polar",
  sf.type = "polygon",
  sf.wrap.dateline = TRUE,
  drop = TRUE
)

Arguments

Details

The function generates a single reference (standard) small circle around the (0,0) long-lat coordinates using a given radius. This reference circle is then rotated to match a given center. The function is iterated for multiple radiiand centers (separately!).

Value

Either a numeric array or and sfc geometry collection.

Examples

set.seed(1)
# generate a random small circle
central <- sc_shape(r=6000, breaks=40)
plot(NULL, xlim=c(-180, 180), ylim=c(-90,90), xlab="longitude", ylab="latitude")
points(central, pch=17, col="gray")
# repeat, same radius multiple centers
smaller <- sc_shape(x=central, r=1000, breaks=100)
for(i in 1:nrow(central)) points(smaller[,,i], col=i, pch=16)

# Random circles with different radii
diff200 <- sc_shape(r=runif(200, 100, 10000))
plot(NULL, xlim=c(-180, 180), ylim=c(-90,90), xlab="", ylab="", axes=FALSE)
for(i in 1:(dim(diff200)[3])){
 points(diff200[,,i], col=i,pch=16)
}

# Same center, different radius
cent <- central[10, ,drop=FALSE]
outward <- sc_shape(cent, r=seq(100, 15000, length.out=20)) 
plot(NULL, xlim=c(-180, 180), ylim=c(-90,90), xlab="", ylab="", axes=FALSE)
for(i in 1:(dim(outward)[3])){
 points(outward[,,i], col=i,pch=16)
}

Spherical hull geometries and hull area calculations

Description

Calculation of hull geometries in spherical space

Usage

shull(x, s, ...)

## S4 method for signature 'matrix,missing'
shull(
  x,
  method,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  sphererad = authRadius
)

## S4 method for signature 'data.frame,missing'
shull(x, long = "long", lat = "lat", ...)

## S4 method for signature 'matrix,trigrid'
shull(
  x,
  s,
  method,
  long = NULL,
  lat = NULL,
  duplicates = FALSE,
  plot = FALSE,
  plot.args = NULL,
  sphererad = authRadius,
  drop = TRUE
)

shullarea(x, ...)

## Default S3 method:
shullarea(
  x,
  method,
  metric = "area",
  full = FALSE,
  sphererad = authRadius,
  ...
)

## S3 method for class 'shull'
shullarea(x, metric = "area", s = NULL, full = FALSE, ...)

Arguments

Details

Constructing and enclosing geometry around a distribution on the surface of a sphere represent unique challenges. The "centroidcircle" method is using the centroid of the distribution as the center of small circle that defines a spherical cap. This is likely not the smallest possible cap to cover the distribution and takes the heterogeneous density of the distribution into account.

Value

A hull-class object, a vector of identifiers (if applicable and drop=FALSE) or the area of te hull as a numeric.

Examples

# example data
data(kentsamples)
p <- kentsamples$dateline_m

# plotting
plot(NULL, NULL, xlim=c(-180, 180), ylim=c(-90,90), xlab="", ylab="")
points(p, pch=3, col="red")

# basic spherical hull definition (native)
cc <- shull(p, method="centroidcircle")
plot(cc, add=TRUE)

# spherical hull area calculation
shullarea(cc)

# basic hull definition (icosahedral grid)
hex <- icosa::hexagrid(spacing=8, sf=TRUE)
# dropping hull container
cc_hex <- shull(p, s=hex, method="centroidcircle")
plot(hex, cc_hex, col="#0000DD33", border="#FFFFFF77", add=TRUE)


# with shull container
cc_hex2 <- shull(p, s=hex, method="centroidcircle", drop=FALSE)
shullarea(cc_hex2, s=hex,  metric="prop")