ranges

README

Ranges

Package ranges implements a pixelation for data about species distribution ranges.

Authorship and license

Copyright © 2022 J. Salvador Arias jsalarias@gmail.com. All rights reserved. Distributed under BSD2 licenses that can be found in the LICENSE file.

Documentation

Overview

Package ranges implements a pixelation for data about species distribution ranges.

A range is a representation of a taxon distribution, and it can be either explicit sampling points, or a probability density for the presence of a taxon at a pixel.

Index

• type Collection
  • func New(pix *earth.Pixelation) *Collection
  • func ReadTSV(r io.Reader, pix *earth.Pixelation) (*Collection, error)
  • func (c *Collection) Add(name string, age int64, lat, lon float64)
  • func (c *Collection) AddPixel(name string, age int64, pixID int)
  • func (c *Collection) Age(name string) int64
  • func (c *Collection) Delete(name string)
  • func (c *Collection) HasTaxon(name string) bool
  • func (c *Collection) Pixelation() *earth.Pixelation
  • func (c *Collection) Range(name string) map[int]float64
  • func (c *Collection) Set(name string, age int64, rng map[int]float64)
  • func (c *Collection) SetPixels(name string, age int64, rng map[int]float64)
  • func (c *Collection) TSV(w io.Writer) error
  • func (c *Collection) Taxa() []string
  • func (c *Collection) Type(name string) Type
• type Type

Types

type Collection

type Collection struct {
	// contains filtered or unexported fields
}

A Collection is a collection of distribution ranges with an associated pixelation.

func New

func New(pix *earth.Pixelation) *Collection

New creates a new collection of taxon ranges using an isolatitude pixelation.

func ReadTSV

func ReadTSV(r io.Reader, pix *earth.Pixelation) (*Collection, error)

ReadTSV reads a collection of range maps from a TSV file.

The TSV must contain the following columns:

• taxon, the name of the taxon
• type, the type of the range model. Can be "points" (for presence-absence pixelation), or "range" (for a pixelated range map).
• age, for the age stage of the pixels (in million years)
• equator, for the number of pixels in the equator
• pixel, the ID of a pixel (from the pixelation)
• density, the density for the presence at that pixel

Here is an example file:

# range distribution models
taxon	type	age	equator	pixel	density
Brontostoma discus	points	0	360	17319	1.000000
Brontostoma discus	points	0	360	19117	1.000000
Eoraptor lunensis	range	230000000	360	34661	0.200000
Eoraptor lunensis	range	230000000	360	34662	0.500000
Eoraptor lunensis	range	230000000	360	34663	1.000000
Eoraptor lunensis	range	230000000	360	34664	0.500000
Eoraptor lunensis	range	230000000	360	34665	0.200000
Rhododendron ericoides	points	0	360	18588	1.000000
Rhododendron ericoides	points	0	360	19305	1.000000
Rhododendron ericoides	points	0	360	19308	1.000000

func (*Collection) Add

func (c *Collection) Add(name string, age int64, lat, lon float64)

Add adds a point to a taxon at an specific age (in years).

To add a point the range of the taxon must be defined as 'points' (i.e. a presence-absence pixelation).

func (*Collection) AddPixel

func (c *Collection) AddPixel(name string, age int64, pixID int)

AddPixel adds a pixel. using the pixel ID in the underlying pixelation, to a taxon at an specific age (in years).

To add a pixel the range of the taxon must be defined as 'points' (i.e. a presence-absence pixelation).

func (*Collection) Age

func (c *Collection) Age(name string) int64

Age returns the age (in years) used to set a range map for a taxon.

func (*Collection) Delete

func (c *Collection) Delete(name string)

Delete removes the indicated taxon from the collection.

func (*Collection) HasTaxon

func (c *Collection) HasTaxon(name string) bool

HasTaxon returns true if the indicated taxon is in the collection.

func (*Collection) Pixelation

func (c *Collection) Pixelation() *earth.Pixelation

Pixelation returns the underlying pixelation of a Collection.

func (*Collection) Range

func (c *Collection) Range(name string) map[int]float64

Range returns a range map of a taxon.

The range map is a map of pixel IDs to the probability field scaled to set the maximum value equal to 1.0 (so in the case of points, all points will be set to be 1.0, and all other pixels will be 0.0).

func (*Collection) Set

func (c *Collection) Set(name string, age int64, rng map[int]float64)

Set sets a range map for a taxon at the indicated age (in years). The range is a map of pixel IDs to a probability. The values will be scaled so the max value will be 1, and values smaller than 0.0000005 will be ignored. It will overwrite any range map previously set for the taxon.

func (*Collection) SetPixels

func (c *Collection) SetPixels(name string, age int64, rng map[int]float64)

SetPixels sets pixel points for a taxon at the indicated age (in years). All pixel points will set to 1.0 no matter the stored value in the range. It will overwrite any data previously set for the taxon.

func (*Collection) TSV

func (c *Collection) TSV(w io.Writer) error

TSV encodes range maps in a collection to a TSV file.

func (*Collection) Taxa

func (c *Collection) Taxa() []string

Taxa returns an slice with the taxon names of the taxa in the collection of ranges.

func (*Collection) Type

func (c *Collection) Type(name string) Type

Type returns the type of a range map for a given taxon.

type Type

type Type string

Type is the type of range map.

const (
	// Points is a range map made of points
	// (i.e. a presence-absence pixelation).
	Points Type = "points"

	// A Range is a continuous range map
	// (for example a pixelation of a range map from literature,
	// the output from a distribution model,
	// or a density estimation for a set of points).
	Range Type = "range"
)

Type valid values.