Skip to content

BiodiversityObservationNetworks.jl

The purpose of this package is to provide a high-level, extensible, modular interface to the selection of sampling point for biodiversity processes in space. It is based around a collection of types representing point selection algorithms, used to select the most informative sampling points based on raster data. Specifically, many algorithms work from a layer indicating entropy of a model based prediction at each location.

This package is in development

The BiodiversityObservationNetworks.jl package is currently under development. The API is not expected to change a lot, but it may change in order to facilitate the integration of new features.

High-level types

# BiodiversityObservationNetworks.BONSampler — Type.

BONSampler

A union of the abstract types BONSeeder and BONRefiner. Both types return a tuple with the coordinates as a vector of CartesianIndex, and the weight matrix as a Matrix of AbstractFloat, in that order.

source

# BiodiversityObservationNetworks.BONSeeder — Type.

abstract type BONSeeder end

A BONSeeder is an algorithm for proposing sampling locations using a raster of weights, represented as a matrix, in each cell.

source

# BiodiversityObservationNetworks.BONRefiner — Type.

abstract type BONRefiner end

A BONRefiner is an algorithm for proposing sampling locations by refining a set of candidate points to a smaller set of 'best' points.

source

Seeder and refiner functions

# BiodiversityObservationNetworks.seed — Function.

seed(sampler::ST, uncertainty::Matrix{T})

Produces a set of candidate sampling locations in a vector coords of length numpoints from a raster uncertainty using sampler, where sampler is a BONSeeder.

source

seed!(coords::Vector{CartesianIndex}, sampler::ST)

The curried version of seed!, which returns a function that acts on the input uncertainty layer passed to the curried function (u below).

source

# BiodiversityObservationNetworks.seed! — Function.

seed!(coords::Vector{CartesianIndex}, sampler::ST, uncertainty::Matrix{T})

Puts a set of candidate sampling locations in the preallocated vector coords from a raster uncertainty using sampler, where sampler is a BONSeeder.

  • Seeder's work on rasters, refiners work on set of coordinates.

source

seed!(coords::Vector{CartesianIndex}, sampler::ST)

The curried version of seed!, which returns a function that acts on the input uncertainty layer passed to the curried function (u below).

source

# BiodiversityObservationNetworks.refine — Function.

refine(pool::Vector{CartesianIndex}, sampler::ST, uncertainty::Matrix{T})

Refines a set of candidate sampling locations and returns a vector coords of length numpoints from a vector of coordinates pool using sampler, where sampler is a BONRefiner.

source

refine(sampler::BONRefiner)

Returns a curried function of refine with two methods: both are using the output of seed, one in its packed form, the other in its splatted form.

source

refine(pack, sampler::BONRefiner)

Calls refine on the appropriatedly splatted version of pack.

source

# BiodiversityObservationNetworks.refine! — Function.

refine!(cooords::Vector{CartesianIndex}, pool::Vector{CartesianIndex}, sampler::ST, uncertainty::Matrix{T})

Refines a set of candidate sampling locations in the preallocated vector coords from a vector of coordinates pool using sampler, where sampler is a BONRefiner.

source

refine!(cooords::Vector{CartesianIndex}, pool::Vector{CartesianIndex}, sampler::ST, uncertainty::Matrix{T})

The curried version of refine!, which returns a function that acts on the input coordinate pool passed to the curried function (p below).

source

Seeder algorithms

# BiodiversityObservationNetworks.BalancedAcceptance — Type.

BalancedAcceptance

A BONSeeder that uses Balanced-Acceptance Sampling (Van-dem-Bates et al. 2017 https://doi.org/10.1111/2041-210X.13003)

source

Refiner algorithms

# BiodiversityObservationNetworks.AdaptiveSpatial — Type.

AdaptiveSpatial

...

numpoints, an Integer (def. 50), specifying the number of points to use.

α, an AbstractFloat (def. 1.0), specifying ...

source

# BiodiversityObservationNetworks.Uniqueness — Type.

Uniqueness

A BONRefiner.

source

Helper functions

# BiodiversityObservationNetworks.squish — Function.

squish(layers, W, α)

Takes a set of n layers and squishes them down to a single layer.

    numcolumns = size(W,2)
    for i in 1:numcolumns
        W[:,i] ./= sum(W[:,i])
    end

For a coordinate in the raster (i,j), denote the vector of values across all locations at that coordinate v⃗ᵢⱼ. The value at that coordinate in squished layer, s⃗ᵢⱼ, is computed in two steps.

(1): First we apply a weights matrix, W``, withnrows andmcolumns (m<n), to reduce the initialnlayers down to a set ofm` layers, each of which corresponds to a particular target of optimization. For example, we may want to propose sampling locations that are optimized to best sample abalance multiple criteria, like (a) the current distribution of a species and (b) if that distribution is changing over time.

Each entry in the weights matrix W corresponds to the 'importance' of the layer in the corresponding row to the successful measurement of the target of the corresponding column. As such, each column of W must sum to 1.0. using Optim

For each location, the value of the condensed layer tᵢ, corresponding to target i, at coordinate (i,j) is given by the dot product of v⃗ᵢⱼ and the i-th column of W.

(2): Apply a weighted average across each target layer. To produce the final output layer, we apply a weighted average to each target layer, where the weights are provided in the vector α⃗ of length m.

The final value of the squished layer at (i,j) is given by s⃗ᵢⱼ = ∑ₓ αₓ*tᵢⱼ(x), where tᵢⱼ(x) is the value of the x-th target layer at (i,j).

source

# BiodiversityObservationNetworks.entropize! — Function.

entropize!(U::Matrix{AbstractFloat}, A::Matrix{Number})

This function turns a matrix A (storing measurement values) into pixel-wise entropy values, stored in a matrix U (that is previously allocated).

Pixel-wise entropy is determined by measuring the empirical probability of randomly picking a value in the matrix that is either lower or higher than the pixel value. The entropy of both these probabilities are calculated using the -p×log(2,p) formula. The entropy of the pixel is the sum of the two entropies, so that it is close to 1 for values close to the median, and close to 0 for values close to the extreme of the distribution.

source

# BiodiversityObservationNetworks.entropize — Function.

entropize(A::Matrix{Number})

Allocation version of entropize!.

source