Species Distribution Toolkit

Appearance

An interface for occurrence data ​

The OccurrencesInterface package provides a lightweight representation of species occurrence data. It is meant to be implemented by other packages that want to be interoperable with the SpeciesDistributionToolkit package, which uses this interface for functions like plotting, masking, and value extraction from occurrence data.

Types that other packages should use ​

The interface relies on two abstract types:

OccurrencesInterface.AbstractOccurrence Type
julia
AbstractOccurrence

Other types describing a single observation should be sub-types of this. Occurrences are always defined as a single observation of a single species.

source

OccurrencesInterface.AbstractOccurrenceCollection Type
julia
AbstractOccurrenceCollection

Other types describing multiple observations can be sub-types of this. Occurrences collections are a way to collect multiple observations of arbitrarily many species.

source

Concrete types shipping with the package ​

In order to wrap user-provided data, regardless of its type, the package offers two concrete types:

OccurrencesInterface.Occurrence Type
julia
Occurrence

This is a sub-type of AbstractOccurrence, with the following types:

  • what - species name, defaults to ""

  • presence - a boolean to mark the presence of the species, defaults to true

  • where - a tuple giving the location as longitude,latitude in WGS84, or missing, defaults to missing

  • when - a DateTime giving the date of observation, or missing, defaults to missing

When the interface is properly implemented for any type that is a sub-type of AbstractOccurrence, there is an Occurrence object can be created directly with e.g. Occurrence(observation). There is, similarly, an automatically implemented convert method.

source

OccurrencesInterface.Occurrences Type
julia
Occurrences

This is a sub-type of AbstractOccurrenceCollection. No default value.

source

The interface ​

In order to implement the interface, packages must implement the following methods for their type that is a subtype of AbstractOccurrence or AbstractOccurrenceCollection. None of these methods are optional. Most of these can be implemented as one-liners.

OccurrencesInterface.elements Function
julia
elements(::T) where {T<:AbstractOccurrenceCollection}

Returns the elements contained in an abstract collection of occurrences – this must be something that can be iterated. The default value, when unimplemented, is nothing.

source

OccurrencesInterface.entity Function
julia
entity(o::Occurrence)

Returns the entity (species name) for an occurrence event.

source

julia
entity(::AbstractOccurrence)

Default method for any abstract occurrence type for the entity operation. Unless overloaded, this returns nothing.

source

julia
entity(::AbstractOccurrenceCollection)

Default method for any abstract occurrence collection type for the entity operation. Unless overloaded, this returns an array of entity on all elements of the argument.

source

OccurrencesInterface.place Function
julia
place(o::Occurrence)

Returns the place of the occurrence event, either as a tuple of float in the longitude, latitude format, or as missing. The CRS is assumed to be WGS84 with no option to change it. This follows the GeoJSON specification.

source

julia
place(::AbstractOccurrence)

Default method for any abstract occurrence type for the place operation. Unless overloaded, this returns nothing.

source

julia
place(::AbstractOccurrenceCollection)

Default method for any abstract occurrence collection type for the place operation. Unless overloaded, this returns an array of place on all elements of the argument.

source

OccurrencesInterface.date Function
julia
date(o::Occurrence)

Returns the date (technically a DateTime object) documenting the time of occurrence event. Can be missing if not known.

source

julia
date(::AbstractOccurrence)

Default method for any abstract occurrence type for the date operation. Unless overloaded, this returns nothing.

source

julia
date(::AbstractOccurrenceCollection)

Default method for any abstract occurrence collection type for the date operation. Unless overloaded, this returns an array of date on all elements of the argument.

source

OccurrencesInterface.presence Function
julia
presence(o::Occurrence)

Returns a Bool for the occurrence status, where true is the presence of the entity and false is the (pseudo)absence.

source

julia
presence(::AbstractOccurrence)

Default method for any abstract occurrence type for the presence operation. Unless overloaded, this returns nothing.

source

julia
presence(::AbstractOccurrenceCollection)

Default method for any abstract occurrence collection type for the presence operation. Unless overloaded, this returns an array of presence on all elements of the argument.

source

Additional methods ​

OccurrencesInterface.presences Function
julia
presences(c::T) where {T<:AbstractOccurrenceCollection}

Returns an Occurrences where only the occurrences in the initial collection for which presence evaluates to true are kept.

source

OccurrencesInterface.absences Function
julia
absences(c::T) where {T<:AbstractOccurrenceCollection}

Returns an Occurrences where only the occurrences in the initial collection for which presence evaluates to false are kept.

source

The Tables.jl interface ​

The Occurrences type is a data source for the Tables.jl interface.