Skip to content

API.md

Latest commit

 

History

History
1224 lines (861 loc) · 44.6 KB

API.md

File metadata and controls

1224 lines (861 loc) · 44.6 KB
Raw

Modules

load

Load the provided source datasets.

names

Parse scientific names.

source

Describe a source dataset.

taxamatch

Match scientific names.

load

Load the provided source datasets.

load~loadSources(path, [filters], [dir]) ⇒ Array.<Source>

Load sources from source properties.

Kind: inner method of load

Param Type Default Description
path string Directory of JS files containing source properties.
[filters] object {}
filters.ids Array.<string> Return only sources with these identifiers.
filters.countries Array.<string> Return only source with these countries.
[dir] string "data/${id}/input" Source input directory (template interpolated on source properties).

names

Parse scientific names.

names~ScientificName

Class representing a scientific name.

Kind: inner class of names
Properties

Name Type Description
parsed ParsedScientificName Parsed scientific name.
[input] string | object Input from which parsed was derived.
[matches] Array.<object> Matches from a taxonomic database.

new ScientificName(obj)

Param Type Description
obj ParsedScientificName Parsed scientific name.

scientificName.toString(options) ⇒ string

Print scientific name to string.

Kind: instance method of ScientificName

Param Type Description
options object Print options (see printScientificName).

Example

ScientificName.fromString(`Malus pumila var. asiatica 'Gala'`).toString()
// "Malus pumila var. asiatica 'Gala'"

scientificName.warnings() ⇒ Array.<string>

Get warnings.

Kind: instance method of ScientificName
Example

ScientificName.fromString('... Malus x pumila ...').warnings()
// [ 'Unparsed head', 'Unparsed tail', 'Hybrid' ]
ScientificName.fromFields({genus: 'Malus', species: 'pumila', scientific: 'Pyrus communis'}).warnings()
// [ 'Inconsistent secondary fields: genus, species' ]

scientificName.errors() ⇒ Array.<string>

Get errors.

Kind: instance method of ScientificName
Example

(new ScientificName({species: 'pumila'})).errors()
// [ 'Missing genus' ]

scientificName.report() ⇒ object

Get full report.

Kind: instance method of ScientificName
Example

ScientificName.fromString('... Malus x pumila ...').report()
// {
//    input: '... Malus x pumila ...',
//    parsed: {
//      head: '... ',
//      genus: 'Malus',
//      species: 'pumila',
//      hybrid: true,
//      tail: '...'
//    },
//    warnings: [ 'Unparsed head', 'Unparsed tail', 'Hybrid' ]
// }

ScientificName.fromString(str) ⇒ ScientificName

Build scientific name from string.

Kind: static method of ScientificName

Param Type
str string

Example

ScientificName.fromString('Malus pumila')
// ScientificName {
//   parsed: { genus: 'Malus', species: 'pumila' },
//   input: 'Malus pumila'
// }

ScientificName.fromFields(fields) ⇒ ScientificName

Build scientific name from feature fields.

Kind: static method of ScientificName

Param Type
fields object

Example

ScientificName.fromFields({ scientific: 'Malus pumila', other: 'Bloop' })
// ScientificName {
//   parsed: { genus: 'Malus', species: 'pumila' },
//   input: { scientific: 'Malus pumila' }
// }
ScientificName.fromFields({ genus: 'malus', species: 'PLATANOÏDES' })
// ScientificName {
//   parsed: { genus: 'Malus', species: 'platanoides' },
//   input: { genus: 'malus', species: 'PLATANOÏDES'}
// }

ScientificName.compareStrings(options) ⇒ function

Generate compare function for sorting by string representation.

Kind: static method of ScientificName
Returns: function - Compare function (a, b).

Param Type Description
options object Print options (see printScientificName).

Example

l = [new ScientificName({genus: 'Prunus'}), new ScientificName({genus: 'Malus'})]
l.sort(ScientificName.compareStrings())
// [
//   ScientificName { parsed: { genus: 'Malus' } },
//   ScientificName { parsed: { genus: 'Prunus' } }
// ]

names~GENERIC

Generic epithet.

Minimum two letters. Dash can be within three letters of end (e.g. 'Uva-ursi', 'Filix-mas').

Kind: inner constant of names

names~SPECIFIC

Specifc epithet.

Minimum two letters. Dashes can be within one letter of end (e.g. 's-stylata', 'laurel-y').

Kind: inner constant of names

names~SUBG

Subgenus rank.

subg: subg(.) | subgen(.) | subgenus

Kind: inner constant of names

names~SP

Species rank.

sp: sp(.), spp(.), species

Kind: inner constant of names

names~RANKS

Infraspecific ranks.

subsp: subsp(.) | subspp(.) | ssp(.) | sspp(.) | subspecies var: var(.) | variety | varietas subvar: subvar(.), subvariety, subvarietas f: f(.) | form | forma subf: subf(.) | subform | subforma

Kind: inner constant of names

names~RANK

Any infraspecific rank.

Kind: inner constant of names

names~HEAD

Everything before the first (latin) letter or hybrid symbol.

Kind: inner constant of names

names~UNINOMIAL

Uninomial.

Kind: inner constant of names

names~GENUS

Genus.

Identical to uninomial, but inferred to be a genus based on context.

Kind: inner constant of names

names~HYBRID_GENUS

Secondary genus in hybrid formula.

May be abbreviated down to a single letter.

Kind: inner constant of names

names~SUBGENUS

Subgenus.

Kind: inner constant of names

names~SPECIES

Species.

Kind: inner constant of names

names~INFRASPECIES

One or more infraspecific epithets, each preceded by an optional rank.

Kind: inner constant of names

names~RANK_EPITHET

Single infraspecific epithet preceded by an optional rank.

Kind: inner constant of names

names~CULTIVAR

Cultivar.

Must be wrapped in quotes and not include certain characters.

Kind: inner constant of names

names~FIRST

Parse a scientific name (or the first name in a hybrid formula).

Each key is a regular expression with named capture groups. Try each in order. As soon as a match is found, proceed to the children keys and repeat until null or no more children are found. Any tags, if encountered, are added to the result.

Kind: inner constant of names

names~HYBRID

Parse a secondary name in a hybrid formula.

Kind: inner constant of names

names~cleanName(s) ⇒ string

Clean name string.

  • Latinizes characters.
  • Replaces whitespace sequences with a single space.
  • Removes leading and trailing whitespace.

Kind: inner method of names

Param Type
s string

Example

cleanName(' Acer  platanoïdes ') // 'Acer platanoides'

names~parseInfraspecies(s) ⇒ Array.<Infraspecies>

Parse infraspecific ranks and epithets.

Kind: inner method of names

Param Type
s string

Example

parseInfraspecies('foo f bar') // [{epithet: 'foo'}, {rank: 'f.', epithet: 'bar'}]

names~printInfraspecies(infraspecies, options) ⇒ string

Print infraspecific ranks and epithets.

Kind: inner method of names

Param Type Default Description
infraspecies Array.<Infraspecies>
options object
[options.n] object Infinity – Number of infraspecies.
[options.rank] object true – Print infraspecies rank.

Example

printInfraspecies([ { rank: 'f.', epithet: 'mora' } ])
// 'f. mora'
printInfraspecies([ { rank: 'f.', epithet: 'mora' } ], { rank: false })
// 'mora'

names~printScientificName(name, [options]) ⇒ string

Print scientific name.

Kind: inner method of names

Param Type Default Description
name ParsedScientificName Scientific name.
[options] object Printing options.
[options.infraspecies] number Infinity Number of infraspecies.
[options.hybrid] boolean true Print hybrid symbol and formulas.
[options.rank] boolean true Print infraspecies rank.
[options.cultivar] boolean true Print cultivar.

Example

name = {
  genus: 'Genus',
  species: 'speciosa',
  infraspecies: [{ rank: 'f.', epithet: 'formosa' }],
  cultivar: 'Gala',
  hybrid: true,
  hybrids: [{ genus: 'Genus', species: 'pendula' }]
}
printScientificName(name)
// "Genus speciosa f. formosa 'Gala' × Genus pendula'"
printScientificName(name, {cultivar: false})
// "Genus speciosa f. formosa × Genus pendula'"
printScientificName(name, {infraspecies: 0, cultivar: false})
// 'Genus speciosa × Genus pendula'
printScientificName(name, {hybrid: false, infraspecies: 0, cultivar: false})
// 'Genus speciosa'

names~formatScientificName(name, defaultGenus) ⇒ ParsedScientificName

Format scientific name.

Kind: inner method of names

Param Type Default Description
name ParsedScientificName – Scientific name.
defaultGenus string | boolean null – Genus to assume if hybrid genus is blank or an abbreviation of defaultGenus. Defaults to genus if null, or skipped if false.

Example

name = {
  genus: ' GENUS',
  species: 'SPECIOSA ',
  infraspecies: [ { rank: 'VAR', epithet: 'FORMOSA' } ],
  cultivar: 'CULTI VAR',
  hybrids: [ {genus: 'G', species: 'spéciosa' } ],
  hybrid: true
}
formatScientificName(name)
// {
//   genus: 'Genus',
//   species: 'speciosa',
//   infraspecies: [ { rank: 'var.', epithet: 'formosa' } ],
//   cultivar: 'Culti Var',
//   hybrids: [ { genus: 'Genus', species: 'speciosa' } ],
//   hybrid: true
// }

names~parseScientificName(name) ⇒ ParsedScientificName

Parse scientific name.

Kind: inner method of names

Param Type Description
name string Name to parse as a scientific name.

Example

parseScientificName(`Genus`)
// { uninomial: 'Genus' }
parseScientificName(`Genus speciosa var. segunda 'Cultivar' x Genus hybrida`)
// {
//   genus: 'Genus',
//   species: 'speciosa',
//   infraspecies: [ { rank: 'var.', epithet: 'segunda' } ],
//   cultivar: 'Cultivar',
//   hybrids: [ { genus: 'Genus', species: 'hybrida' } ],
//   hybrid: true
// }

names~Infraspecies : object

Infraspecies.

Kind: inner typedef of names
Properties

Name Type Description
rank string Rank (subsp., var., f., subvar., subf.).
epithet string Epithet (lowercase: e.g. pontica).

names~ParsedScientificName : object

Scientific name.

Kind: inner typedef of names
Properties

Name Type Description
head string Unparsed head.
uninomial string – Uninomial name (maybe genus).
genus string Genus (capitalized: e.g. Malus).
subgenus string Subgenus (capitalized: e.g. Malus).
species string Specific epithet (lowercase: e.g. pumila).
infraspecies Array.<Infraspecies> Infraspecific epithets.
cultivar string Cultivar (title case: e.g. Golden Delicious).
hybrid boolean Whether this is a hybrid.
hybridGenus boolean – Whether genus is a nothogenus (e.g. × Sorbopyrus).
hybrids Array.<Hybrid> – Secondary names in a hybrid formula.
tail string Unparsed tail.

source

Describe a source dataset.

source~Source

Class representing a source dataset.

Kind: inner class of source

new Source(props, dir, [options])

Param Type Default Description
props SourceProperties Source properties.
dir string Local directory to which remote files are downloaded and where local files are searched for.
[options] object
[options.exit] boolean true Whether to throw errors or print them to the console.
[options.srs] string "EPSG:4326" Spatial reference system to assume if none is defined in props.srs and none can be read from the input files.

source.get([overwrite]) ⇒ Promise.<Array.<string>>

Prepare remote source data for processing.

Downloads remote data (this.props.download, this.props.featureLayer), unpacks compressed or archive files, and executes shell commands (this.props.execute).

Kind: instance method of Source
Returns: Promise.<Array.<string>> - Resolves to the paths of the downloaded and unpacked local files (if any).

Param Type Default Description
[overwrite] boolean false Whether to proceed if working directory is not empty (see Source#isEmpty).

source.process(file, [options]) ⇒ boolean

Process input and write to output.

Reading, writing, and coordinate transformations are performed by GDAL via the node-gdal-next bindings.

Processing steps include a schema crosswalk (this.props.crosswalk), skipping features by field values (this.props.delFunc), reducing complex geometries to centroid points (options.centroids), and skipping features outside a bounding box (options.bounds). For files without explicit geometries, a temporary VRT file is created (see Source#getVrt).

Kind: instance method of Source
Returns: boolean - Whether processed file (true) or skipped (false).

Param Type Default Description
file string Output file path.
[options] object Output options.
[options.driver] string Name of GDAL driver to use to write to the output file (see https://gdal.org/drivers/vector). Guessed from file extension if not provided.
[options.creation] Array.<string> | object Driver-specific dataset creation options (see https://gdal.org/drivers/vector). Only default, for 'CSV', is ['GEOMETRY=AS_WKT'] to include feature geometry in output.
[options.overwrite] boolean false Whether to proceed if file already exists.
[options.srs] string "+init=epsg:4326" Output spatial reference system in any format supported by OGRSpatialReference.SetFromUserInput(). Use 'EPSG:' for (latitude, longitude) and '+init=epsg:' (PROJ<6 behavior) for (longitude, latitude). If it is the same as the input SRS, axis order will remain unchanged regardless.
[options.centroids] boolean false Whether to reduce non-point geometries to centroids.
[options.keepInvalid] boolean false Whether to keep features with empty or invalid geometries.
[options.keepFields] boolean false Whether to keep the input feature fields alongside the result of the schema crosswalk (this.props.crosswalk).
[options.keepGeometryFields] boolean false Whether to keep the input feature geometry fields. Applies only to inputs for which a VRT file is written (see Source#getVrt) and if options.keepFields is also true.
[options.prefix=] string String to append to input field names to prevent collisions with output field names. Applies only if options.keepFields is true.
[options.bounds] Array.<number> Bounding box in output SRS (options.srs) in the format [xmin, ymin, xmax, ymax]. If provided, features outside the bounds are skipped.
[options.delFunc] function Function that takes an object (of feature field values after the crosswalk) and returns a value (e.g. obj => obj.description === 'vacant site'). The feature is excluded from the output if the returned value evaluates to true.
[options.allowEmptyGeometry] boolean false Whether to allow feature layer with empty geometry.

source.getFields() ⇒ object

Get layer field names and GDAL data types.

Kind: instance method of Source
Returns: object - Field names (keys) and GDAL data types (values)

source.getRows([n]) ⇒ Array.<object>

Get feature fields.

Kind: instance method of Source

Param Type Default Description
[n] integer Infinity Maximum number of features to read.

source.sample([options]) ⇒ object.<string, Array>

Sample field values from input.

Kind: instance method of Source
Returns: object.<string, Array> - Object of field values with field names as keys.

Param Type Default Description
[options] object
[options.n] number 1000 Maximum number of features to sample.
[options.max] number 100 Maximum number of values to collect for each field.
[options.sort] boolean true Whether to sort values.
[options.unique] boolean true Whether to only save unique values.

source.glimpse([options])

Print table of input field names, types, and unique values.

Kind: instance method of Source

Param Type Default Description
[options] object Options to pass to Source#sample, plus:
[options.sample] object.<string, Array> Result of Source#sample.
[options.truncate] number 1280 Maximum number of characters to print per field.
[options.widths] Array.<number> [20, 10, 130] Column widths for field names, types, and unique values, respectively.
[options.sep] string "·" Separator between unique values.

source.empty()

Empty and remove the source directory.

Kind: instance method of Source

source.isEmpty() ⇒ boolean

Check whether the source directory is missing or empty of files.

Checks any child directories recursively and ignores dotfiles (.*).

Kind: instance method of Source
Returns: boolean - Whether source directory is empty.

source.find() ⇒ string

Find path to input file.

Searches for all non-dotfiles in the source directory recursively and attempts to guess which file to pass to GDAL based on file extensions. Throws an error if no file is found or if multiple candidate files are found.

Kind: instance method of Source
Returns: string - File path.

source.open() ⇒ gdal.Dataset

Open input file with GDAL.

Kind: instance method of Source
Returns: gdal.Dataset - See the documentation for node-gdal-next. Result is cached until closed with Source#close.

source.close()

Close input file if open with GDAL.

Kind: instance method of Source

source.openVrt([keepGeometryFields]) ⇒ gdal.Dataset

Open input file with GDAL via a VRT file.

Opens the input file via a virtual format (VRT) file written to the dotfile .vrt. The contents of the file is built by Source#getVrt.

Kind: instance method of Source
Returns: gdal.Dataset - See the documentation for node-gdal-next. The result is cached until closed with Source#closeVrt.

Param Type Default Description
[keepGeometryFields] boolean false Whether the VRT file should return geometry fields as regular feature fields.

source.closeVrt()

Close input file if open with GDAL via a VRT file.

Kind: instance method of Source

source.getSrsString([layer]) ⇒ string

Get spatial reference system (SRS) of input as a string.

Kind: instance method of Source
Returns: string - Either the provided SRS (this.props.srs), the SRS read from the input file (as well-known-text), or the default SRS (this.options.srs).

Param Type Description
[layer] gdal.Layer Feature layer from which to read SRS. If not provided, defaults to the first layer of the input file (see @link Source#open).

source.getSrs([layer]) ⇒ gdal.SpatialReference

Get spatial reference system (SRS) of input.

Kind: instance method of Source
Returns: gdal.SpatialReference - SRS object initialized by gdal.SpatialReference.fromUserInput() from the result of Source#getSrsString. See the documentation for node-gdal-next.

Param Type Description
[layer] gdal.Layer Feature layer from which to read SRS. If not provided, defaults to the first layer of the input file (see @link Source#open).

source.getGeometry() ⇒ Object | undefined

Get geometry field name(s) of input.

Kind: instance method of Source
Returns: Object | undefined - Names of geometry fields either provided (this.props.srs) or guessed from field names, or undefined if the input already has explicit geometries.

source.getVrt([keepGeometryFields]) ⇒ string

Get VRT (OGR Virtual Format) file content.

For files without explicit geometries (e.g. tabular text files), a temporary VRT file can be created listing the spatial reference system (see Source#getSrsString) and geometry field names (see Source#getGeometry) for GDAL to use.

Kind: instance method of Source
Returns: string - VRT file content.

Param Type Default Description
[keepGeometryFields] boolean false Whether VRT file should return geometry fields as regular feature fields.

source.success(msg, ...objects)

Print success message to console (green).

Kind: instance method of Source

Param Type Description
msg string Message prepended with green tag ([props.id]).
...objects * Additional objects passed to console.log().

source.log(msg, ...objects)

Print message to console (cyan).

Kind: instance method of Source

Param Type Description
msg string Message prepended with cyan tag ([props.id]).
...objects * Additional objects passed to console.log().

source.warn(msg, ...objects)

Print warning to console (yellow).

Kind: instance method of Source

Param Type Description
msg string Message prepended with yellow tag ([props.id]).
...objects * Additional objects passed to console.log().

source.error(msg, ...objects)

Throw or print error to console (red).

Kind: instance method of Source

Param Type Description
msg string Message prepended with red tag ([props.id]).
...objects * Additional objects passed directly to console.error() or appended to error via util.inspect().

source~SourceProperties : object

Properties used by Source for data processing.

Kind: inner typedef of source
Properties

Name Type Description
id string Identifier prepended to console output.
download string | Array.<string> Path to remote files to download and unpack.
featureLayer string Path to ArcGIS Feature Server layer. See https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm.
execute string | Array.<string> Shell commands executed from working directory (Source.dir) after file download and unpack. In npm run commands, prepend the INIT_CWD variable to paths to the files (https://docs.npmjs.com/cli/run-script).
filename string Glob pattern (relative to working directory) used to find the file to read. Only needed when there are multiple files and either none or multiple have extensions recognized by GDAL.
srs string Spatial reference system in any format supported by OGRSpatialReference.SetFromUserInput().
geometry object Geometry field names for formats without explicit geometries (e.g. tabular text files like CSV). If not provided, will attempt to guess from field names.
geometry.wkt string Name of field with well-known-text (wkt) geometry. If provided, takes precedence over x, y.
geometry.x string Name of field with x coordinate (longitude, easting).
geometry.y string Name of field with y coordinate (latitude, northing).
crosswalk Object.<string, (string|function())> Crosswalk mapping to a target schema. For each key: value pair, key is the new field name and value is either the old field name (e.g. height: 'HEIGHT') or a function that takes an object (of feature field values) and returns a value (e.g. height: obj => obj.HEIGHT / 100).
delFunc function Function that takes an object (of feature field values before the crosswalk) and returns a value (e.g. obj => obj.HEALTH === 'dead'). The feature is excluded from the output if the returned value evaluates to true.
coordsFunc function Function that takes an object (of feature field values before the crosswalk) and returns a number array of point coordinates [x, y]. This is a useful alternative to geometry if the coordinates need to be extracted from field values (e.g. obj => obj.XY.split(';').map(Number)).

source~SourcePropertiesExtended : SourceProperties

Additional properties not used by Source but used downstream.

Kind: inner typedef of source
Properties

Name Type Description
pending string Pending issues preventing processing.
primary string id of the primary source (for grouping sources together).
long string Full name of the government body, university, or other institution (e.g. City of Melbourne).
short string Short name (e.g. Melbourne).
country string Country name in English (e.g. Australia).
centre object Centre point (for map label placement).
centre.lon number Longitude in decimal degrees (EPSG:4326).
centre.lat number Latitude in decimal degrees (EPSG:4326).
info string Path to page with more information.
language string Language of contents as an ISO 639-1 code (e.g. en) and an optional ISO 3166-1 alpha-2 region code (e.g. en-AU).
license object Data license.
license.id string License identifier from the Software Package Data Exchange (SPDX) license list (e.g. CC-BY-4.0).
license.name string License name (e.g. Creative Commons Attribution 4.0 International).
license.url string Path to page with license text (e.g. https://creativecommons.org/licenses/by/4.0).

taxamatch

Match scientific names.

taxamatch~Matcher

Class for matching scientific names to a taxonomic dictionary.

Currently supports exact, fuzzy, and phonetic matching on:

  • genus
  • species
  • first infraspecies epithet and rank

Kind: inner class of taxamatch

new Matcher(taxa, [id])

Param Type Default Description
taxa Array.<object> Taxonomic dictionary. Each taxon must have a unique id and genus, and may have species and infraspecies [{ rank, epithet }, ...].
[id] string "'id'" Key in taxa to use as unique object identifier.

Example

taxa = [
 { id: 0, genus: 'Malus' },
 { id: 1, genus: 'Malus', species: 'pumila' },
 { id: 2, genus: 'Malus', species: 'pumila', infraspecies: [{ rank: 'var.', epithet: 'asiatica' }] }
]
matcher = new Matcher(taxa)
matcher.match({ genus: 'Malus' })
matcher.match({ genus: 'Malis' })
matcher.match({ genus: 'Malus', species: 'pumila' })
matcher.match({ genus: 'Malus', species: 'pimila' })
matcher.match({ genus: 'Mala', species: 'pimila' })
matcher.match({ genus: 'Malus', species: 'pumila', infraspecies: [{ epithet: 'asiatica'}] })
matcher.match({ genus: 'Malus', species: 'pumila', infraspecies: [{ rank: 'f.', epithet: 'asiatica'}] })
matcher.match({ genus: 'Malus', species: 'pumila', infraspecies: [{ rank: 'var.', epithet: 'asiatica'}] })
matcher.match({ genus: 'Malis', species: 'pimila', infraspecies: [{ rank: 'var.', epithet: 'asiatica'}] })
matcher.match({ genus: 'malus', species: 'pu-mila' })

matcher.match(name) ⇒ Array.<object>

Match scientific name to taxa.

Kind: instance method of Matcher
Returns: Array.<object> - Taxon match(es) in the following order:

  • exact and complete match, or
  • complete phonetic match or fuzzy match(es)
  • incomplete exact, phonetic, or fuzzy match(es) Each match is in the following format:
  • {boolean} incomplete - Whether match is of a higher rank than the provided name.
  • {number[]} fuzzy - Similarity score (0-1) for each matched name component (in the order genus, species, infraspecies), if fuzzy.
  • {boolean} phonetic - Whether match is phonetic.
  • {object} taxon - Matched taxon.
Param Type Description
name names.ParsedScientificName Scientific name.