Create a spatial phylogenetic object

This function creates a phylospatial object. This is the core data type in the phylospatial library, and is a required input to most other functions in the package. The two essential components of a spatial phylogenetic object are a phylogenetic tree and an community data set.

Usage

phylospatial(
  comm,
  tree = NULL,
  spatial = NULL,
  data_type = c("auto", "probability", "binary", "abundance", "other"),
  clade_fun = NULL,
  build = TRUE,
  check = TRUE,
  area_tol = 0.01,
  rescale = c("sum1", "tip1", "raw"),
  site_weight = NULL
)

Arguments

comm: Community data representing the distribution of terminal taxa across sites. Can be a matrix with a column per terminal and a row per site, a SpatRaster with one layer per terminal, or a sf data with a column per terminal. Taxa whose names do not match between column/layer names in comm and tip labels in tree will be dropped with a warning (unless build = FALSE).
tree: Phylogeny of class phylo. Terminals whose names do not match comm will be dropped with a warning (unless build = FALSE). If this argument is not provided, terminals are assumed to follow a "star" tree with uniform branch lengths, which will lead to non-phylogenetic versions of any analyses done with the resulting phylospatial object. Must be a rooted tree.
spatial: An optional SpatRaster layer or sf object indicating site locations. The number of cells or rows must match comm. Ignored if comm is a SpatRaster or sf object.
data_type: Character giving the data type of comm. Must be "binary", "probability", "abundance", "auto" (the default), or "other". This determines how community values for clades are calculated from the values for terminal taxa. If "binary" (presence-absence), a clade is considered present in a site if any terminal in the clade is present. If "probability," clade probabilities are calculated as the probability that at least one terminal is present in a site. If "abundance," clade abundances are calculated as the sum of abundances for terminals in the clade in a site. If "auto," an attempt is made to guess which of these three data types was provided. This argument is ignored if clade_fun is provided, or if build = FALSE. If "other", a custom clade_fun must be supplied.
clade_fun: Function to calculate the local community weight for a clade based on community weights for tips found in a given location. Must be either NULL (the default, in which case the default function for the selected data_type is used) or a summary function that takes a numeric vector and returns a single numeric output. Ignored if comm already includes clade ranges.
build: Logical indicating whether comm already includes clade ranges that should be used instead of building new ones. Default is TRUE. If FALSE, clade_fun is ignored, no checks are performed to harmonize the tip labels and the community data, and the columns of comm must exactly match the order of tree edges including tips and larger clades. If clade ranges are included in comm but build = TRUE, they will be dropped and new clade ranges will be built.
check: Logical indicating whether community data should be validated. Default is TRUE.
area_tol: Numeric value giving tolerance for variation in the area of sites. Default is 0.01. If site_weight is NULL and the coefficient of variation in the area or length of occupied spatial units (e.g. grid cells) exceeds this value, a warning is issued, since sites will be weighted equally in calculating range sizes even though they differ in size. This argument is ignored if site_weight is provided, if check = FALSE, or if no spatial data is provided.
rescale: Character giving the branch-length rescaling method applied to the tree during construction. Must be "sum1" (default), "tip1", or "raw". "sum1" divides all branch lengths so they sum to 1. "tip1" divides all branch lengths by the longest root-to-tip path. "raw" applies no rescaling, preserving the original branch-length units. See rescale_tree() for details. Note that rescaling does not affect spatial patterns or statistical significance of diversity metrics—only their numeric scale.
site_weight: Optional weights determining how much each site contributes to the range sizes of the taxa that occur there. Can be NULL (the default), in which case all sites are weighted equally; "area", in which case sites are weighted by their area (or length, for lines) as calculated by ps_area(); or a numeric vector, single-layer SpatRaster, or sf object with one value per site (including unoccupied sites). Values must be positive for occupied sites, and are rescaled to have a mean of 1 across occupied sites. See the "Site weights" section below.

Value

A phylospatial object, which is a list containing the following elements:

"data_type":: Character indicating the community data type
"tree":: Phylogeny of class phylo
"comm":: Community matrix containing only occupied sites, including a column for every terminal taxon and every larger clade. Column order corresponds to tree edge order.
"spatial":: A SpatRaster or sf providing spatial coordinates for all sites (including unoccupied). May be missing if no spatial data was supplied.
"occupied":: Integer vector of row indices identifying which sites in the original data are occupied.
"n_sites":: Total number of sites in the original data, including unoccupied.
"site_weight":: Numeric vector of site weights for occupied sites, rescaled to a mean of 1, or NULL if all sites are weighted equally.
"dissim":: A community dissimilarity matrix of class dist indicating pairwise phylogenetic dissimilarity between occupied sites. Missing unless ps_add_dissim() is called.
"rescale":: Character indicating which branch-length rescaling was applied.

Details

This function formats the input data as a phylospatial object. Beyond validating, cleaning, and restructing the data, the main operation it performs is to compute community occurrence data for every internal clade on the tree.

Unoccupied sites (rows where no taxon occurs) are automatically removed from the community matrix during construction to improve performance. The original site indices of occupied rows are stored in ps$occupied, and the total number of sites (including unoccupied) in ps$n_sites, enabling reconstruction of full-extent spatial outputs. Functions that return spatial results automatically expand occupied-only data back to the full spatial extent.

If your data are in the form of occurrence point localities (e.g. from GBIF or BIEN) rather than a gridded community data set, use ps_grid() to rasterize the points onto a spatial grid before passing the result to this function.

Site weights

A taxon's range size underlies endemism metrics and spatial prioritization: the endemism a taxon contributes to a site, and the value of protecting that site, both depend on the share of the taxon's range found there. By default, every site counts equally toward range size, so the range size of a taxon is the number of sites it occupies (or its total probability or abundance across sites). This is appropriate for equal-area grid cells, but not necessarily when sites differ in size, as with polygons of varying size or grid cells in a longitude/latitude coordinate system.

The site_weight argument controls how much each site counts. Weighting by area treats range size as the total area of the sites a taxon occupies. This is exact if community values represent the fraction of each site occupied by a taxon. But for presence data, it assumes that a taxon present in a site occupies all of it, overstating the range sizes of taxa found in large sites. Equal weights err in the opposite direction, counting presence in a large site no more than presence in a small one. Neither is correct in general. An intermediate option is to use weights of ps_area(x)^z with 0 < z < 1, reflecting the tendency of taxa to occupy a declining fraction of a site as site size increases. Because the appropriate value of z is generally unknown and varies among taxa, it can be useful to compare results across a range of values.

Site weights affect functions and metrics that depend on range size: the endemism metrics in ps_diversity(), ps_rand(), and ps_canape(); the endemism option of ps_dissim() and ps_regions(); and ps_prioritize(), ps_prioritizr(), and ps_performance(). They do not affect metrics that don't involve range size, such as PD. ps_canaper() does not support site weights.

Examples