`set_coverage()`: Express common names in `commonName` in `taxonomicCoverage`

[peterdesmet]

Taxonomic coverage can be provided as a data frame where each column is a rank. Common is also considered a rank (https://docs.ropensci.org/EML/reference/set_coverage.html#note):

library(EML)
df <- data.frame(Class = "Aves", Species = "Anas platyrhynchos", Common = "mallard")
coverage <- set_coverage(sci_names = df)
str(coverage$taxonomicCoverage)
#> List of 1
#>  $ taxonomicClassification:List of 1
#>   ..$ :List of 3
#>   .. ..$ taxonRankName          : chr "Class"
#>   .. ..$ taxonRankValue         : chr "Aves"
#>   .. ..$ taxonomicClassification:List of 3
#>   .. .. ..$ taxonRankName          : chr "Species"
#>   .. .. ..$ taxonRankValue         : chr "Anas platyrhynchos"
#>   .. .. ..$ taxonomicClassification:List of 2
#>   .. .. .. ..$ taxonRankName : chr "Common"
#>   .. .. .. ..$ taxonRankValue: chr "mallard"

^{Created on 2022-06-03 by the reprex package (v2.0.1)}

GBIF IPT handles Common names in a separate property:

<taxonomicClassification>
  <taxonRankName>species</taxonRankName>
  <taxonRankValue>Anas platyrhynchos</taxonRankValue>
  <commonName>mallard</commonName>
</taxonomicClassification>

I'm not sure is that is according to EML specs, but if so, would it be possible for set_coverage() to treat Common the same way?

[mbjones]

Good catch, @peterdesmet -- I agree this is a serialization error. The common name should be in the commonName element, and not as a child node as if it were another rank and value. Here's the XML generated from your example, which should be like the one generated by the IPT that you showed above.

      <taxonomicCoverage>
        <taxonomicClassification>
          <taxonRankName>Class</taxonRankName>
          <taxonRankValue>Aves</taxonRankValue>
          <taxonomicClassification>
            <taxonRankName>Species</taxonRankName>
            <taxonRankValue>Anas platyrhynchos</taxonRankValue>
            <taxonomicClassification>
              <taxonRankName>Common</taxonRankName>
              <taxonRankValue>mallard</taxonRankValue>
            </taxonomicClassification>
          </taxonomicClassification>
        </taxonomicClassification>
      </taxonomicCoverage>

[mbjones]

I see where the problem lies -- the setCoverage convenience method is not designed to handle common names. Instead, it interprets each column in the data frame as a descending set or rank names. Here's the note in the package documentation about this:

#' @note If "sci_names" is a data frame, column names of the data frame are rank names.
#' For user-defined "sci_names", users must make sure that the order of rank names
#' they specify is from high to low.
#' Ex. "Kingdom","Phylum","Class","Order","Family","Genus","Species","Common"
#' EML permits any rank names provided they go in descending order.

So the code is behaving as planned, and there is no capability to add a commonName using the convenience method. That said, you could use the convenience method to create the structure, then add the commonName to the list manually like so:

library(EML)
df <- data.frame(Class = "Aves", Species = "Anas platyrhynchos")
coverage <- set_coverage(sci_names = df)
coverage$taxonomicCoverage$taxonomicClassification[[1]]$taxonomicClassification$commonName <- 'Mallard'
str(coverage$taxonomicCoverage)
#> List of 1
#>  $ taxonomicClassification:List of 1
#>   ..$ :List of 3
#>   .. ..$ taxonRankName          : chr "Class"
#>   .. ..$ taxonRankValue         : chr "Aves"
#>   .. ..$ taxonomicClassification:List of 3
#>   .. .. ..$ taxonRankName : chr "Species"
#>   .. .. ..$ taxonRankValue: chr "Anas platyrhynchos"
#>   .. .. ..$ commonName    : chr "Mallard"

^{Created on 2022-06-03 by the reprex package (v2.0.1)}

This produces the following XML output, which matches the IPT format.

      <taxonomicCoverage>
        <taxonomicClassification>
          <taxonRankName>Class</taxonRankName>
          <taxonRankValue>Aves</taxonRankValue>
          <taxonomicClassification>
            <taxonRankName>Species</taxonRankName>
            <taxonRankValue>Anas platyrhynchos</taxonRankValue>
            <commonName>Mallard</commonName>
          </taxonomicClassification>
        </taxonomicClassification>
      </taxonomicCoverage>

[peterdesmet]

Thanks for answering! I guess there are two solutions then:

1. Don’t list Common name in the documentation for the convenience method.
2. Update the convenience method so that the Common column is treated differently? I.e. turn this issue in a feature request?

[mbjones]

Yeah, I was contemplating both of those as well. (1) seems like a good idea, (2) seems like a bit of a hack, especially as commonName is a repeatable element in EML. So I was thinking a new feature to add commonNames would be good, but hadn't settled on how to do it. Maybe columns in the data frame with names Common_1 to Common_n? In other places in the package with 1:n cardinality, we use another table, but its a lot of overhead for this. Open to suggestions. @jeanetteclark any thoughts on this one from your perspective?

[jeanetteclark]

there are a handful of functions in the EML package that only partially support the schema. For example, for a very long time set_attributes only supported having one missing value code. If it seems like a common enough use case, then we could support repeatable common names as you suggest @mbjones though I agree it seems a little like a hack. I think in order of complexity (time permitting) we could plan to:

1. remove common name from documentation
2. add support for a single common name (and re-document as needed)
3. add support for multiple common names

[cboettig]

👍

Yup, I think it's deliberate that some functions support a simplified subset of the schema, (complex structures can always be built with the list-constructors and should still be covered by the validator). Even with good documentation, too much complexity can be off-putting to new users. Sometimes I think we can nudge people to better options too. For instance, very few programmatic parsers of text-delignated tabular data can handle multiple missing value codes, even though this case does occur in real-world data. It's important the EML can support such cases, but it might be useful to nudge folks away from some options.

For taxonomy, I think it would be useful to nudge people to taxonomic identifiers. As you know, these provide mappings to naming authorities, common names in different languages etc.

[peterdesmet]

For what it's worth, the dataframe I wanted to provide was one like:

taxonID	rank	scientificName	common.en	common.nl
5BSG3	species	Vulpes vulpes	fox	vos

Which I reduced to the convenience format:

Species	Common
Vulpes vulpes	fox

But as originally described, the common name ended up as a child.

I would be happy with a convenience method that supported 1 common name (and 1 taxonID) for the lowest rank in the row. In fact - since I don't use the hierarchy because the IPT does not support it - I would be fine with ID, scientificName, rank, vernacularName.

[cboettig]

@peterdesmet Thanks! Nice example.

I think it would be better though for the user to specify only the taxonID, from which we derive the rest. Note that I think we would need to use recognized prefixes on the taxonID or some other indication of which authority we're referring too, e.g. that looks like a a stable (i.e. post 2019) Catalogue of Life ID. Note that according to COL, the English common name appears to be "red fox". When the user gives both a taxon ID and other data such as a common name(s) that may not match that associated with the taxon ID, it's not obvious which one the R package should add to the metadata.

e.g.:

taxalight::tl("COL:5BSG3", "col")

[peterdesmet]

I think it would be better though for the user to specify only the taxonID, from which we derive the rest.

It would be nice to provide that as an option, but I think users should still have the option to provide a list of taxa and be done with it.

[mbjones]

I agree with that sentiment, @peterdesmet -- while the taxon databases are good for looking up official scientific names, vernacular names are often locally idiosyncratic, and people may want to include them in the metadata to establish that local usage.