---
title: Introduction to ridigbio
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to ridigbio}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The ridigbio package can be used to obtain records from [iDigBio](https://www.idigbio.org/) API's, including both the [Search API](https://github.com/idigbio/idigbio-search-api/wiki) and the [Media APIs](https://www.idigbio.org/wiki/index.php/IDigBio_API#Record_.26_Media_APIs). 

## General Overview   

In this demo we will cover how to:

1. Install `ridigbio`
2. Search for records with  `idig_search_records()`
3. Search for media records with `idig_search_media()`

## Getting Started

First, you must install the ridigbio package. If you are new to R and R studio, please refer to our QUBES module to get started: Introduction to R with Biodiversity Data, [doi:10.25334/84FC-TE88](https://www.doi.org/10.25334/84FC-TE88) .

The lastest version of our R package can be installed via CRAN. 
```{r eval=FALSE, include=TRUE}
install.packages("ridigbio")
```

Before downloading any records, you must load the ridigbio package.

```{r message=FALSE, warning=FALSE}
library(ridigbio)
```
```{r echo = FALSE}

verify_galax_records <- FALSE

#Test that examples will run
tryCatch({
    # Your code that might throw an error
    verify_galax_records <- idig_search_records(rq=list(scientificname="Galax urceolata"),
      limit = 10
    )
}, error = function(e) {
    # Code to run if an error occurs
    cat("An error occurred during the idig_search_records call: ", e$message, "\n")
    cat("Vignettes will not be fully generated. Please try again after resolving the issue.")
    # Optionally, you can return NULL or an empty dataframe
    verify_galax_records <- FALSE
})
```

## Download Records
To download records from the Search API, we will use the function `idig_search_records()`. 
Here the `rq`, or record query, indicates we want to download all the records where the `scientificname` is equal to [<i>Galax urceolata</i>](https://en.wikipedia.org/wiki/Galax). 

```{r eval=verify_galax_records}
galax_records <- idig_search_records(rq=list(scientificname="Galax urceolata"))
```

```{r eval=verify_galax_records}
colnames(galax_records)
```

When fields are not specified, default columns include the following:   

| Column | Description |
| ----------- | ----------- |
| uuid | Universally Unique IDentifier assigned by iDigBio  |
| occurrenceid |identifier for the occurrence, 	https://rs.tdwg.org/dwc/terms/occurrenceID| 
| catalognumber |identifier for the record within the collection, https://rs.tdwg.org/dwc/terms/catalogNumber|
| family | scientific name of the family, https://rs.tdwg.org/dwc/terms/family|
| genus | scientific name of the genus, https://rs.tdwg.org/dwc/terms/genus |
| scientificname | scientific name, https://rs.tdwg.org/dwc/terms/scientificName |
| country | country, 	https://rs.tdwg.org/dwc/terms/country |
| stateprovince |name of the next smaller administrative region than country, https://rs.tdwg.org/dwc/terms/stateProvince|
| geopoint.lon | equivalent to decimalLongitude, 	https://rs.tdwg.org/dwc/terms/decimalLongitude|
| geopoint.lat | equivalent to decimalLatitude,https://rs.tdwg.org/dwc/terms/decimalLatitude |
| datecollected | [Modified field and could lack biological meaning](https://github.com/iDigBio/idb-backend/issues/229) |
| data.dwc:eventDate | equivalent to eventDate, https://dwc.tdwg.org/list/#dwc_eventDate |
| data.dwc:year | year of collection event, https://dwc.tdwg.org/list/#dwc_year |
| data.dwc:month | month of collection event, https://dwc.tdwg.org/list/#dwc_month |
| data.dwc:day | day of collection event | (https://dwc.tdwg.org/list/#dwc_day |
| collector | equivalent to recordedBy,	https://rs.tdwg.org/dwc/terms/recordedBy |
| recordset | indicates the iDigBio recordset the observation belongs too! |


### More ways to search

In addition to `scientificname`, record query may be based on many other fields. For example, you can search for all members of the `family`[Diapensiaceae](https://en.wikipedia.org/wiki/Diapensiaceae): 

```{r eval=verify_galax_records}
diapensiaceae_records <- idig_search_records(rq=list(family="Diapensiaceae"), limit=1000)
```


**What if you want to read in all the points for a family within an extent?**

**Hint**: Use the [iDigBio portal](https://www.idigbio.org/portal/search) to determine the bounding box for your region of interest.       

The bounding box delimits the geographic extent. 

```{r eval=verify_galax_records}
rq_input <- list("scientificname"=list("type"="exists"),
                 "family"="Diapensiaceae", 
                 geopoint=list(
                   type="geo_bounding_box",
                   top_left=list(lon = -98.16, lat = 48.92),
                   bottom_right=list(lon = -64.02, lat = 23.06)
                   )
                 )
```

Search using the input you just made

```{r eval=verify_galax_records}
diapensiaceae_records_USA <- idig_search_records(rq_input, limit=1000)
```


## Download Media Records
To download media records from the Media API, we will use the function `idig_search_media()`. 
Here the `rq`, or record query, indicates we want to download all the records where the `scientificname` is equal to [<i>Galax urceolata</i>](https://en.wikipedia.org/wiki/Galax). 

```{r eval=verify_galax_records}
galax_media <- idig_search_media(rq=list(scientificname="Galax urceolata"))
```

```{r eval=verify_galax_records}
colnames(galax_media)
```

When fields are not specified, default columns include the following:   

| Column | Description |
| ----------- | ----------- |
| accessuri | Unique identifier for a resource, https://ac.tdwg.org/termlist/#ac_accessURI  |
| datemodified | date last modified, which is assigned by iDigBio | 
| dqs | data quality score assigned by iDigBio |
| etag | tag assigned by iDigBio |
| flags | data quality flag assigned by iDigBio |
| format | media format, https://purl.org/dc/terms/format |
| hasSpecimen | TRUE or FALSE, indicates if there is an associated record for this media |
| licenselogourl  | media license, https://ac.tdwg.org/termlist/#ac_licenseLogoURL) |
| mediatype  | media object type |
| modified | date modified, https://purl.org/dc/terms/modified  |
| recordids | list of UUID for associated records |
|  records  | UUID for the associated record. Use this field to connect Record downloads with Media downloads |
|  recordset  | indicates the iDigBio recordset the observation belongs too! |
| rights | media rights, https://purl.org/dc/terms/rights  |
| tag  | general keywords or tags, https://rs.tdwg.org/ac/terms/tag  |
| type | media type, https://purl.org/dc/terms/type |
|  uuid | Universally Unique IDentifier assigned by iDigBio  |
| version  | media record version assigned by iDigBio |
| webstatement  | media rights, https://developer.adobe.com/xmp/docs/XMPNamespaces/xmpRights/ | 
| xpixels |  as defined by EXIF, x dimension in pixel |
| ypixels | as defined by EXIF,y dimension in pixels  |
 

### More ways to search 

The media search above retained ```{r eval=verify_galax_records} nrow(galax_media)``` rows, however some of these observations do not have information in the `accessuri` field. To only obtain records with `acessuri`, we indicate we only want records where `data.ac:accessURI` exist, by setting `mq`, or media query, as followed:
```{r eval=verify_galax_records}
galax_media2 <- idig_search_media(rq=list(scientificname="Galax urceolata"),
                                  mq=list("data.ac:accessURI"=list("type"="exists")))
```

Now we have  ```{r eval=verify_galax_records} nrow(galax_media2)``` observations with `accessuri`!