abbr

package
v0.69.0 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

package abbr describes entities for the abbreviated names endpoint. The endpoint receives names with an abbreviated genus, such as `C. elegans`, that share the same genus abbreviation, and returns candidate genera that explain most of these names.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Features added in v0.69.0

type Features struct {
	// GenusSize is the size of the genus used by the score: the largest
	// number of distinct epithet stems among its homonyms. It can differ
	// from Genus.EpithetsNumber, which belongs to the shown
	// classification.
	GenusSize int `json:"genusSize"`

	// DominantClassFit is 1 if the genus is in the DominantClass, -1 if
	// it is in another class, and 0 if the class or the DominantClass is
	// unknown.
	DominantClassFit int `json:"dominantClassFit"`

	// MainTaxonFit is 1 if the genus is in the MainTaxon, -1 if it is
	// not, and 0 if the classification or the MainTaxon is unknown.
	MainTaxonFit int `json:"mainTaxonFit"`

	// Known is true if the genus is in IRMNG or has a classification.
	Known bool `json:"known"`

	// UnmatchedUnits is the number of distinct names that the genus did
	// not match. A name that occurs several times counts once.
	UnmatchedUnits int `json:"unmatchedUnits"`

	// Matches contains features of distinct matched names. A name that
	// occurs several times counts once.
	Matches []MatchFeatures `json:"matches"`
}

Features are raw values the score of a genus is calculated from. Together with Meta.PrefixSize they are enough to recalculate the score with other weights.

type Genus

type Genus struct {
	// Name is the name of the genus.
	Name string `json:"name"`

	// ClassificationPath contains the classification of the genus as
	// a hierarchy of names separated by `|`.
	ClassificationPath string `json:"classificationPath,omitempty"`

	// ClassificationRanks contains ranks of the ClassificationPath,
	// separated by `|`.
	ClassificationRanks string `json:"classificationRanks,omitempty"`

	// EpithetsNumber is the size of the genus, as the number of its
	// distinct epithet stems. A matched name gives less to the score of
	// a large genus.
	EpithetsNumber int `json:"epithetsNumber"`

	// Score is the score of the genus and its parts.
	Score Score `json:"score"`

	// MatchedNames contains input names matched by the genus.
	MatchedNames []MatchedName `json:"matchedNames"`

	// UnmatchedNames contains input names not matched by the genus,
	// within the Tolerance. Genus hints are not included.
	UnmatchedNames []Name `json:"unmatchedNames,omitempty"`

	// Features are raw values the score is calculated from. They are
	// given only with WithFeatures.
	Features *Features `json:"features,omitempty"`
}

Genus is a candidate genus for a group of abbreviated names.

type Input

type Input struct {
	// Names contains abbreviated names as found in a text. All names must
	// have the same genus abbreviation, which is capitalized and ends with
	// a period, for example `C.` or `Cae.`. Otherwise the request is an
	// error.
	Names []Name `json:"names"`

	// MainTaxon is the lowest taxon that contains most of the names of
	// the source, as calculated by GNverifier statistics.
	MainTaxon string `json:"mainTaxon,omitempty"`

	// DominantClass is the most common class of the names of the source,
	// as calculated by GNverifier statistics.
	DominantClass string `json:"dominantClass,omitempty"`

	// Tolerance is the percentage (0-100) of names that may be unmatched
	// for a genus to stay a candidate. The number of allowed unmatched
	// names is rounded down. If nil, the default is used. Zero requires
	// all names to match.
	Tolerance *int `json:"tolerance,omitempty"`

	// GeneraLimit is the maximum number of candidate genera in the result.
	// If zero, the default is used.
	GeneraLimit int `json:"generaLimit,omitempty"`

	// WithFeatures adds raw features of the score to each genus, so a
	// client can recalculate the score with other weights. It is meant for
	// tuning of the weights. Genera are still ranked and limited by the
	// current score, so a client that tunes weights should ask for many
	// genera.
	WithFeatures bool `json:"withFeatures,omitempty"`
}

Input contains a group of abbreviated names and parameters that control how candidate genera are found and ranked.

type MatchFeatures added in v0.69.0

type MatchFeatures struct {
	// Name is the first input name with these epithets.
	Name string `json:"name"`

	// IDs are client IDs of all input names with these epithets.
	IDs []string `json:"ids,omitempty"`

	// NamesNumber is the number of input names with these epithets.
	NamesNumber int `json:"namesNumber"`

	// MatchType tells how the name matched.
	MatchType MatchTypeValue `json:"matchType"`

	// Key is the lookup key of the epithet the evidence is based on, for
	// example `c-elegans`.
	Key string `json:"key"`

	// KeyGenera is the number of genera that start with the abbreviation
	// and have the Key.
	KeyGenera int `json:"keyGenera"`

	// DsNum is the number of data sources with the matched name.
	DsNum int `json:"dsNum"`

	// HintPosition is the best position of the genus among genus hints of
	// the name, starting from 1. It is 0 if the genus is not hinted.
	HintPosition int `json:"hintPosition,omitempty"`
}

MatchFeatures are raw values of a distinct name matched by a genus.

type MatchTypeValue

type MatchTypeValue int

MatchTypeValue describes how an abbreviated name matched a name of a candidate genus.

const (
	// NoMatch means that matching failed.
	NoMatch MatchTypeValue = iota

	// SpeciesLevel means that the input and the matched name have the
	// same species epithet, but their last epithets differ. The match
	// can be coarser (`P. tigris altaica` matched `Panthera tigris`),
	// finer (`P. tigris` matched `Panthera tigris altaica`), or another
	// infraspecies of the same species (`P. tigris altaica` matched
	// `Panthera tigris amurensis`). It is not the name from the text,
	// but it still shows the genus.
	SpeciesLevel

	// EpithetMoved means that the input and the matched name have the
	// same last epithet, but other epithets differ. The epithet moved to
	// another rank or species, for example `P. tigris altaica` matched
	// `Panthera altaica`, or `P. altaica` matched
	// `Panthera tigris altaica`.
	EpithetMoved

	// Full means that the input and the matched name have the same
	// epithets, for example `P. tigris altaica` matched
	// `Panthera tigris altaica`. Nominotypical repeats are ignored, so
	// `B. bubo` matches `Bubo bubo bubo` fully.
	Full
)

func NewMatchType

func NewMatchType(t string) MatchTypeValue

NewMatchType takes a string and converts it into a MatchType. If the string is unknown, it returns NoMatch type.

func (MatchTypeValue) MarshalJSON

func (mt MatchTypeValue) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaller interface and converts MatchType into a string.

func (MatchTypeValue) String

func (mt MatchTypeValue) String() string

String implements fmt.String interface and returns a string representation of a MatchType. The returned string can be converted back to MatchType via NewMatchType function.

func (*MatchTypeValue) UnmarshalJSON

func (mt *MatchTypeValue) UnmarshalJSON(bs []byte) error

UnmarshalJSON implements json.Unmarshaller interface and converts a string into MatchType.

type MatchedName

type MatchedName struct {
	// ID is the client ID of the input name.
	ID string `json:"id,omitempty"`

	// Name is the input name.
	Name string `json:"name"`

	// MatchedCanonical is the full canonical form the name matched,
	// for example `Panthera tigris altaica`.
	MatchedCanonical string `json:"matchedCanonical"`

	// MatchType tells how the name matched.
	MatchType MatchTypeValue `json:"matchType"`

	// StemMatch is true if an epithet ending matched only by its stem,
	// for example `alba` and `albus`.
	StemMatch bool `json:"stemMatch,omitempty"`
}

MatchedName is an input name matched by a candidate genus.

type Meta

type Meta struct {
	// Names contains the input names and their client IDs.
	Names []Name `json:"names"`

	// Abbreviation is the normalized genus abbreviation of the names.
	Abbreviation string `json:"abbreviation,omitempty"`

	// MainTaxon is the MainTaxon from the input.
	MainTaxon string `json:"mainTaxon,omitempty"`

	// DominantClass is the DominantClass from the input.
	DominantClass string `json:"dominantClass,omitempty"`

	// Tolerance is the percentage of names that may be unmatched for a
	// genus, as applied.
	Tolerance int `json:"tolerance"`

	// GeneraLimit is the maximum number of candidate genera, as applied.
	GeneraLimit int `json:"generaLimit"`

	// WithFeatures is the WithFeatures from the input.
	WithFeatures bool `json:"withFeatures,omitempty"`

	// PrefixSize is the sum of sizes (distinct epithet stems) of all
	// genera that start with the abbreviation. It is a feature of the
	// score shared by all genera, and is given only with WithFeatures.
	PrefixSize int `json:"prefixSize,omitempty"`

	// NamesNumber is the number of submitted names.
	NamesNumber int `json:"namesNumber"`

	// MatchedNamesNumber is the number of names matched by at least one
	// candidate genus.
	MatchedNamesNumber int `json:"matchedNamesNumber"`

	// UnmatchedNamesNumber is the number of names not matched by any
	// candidate genus.
	UnmatchedNamesNumber int `json:"unmatchedNamesNumber"`

	// Error contains an error message, if any. If Error is not empty,
	// no genera are returned.
	Error string `json:"error,omitempty"`
}

Meta contains metadata about the request, including parameters as they were applied.

type Name

type Name struct {
	// ID is an optional identifier provided by the client. It allows to
	// map results back to positions in a text, because the same name can
	// occur many times.
	ID string `json:"id,omitempty"`

	// Name is the abbreviated name as found in a text, for example
	// `C. elegans`.
	Name string `json:"name"`

	// GenusHints contains full genera found near the name, sorted by
	// closeness, the closest first. Hints never exclude candidates, they
	// only change the ranking.
	GenusHints []string `json:"genusHints,omitempty"`
}

Name is an abbreviated name with an optional client ID and genus hints.

type Output

type Output struct {
	// Meta contains the metadata of the request results.
	Meta `json:"metadata"`

	// Genera contains candidate genera sorted by their total score. If
	// nothing matched, it is empty.
	Genera []Genus `json:"genera"`
}

Output contains candidate genera for a group of abbreviated names.

type Score

type Score struct {
	// MatchedNames is the part of the score that comes from matched names.
	// A name gives less to a large genus, or if its epithet is common.
	MatchedNames float64 `json:"matchedNames"`

	// GenusHints is the part of the score that comes from genus hints.
	GenusHints float64 `json:"genusHints"`

	// UnmatchedNames is the part of the score that comes from unmatched
	// names. It is zero or negative.
	UnmatchedNames float64 `json:"unmatchedNames"`

	// DominantClass is the part of the score that comes from the genus
	// being in the DominantClass.
	DominantClass float64 `json:"dominantClass"`

	// MainTaxon is the part of the score that comes from the genus being
	// in the MainTaxon.
	MainTaxon float64 `json:"mainTaxon"`

	// UnknownGenus is the penalty for a genus that is not in IRMNG and
	// has no classification. Such genera are often misspellings. It is
	// zero or negative.
	UnknownGenus float64 `json:"unknownGenus"`

	// Popularity is the part of the score that comes from the number of
	// data sources with the matched names. It breaks ties between genera
	// that explain names equally well. It is zero or positive.
	Popularity float64 `json:"popularity"`

	// Total is the total score of the genus.
	Total float64 `json:"total"`
}

Score contains weighted parts of the score of a candidate genus and their total. The parts add up to the total.

Jump to

Keyboard shortcuts

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