The ‘En Tibi’ tomato specimen

Using the SpecimenClient

For the different data types in the NBA (Specimen, Taxon, Multimedia, Geo), there are respective client classes (SpecimenClient, TaxonClient, MultimediaClient, GeoClient). To retreive electronic specimen records, we instantiate a SpecimenClient:

To get an overview of what we can do with such a client, ?SpecimenClient will give us some description and list all the methods that are available for this client. To get an overview of what nbaR stores in a Specimen object, we could use the function get_paths, which lists everything that can be queried for a specimen:

Note that client class methods (and other class members) are accessed with a $. The response from the taxon client is stored in res, an object of class Response. Have a look at ?Response to see what this object contains. But how to get the data? It is in the field content.

##   [1] "sourceSystem.code"                                                              
##   [2] "sourceSystem.name"                                                              
##   [3] "sourceSystemId"                                                                 
##   [4] "recordURI"                                                                      
##   [5] "unitID"                                                                         
##   [6] "unitGUID"                                                                       
##   [7] "collectorsFieldNumber"                                                          
##   [8] "assemblageID"                                                                   
##   [9] "sourceInstitutionID"                                                            
##  [10] "sourceID"                                                                       
##  [11] "previousSourceID"                                                               
##  [12] "owner"                                                                          
##  [13] "licenseType"                                                                    
##  [14] "license"                                                                        
##  [15] "recordBasis"                                                                    
##  [16] "kindOfUnit"                                                                     
##  [17] "collectionType"                                                                 
##  [18] "sex"                                                                            
##  [19] "phaseOrStage"                                                                   
##  [20] "title"                                                                          
##  [21] "notes"                                                                          
##  [22] "preparationType"                                                                
##  [23] "previousUnitsText"                                                              
##  [24] "numberOfSpecimen"                                                               
##  [25] "fromCaptivity"                                                                  
##  [26] "objectPublic"                                                                   
##  [27] "multiMediaPublic"                                                               
##  [28] "acquiredFrom.agentText"                                                         
##  [29] "gatheringEvent.projectTitle"                                                    
##  [30] "gatheringEvent.worldRegion"                                                     
##  [31] "gatheringEvent.continent"                                                       
##  [32] "gatheringEvent.country"                                                         
##  [33] "gatheringEvent.iso3166Code"                                                     
##  [34] "gatheringEvent.provinceState"                                                   
##  [35] "gatheringEvent.island"                                                          
##  [36] "gatheringEvent.locality"                                                        
##  [37] "gatheringEvent.city"                                                            
##  [38] "gatheringEvent.sublocality"                                                     
##  [39] "gatheringEvent.localityText"                                                    
##  [40] "gatheringEvent.dateTimeBegin"                                                   
##  [41] "gatheringEvent.dateTimeEnd"                                                     
##  [42] "gatheringEvent.dateText"                                                        
##  [43] "gatheringEvent.method"                                                          
##  [44] "gatheringEvent.altitude"                                                        
##  [45] "gatheringEvent.altitudeUnifOfMeasurement"                                       
##  [46] "gatheringEvent.behavior"                                                        
##  [47] "gatheringEvent.biotopeText"                                                     
##  [48] "gatheringEvent.depth"                                                           
##  [49] "gatheringEvent.depthUnitOfMeasurement"                                          
##  [50] "gatheringEvent.code"                                                            
##  [51] "gatheringEvent.establishmentMeans"                                              
##  [52] "gatheringEvent.gatheringPersons.agentText"                                      
##  [53] "gatheringEvent.gatheringPersons.fullName"                                       
##  [54] "gatheringEvent.gatheringPersons.organization.agentText"                         
##  [55] "gatheringEvent.gatheringPersons.organization.name"                              
##  [56] "gatheringEvent.gatheringOrganizations.agentText"                                
##  [57] "gatheringEvent.gatheringOrganizations.name"                                     
##  [58] "gatheringEvent.siteCoordinates.longitudeDecimal"                                
##  [59] "gatheringEvent.siteCoordinates.latitudeDecimal"                                 
##  [60] "gatheringEvent.siteCoordinates.gridCellSystem"                                  
##  [61] "gatheringEvent.siteCoordinates.gridLatitudeDecimal"                             
##  [62] "gatheringEvent.siteCoordinates.gridLongitudeDecimal"                            
##  [63] "gatheringEvent.siteCoordinates.gridCellCode"                                    
##  [64] "gatheringEvent.siteCoordinates.gridQualifier"                                   
##  [65] "gatheringEvent.siteCoordinates.coordinateErrorDistanceInMeters"                 
##  [66] "gatheringEvent.siteCoordinates.spatialDatum"                                    
##  [67] "gatheringEvent.siteCoordinates.geoShape"                                        
##  [68] "gatheringEvent.namedAreas.areaName"                                             
##  [69] "gatheringEvent.namedAreas.areaClass"                                            
##  [70] "gatheringEvent.associatedTaxa.name"                                             
##  [71] "gatheringEvent.associatedTaxa.relationType"                                     
##  [72] "gatheringEvent.chronoStratigraphy.youngRegionalSubstage"                        
##  [73] "gatheringEvent.chronoStratigraphy.youngRegionalStage"                           
##  [74] "gatheringEvent.chronoStratigraphy.youngRegionalSeries"                          
##  [75] "gatheringEvent.chronoStratigraphy.youngDatingQualifier"                         
##  [76] "gatheringEvent.chronoStratigraphy.youngInternSystem"                            
##  [77] "gatheringEvent.chronoStratigraphy.youngInternSubstage"                          
##  [78] "gatheringEvent.chronoStratigraphy.youngInternStage"                             
##  [79] "gatheringEvent.chronoStratigraphy.youngInternSeries"                            
##  [80] "gatheringEvent.chronoStratigraphy.youngInternErathem"                           
##  [81] "gatheringEvent.chronoStratigraphy.youngInternEonothem"                          
##  [82] "gatheringEvent.chronoStratigraphy.youngChronoName"                              
##  [83] "gatheringEvent.chronoStratigraphy.youngCertainty"                               
##  [84] "gatheringEvent.chronoStratigraphy.oldDatingQualifier"                           
##  [85] "gatheringEvent.chronoStratigraphy.chronoPreferredFlag"                          
##  [86] "gatheringEvent.chronoStratigraphy.oldRegionalSubstage"                          
##  [87] "gatheringEvent.chronoStratigraphy.oldRegionalStage"                             
##  [88] "gatheringEvent.chronoStratigraphy.oldRegionalSeries"                            
##  [89] "gatheringEvent.chronoStratigraphy.oldInternSystem"                              
##  [90] "gatheringEvent.chronoStratigraphy.oldInternSubstage"                            
##  [91] "gatheringEvent.chronoStratigraphy.oldInternStage"                               
##  [92] "gatheringEvent.chronoStratigraphy.oldInternSeries"                              
##  [93] "gatheringEvent.chronoStratigraphy.oldInternErathem"                             
##  [94] "gatheringEvent.chronoStratigraphy.oldInternEonothem"                            
##  [95] "gatheringEvent.chronoStratigraphy.oldChronoName"                                
##  [96] "gatheringEvent.chronoStratigraphy.chronoIdentifier"                             
##  [97] "gatheringEvent.chronoStratigraphy.oldCertainty"                                 
##  [98] "gatheringEvent.bioStratigraphy.youngBioDatingQualifier"                         
##  [99] "gatheringEvent.bioStratigraphy.youngBioName"                                    
## [100] "gatheringEvent.bioStratigraphy.youngFossilZone"                                 
## [101] "gatheringEvent.bioStratigraphy.youngFossilSubZone"                              
## [102] "gatheringEvent.bioStratigraphy.youngBioCertainty"                               
## [103] "gatheringEvent.bioStratigraphy.youngStratType"                                  
## [104] "gatheringEvent.bioStratigraphy.bioDatingQualifier"                              
## [105] "gatheringEvent.bioStratigraphy.bioPreferredFlag"                                
## [106] "gatheringEvent.bioStratigraphy.rangePosition"                                   
## [107] "gatheringEvent.bioStratigraphy.oldBioName"                                      
## [108] "gatheringEvent.bioStratigraphy.bioIdentifier"                                   
## [109] "gatheringEvent.bioStratigraphy.oldFossilzone"                                   
## [110] "gatheringEvent.bioStratigraphy.oldFossilSubzone"                                
## [111] "gatheringEvent.bioStratigraphy.oldBioCertainty"                                 
## [112] "gatheringEvent.bioStratigraphy.oldBioStratType"                                 
## [113] "gatheringEvent.lithoStratigraphy.qualifier"                                     
## [114] "gatheringEvent.lithoStratigraphy.preferredFlag"                                 
## [115] "gatheringEvent.lithoStratigraphy.member2"                                       
## [116] "gatheringEvent.lithoStratigraphy.member"                                        
## [117] "gatheringEvent.lithoStratigraphy.informalName2"                                 
## [118] "gatheringEvent.lithoStratigraphy.informalName"                                  
## [119] "gatheringEvent.lithoStratigraphy.importedName2"                                 
## [120] "gatheringEvent.lithoStratigraphy.importedName1"                                 
## [121] "gatheringEvent.lithoStratigraphy.lithoIdentifier"                               
## [122] "gatheringEvent.lithoStratigraphy.formation2"                                    
## [123] "gatheringEvent.lithoStratigraphy.formationGroup2"                               
## [124] "gatheringEvent.lithoStratigraphy.formationGroup"                                
## [125] "gatheringEvent.lithoStratigraphy.formation"                                     
## [126] "gatheringEvent.lithoStratigraphy.certainty2"                                    
## [127] "gatheringEvent.lithoStratigraphy.certainty"                                     
## [128] "gatheringEvent.lithoStratigraphy.bed2"                                          
## [129] "gatheringEvent.lithoStratigraphy.bed"                                           
## [130] "informationWithheld"                                                            
## [131] "dataGeneralizations"                                                            
## [132] "modified"                                                                       
## [133] "identifications.taxonRank"                                                      
## [134] "identifications.scientificName.fullScientificName"                              
## [135] "identifications.scientificName.taxonomicStatus"                                 
## [136] "identifications.scientificName.genusOrMonomial"                                 
## [137] "identifications.scientificName.subgenus"                                        
## [138] "identifications.scientificName.specificEpithet"                                 
## [139] "identifications.scientificName.infraspecificEpithet"                            
## [140] "identifications.scientificName.infraspecificMarker"                             
## [141] "identifications.scientificName.nameAddendum"                                    
## [142] "identifications.scientificName.authorshipVerbatim"                              
## [143] "identifications.scientificName.author"                                          
## [144] "identifications.scientificName.year"                                            
## [145] "identifications.scientificName.scientificNameGroup"                             
## [146] "identifications.scientificName.references.titleCitation"                        
## [147] "identifications.scientificName.references.citationDetail"                       
## [148] "identifications.scientificName.references.uri"                                  
## [149] "identifications.scientificName.references.author.agentText"                     
## [150] "identifications.scientificName.references.author.fullName"                      
## [151] "identifications.scientificName.references.author.organization.agentText"        
## [152] "identifications.scientificName.references.author.organization.name"             
## [153] "identifications.scientificName.references.publicationDate"                      
## [154] "identifications.scientificName.experts.agentText"                               
## [155] "identifications.scientificName.experts.fullName"                                
## [156] "identifications.scientificName.experts.organization.agentText"                  
## [157] "identifications.scientificName.experts.organization.name"                       
## [158] "identifications.typeStatus"                                                     
## [159] "identifications.dateIdentified"                                                 
## [160] "identifications.defaultClassification.kingdom"                                  
## [161] "identifications.defaultClassification.phylum"                                   
## [162] "identifications.defaultClassification.className"                                
## [163] "identifications.defaultClassification.order"                                    
## [164] "identifications.defaultClassification.superFamily"                              
## [165] "identifications.defaultClassification.family"                                   
## [166] "identifications.defaultClassification.genus"                                    
## [167] "identifications.defaultClassification.subgenus"                                 
## [168] "identifications.defaultClassification.specificEpithet"                          
## [169] "identifications.defaultClassification.infraspecificEpithet"                     
## [170] "identifications.defaultClassification.infraspecificRank"                        
## [171] "identifications.systemClassification.rank"                                      
## [172] "identifications.systemClassification.name"                                      
## [173] "identifications.vernacularNames.name"                                           
## [174] "identifications.vernacularNames.language"                                       
## [175] "identifications.vernacularNames.preferred"                                      
## [176] "identifications.vernacularNames.references.titleCitation"                       
## [177] "identifications.vernacularNames.references.citationDetail"                      
## [178] "identifications.vernacularNames.references.uri"                                 
## [179] "identifications.vernacularNames.references.author.agentText"                    
## [180] "identifications.vernacularNames.references.author.fullName"                     
## [181] "identifications.vernacularNames.references.author.organization.agentText"       
## [182] "identifications.vernacularNames.references.author.organization.name"            
## [183] "identifications.vernacularNames.references.publicationDate"                     
## [184] "identifications.vernacularNames.experts.agentText"                              
## [185] "identifications.vernacularNames.experts.fullName"                               
## [186] "identifications.vernacularNames.experts.organization.agentText"                 
## [187] "identifications.vernacularNames.experts.organization.name"                      
## [188] "identifications.identificationQualifiers"                                       
## [189] "identifications.identifiers.agentText"                                          
## [190] "identifications.taxonomicEnrichments.vernacularNames.name"                      
## [191] "identifications.taxonomicEnrichments.vernacularNames.language"                  
## [192] "identifications.taxonomicEnrichments.synonyms.fullScientificName"               
## [193] "identifications.taxonomicEnrichments.synonyms.taxonomicStatus"                  
## [194] "identifications.taxonomicEnrichments.synonyms.genusOrMonomial"                  
## [195] "identifications.taxonomicEnrichments.synonyms.subgenus"                         
## [196] "identifications.taxonomicEnrichments.synonyms.specificEpithet"                  
## [197] "identifications.taxonomicEnrichments.synonyms.infraspecificEpithet"             
## [198] "identifications.taxonomicEnrichments.synonyms.authorshipVerbatim"               
## [199] "identifications.taxonomicEnrichments.defaultClassification.kingdom"             
## [200] "identifications.taxonomicEnrichments.defaultClassification.phylum"              
## [201] "identifications.taxonomicEnrichments.defaultClassification.className"           
## [202] "identifications.taxonomicEnrichments.defaultClassification.order"               
## [203] "identifications.taxonomicEnrichments.defaultClassification.superFamily"         
## [204] "identifications.taxonomicEnrichments.defaultClassification.family"              
## [205] "identifications.taxonomicEnrichments.defaultClassification.genus"               
## [206] "identifications.taxonomicEnrichments.defaultClassification.subgenus"            
## [207] "identifications.taxonomicEnrichments.defaultClassification.specificEpithet"     
## [208] "identifications.taxonomicEnrichments.defaultClassification.infraspecificEpithet"
## [209] "identifications.taxonomicEnrichments.defaultClassification.infraspecificRank"   
## [210] "identifications.taxonomicEnrichments.sourceSystem.code"                         
## [211] "identifications.taxonomicEnrichments.taxonId"                                   
## [212] "identifications.preferred"                                                      
## [213] "identifications.verificationStatus"                                             
## [214] "identifications.rockType"                                                       
## [215] "identifications.associatedFossilAssemblage"                                     
## [216] "identifications.rockMineralUsage"                                               
## [217] "identifications.associatedMineralName"                                          
## [218] "identifications.remarks"                                                        
## [219] "associatedMultiMediaUris.accessUri"                                             
## [220] "associatedMultiMediaUris.format"                                                
## [221] "associatedMultiMediaUris.variant"                                               
## [222] "theme"

Suppose that we do not know the scientific name of the tomato plant, there are two fields that store a vernacular name for a specimen:

  • identifications.vernacularNames.name
  • identifications.taxonomicEnrichments.vernacularNames.name

The first one is the vernacular name that is exactly equal to the one in the source database. Since often, a vernacular name is missing in the source database, a taxonomic enrichment is performed during the import of the data from the source database in which, using among others the Catalogue of life, species names are enriched with synonyms and vernacular names.

Simple queries

Let’s try the first field and query for all Specimen records with identifications.vernacularNames.name field matching the name tomato, we can use the client’s query function:

res <-
  sc$query(queryParams = list(identifications.vernacularNames.name = "tomato"))

Note that the queryParams arguments takes a list, so we could search for more criteria. How many hits do we got?

## [1] 0

No hits, thus no record has the vernacular name equal to tomato. We therefore search in identifications.taxonomicEnrichments.vernacularNames.name:

res <-
  sc$query(
    queryParams =
      list(identifications.taxonomicEnrichments.vernacularNames.name =
             "tomato")
  )
# how many hits?
res$content$totalSize
## [1] 0

Again, no hits.

More complex queries

Let’s try partial matching. For this, we have to make a more complicated query, involving QuerySpec and QueryCondition objects, which are very powerful for constructing complex and nested queries.

A QueryCondition can be specified as follows:

Note that we use the operator MATCHES that does a partial instead of an exact match (which would be EQUALS).

From one or multiple QueryConditions, a QuerySpec can be created, and used as input for he query function.

## [1] 380

Finally, we have some hits. The content of the response of the query function is always of type QueryResult (see also ?QueryResult) which has the fields totalSize (as used above) and a resultSet, a list which stores the actual data. From the resultSet, a single Specimen object can be obtained as follows:

## [1] "Specimen" "R6"
## <Specimen>
## Fields:
##  sourceSystem:   object of class <SourceSystem> 
##  sourceSystemId:  L.1110630 
##  recordURI:   
##  id:  L.1110630@BRAHMS 
##  unitID:  L.1110630 
##  unitGUID:    http://data.biodiversitydata.nl/naturalis/specimen/L.1110630 
##  collectorsFieldNumber:   Unknown  s.n.  
##  assemblageID:    4394584@BRAHMS 
##  sourceInstitutionID:     Naturalis Biodiversity Center 
##  sourceID:    Brahms 
##  previousSourceID:    
##  owner:   Naturalis Biodiversity Center 
##  licenseType:     Copyright 
##  license:     CC0 4.0 
##  recordBasis:     Microscopic slide: Anatomy 
##  kindOfUnit:  
##  collectionType:  Botany 
##  sex:     
##  phaseOrStage:    
##  title:   
##  notes:   
##  preparationType:     
##  previousUnitsText:   
##  numberOfSpecimen:    
##  fromCaptivity:   
##  objectPublic:    TRUE 
##  multiMediaPublic:    
##  acquiredFrom:   object of class <Agent> 
##  gatheringEvent: object of class <GatheringEvent> 
##  identifications:    list of length 1 
##  associatedMultiMediaUris:   list of length 1 
##  theme:   
## Methods:
##  fromJSONString
##  toJSONString
##  fromList
##  toList
##  print

Note: By default, the NBA (and thus nbaR) returns the first 10 hits. To fetch more records, we need to specify this in the QuerySpec object.

## [1] TRUE

Sorting

We now want to see which one is the oldest specimen. We could, of course do the sorting in R (e.g. sort(unlist(lapply(res$content$resultSet, function(x)x$item$gatheringEvent$dateTimeBegin)))), but there is also functionality to do this directly in the query. This can be done with objects of type ?SortField, which can take a path specifying on what to sort, and whether to sort ascending or descending. We will sort our results by the values of the field gatheringEvent.dateTimeBegin:

Now, the first result should be the specimen with a gathering event the furthest in the past.

## [1] "1550-01-01T00:00:00+0000"

Multimedia content

Many specimens have associated multimedia content, such as photos or videos. To retrieve e.g. the URL of the first multimedia item of our specimen:

## [1] "http://medialib.naturalis.nl/file/id/L.2111092/format/large"

Retrieving specimen records with lat/long coordinates

Geo-referenced specimens are an invaluable resource for biogeographic analyses. The below example shows how to extract the tomato specimen (species Solanum lycopersicum) that are geo referenced. The coordinates, stored in the field gatheringEvent.siteCoordinates are then extracted and the locations are plotted on a world map.

Note: When querying for records with non-empty values for a specific field, we use the operator NOT_EQUALS in combination with the value NULL.