Package 'ritalic'

Title: Interface to the ITALIC Database of Lichen Biodiversity
Description: A programmatic interface to the Web Service methods provided by ITALIC (<https://italic.units.it>). ITALIC is a database of lichen data in Italy and bordering European countries. 'ritalic' includes functions for retrieving information about lichen scientific names, geographic distribution, ecological data, morpho-functional traits and identification keys. More information about the data is available at <https://italic.units.it/?procedure=base&t=59&c=60>. The API documentation is available at <https://italic.units.it/?procedure=api>.
Authors: Matteo Conti [aut, cre] (ORCID: <https://orcid.org/0009-0003-4917-2639>), Luana Francesconi [aut], Alice Musina [aut], Luca Di Nuzzo [aut], Gabriele Gheza [aut], Chiara Pistocchi [aut], Juri Nascimbene [aut], Pier Luigi Nimis [aut], Stefano Martellos [aut]
Maintainer: Matteo Conti <[email protected]>
License: MIT + file LICENSE
Version: 0.12.0
Built: 2026-05-15 09:39:36 UTC
Source: https://github.com/plant-data/ritalic

Help Index

Get species names in the checklist of the lichens of Italy

Description

Retrieves the complete list of accepted scientific names from the Checklist of the Lichens of Italy in ITALIC. The function returns all accepted names of species occurring in Italy. If the parameter include_bordering_countries is set to TRUE the function returns all the accepted names of species in ITALIC occurring both in Italy and in bordering countries.

Usage

italic_checklist(
  include_bordering_countries = FALSE,
  genus = NULL,
  family = NULL,
  order = NULL,
  class = NULL,
  phylum = NULL
)

Arguments

include_bordering_countries

Optional. Default FALSE. If TRUE the result includes also taxa occurring in bordering countries.
genus

Optional. A genus name to filter the checklist.
family

Optional. A family name to filter the checklist.
order

Optional. An order name to filter the checklist.
class

Optional. A class name to filter the checklist.
phylum

Optional. A phylum name to filter the checklist.

Value

A character vector containing all accepted scientific names from the checklist of ITALIC.

References

ITALIC - The Information System on Italian Lichens: checklist https://italic.units.it/index.php?procedure=checklist

Examples

## Not run: 
# Get the complete checklist of Italy
italic_checklist()
# Get the complete checklist of Italy and bordering countries
italic_checklist(include_bordering_countries=TRUE)
# Get the checklist of the species of genus Lecanora
italic_checklist(genus ="Lecanora")

## End(Not run)

Get descriptions of lichen taxa

Description

Retrieves morphological descriptions and additional taxonomic or ecological notes about lichen taxa present in the Checklist of the Lichens of Italy. Only accepts names that exist in the database of ITALIC.

Usage

italic_description(sp_names)

Arguments

sp_names

Character vector of accepted names

Value

A data frame with columns:

scientific_name

The scientific name provided as input

description

Morphological description

notes

Additional taxonomic or ecological information

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      descriptions <- italic_description(names_matched$accepted_name)

Examples

## Not run: 
italic_description("Cetraria islandica (L.) Ach. subsp. islandica")

## End(Not run)

Create distribution map of a lichen taxon

Description

Creates a distribution map for a given lichen species based on its commonness/rarity status across Italian ecoregions and presence/absence across administrative regions. The map visually represents the data obtained from italic_ecoregions_distribution() and italic_regions_distribution().

Usage

italic_distribution_map(sp_name, plot_map = TRUE)

Arguments

sp_name

Character string representing the accepted scientific name of a lichen species. If multiple names are provided, a list is returned.
plot_map

If TRUE (default) the function returns a ggplot graph, if FALSE returns a sf object

Details

The function internally utilizes italic_ecoregions_distribution() and italic_regions_distribution() to retrieve the commonness/rarity status across Italian ecoregions and presence/absence across administrative regions data for the provided species. It then joins this data with a geospatial dataset of Italian regions and ecoregions (included in the package) to generate the map.

Commonness/rarity categories are visualized with a color scale, where each color corresponds to a different level of commonness/rarity ("extremely common", "very common", "common", "rather common", "rather rare", "rare", "very rare", "extremely rare", "absent").

Value

If one name is provided: if plot_map = TRUE (default), a ggplot object; if plot_map = FALSE, the sf object used to create the plot. If multiple names are provided, a named list of ggplot or sf objects, one for each input name.

Note

Before using this function, ensure that you have obtained the accepted name of the lichen using italic_match(). Example workflow: 

      name_matched <- italic_match("Cetraria islandica")
      map <- italic_distribution_map(name_matched$accepted_name)

References

For more information about Italian ecoregions see ITALIC ecoregions distribution https://italic.units.it/?procedure=base&t=59&c=60#commonness and the scientific publication describing the ecoregions used in ITALIC doi:10.3390/d12080294

Examples

## Not run: 
italic_distribution_map("Flavoparmelia caperata (L.) Hale")
italic_distribution_map("Anisomeridium biforme (Schaer.) R.C. Harris")

## End(Not run)

Get ecology data and morphological traits of lichen taxa

Description

Retrieves morpho-functional traits, ecological indicators, altitudinal distribution, and poleotolerance data for lichen taxa. Only accepts names that exist in the database of ITALIC.

Usage

italic_ecology_traits(sp_names)

Arguments

sp_names

Character vector of accepted names

Value

A data frame with:

scientific_name

The scientific name provided as input

substrata

Substrate

photobiont

Type of photosynthetic partner

growth_form

Growth form

phytoclimatic_range

Distribution in vegetation zones

special_requirements_for_water

Water requirements

reproductive_strategy

Main reproductive methods

ph_of_the_substrata_min

Minimum pH value (1-5 scale)

ph_of_the_substrata_max

Maximum pH value (1-5 scale)

solar_irradiation_min

Minimum light requirements (1-5 scale)

solar_irradiation_max

Maximum light tolerance (1-5 scale)

aridity_min

Minimum aridity tolerance (1-5 scale)

aridity_max

Maximum aridity tolerance (1-5 scale)

eutrophication_min

Minimum nutrient requirements (1-5 scale)

eutrophication_max

Maximum nutrient tolerance (1-5 scale)

altitudinal_distribution_min

Minimum altitude zone (1-6 scale)

altitudinal_distribution_max

Maximum altitude zone (1-6 scale)

poleotolerance_min

Minimum poleotolerance level (1-5 scale)

poleotolerance_max

Maximum poleotolerance level (1-5 scale)

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      data <- italic_ecology_traits(names_matched$accepted_name)

References

ITALIC - The Information System on Italian Lichens: data about taxa https://italic.units.it/?procedure=base&t=59&c=60#otherdata

Examples

## Not run: 
italic_ecology_traits("Cetraria islandica (L.) Ach. subsp. islandica")

## End(Not run)

Get distribution of lichen taxa across Italian ecoregions

Description

Returns the distribution and commonness status of lichen taxa across Italian ecoregions. Only accepts names that exist in the database of ITALIC.

Usage

italic_ecoregions_distribution(sp_names, result_data = "rarity")

Arguments

sp_names

Character vector of accepted names
result_data

Character string specifying the output format: "rarity" (default) returns commonness/rarity categories, "presence-absence" returns only values for presence/absence (0/1)

Value

A data frame with:

scientific_name

The scientific name provided as input

alpine

Status in alpine belt (extremely common to absent)

subalpine

Status in subalpine belt (extremely common to absent)

oromediterranean

Status in oromediterranean belt (extremely common to absent)

montane

Status in montane belt (extremely common to absent)

dry_submediterranean

Status in dry submediterranean belt (extremely common to absent)

padanian

Status in padanian belt (extremely common to absent)

humid_submediterranean

Status in humid submediterranean belt (extremely common to absent)

humid_mediterranean

Status in humid mediterranean belt (extremely common to absent)

dry_mediterranean

Status in dry mediterranean belt (extremely common to absent)

The possible values of commonness/rarity are: "extremely common", "very common", "common", "rather common", "rather rare", "rare", "very rare", "extremely rare", "absent"

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      ecoregions_distribution <- italic_ecoregions_distribution(names_matched$accepted_name)

References

For more information about Italian ecoregions see ITALIC ecoregions distribution https://italic.units.it/?procedure=base&t=59&c=60#commonness and the scientific publication describing the ecoregions doi:10.3390/d12080294

Examples

## Not run: 
# Get commonness/rarity categories
italic_ecoregions_distribution("Cetraria ericetorum Opiz")

# Get presence/absence data
italic_ecoregions_distribution("Cetraria ericetorum Opiz", result_data="presence-absence")

## End(Not run)

Generate interactive identification keys for lichen taxa

Description

Creates a URL link to a custom interactive dichotomous key for identifying the specified lichen taxa using the KeyMaker system of ITALIC. Only accepts names that exist in the database of ITALIC.

Usage

italic_identification_key(sp_names)

Arguments

sp_names

Character vector of accepted names

Value

Character string containing the URL to a web-based interactive identification key. The key is uniquely generated for the input taxa and allows step-by-step identification through dichotomous choices.

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      key_url <- italic_identification_key(names_matched$accepted_name)

References

ITALIC - The KeyMaker https://italic.units.it/key-maker/

Examples

## Not run: 
# Generate key for two species
italic_identification_key(c("Cetraria ericetorum Opiz","Xanthoria parietina (L.) Th. Fr."))

## End(Not run)

Match scientific names of lichens against the database of ITALIC

Description

Aligns scientific names of lichens against the Checklist of the Lichens of Italy available in ITALIC database. The function handles infraspecific ranks (subspecies, varieties, forms) and returns detailed matching information including nomenclatural status and matching scores.

Usage

italic_match(sp_names, subsp_marks = c(), var_marks = c(), form_marks = c())

Arguments

sp_names

A character vector of scientific names to match
subsp_marks

Character vector of markers used to indicate uncommon subspecies rank in the input names (different from "subsp.", "ssp."). For example, to match "Pseudevernia furfuracea b) ceratea", you need to pass "b)" as subsp_mark
var_marks

Character vector of markers used to indicate uncommon variety rank in the input names (different from "var.", "v."). For example, to match "Acarospora sulphurata varietas rubescens", you need to pass "varietas" as var_mark
form_marks

Character vector of markers used to indicate uncommon form rank in the input names (different from "f.", "form"). For example, to match "Verrucaria nigrescens fo. tectorum", you need to pass "fo." as form_mark

Value

A data frame with the following columns:

input_name

Original scientific name provided

matched_name

Name matched in ITALIC database

status

Nomenclatural status ("accepted" or "synonym")

accepted_name

Currently accepted name in ITALIC

name_score

Matching score for the name part (0-100)

auth_score

Matching score for the authority part (0-100)

Examples

## Not run: 
# Simple name match
italic_match("Cetraria islandica")

# Name match where the name contains spelling mistakes
italic_match("Xantoria parietina")

# Match where the name contains uncommon marker
italic_match("Acarospora sulphurata varietas rubescens",
                      var_marks = "varietas")

# Match multiple names
italic_match(c("Cetraria islandica", "Xanthoria parietina"))

## End(Not run)

Get details of species names

Description

Retrieves information for a scientific name used in ITALIC, including name id, taxonomic status, Index Fungorum id and related taxon id.

Usage

italic_name_usage(sp_names)

Arguments

sp_names

Character vector of matched names or accepted names

Value

A data frame with columns:

input_name

The scientific name provided as input

scientific_name_id

Unique identifier of ITALIC for the scientific name

index_fungorum_id

Corresponding Index Fungorum identifier

scientific_name_full

Complete scientific name including authority

scientific_name

Scientific name without authority

authorship

Author of the name

notes

Additional notes about the taxon, if any

rank

Taxonomic rank of the name

status

Taxonomic status ('accepted', 'synonym' or 'basionym')

related_accepted_name_id

ID of the currently accepted name related to the input name in ITALIC

related_accepted_name

Full accepted name

related_taxon_id

ID of the related taxon in ITALIC

Note

Before using this function with a list of names, first obtain their matched names or accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      name_data <- italic_name_usage(names_matched$matched_name)
      # or
      accepted_name_data <- italic_name_usage(names_matched$accepted_name)

Examples

## Not run: 
italic_name_usage(c("Cetraria islandica (L.) Ach. subsp. islandica", "Secoliga annexa Arnold"))

## End(Not run)

Get occurrence records for lichen taxa

Description

Retrieves occurrence records from Italian herbarium collections for specified lichen taxa. Only accepts names that exist in the database of ITALIC.

Usage

italic_occurrences(sp_names, result_data = "simple")

Arguments

sp_names

Character vector of accepted names
result_data

Character string specifying output detail level: "simple" (default) or "extended"

Value

A data frame with occurrence records. Column names follow the Darwin Core standard, with the additional column substratum, which is particularly relevant for lichens. For simple output:

scientificName

The scientific name provided as input

decimalLatitude

Latitude in decimal degrees

decimalLongitude

Longitude in decimal degrees

coordinatesUncertaintyInMeters

Spatial uncertainty of the coordinates

substratum

Substrate on which the specimen was found

institutionCode

Code of the herbarium holding the specimen

eventDate

Collection date

Extended output adds:

locality

Collection locality

catalogNumber

Specimen identifier in the collection

minimumElevationInMeters

Lower limit of the elevation range

maximumElevationInMeters

Upper limit of the elevation range

verbatimIdentification

Scientific name reported on the original label

identifiedBy

Person who identified the specimen

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      occ <- italic_occurrences(names_matched$accepted_name)

References

ITALIC - The Information System on Italian Lichens https://italic.units.it

Examples

## Not run: 
# Get simple occurrence data
italic_occurrences("Cetraria ericetorum Opiz")

# Get extended occurrence data
occ_ext <- italic_occurrences("Cetraria ericetorum Opiz", result_data = "extended")

# Then get citations for the retrieved occurrences
italic_occurrences_references(occ_ext)

## End(Not run)

Get scientific references for occurrence data

Description

Retrieves bibliographic references and DOIs for scientific publications describing occurrence datasets from specific herbarium collections.

Usage

italic_occurrences_references(occurrences_dataframe)

Arguments

occurrences_dataframe

Data frame containing occurrence records, obtained from italic_occurrences(). Must include an 'institutionCode' column

Value

A data frame with two columns:

reference

Full bibliographic citation of the publication

doi

Digital Object Identifier URL

Examples

## Not run: 
# Get occurrences first
occurrences <- italic_occurrences("Cetraria ericetorum Opiz")

# Then get associated references
italic_occurrences_references(occurrences)

## End(Not run)

Get distribution of lichen taxa in Italy

Description

Retrieves presence/absence data (1/0) for lichen taxa across all the Italian administrative regions. Only accepts accepted names from the ITALIC database.

Only accepts names that exist in the database of ITALIC.

Usage

italic_regions_distribution(sp_names)

Arguments

sp_names

Character vector of accepted names from ITALIC database

Value

A data frame with columns:

scientific_name

The scientific name provided as input

abruzzo

Presence (1) or absence (0) in Abruzzo

basilicata

Presence (1) or absence (0) in Basilicata

calabria

Presence (1) or absence (0) in Calabria

campania

Presence (1) or absence (0) in Campania

emilia_romagna

Presence (1) or absence (0) in Emilia Romagna

friuli_venezia_giulia

Presence (1) or absence (0) in Friuli Venezia-Giulia

lazio

Presence (1) or absence (0) in Lazio

liguria

Presence (1) or absence (0) in Liguria

lombardia

Presence (1) or absence (0) in Lombardia

marche

Presence (1) or absence (0) in Marche

molise

Presence (1) or absence (0) in Molise

piemonte

Presence (1) or absence (0) in Piemonte

puglia

Presence (1) or absence (0) in Puglia

sardegna

Presence (1) or absence (0) in Sardegna

sicilia

Presence (1) or absence (0) in Sicilia

toscana

Presence (1) or absence (0) in Toscana

trentino_alto_adige

Presence (1) or absence (0) in Trentino Alto-Adige

umbria

Presence (1) or absence (0) in Umbria

valle_d_aosta

Presence (1) or absence (0) in Valle d'Aosta

veneto

Presence (1) or absence (0) in Veneto

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      distribution <- italic_regions_distribution(names_matched$accepted_name)

Examples

## Not run: 
# First match names
matched <- italic_match("Cetraria islandica")
# Then get distribution in administrative regions
italic_regions_distribution(matched$accepted_name)

## End(Not run)

Get data of lichen taxa

Description

This function returns a dataframe containing taxonomy, ecology_traits, regions_distribution, ecoregions_distribution of the lichen species passed as input. For more info about these parameters see https://italic.units.it/?procedure=base&t=59&c=60#otherdata Only accepts names that exist in the database of ITALIC.

Usage

italic_taxon_data(sp_names)

Arguments

sp_names

A vector containing the scientific names of the lichen species.

Value

A dataframe containing the taxonomy, ecology distribution and rarity of the lichen species passed as input.

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      italic_taxon_data(names_matched$accepted_name)

References

ITALIC - The Information System on Italian Lichens: data about taxa https://italic.units.it/?procedure=base&t=59&c=60#otherdata

Examples

## Not run: 
italic_taxon_data(c("Cetraria ericetorum Opiz", "Lecanora salicicola H. Magn."))

## End(Not run)

Get taxonomic classification of lichen taxa

Description

Retrieves the complete taxonomic classification of lichen taxa from the ITALIC database. Only accepts names that exist in the database of ITALIC.

Usage

italic_taxonomy(sp_names)

Arguments

sp_names

Character vector of accepted names

Value

A data frame with:

scientific_name

The scientific name provided as input

phylum

Phylum

class

Class

order

Order

family

Family

genus

Genus

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      taxonomy <- italic_taxonomy(names_matched$accepted_name)

Examples

## Not run: 
italic_taxonomy("Cetraria islandica (L.) Ach. subsp. islandica")

## End(Not run)

Get a presence-absence matrix of lichen traits

Description

This function returns morphological traits of the lichen species passed as input. Only accepts names that exist in the database of ITALIC.

Usage

italic_traits_pa(sp_names)

Arguments

sp_names

A vector containing scientific names of lichens.

Value

A dataframe containing a series of traits for the lichen species passed as input.

Note

Before using this function with a list of names, first obtain their accepted names using italic_match(). Example workflow: 

      names_matched <- italic_match(your_names)
      traits <- italic_taits_pa(names_matched$accepted_name)

Examples

## Not run: 
italic_traits_pa("Cetraria ericetorum Opiz")

## End(Not run)