Biodiversity analysis operators

`bio.cluster`#

Biodiverse's cluster analysis (landschaft's cluster): groups joined pair by pair by the dissimilarity of their labels (SORENSON, JACCARD, S2, BRAY_CURTIS, PHYLO_SORENSON...; the linkage giving cluster to cluster values), within the first spatial condition first. Ties broken by Biodiverse's Mersenne Twister. The dendrogram, its nodes (Biodiverse's values), the calculations of each node's groups and, with k, k clusters.

Input	Type	What it is
`basedata`required	base_data	groups x labels sample counts
`tree`	tree	a phylogeny for phylogenetic indices (bio.tree)
`matrix`	label_matrix	a label matrix (bio.matrix)

Output	Type	What it is
`tree`	tree	the dendrogram: groups at the tips, joins named 0___...
`nodes`	table	a row per node (name order): its parent, length, Biodiverse's values, its group
`table`	table	with calculations: those of each node's groups
`clusters`	table	with k: each group's cluster
`map`	map	with k: the clusters (groups that are cells of two axes)

Setting	Type	What it is
`index`	text	the dissimilarity (SORENSON, default)
`linkage`	text	link_average (default)...
`conditions`	any	spatial conditions limiting the pairs (sp_select_all())
`definition_query`	text	only the groups passing it
`calculations`	any	indices of each node's groups
`seed`	integer	Biodiverse's prng_seed, of the ties (default 1)
`tie_breaker`	any	["random", "maximise"] (default: random shuffles)
`clear_singletons`	bool	leave out groups that joined nothing
`k`	integer	cut the dendrogram into k clusters

`bio.h3`#

A basedata of lon/lat records in H3 cells (landschaft's BaseData.from_h3): the groups the centres of the cells of a resolution holding the records, the cells' ids kept.

Input	Type	What it is
`records`required	any	points, or a table with lon/lat columns

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`label`required	any	the label column(s)
`resolution`required	integer	H3's resolution, 0 to 15
`count`	text	a count column (default 1 per record)
`lon`	text	the longitude column (default the points, or lon...)
`lat`	text	the latitude column

`bio.hex`#

A basedata of records in a grid of hexagons (landschaft's BaseData.from_hex): the groups the centres of the hexagons (pointy or flat, of a circumradius) holding the records, so that Biodiverse's distance conditions work on them.

Input	Type	What it is
`records`required	any	points, or a table with coordinate columns

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`label`required	any	the label column(s)
`size`required	number	from a hexagon's centre to its vertices (projected units)
`orientation`	text	pointy (default) or flat
`origin`	any	[x, y], a hexagon's centre (default 0)
`count`	text	a count column (default 1 per record)
`x`	text	the x column (default the points, or x, lon...)
`y`	text	the y column

`bio.matrix`#

A label matrix from a Biodiverse matrix file (landschaft's read_matrix): full or a triangle (the element of each row from its columns, the values in the rows' order), or sparse pairs; the first value read for a pair wins. For the matrix calculations (matrix_stats, compare_dissim_matrix_values, mx_rao_qe).

Output	Type	What it is
`matrix`	label_matrix	values between labels

Setting	Type	What it is
`path`required	text	the matrix file
`element_columns`	any	the element's columns ([1, 2], default)
`values_start_col`	integer	the first value column (after the elements)
`sparse`	bool	one pair per line
`row_columns`	any	sparse: the row element's columns
`col_columns`	any	sparse: the column element's columns
`value_column`	any	sparse: the value's column
`self_similarity`	number	the value of a missing (a, a)
`separator`	text	guess (default), tab, space or a character
`quote`	text	guess (default) or a character

`bio.occurrences`#

A basedata of occurrence records (landschaft's BaseData.from_occurrences and read_occurrences): a GBIF download (the zip or its table), a Darwin Core Archive (a zip or a folder with meta.xml), a delimited file, or records with Darwin Core columns (sdm.download_gbif's); those without a label or valid coordinates, absent, too uncertain, of other bases of record or with some GBIF issues left out, one per label and place; in cells (degrees, or of to_crs), read a line at a time.

Input	Type	What it is
`occurrences`	any	records with Darwin Core columns, in place of a file

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`path`	text	the GBIF download, Darwin Core Archive or table
`cell_sizes`required	any	[x, y]: degrees, or the units of to_crs
`cell_origins`	any	[x, y] (default 0)
`to_crs`	text	reproject the records first (EPSG:...)
`label`	any	the column(s) naming the taxon (default species)
`count`	text	the column of individuals (individualCount; default 1)
`max_uncertainty`	number	drop records less precise (metres)
`basis_of_record`	any	keep only these bases (HUMAN_OBSERVATION...)
`exclude_issues`	any	drop records with any of these GBIF issues
`present_only`	bool	drop the ABSENT records (default true)
`drop_duplicates`	bool	one per label and place (default true)

`bio.points`#

A basedata of point records read like Biodiverse's feature import (landschaft's BaseData.from_points): each point in the cell holding it, its label the label attributes joined with ':', its count 1 or a count attribute's.

Input	Type	What it is
`points`required	vector	the records

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`label`required	any	the label attribute(s)
`count`	text	a count attribute (default 1 per point)
`cell_sizes`required	any	[x, y] in the points' units (0 keeps the coordinates)
`cell_origins`	any	[x, y] (default 0)

`bio.properties`#

Label or group properties of a basedata from a Biodiverse properties file (landschaft's read_properties and set_label_properties / set_group_properties): the element from its columns joined with ':', property names upper-cased, only values that look like numbers (empty fields set but undefined), a later row overriding. They feed the lbprop and gpprop calculations; RANGE and ABUNDANCE set the labels' ranges and abundances.

Input	Type	What it is
`basedata`required	base_data	groups x labels sample counts

Output	Type	What it is
`basedata`	base_data	with the properties

Setting	Type	What it is
`path`required	text	the properties file
`of`	text	labels (default) or groups
`element_columns`required	any	the element's columns (names or 0-based positions)
`property_columns`required	any	the property columns (each named by its header)
`separator`	text	guess (default), tab, space or a character
`quote`	text	guess (default) or a character

`bio.randomise`#

Randomisations of a spatial analysis (landschaft's randomise, Biodiverse's): each iteration randomises the basedata (rand_structured, Biodiverse's default; its spatial forms rand_spatially_structured, rand_diffusion, rand_random_walk; the swaps rand_independent_swaps, rand_independent_swaps_modified, rand_curveball; rand_csr_by_group; rand_nochange), runs the analysis again with the same neighbourhoods and counts how often each observed index exceeds, ties and is compared with the randomised one. The p-ranks, z-scores, the counters (C, P, Q, SUMX, SUMXX, T) and, with pe and phylo_rpe2, CANAPE (0 not significant, 1 neo, 2 palaeo, 3 mixed, 4 super). Biodiverse's Mersenne Twister: the same seed gives its randomisations.

Input	Type	What it is
`basedata`required	base_data	groups x labels sample counts
`tree`	tree	a phylogeny for the phylogenetic indices (bio.tree)
`matrix`	label_matrix	a label matrix for the matrix indices (bio.matrix)

Output	Type	What it is
`table`	table	the observed indices
`p_rank`	table	the p-rank of each index
`z_scores`	table	the z-score of each index
`comparison`	table	the counters: C_, P_, Q_, SUMX_, SUMXX_, T_ of each index
`canape`	table	CANAPE (with pe and phylo_rpe2)
`maps`	stack	the p-ranks, and CANAPE (groups that are cells of two axes)

Setting	Type	What it is
`conditions`required	any	one or two spatial conditions (bio.spatial)
`calculations`required	any	["richness", "pe", "phylo_rpe2", ...]
`definition_query`	text	of the analysis: only the groups passing it
`seed`	integer	of the analysis (Biodiverse's prng_seed; default 0)
`function`	text	rand_structured (default)...
`iterations`	integer	99 (default)
`rand_seed`	integer	of the randomisations (default 0)
`richness_multiplier`	number	rand_structured: richness targets x (1)
`richness_addition`	number	rand_structured: richness targets + (0)
`spatial_conditions_for_label_allocation`	text	rand_structured: occurrences around seed groups (sp_select_all() for its spatial forms)
`spatial_allocation_order`	text	diffusion, random_walk, random, proximity
`label_allocation_backtracking`	text	from_end, from_start, random
`spatial_allocation_reseed_prob`	number	0 to 1
`spatial_conditions_for_seed_location`	text	the seed groups
`swap_count`	integer	swaps (default twice the non-zero cells)
`max_swap_attempts`	integer	(default 100 times the swaps)
`stop_on_all_swapped`	bool	swaps: stop when every cell was swapped
`use_max_swap`	bool	curveball
`spatial_conditions_for_subset`	text	randomise within subsets of groups
`subset_definition_query`	text	groups randomised (others kept)
`labels_not_to_randomise`	any	labels kept in place
`randomise_group_props_by`	text	no_change (default), by_set, by_item
`randomise_trees_by`	text	shuffle_terminal_names

`bio.raster`#

A basedata of rasters read like Biodiverse's raster import (landschaft's BaseData.from_raster): each layer a label (its name) and the values its counts in the cells' groups (with a threshold, presence from species distribution models), or the values themselves labels, each cell counting 1; the cells snapped to the group cells (default the raster's).

Input	Type	What it is
`raster`required	any	a stack (a label per layer) or a map

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`labels_as_bands`	bool	a label per layer (default true), else values
`threshold`	number	values >= it count 1, others 0
`cell_sizes`	any	[x, y] of the group cells (default the raster's)
`cell_origins`	any	[x, y] (default 0)
`given_label`	text	one label for every layer
`label`	text	the label of a map (default its node's output name)

`bio.region_grower`#

Biodiverse's region grower (landschaft's region_grower): pairs of groups joined in decreasing order of an index of the pair's groups together (RICHNESS_ALL, PE_WE...), recomputed for each merged region; with one condition selecting every group, joining stops once a region reaches the value of all the groups. The dendrogram, its nodes, the calculations of each node and, with k, k regions.

Input	Type	What it is
`basedata`required	base_data	groups x labels sample counts
`tree`	tree	a phylogeny for phylogenetic indices (bio.tree)
`matrix`	label_matrix	a label matrix (bio.matrix)

Output	Type	What it is
`tree`	tree	the dendrogram: groups at the tips, joins named 0___...
`nodes`	table	a row per node (name order): its parent, length, Biodiverse's values, its group
`table`	table	with calculations: those of each node's groups
`clusters`	table	with k: each group's cluster
`map`	map	with k: the clusters (groups that are cells of two axes)

Setting	Type	What it is
`index`	text	the index to maximise (RICHNESS_ALL, default)
`conditions`	any	spatial conditions limiting the pairs (sp_select_all())
`definition_query`	text	only the groups passing it
`calculations`	any	indices of each node's groups
`seed`	integer	Biodiverse's prng_seed, of the ties (default 1)
`tie_breaker`	any	["random", "maximise"] (default: random shuffles)
`clear_singletons`	bool	leave out groups that joined nothing
`k`	integer	cut the dendrogram into k clusters

`bio.spatial`#

Biodiverse's spatial analysis (landschaft's spatial_analysis): its indices over the neighbourhood of every group. Neighbourhoods are spatial conditions in Biodiverse's Perl (sp_circle (radius => 200000), sp_block (size => 500000), $D <= 3 && $nbr_y > $y, sp_select_all()...): one, or two (the second leaves out the first) for the indices comparing two sets. Calculations by Biodiverse's names, with or without calc_ (richness, endemism_whole, sorenson, rarity_central, abc_counts...). A table of the indices of each group, and their maps when the groups are cells of two axes.

Input	Type	What it is
`basedata`required	base_data	groups x labels sample counts
`tree`	tree	a phylogeny for the phylogenetic indices (bio.tree)
`matrix`	label_matrix	a label matrix for the matrix indices (bio.matrix)

Output	Type	What it is
`table`	table	a row per processed group: its coordinates, then each index
`maps`	stack	an index per layer (groups that are cells of two axes)
`lists`	any	the list indices: per list and group, its keys and values (JSON)

Setting	Type	What it is
`conditions`required	any	one or two spatial conditions
`calculations`required	any	["richness", "endemism_whole", ...]
`definition_query`	text	only the groups passing it are processed
`seed`	integer	Biodiverse's prng_seed: the random tips of the expected NTI (trees not ultrametric) and the net VPD (default 0)

`bio.table`#

A basedata of a delimited text file read like Biodiverse's import (landschaft's BaseData.from_table): group coordinates from the group columns snapped to cells (> 0), kept as given (0) or as text (< 0), labels from the label columns joined with ':', counts summed per group and label (1 per record without count columns). Columns by name or 0-based position; separator and quote guessed.

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`path`required	text	the file (CSV, tab-separated...)
`group_columns`required	any	["x", "y"]
`label_columns`required	any	["genus", "species"]
`count_columns`	any	sample counts, summed (default 1 per record)
`cell_sizes`	any	per group column (default 0)
`cell_origins`	any	per group column (default 0)
`crs`	text	of the coordinates (EPSG:..., WKT)
`separator`	text	guess (default), tab, space or a character
`quote`	text	guess (default) or a character
`binarise`	bool	counts become 1

`bio.tree`#

A phylogenetic tree of a Newick or Nexus file read as Biodiverse reads it (landschaft's read_tree): unnamed nodes 0___, 1___..., duplicated names __dup1..., the Nexus Translate table applied, all-zero lengths made 1, a forest given a new root.

Output	Type	What it is
`tree`	tree	the tree

Setting	Type	What it is
`path`required	text	the file (or the Newick text itself)
`format`	text	nexus or newick (default: from the text)
`index`	any	the tree's number (0, default) or name

`bio.vector`#

A basedata of vector features read like Biodiverse's feature import (landschaft's BaseData.from_vector): points in the cell holding them; lines and polygons over a fishnet of cells spanning the layer, every cell they touch counting 1, or (measure) the area or length of their part in it (GEOS through GDAL); the labels from attributes joined with ':'.

Input	Type	What it is
`features`required	vector	points, lines or polygons

Output	Type	What it is
`basedata`	base_data	groups x labels sample counts

Setting	Type	What it is
`label`required	any	the label attribute(s)
`cell_sizes`required	any	[x, y] in the features' units (0 keeps point coordinates)
`cell_origins`	any	[x, y] (default 0)
`count`	any	count attribute(s), summed (default 1, or the measure)
`measure`	text	none (the cells touched, default), area or length
`binarise`	bool	counts become 1

bio.cluster#

bio.h3#

bio.hex#

bio.matrix#

bio.occurrences#

bio.points#

bio.properties#

bio.randomise#

bio.raster#

bio.region_grower#

bio.spatial#

bio.table#

bio.tree#

bio.vector#