jdh

package
v0.0.0-...-6d303d2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 13, 2014 License: BSD-2-Clause Imports: 6 Imported by: 0

Documentation

Overview

Package jdh defines the database used by a jdh client application.

This package provides the general database interface, as well as associated types for retrieval, insertion or modification of the database.

In client side code, jdh package must be used in conjunction with a database driver.

Index

Constants

View Source
const (
	// Preferred citation of the dataset, as a free string. An empty
	// value will delete the content of the citation field.
	DataCitation Key = "citation"

	// License or rights of use of the data included in the dataset. An
	// empty value will delete the content of the license field.
	DataLicense = "license"

	// Title of the dataset.
	DataTitle = "title"

	// Url of the dataset. An empty value will delete the url.
	DataUrl = "url"
)

Key values used in Datasets table.

View Source
const (
	// Add request the addition of an element to the database. The param
	// parameter is the element to be added.
	Add Query = "add"

	// Commit requests the commit of the database.
	Commit = "commit"

	// Close request the closing of the database.
	Close = "close"

	// Delete requests the removal of an element from the database. The
	// param argument is a Values variable that must be include the id
	// of the element to be deleted (all other values will be ignored).
	Delete = "delete"

	// Get request an element form the database.
	Get = "get"

	// List request a list of elements from the database.
	List = "list"

	// Set requests the setting of a value in the database. The param
	// argument is a Values variable that must be included the id, all
	// other values will be modified if they are valid.
	Set = "set"
)

Available queries.

View Source
const (
	// Identifier of an element in a table. Valid values are id and
	// extern ids of the element.
	KeyId Key = "id"

	// Comment field of an element. All free text values are valid.
	// An empty value during a set operation will delete the comment.
	KeyComment = "comment"

	// Extern field of a method. The value is in the form <serv>:<id>,
	// e.g. "gbif:5216933". An empty <id> during a set operation will
	// delete the extern identifier.
	KeyExtern = "extern"

	// A bibliographic reference.
	KeyReference = "reference"
)

General Keys used in all or most table's elements.

View Source
const (
	// The age of the node, an integer value.
	NodAge Key = "age"

	// Used in list will retrieve the list of descendants of the node.
	NodChildren = "children"

	// Used in set operation to collapse a node.
	NodCollapse = "collapse"

	// The length of the  branch that connects the node with its ancestor.
	// An integer value.
	NodLength = "length"

	// Id of the parent node of a node. In list operation will return the
	// list of ancestors of a node.
	NodParent = "parent"

	// Taxon id of the taxon associated with the node. Used in delete
	// will removes the association (but not the node). Used in list will
	// retrieve the node associated with the indicated taxon.
	NodTaxon = "taxon"

	// In list operations it retrieves all the nodes of a tree.
	NodTree = "nodtree"

	// In set operation, will move a node to be sister of the indicated
	// taxon.
	NodSister = "sister"
)

Key values used for a phylogenetic tree node.

View Source
const (
	// Number of columns of the raster. This value can not be setted.
	RDisCols Key = "cols"

	// Source of the raster using a string value of RasterSource.
	RDisSource = "source"

	// Taxon id of the taxon associated with a raster. Used in delete
	// operation will delete all the rasters associated with a taxon id.
	// Used in list operation to retrieve all the rasters directly
	// identified with the indicated id.
	RDisTaxon = "taxon"

	// Used in list operations to retrieve all the rasters associated
	// with a taxon id, or any of its descendants.
	RDisTaxonParent = "parent"
)

Key values used in the rasterized distributions table.

View Source
const (
	// Basis of the specimen record. It must be a string expression of
	// a valid BasisOfRecord accepted in jdh.
	SpeBasis Key = "basis"

	// The catalog code of the specimen. Usually is expected to be in the
	// form <inst>:<coll>:<catalog>.
	SpeCatalog = "catalog"

	// The person who collected the specimen.
	SpeCollector = "collector"

	// The dataset that kepts the specimen data.
	SpeDataset = "dataset"

	// The time of the collection, using the ISO 8601 layout.
	SpeDate = "date"

	// The person who determined the identity the specimen.
	SpeDeterminer = "determiner"

	// Point locality of the specimen sample.
	SpeLocality = "locality"

	// Used in list operations to retrieve only records with or without
	// a georeference. Valid values are "true" and "false"
	SpeGeoref = "georef"

	// Taxon id of the taxon associated with a specimen. Used in delete
	// operation will delete all the specimens associated with a taxon id.
	// Used in list operation to retrieve all the specimens directly
	// identied with the indicated id.
	SpeTaxon = "taxon"

	// Used in list operations to retrieve all the specimens associated
	// with a taxon id, or any of its descendants.
	SpeTaxonParent = "parent"
)

Key values used in specimens table.

View Source
const (
	// Country of the specimen sample location, using ISO 3166-1 alpha-2 code.
	GeoCountry Key = "coutry"

	// County, Municipality (or equivalent) of the specimen sample
	// location.
	GeoCounty = "county"

	// Longitude and latitude of the location, in the form "lon,lat"
	GeoLonLat = "lonLat"

	// Source of the georeference, for example, gps data or a gazetter.
	GeoSource = "source"

	// State, Province (or equivalent) of the specimen sample location.
	GeoState = "state"

	// Uncertainty of the georeference in meters.
	GeoUncertainty = "uncertainty"

	// Validation of the georeference.
	GeoValidation = "validation"
)

Key values used for geography of an specimen.

View Source
const (
	// Authority asociated with the taxon.
	TaxAuthority Key = "authority"

	// Used in list operation to retrieve taxon's valid children.
	// The value is the id of the taxon.
	TaxChildren = "children"

	// Name of the taxon. In set operation, empty values are not
	// accepted. In list operation, if the name ends with an
	// asterisk ("*"), the name will be interpreted as a prefix.
	TaxName = "name"

	// Taxon's parent in set operation. In list opertation, is used
	// as filter to select only taxons descendants of the indicated
	// taxon.
	TaxParent = "parent"

	// Used in list operation as a filter to select only taxons that
	// have a parent with a given parent name.
	TaxParentName = "parentName"

	// Used in list operation to retrieve taxon's parents. The value
	// is the id of the taxon.
	TaxParents = "parents"

	// Rank of the taxon. It must be the string expression of a
	// rank accepted in jdh.
	TaxRank = "rank"

	// Set a taxon as a synonym of the taxon id indicated in value.
	// Only used during set opertation. If the value is empty, it will
	// be assumed that the parent of the taxon its is new senior
	// synonym.
	TaxSynonym = "synonym"

	// Used in list operation to retrieve taxon's synonyms. The value
	// is the id of the taxon.
	TaxSynonyms = "synonyms"

	// Validity of the taxon's name. Only using during set operation
	// an will always set a taxon as valid (the value field will be
	// ignored). The taxon will be set as valid, and sister of its
	// previous senior.
	TaxValid = "valid"
)

Key values used in Taxonomy table.

View Source
const Iso8601 = "2006-01-02T15:04:05+07:00"

ISO 8601 layout for time, as in <http://en.wikipedia.org/wiki/ISO_8601>

Variables

This section is empty.

Functions

func ParseExtern

func ParseExtern(extern string) (string, string, error)

ParseExtern parses an extern identifier. Extern identifiers are of the form <service>:<key>, for example "gbif:2423087". It returns the service, the key, an error if the extern id is malformed.

To avoid matches like "db" with "dbx", the service is returned including the colon, so in this example, it will return unambiguous "db:" or "dbx:".

func Register

func Register(name string, open func(param string) (DB, error))

Register makes a database driver available by the provided name. If the name is black, or registred twice, it panics.

Types

type BasisOfRecord

type BasisOfRecord uint

BasisOfRecord is the id of a kind of specimen.

const (
	UnknownBasis BasisOfRecord = iota
	Preserved                  // a preserved specimen
	Fossil                     // a fossilized specimen
	Observation                // a human observation
	Remote                     // a remote observation
)

Valid BasisOfRecord values.

func GetBasisOfRecord

func GetBasisOfRecord(s string) BasisOfRecord

GetBasisOfRecord returns the id of a record.

func (BasisOfRecord) String

func (b BasisOfRecord) String() string

String returns the basis of record string of a given BasisOfRecord id.

type DB

type DB interface {
	// Close closes the database.
	Close() error

	// Driver returns the name of the driver that underlies the database.
	Driver() string

	// Exec executes a query without returning any row (e.g. Add, Delete),
	// usually this executions require modification of the database data.
	// It returns a string result (that depends on the query), or an
	// error, if the query fail.
	Exec(query Query, table Table, param interface{}) (string, error)

	// Get executes a query that is expected to return at most a single
	// value.
	Get(table Table, id string) (Scanner, error)

	// List executes a query that returns a list.
	List(table Table, args *Values) (ListScanner, error)
}

DB is the database handle to be used by a client application.

This interface should be implemented by a valid jdh database driver.

func Open

func Open(name, par string) (DB, error)

Open opens a database by its driver.If driver is not present, it returns an error.

type Dataset

type Dataset struct {
	// identifier of the dataset.
	Id string

	// title of the dataset.
	Title string

	// simple citation of the dataset.
	Citation string

	// license or rights of use of the dataset.
	License string

	// url of the dataset, if any
	Url string

	// extern identifiers of the dataset.
	Extern []string

	// free text comment about the dataset.
	Comment string
}

Dataset is a museum collection, a published dataset, or any other source of specimen records.

type IdElement

type IdElement struct {
	Id string
}

IdElement is an Id returned by a jdh database (for example, in a list).

type Key

type Key string

Key is a key used to query a particular element o field in the jdh database.

const (
	// Used to set the name of the tree.
	TreName Key = "name"

	// Used in delete operation to remove all the references to a taxon
	// in the trees.
	TreTaxon = "phytaxon"
)

Key values used for a phylogenetic tree.

const (
	// Sets a pixel value, in the form "X,Y,Val"
	RasPixel Key = "pixel"
)

Key values used for the raster of a rasterized distribution.

type KeyValue

type KeyValue struct {
	Key   Key
	Value []string
}

KeyValue is a key:value pair used for jdh database queries. Instead of this structure most code should use values.

type ListScanner

type ListScanner interface {
	Scanner
	Close()
}

ListScanner is the result of a list query. It can be read until no more elements are in the answer. If the list is abandoned before any error of the last element was scanned, it should be closed by the caller.

type Node

type Node struct {
	// identifier of the node.
	Id string

	// tree that contains the node.
	Tree string

	// taxon assigned to the node (if any).
	Taxon string

	// parent node.
	Parent string

	// Length of the node.
	Len uint

	// Age of the node, counted down from the present (present == 0).
	Age uint

	// free text comment about the node.
	Comment string
}

Node is a node of a phylogenetic tree.

type Phylogeny

type Phylogeny struct {
	// identifier of the tree.
	Id string

	// name of the tree.
	Name string

	// id of the root node of the tree.
	Root string

	// extern identifier of the tree.
	Extern []string

	// free text comment about the tree.
	Comment string
}

Phylogeny is a phylogenetic tree.

type Query

type Query string

Query is a query to the database.

type Rank

type Rank uint

Rank is a rank value. Ranks are arranged in a way that an inclusive rank in the taxonomy is always smaller than more exclusive ranks. Then is possible to use this form:

if rank < jdh.Genus {
    // do something
}
const (
	Unranked Rank = iota
	Kingdom
	Phylum
	Class
	Order
	Family
	Genus
	Species
)

Valid taxonomic ranks.

func GetRank

func GetRank(s string) Rank

GetRank returns a rank id from a string.

func (Rank) String

func (r Rank) String() string

String returns the rank string of a given rank id.

type Raster

type Raster struct {
	// identifier of the raster.
	Id string

	// id of the taxon used in the raster.
	Taxon string

	// source of the raster.
	Source RasterSource

	// a reference of the raster.
	Reference string

	// number of colums the raster will have if it occupies all earth
	// (i.e. a 360 degrees span). The number of rows is just this number
	// divided by two.
	Cols uint

	// stored raster.
	Raster *raster.PixList

	// extern identifiers of the raster.
	Extern []string

	// free text comment about the raster.
	Comment string
}

Raster holds the information about a rasterized taxon distribution.

type RasterSource

type RasterSource int

RasterSource indicates how the raster was adquired.

const (
	UnknownRaster RasterSource = iota

	// a raster from explicit georeferenced points. Its values are expected
	// to be booleans (0 or 1).
	ExplicitPoints

	// a raster from expert's opinion about taxon's distribution. Its
	// values are expected to be booleans (0 or 1).
	ExpertOpinion

	// a raster from a predictive distribution algorithm. Its values
	// are expected to be between 0 and 1000.
	MachineModel
)

Valid RasterSource values.

func GetRasterSource

func GetRasterSource(s string) RasterSource

GetRasterSource returns the id of a raster source.

func (RasterSource) String

func (sr RasterSource) String() string

String returns the raster source for a guiven RasterSource id.

type Scanner

type Scanner interface {
	Scan(dest interface{}) error
}

Scanner is the result of a get query. It can be read only one time.

type Specimen

type Specimen struct {
	// identifier of the specimen.
	Id string

	// id of the taxon assigned to the specimen.
	Taxon string

	// basis of the recorded specimen.
	Basis BasisOfRecord

	// a reference of the specimen.
	Reference string

	// Dataset is the id of the dataset that holds the specimen
	// information.
	Dataset string

	// catalog code of the specimen, it is expected to be in the format
	// <instituion acronym>:<collection acronym>:<catalog id>.
	Catalog string

	// the person who determined the identity the specimen.
	Determiner string

	// the person who collected the specimen.
	Collector string

	// the time and date of the collection event.
	Date time.Time

	// general geographic location data of the collection event.
	Geography geography.Location

	// locality of the collection event.
	Locality string

	// georeference of the specimen, if any.
	Georef geography.Georeference

	// extern identifiers of the specimen.
	Extern []string

	// free text comment about the specimen.
	Comment string
}

Specimen holds the information of a collection specimen.

type Table

type Table string

Table is a request parameter that indicate the "table" in whinch an operation should be performed.

const (
	// Used to retrieve, set information about a tree
	Trees Table = "trees"

	// Used to retrieve, set information about a node.
	Nodes = "nodes"
)

Tables used for phylogenetic tree data.

const Datasets Table = "datasets"

Datasets is the table that store dataset information.

const RasDistros Table = "rasdistros"

RasDistros is the table that store the rasterized distributions.

const Specimens Table = "specimens"

Specimens is the table that store the specimen information.

const Taxonomy Table = "taxonomy"

Taxonomy is the table that store taxon information.

type Taxon

type Taxon struct {
	// identifier of the taxon.
	Id string

	// taxon's canonical name.
	Name string

	// taxon's authority citation.
	Authority string

	// taxon's rank id.
	Rank Rank

	// true if the taxon is valid/accepted.
	IsValid bool

	// id of the parent taxon.
	Parent string

	// extern identifiers of the taxon.
	Extern []string

	// free text comment about the taxon.
	Comment string
}

Taxon holds the taxonomic information of a taxon.

type Values

type Values struct {
	KV []KeyValue
}

Values kepts a list of key:value pairs used for jdh database queries. Key values are case-sensitive, and each key can only hold a unique value.

func (*Values) Add

func (v *Values) Add(key Key, value string)

Add adds a new key:value pair. If the key is already assigned it will append the value.

func (*Values) Reset

func (v *Values) Reset()

Reset cleans the key-values stored in values.

func (*Values) Set

func (v *Values) Set(key Key, value string)

Set sets a key:value pair. If the key is already assigned, it will deletes the old content.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL